diff --git a/README.md b/README.md index 7597a21..c07e9a6 100644 --- a/README.md +++ b/README.md @@ -48,14 +48,14 @@ Supports two modes: File, PID - Scanning executable files and processes to identify suspicious behavioral characteristics - Inspecting memory regions to detect anomalous content and hidden payloads - Analyzing process hollowing and injection techniques for detection artifacts -- Monitoring sleep patterns and network behavior of beacon processes +- Monitoring sleep patterns of a beacon processes - Validating integrity of PE files and detecting runtime modifications ## Integrated Tools ### Static Analyzers - YARA - Pattern matching and signature detection -- CheckPlz (ThreatCheck) - AV detection testing +- CheckPlz - AV detection testing ### Dynamic Analyzers - YARA (memory scanning) - Runtime pattern detection @@ -88,3 +88,243 @@ The `config.yml` file controls: - Analysis tool paths and options - YARA rule locations - Analysis timeouts and limits + + + +## Creating Your Own Analyzer + +LitterBox supports two types of analyzers: + +- **Static Analyzers**: Analyze files directly (e.g., exe, dll, docs). +- **Dynamic Analyzers**: Analyze running processes using PIDs. + +--- + +## Basic Setup + +### Step 1: Choose Your Analyzer Type + +Select the type of analyzer based on the target: + +```python +# For file analysis (exe, dll, docs) +from .base import StaticAnalyzer + +# For process analysis (PIDs) +from .base import DynamicAnalyzer +``` + +### Step 2: Create Your Analyzer Class + +#### Static Analyzer (for files): + +```python +class MyFileAnalyzer(StaticAnalyzer): + def analyze(self, file_path): + try: + tool_config = self.config['analysis']['static']['my_tool'] + command = tool_config['command'].format( + tool_path=tool_config['tool_path'], + file_path=file_path + ) + + process = subprocess.Popen(command, shell=True, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + universal_newlines=True + ) + + stdout, stderr = process.communicate() + + self.results = { + 'status': 'completed', + 'findings': self._parse_output(stdout), + 'errors': stderr + } + except Exception as e: + self.results = { + 'status': 'error', + 'error': str(e) + } +``` + +#### Dynamic Analyzer (for PIDs): + +```python +class MyProcessAnalyzer(DynamicAnalyzer): + def analyze(self, pid): + try: + tool_config = self.config['analysis']['dynamic']['my_tool'] + command = tool_config['command'].format( + tool_path=tool_config['tool_path'], + pid=pid + ) + + process = subprocess.Popen(command, shell=True, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + universal_newlines=True + ) + + stdout, stderr = process.communicate() + + self.results = { + 'status': 'completed', + 'findings': self._parse_output(stdout), + 'errors': stderr + } + except Exception as e: + self.results = { + 'status': 'error', + 'error': str(e) + } +``` + +### Step 3: Implement the Output Parser + +```python +def _parse_output(self, output): + findings = { + 'statistics': {}, # For the stats cards + 'detections': [], # For detailed findings + 'total_detections': 0 # For summary view + } + + for line in output.split('\n'): + if ':' in line: + key, value = line.split(':', 1) + findings['statistics'][key.strip()] = value.strip() + + return findings +``` + +### Step 4: Add Configuration to `config.yml` + +```yaml +analysis: + # For file analysis tools + static: + my_tool: + enabled: true + tool_path: /path/to/tool + command: "{tool_path} -f {file_path}" + timeout: 300 + + # For process analysis tools + dynamic: + my_tool: + enabled: true + tool_path: /path/to/tool + command: "{tool_path} --pid {pid}" + timeout: 300 +``` + +### Step 5: Register Your Analyzer + +In `manager.py`: + +```python +def _initialize_analyzers(self): + # For file analysis + if self.config['analysis']['static']['my_tool']['enabled']: + self.static_analyzers['my_tool'] = MyFileAnalyzer(self.config) + + # For process analysis + if self.config['analysis']['dynamic']['my_tool']['enabled']: + self.dynamic_analyzers['my_tool'] = MyProcessAnalyzer(self.config) +``` + +--- + +## Adding Web UI Components + +### Add Your Analyzer Tab in `results.html` + +```html + +{% if analysis_type == 'static' %} + +
+
+
+
+ + +{% else %} + +
+
+
+
+{% endif %} +``` + +### Create Your Renderer in `results.js` + +```javascript +tools.my_tool = { + element: document.getElementById('myToolResults'), + statsElement: document.getElementById('myToolStats'), + render: (results) => { + if (results.status === 'error') { + tools.my_tool.element.innerHTML = ` +
+
+ + + + ${results.error} +
+
`; + return; + } + + const findings = results.findings; + const isClean = findings.total_detections === 0; + + tools.my_tool.statsElement.innerHTML = ` +
+
+
Status
+
+ ${isClean ? 'Clean' : 'Suspicious'} +
+
+ +
`; + + let html = ''; + if (isClean) { + html = ` +
+ + + + No threats detected +
`; + } else { + html = `
+ ${findings.detections.map(finding => ` + + `).join('')} +
`; + } + + tools.my_tool.element.innerHTML = html; + } +} +``` + +--- + +Now your analyzer's results will be displayed in the web interface following LitterBox's UI pattern! The UI components include: + +- **Tab button** to access your results +- **Stats cards** showing an overview +- **Clean/Suspicious status** indicators +- **Detailed findings display** +- **Error handling**