malware-analysis-orchestrator

name

malware-analysis-orchestrator

description

Structured malware triage and reverse-engineering orchestration for PE, ELF, and Mach-O binaries with strict artifact dumping to a status folder. Use when requests involve malware sample analysis, strings triage, API/import analysis, behavioral hypothesis generation, component mapping, deep-analysis planning, Binary Ninja MCP usage, Ghidra MCP usage, or role-based orchestration (orchestrator/planner/reporter) with complete intermediate outputs.

Malware Analysis Orchestrator

Overview

Execute a static-first malware workflow for PE, ELF, and Mach-O samples and always write detailed intermediate artifacts to a per-sample case directory under status/.

Case Directory Convention

Each analysis gets a case directory at status/<NNN>-<filename>, e.g. status/000-malware.bin. When the same sample is analyzed again, the existing case is reused. To force a fresh case (e.g. after re-packing or for a second opinion), pass --new to init_status_tree.sh, which increments the number: status/001-malware.bin.

Supported binary formats:

1. PE (Windows) -- .exe, .dll, .sys
2. ELF (Linux) -- executables, shared objects, kernel modules
3. Mach-O (macOS) -- executables, dylibs, bundles

Use role-separated execution:

1. Orchestrator role: drive phases, enforce artifact completeness, schedule parallel collection.
2. Planning role: refine investigation priorities from intermediate evidence.
3. Reporting role: produce high-level and technical summaries with traceable evidence.

Load these references before execution:

1. references/workflow.md
2. references/artifact-spec.md
3. references/agent-roles.md
4. references/interesting-signals.md
5. references/deep-analysis-checklist.md

Codex-Specific Guidance

Codex reasons about evidence directly instead of delegating all thinking to scripts.

• Scripts are data-collection helpers. They extract raw strings, imports, and metadata. They produce baseline rankings and template hypotheses.
• Codex does hypothesis generation, planning, and reporting natively. After scripts run, read their output and apply your own reasoning. Correlate evidence across artifacts, generate richer hypotheses, and write deeper analysis than the script templates provide.
• build_hypothesis.py is optional. It produces baseline hypotheses as a starting point. Codex should refine, extend, or replace them with contextual reasoning grounded in the collected evidence.
• Format detection is automatic. Scripts use the file command to detect PE/ELF/Mach-O and branch accordingly. The --format flag can override auto-detection.
• Case directories are automatic. init_status_tree.sh creates and prints the case directory path. Subsequent scripts resolve the latest case for a sample automatically, or accept an explicit case_dir argument.

Required Rules

1. Run init_status_tree.sh <sample> to create the case directory before analysis.
2. Use the printed case directory path for all subsequent --status-dir arguments.
3. Dump all intermediate outputs, not just summaries.
4. Keep raw artifacts and interpreted artifacts separate.
5. Include evidence references in every conclusion.
6. If a tool is missing, use the documented fallback and record the gap in <case_dir>/INDEX.md.
7. Do not skip required artifact files listed in references/artifact-spec.md.

Quick Start

Run these scripts in order:

# Step 1: create (or reuse) the case directory
CASE_DIR=$(scripts/init_status_tree.sh <sample_path> | tail -1 | awk '{print $NF}')

# Step 2: collect raw data (auto-resolves case dir, or pass explicitly)
scripts/collect_strings.sh <sample_path>
scripts/collect_imports.sh <sample_path>
scripts/scan_yara.sh <sample_path>
scripts/scan_capa.sh <sample_path>

# Step 3: rank and hypothesize
python3 scripts/rank_signals.py --status-dir "$CASE_DIR"
python3 scripts/build_hypothesis.py --status-dir "$CASE_DIR"   # optional baseline
python3 scripts/update_state.py --status-dir "$CASE_DIR" --phase triage_complete

To force a new case for the same sample: scripts/init_status_tree.sh <sample_path> --new

After quick start, perform deep-analysis planning using references/deep-analysis-checklist.md and write:

1. <case_dir>/06_component_inventory.md
2. <case_dir>/07_interaction_model.md
3. <case_dir>/08_deep_analysis_plan.md
4. <case_dir>/09_priority_queue.md
5. <case_dir>/10_reporting_draft.md

Then update state:

python3 scripts/update_state.py --status-dir "$CASE_DIR" --phase planning_complete

Workflow Decision Tree

1. Detect binary format using file command output.
2. If format is PE: use PE-specific tooling and signal rules.
3. If format is ELF: use ELF-specific tooling (readelf, nm) and signal rules.
4. If format is Mach-O: use rabin2 for metadata and imports, apply Mach-O signal rules.
5. If format is unrecognized: record unsupported format in profile and attempt generic strings/entropy analysis.
6. If imports are packed/obfuscated: continue with strings and static structure, then prioritize unpacking in deep plan.
7. If clear C2, persistence, or kernel indicators are present: raise priority and move them to top of <case_dir>/09_priority_queue.md.
8. If capa is available and format is PE or ELF: run capa scan for ATT&CK-mapped capability identification.
9. If Binary Ninja MCP or Ghidra MCP is available (prefer Binary Ninja MCP; fall back to Ghidra MCP; fall back to r2): include disassembly/decompilation artifacts and xref tables.

Tooling and Fallbacks

All tools below are installed in the analysis environment (Kali Linux).

Fingerprinting and Profiling

1. file -- format detection
2. sha256sum, md5sum -- cryptographic hashes
3. ssdeep -- fuzzy hashing
4. die / diec (detect-it-easy) -- packer, compiler, linker detection
5. rabin2 -I -- binary metadata (universal, all formats)
6. r2 /ca -- crypto constant / expanded key detection (AES, SM4)
7. yara + bundled rules (scan_yara.sh) -- automated detection of:
   • Crypto algorithms and constants (124 rules)
   • Anti-debug and anti-VM techniques (64 rules)
   • Malicious capabilities (55 rules)
   • Packer/compiler signatures (36 rules) Rules sourced from Yara-Rules/rules (GPL-2.0), stored in assets/yara_rules/.
8. capa (Mandiant) -- automated capability identification mapped to MITRE ATT&CK and MBC. Supports PE and ELF. Raw JSON saved to tool-logs/capa.json, summary appended to profile.

String Extraction

1. strings -a -- raw ASCII/Unicode
2. rabin2 -zz -- section-aware strings
3. floss (FLARE) -- stack and decoded strings

Import / Symbol Collection

1. rabin2 -i -- imports (universal, all formats)
2. rabin2 -l -- linked libraries (universal)
3. PE: objdump -p (DLL name + symbol parsing)
4. ELF: readelf --dyn-syms, readelf -d, nm -D
5. Mach-O: rabin2 -i and rabin2 -l (primary; no otool in this environment)

Disassembly and Decompilation

1. Binary Ninja MCP server -- primary tool for disassembly, decompilation, xrefs, patching, scripting, and more. Interact via MCP tool calls (tool prefix mcp__binary_ninja_headless_mcp__*, derived from the binary_ninja_headless_mcp key in .mcp.json), NOT by importing the Python API directly (import binaryninja).
2. Ghidra MCP server -- secondary tool for disassembly, decompilation, xrefs, patching, scripting, and more. Interact via MCP tool calls (tool prefix mcp__ghidra_headless_mcp__*, derived from the ghidra_headless_mcp key in .mcp.json), NOT by importing pyghidra directly. Use when Binary Ninja MCP is unavailable.
3. r2 (radare2 CLI) -- fallback disassembly and scripted analysis when neither Binary Ninja MCP nor Ghidra MCP is available

Deep Analysis Tools (available for manual/scripted use)

1. binwalk -- entropy analysis, embedded file detection
2. xxd -- hex dumps
3. gdb / gdb-multiarch -- dynamic debugging
4. strace, ltrace -- syscall/library call tracing
5. capstone (Python) -- programmatic disassembly
6. ropper -- gadget finding
7. unblob -- recursive extraction
8. upx -- UPX unpacking
9. qemu-user -- cross-architecture emulation
10. yq, jq -- structured data processing

Fallback Order

1. Strings: strings -> rabin2 -zz -> floss -> note missing source.
2. Imports: rabin2 -i -> format-specific tools -> note missing source.
3. Metadata: rabin2 -I -> readelf -h (ELF) / objdump -f (PE) -> note gap.
4. Disassembly: Binary Ninja MCP -> Ghidra MCP -> r2.
5. Capability detection: capa -> YARA capabilities rules -> manual string/API analysis -> note gap.

Role-Oriented Execution Model

Orchestrator

1. Initialize case directory and sample profile.
2. Run independent collection in parallel where possible.
3. Gate phase progression on artifact completeness.
4. Hand off to planner when triage artifacts are present.

Planner

1. Consume strings/API signal outputs.
2. Build behavior hypotheses with confidence and evidence.
3. Define component-focused deep-analysis sequence.
4. Update priority queue after each new intermediate result.

Reporter

1. Build high-level overview for analysts.
2. Build technical drill-down with evidence pointers.
3. Capture open questions, unknowns, and next probes.

Artifact Discipline

Follow references/artifact-spec.md exactly.

Minimum required artifacts (all relative to the case directory):

1. 00_sample_profile.md
2. 01_strings_raw.txt
3. 02_strings_interesting.md
4. 03_imports_raw.txt
5. 04_imports_interesting.md
6. 05_behavior_hypotheses.md
7. 06_component_inventory.md
8. 07_interaction_model.md
9. 08_deep_analysis_plan.md
10. 09_priority_queue.md
11. 10_reporting_draft.md
12. INDEX.md
13. CURRENT_STATE.json

Binary Ninja MCP Guidance

Use Binary Ninja exclusively through its MCP server. Do NOT use import binaryninja directly. The MCP server exposes capabilities as tool calls that Codex can invoke directly, including:

• Disassembly and decompilation (HLIL/MLIL/LLIL)
• Cross-references (API xrefs, string xrefs, call graphs)
• Patching (binary modification, NOP-ing, instruction replacement)
• Scripting (run Binary Ninja Python snippets server-side for complex or custom analysis)
• Type and structure recovery
• Symbol and annotation management

If the Binary Ninja MCP server is available, include these artifacts under subdirectories of the case directory:

1. disassembly/ for function disassembly.
2. decompilation/ for HLIL/MLIL outputs.
3. xrefs/ for API and string cross-references.
4. patches/ for any binary patches applied during analysis.

Capture only high-value functions first:

1. Entry point and initialization chain.
2. Persistence and service management functions.
3. Network connect/send/recv and protocol handlers.
4. Process injection and memory manipulation functions.
5. Kernel/device communication and IOCTL handlers.

Ghidra MCP Guidance

Use Ghidra exclusively through its MCP server. Do NOT use import pyghidra directly. The MCP tool prefix is mcp__ghidra_headless_mcp__*. The MCP server exposes capabilities as tool calls that Codex can invoke directly, including:

• Disassembly and decompilation (C-like output, P-code)
• Cross-references (API xrefs, string xrefs, call graphs)
• Patching (binary modification, NOP-ing, instruction replacement, branch inversion)
• Scripting (run Ghidra scripts server-side via ghidra_eval, ghidra_call, and ghidra_script for complex or custom analysis)
• Type and structure recovery (struct creation, enum definition, C type parsing)
• Symbol and annotation management (labels, comments, bookmarks, tags)
• Graph extraction (basic blocks, CFG edges, call paths)

If the Ghidra MCP server is available (and Binary Ninja MCP is not), include these artifacts under subdirectories of the case directory:

1. disassembly/ for function disassembly.
2. decompilation/ for decompiler outputs.
3. xrefs/ for API and string cross-references.
4. patches/ for any binary patches applied during analysis.

Capture only high-value functions first:

1. Entry point and initialization chain.
2. Persistence and service management functions.
3. Network connect/send/recv and protocol handlers.
4. Process injection and memory manipulation functions.
5. Kernel/device communication and IOCTL handlers.

Completion Criteria

Declare analysis complete only when:

1. All required artifacts exist and are updated.
2. Hypotheses include confidence scores and evidence.
3. Deep-analysis plan has ordered steps and expected outputs.
4. Reporting draft contains both executive overview and technical map.

Expected Deliverable Style

1. Keep claims falsifiable and evidence-linked.
2. Distinguish observed facts from inferred hypotheses.
3. Track uncertainties explicitly.
4. Keep artifacts machine-parsable where practical.