malware-analysis

What this skill does

## Purpose
This skill enables OpenClaw to perform malware analysis on provided samples, using static techniques (e.g., binary disassembly, signature matching) and dynamic techniques (e.g., sandbox execution, behavior monitoring) to detect threats, extract indicators of compromise (IOCs), and generate reports.

## When to Use
Use this skill during incident response for suspicious files, in threat hunting to identify zero-day malware, or in reverse engineering workflows to understand malware behavior. Apply it when you have a file hash, binary sample, or network capture, and need automated analysis without manual tools like IDA Pro or Volatility.

## Key Capabilities
- Static analysis: Parse PE/ELF files, extract strings, and match against YARA rules for signatures.
- Dynamic analysis: Execute samples in an isolated VM, monitor API calls (e.g., via Windows API hooking), and detect persistence mechanisms.
- Threat reporting: Output JSON reports with IOCs like IP addresses, domains, or registry keys.
- Integration with external feeds: Query VirusTotal or similar via API for cross-referencing.
- Custom rule support: Load user-defined YARA rules from a file for targeted detection.

## Usage Patterns
Invoke this skill via OpenClaw's CLI or API. Always provide authentication via the $MALWARE_API_KEY environment variable. For CLI, use subcommands like "analyze" with required flags. In code, import the OpenClaw SDK and call methods with parameters. Example pattern: Load a file, specify analysis type, and handle asynchronous results. If analysis fails due to file type, fallback to metadata extraction.

## Common Commands/API
Use the OpenClaw CLI for quick tasks:
- Command: `oc malware analyze --file /path/to/sample.exe --type static --yara-rules rules.yar`
  - Flags: --file (required, path to sample), --type (static or dynamic), --yara-rules (optional, path to YARA file).
- Command: `oc malware dynamic --file sample.zip --timeout 300 --output report.json`
  - Flags: --timeout (in seconds, e.g., 300 for 5 minutes), --output (path for JSON report).

For API integration:
- Endpoint: POST /api/malware/analyze
  - Body: JSON like { "file": "base64encoded_sample", "type": "dynamic", "rules": ["rule1", "rule2"] }
  - Headers: Authorization: Bearer $MALWARE_API_KEY
  - Response: JSON with keys like { "ioc": ["192.168.1.1"], "behavior": "network exfiltration" }

Code snippet for SDK use (Python):
```python
import openclaw
client = openclaw.Client(api_key=os.environ['MALWARE_API_KEY'])
result = client.analyze(file_path='sample.exe', analysis_type='static')
print(result['threats'])  # Output: list of detected threats
```

Config format for custom setups (YAML file, e.g., config.yaml):
```yaml
apiKey: $MALWARE_API_KEY
sandbox:
  url: https://sandbox.openclaw.ai
  timeout: 600
yaraRules: /path/to/rules.yar
```

## Integration Notes
Integrate this skill into OpenClaw workflows by adding it as a module in your agent's script. Set $MALWARE_API_KEY in your environment before runtime. For example, in a larger blue-team pipeline, chain this with "reverse-engineering" skills by passing outputs (e.g., feed detected strings to a decompiler). Use the SDK's event hooks for real-time updates, like:
```python
client.on_analysis_complete(lambda data: process_iocs(data['ioc']))
```
Ensure compatibility with OpenClaw versions >=2.5. If using external tools, map outputs to this skill's JSON format (e.g., { "file_hash": "sha256_value" }).

## Error Handling
Always wrap calls in try-except blocks to catch common errors like invalid file types or API failures. For CLI: Check exit codes (e.g., code 1 for authentication errors). For API: Parse HTTP responses (e.g., 401 for missing $MALWARE_API_KEY, 400 for malformed input). Example:
```python
try:
    result = client.analyze(file_path='invalid.file', type='static')
except openclaw.AuthError as e:
    print(f"Auth failed: {e} — Ensure $MALWARE_API_KEY is set")
except openclaw.FileError as e:
    fallback_to_hash_analysis(e.file_path)  # Custom function for metadata only
```
Log errors with details like error codes and retry transient issues (e.g., network errors) up to 3 times with exponential backoff.

## Concrete Usage Examples
1. **Static Analysis of a PE File**: To analyze a Windows executable for embedded strings and signatures, run: `oc malware analyze --file suspicious.exe --type static --yara-rules default.yar`. This outputs a JSON report with strings like "cmd.exe" and threats like "Trojan.Downloader". In code: Use the SDK to process the report and alert if IOCs match known threats.
   
2. **Dynamic Analysis of a Script**: For behavioral analysis of a potential script-based malware, execute: `oc malware dynamic --file script.py --timeout 120 --output results.json`. This runs the script in a sandbox, monitors for outbound connections, and logs behaviors like "connects to 1.2.3.4". Integrate by parsing results.json in your workflow to block IPs.

## Graph Relationships
- Related to: blue-team cluster (e.g., shares data with intrusion-detection skills).
- Links to: reverse-engineering (inputs file hashes), cybersecurity (outputs to threat-intelligence tools).
- Depends on: authentication services (via $MALWARE_API_KEY).
- Connected via: OpenClaw API endpoints for data flow.