agentic-malware-analysis packages a Kali-based Docker lab with 50+ RE tools, MCP-connected disassemblers, and an AI orchestrator skill that turns a raw binary into ranked evidence and hypotheses for authorized malware analysts.
| Tool | mrphrazer/agentic-malware-analysis — AI-agent-driven malware triage and reverse engineering environment with MCP disassembler backends |
| Category | Automated malware analysis / reverse engineering orchestration |
| Primary Use | Automating repetitive triage of suspicious binaries in a lab: hashing, YARA, capa, strings, imports, then MCP-driven disassembly of PE, ELF, and Mach-O samples |
| Safe Use | For authorized malware analysts, CERT/CSIRT teams, and defensive researchers working on samples inside an isolated Docker lab on systems they control |
| Telemetry Note | Purely a passive static-analysis pipeline; all results land in a per-sample case directory under status/, making analyst activity fully auditable on the host it runs on |
agentic-malware-analysis is a fascinating entry in the growing field of agent-driven security tooling, because rather than bolting an LLM onto a single scanner, it builds an entire analysis pipeline around one. The repository ships a Kali Linux Docker image preloaded with more than fifty reverse engineering and malware analysis tools, and pairs that environment with MCP-connected disassembler backends — either Binary Ninja via binary-ninja-headless-mcp or Ghidra via ghidra-headless-mcp. On top of that sits a structured multi-phase orchestrator skill, malware-analysis-orchestrator, designed for Claude Code and Codex CLI, that walks a raw binary from intake through fingerprinting, signal ranking, hypothesis generation, component modeling, and finally a prioritized deep-analysis plan. The explicit goal is to remove the human from the routine portion of initial triage while producing an evidence-backed starting point for follow-up work.
The motivation section of the README is honest about what this actually automates. Initial malware analysis is a checklist: collect hashes and compiler artifacts, extract strings, inspect imports, run YARA and capa, correlate the results, and flag code regions worth closer inspection. None of this is intellectually hard; it is repetitive and time-consuming, which makes it exactly the kind of work an agent with shell access and a structured workflow can absorb. The orchestrator collects and organizes artifacts, highlights relevant signals, generates hypotheses tied to evidence, builds a component model, and prepares a ranked deep-analysis plan. The framing matters here: the output is described as a structured starting point rather than a finished report, which is a realistic assessment of where agentic analysis currently sits.
Architecturally, the most interesting decision is the externalized case directory. Every analysis creates a persistent per-sample directory at status/<NNN>-<filename>/ containing thirteen required artifact files, from 00_sample_profile.md with hashes and YARA/capa results, through 05_behavior_hypotheses.md and 07_interaction_model.md, down to 10_reporting_draft.md and a machine-readable CURRENT_STATE.json tracking phase progress. The README states the purpose plainly: this design makes the workflow resilient to context-window compaction, because the agent re-reads case files from disk instead of depending on conversation history. That is a mature engineering choice — anyone who has watched an LLM-driven analysis silently degrade over a long session will recognize why persisted state beats conversational memory.
The workflow itself is staged across eight phases. Intake and fingerprinting computes hashes, detects file type and packers, and runs YARA and capa scans. Raw string collection combines strings, rabin2, and floss with source tags so every extracted string is attributable to a tool. Import collection is format-aware, handling PE, ELF, and Mach-O binaries. Then the pipeline shifts from collection to reasoning: rank_signals.py scores strings and imports by capability relevance, build_hypothesis.py generates baseline behavior hypotheses with confidence levels, and subsequent phases infer a component inventory, model data and control flow between components, and finally produce an ordered deep-analysis task list with target functions, expected findings, and stop criteria. Reporting closes the loop with an executive summary, technical findings, IOCs, and open questions.
The bundled toolchain reads like a curated triage kit. Fingerprinting is handled by file, sha256sum, ssdeep, die/diec, yara, and capa. String extraction uses FLARE's floss alongside strings and rabin2. Disassembly and general binary work includes radare2, binwalk, gdb, objdump, readelf, nm, patchelf, and Python bindings for capstone. Dynamic-analysis primitives like strace, ltrace, and qemu-user are present, as are unpacking tools upx, unblob, and ropper, plus a full build toolchain and Node.js 22 for the agent CLIs themselves. The heavy lifting on actual disassembly is delegated over MCP: if a binaryninja.zip is placed in the repository root, the environment installs Binary Ninja headless with its MCP server; otherwise it falls back to Ghidra with pyghidra. The README is candid that Binary Ninja produces substantially better results, which matches general experience with its headless API.
YARA coverage comes from four rule sets bundled from the Yara-Rules/rules project under GPL-2.0: crypto_signatures.yar for cryptographic constants, antidebug_antivm.yar for evasion techniques, capabilities.yar for malicious capability detection, and packer_compiler_signatures.yar for packer identification. Bundling these rather than requiring the analyst to fetch them means the container is self-sufficient at first run, and the scan_yara.sh and scan_capa.sh helper scripts make the scans reproducible parts of the case record rather than ad hoc shell invocations an agent might improvise. The helper script table is worth reading as a design document in itself: init_status_tree.sh, collect_strings.sh, collect_imports.sh, rank_signals.py, update_state.py, and resolve_case.sh together encode the entire mechanical skeleton of the workflow, with the LLM orchestrator coordinating them.
Setup is a single script: ./run_docker.sh after cloning the repository. The script prepares a Docker Buildx builder, installs the selected disassembler backend, clones the MCP server repo into mcp/, builds or reuses a content-hash-cached image, seeds credentials, and launches the container with the working directory mounted at /agent. Inside, the analyst runs claude or codex and invokes the orchestrator skill against a sample. The README thoughtfully includes a password-protected example archive under examples/ so the pipeline can be exercised end-to-end on a documented sample before pointing it at anything live — a good sign that the author expects this to be used as a learning and evaluation harness, not just a production triage box.
There are operational caveats a professional should internalize before running this anywhere. The README's own warning is explicit: run_docker.sh mounts the current working directory into the container at /agent, and the agent wrappers launch with --dangerously-skip-permissions or --dangerously-bypass-approvals-and-sandbox, meaning the agent can read, write, and execute anything in that directory without human gating. The recommended mitigation is to clone into a dedicated directory containing only files the agent should touch. The container also runs with SYS_PTRACE and seccomp=unconfined to support debugging and dynamic analysis. This combination is defensible inside an isolated analysis VM, but it is a reminder that you are granting an LLM broad execution rights over a directory — treat the containment boundary seriously.
Credential and license handling shows attention to operational practicality. The Binary Ninja license.dat is copied from ~/.binaryninja/ into a separate ~/.binaryninja-docker/ directory that is mounted into the container, and deliberately never baked into the image. Claude and Codex authentication state persists across container rebuilds via mounted directories at ~/.claude-docker/ and ~/.codex-docker/, seeded from existing host credentials on first run. Environment variables like BINARY_NINJA_ZIP, CLAUDE_USER_DIR, and CODEX_USER_DIR let you redirect all of these paths, and BINJA_MCP_REPO_URL/GHIDRA_MCP_REPO_URL allow pinning or replacing the MCP server sources — useful for supply-chain hygiene if you want to vendor the backends yourself.
From a defensive-research perspective, where this fits is the tedious first hour of a malware investigation. Analysts at CERTs, sandboxes, and vendor research teams spend disproportionate time on the mechanical triage this automates, and the output format — ranked signals, confidence-scored hypotheses, component maps, and a prioritized function-level work plan tied to concrete code locations via cross-references from the disassembler — maps cleanly onto how a human analyst would structure a report anyway. The evidence-tagging discipline (every hypothesis must carry evidence, every deep-analysis task names target functions and stop criteria) is what separates this from the common failure mode of LLM analysis: confident narrative untethered from the binary.
The project carries a GPL-2.0 license, sits at a respectable 314 stars, and lists YARA as its primary language, reflecting the bundled rule sets. The author points to a companion blog post covering background, a case study, and evaluation, which suggests the pipeline has been exercised against real samples rather than existing only as scaffolding. For teams evaluating agentic tooling, this repository is also valuable as a reference architecture: the combination of externalized case state, scripted mechanical phases, MCP-mediated disassembly, and an orchestrator that only reasons over collected artifacts is a clean pattern applicable well beyond malware analysis. Anyone building similar agent workflows — in authorized testing, code review, or incident response — could do worse than study how the case directory and CURRENT_STATE.json design survives context limits.
mrphrazer/agentic-malware-analysis.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.