@pompelmi/engine-binaryninja

Binary Ninja HLIL (High-Level Intermediate Language) decompilation engine for Pompelmi file scanner.

This package integrates Binary Ninja's powerful static analysis capabilities with Pompelmi's modular scanning architecture to detect malicious patterns in compiled binaries through decompilation analysis.

Features

- HLIL Decompilation: Extracts high-level intermediate representations from binaries
- Pattern Detection: Identifies suspicious API calls, obfuscation techniques, and anti-analysis measures
- Configurable Analysis: Multiple analysis depths from minimal to deep inspection
- Timeout Protection: Prevents analysis from hanging on complex binaries
- Rich Metadata: Detailed function analysis including complexity metrics

Prerequisites

- Binary Ninja License: Requires Binary Ninja Commercial or Personal license
- Python Environment: Binary Ninja Python API must be accessible
- Node.js: Version 18 or higher

Installation

``bash
pnpm add @pompelmi/engine-binaryninja
`

Quick Start

`typescript
import { createBinaryNinjaScanner } from '@pompelmi/engine-binaryninja';

const scanner = createBinaryNinjaScanner({
timeout: 30000, // 30 second timeout
depth: 'basic', // Analysis depth
pythonPath: 'python3', // Path to Python with Binary Ninja
});

// Scan a binary file
const bytes = await fs.readFile('suspicious.exe');
const matches = await scanner.scan(bytes);

// Or get detailed analysis
const result = await scanner.analyze(bytes);
console.log(Found ${result.functions.length} functions);
console.log(Detected ${result.matches.length} suspicious patterns);
`

Configuration

$3

- timeout (number): Analysis timeout in milliseconds (default: 30000)
- depth ('minimal' | 'basic' | 'deep'): Analysis depth (default: 'basic')
- enableHeuristics (boolean): Enable pattern detection (default: true)
- pythonPath (string): Path to Python executable (default: 'python3')
- binaryNinjaPath (string): Path to Binary Ninja installation

$3

- BINJA_PATH: Path to Binary Ninja installation directory
- PYTHONPATH: Should include Binary Ninja's Python API path

Analysis Results

$3

`typescript
interface DecompilationMatch {
rule: string; // Pattern rule name
severity: 'low' | 'medium' | 'high' | 'critical';
engine: 'binaryninja-hlil'; // Engine identifier
confidence: number; // 0.0 to 1.0
meta?: {
function?: string; // Function name where pattern found
address?: string; // Memory address
api_call?: string; // Suspicious API call
[key: string]: unknown;
};
}
`

$3

`typescript
interface FunctionAnalysis {
name: string; // Function name
address: string; // Start address
size: number; // Function size in bytes
complexity?: number; // Cyclomatic complexity
callCount?: number; // Number of function calls
isObfuscated?: boolean; // High complexity indicator
hasAntiAnalysis?: boolean; // Anti-analysis techniques
suspiciousCalls?: string[]; // List of suspicious API calls
}
`

Detected Patterns

The scanner automatically detects:

- Suspicious API Calls: Process injection, debugging, anti-analysis functions
- High Complexity: Functions with unusual complexity indicating obfuscation
- Anti-Debugging: Debug detection and evasion techniques
- Crypto Constants: Common cryptographic algorithm signatures

Integration with Pompelmi

Use with the main Pompelmi scanner:

`typescript
import { composeScanners } from 'pompelmi';
import { createBinaryNinjaScanner } from '@pompelmi/engine-binaryninja';
import { createYaraScanner } from '@pompelmi/engine-yara';

const scanner = composeScanners([
['yara', createYaraScanner()],
['binja', createBinaryNinjaScanner({ depth: 'basic' })],
]);

const results = await scanner.scan(binaryData);
`

Performance Considerations

- CPU Intensive: Decompilation requires significant computational resources
- Memory Usage: Large binaries may consume substantial memory during analysis
- Timeout Settings: Adjust timeout based on binary size and system performance
- Analysis Depth: Use 'minimal' for fast scanning, 'deep' for thorough analysis

Troubleshooting

$3


`
Error: "Binary Ninja Python executable not found"
`
- Ensure Binary Ninja is installed and licensed
- Set BINJA_PATH environment variable
- Verify Python can import binaryninja module

$3

`
Error: "Analysis timeout"
``
- Increase timeout value
- Use 'minimal' analysis depth for large binaries
- Consider pre-filtering files by size/type

License

MIT - See LICENSE file for details.

Contributing

Contributions welcome! Please see the main Pompelmi repository for guidelines.