agentic-malware-analysis - Agentic malware analysis environment with MCP-conn

项目说明

Agentic Malware Analysis

Automated deep malware reverse engineering driven by AI agents. A Kali-based Docker en pairs 50+ RE tools with MCP-connected disassembler backends ([Binary Ninja][binary-ninja-headless-mcp] or [Ghidra][ghidra-headless-mcp]) and a structured multi-phase orchestrator skill that turns a raw binary into a case directory of ranked e, hypotheses, component maps, and a prioritized deep-analysis plan -- with no human interaction required. Ready for [Claude Code][claude-code] and [Codex CLI][codex-cli].

See the companion blog post [Building a Pipeline for Agentic Malware Analysis][blog-post] for background, a case study, and e.

Why

Initial malware analysis in a number of routine steps: collecting hashes and compiler artifacts, extracting strings, inspecting imports, running YARA and capa, correlating the results, and identifying code areas for closer inspection. These steps provide the basis for deeper analysis, but they are often repetitive and time-consuming.

This repository automates much of that workflow. The orchestrator skill collects and organizes analysis artifacts, highlights relevant signals, generates e hypotheses, builds a basic component model, and prepares a prioritized deep-analysis plan. All intermediate results are stored in a per-sample case directory on disk, making the workflow easier to resume and review.

Via MCP, the agent can also use Binary Ninja or Ghidra to inspect functions, follow cross-references, and tie findings to concrete code locations. The result is a structured starting point for follow-up analysis rather than ad hoc triage alone.

Features

Prerequisites

Quick Start

> Important: run_docker.sh mounts your current working directory into the container at /agent. The agent wrappers run with full permissions (--dangerously-skip-permissions / --dangerously-bypass-appro) by design, so the agent can read, write, and execute anything in that directory. Clone the repository into a dedicated directory and place only the files you want the agent to access there.

What happens:

1. Prepares a Docker Buildx builder
2. If binaryninja.zip is present, Binary Ninja and its MCP server are installed; otherwise Ghidra and its MCP server are installed as a fallback
3. Clones the selected MCP server repo into mcp/
4. Builds the image (or reuses a cached one based on content hash)
5. Seeds BN license, Claude credentials, and Codex credentials from host directories
6. Launches the container with the current directory mounted at /agent

Inside the container:

Extract the included example sample and start an analysis with the orchestrator skill:

Then prompt the agent:

See examples/README.md for sample details and background.

Setup

Binary Ninja (recommended)

Binary Ninja provides substantially better analysis results than Ghidra through its [headless MCP server][binary-ninja-headless-mcp] and is the recommended disassembler backend. If no Binary Ninja zip is present, the en falls back to Ghidra automatically.

To use Binary Ninja, place your Linux headless zip in the repository root before running run_docker.sh:

The file must be named binaryninja.zip. Alternatively, point to it explicitly:

Binary Ninja requires a valid license.dat. On first run, run_docker.sh copies your existing license from ~/.binaryninja/license.dat into a Docker-specific directory (~/.binaryninja-docker/) that is mounted into the container at /home/agent/.binaryninja. The license is ne into the image. To use a different host directory:

Claude Code Authentication

run_docker.sh maintains a persistent Claude state directory at ~/.claude-docker/ on the host, mounted into the container at /home/agent/.claude. On first run, it seeds credentials from ~/.claude/.credentials.json if a. You can also log in inside the container with claude auth; credentials persist across container rebuilds in the mounted directory. To use a different host directory:

Codex CLI Authentication

run_docker.sh maintains a persistent Codex state directory at ~/.codex-docker/ on the host, mounted into the container at /home/agent/.codex. On first run, it seeds credentials from ~/.codex/auth.json if a. You can also log in inside the container with codex login; credentials persist across container rebuilds in the mounted directory. To use a different host directory:

Docker En

Installed Tooling

Fingerprinting: file, sha256sum, md5sum, ssdeep, die/diec, yara, capa

String extraction: strings, floss (FLARE-FLOSS), rabin2

Disassembly and analysis: radare2, binwalk, gdb/gdb-multiarch, capstone (Python)

Binary utilities: objdump, readelf, nm, patchelf, elfutils

Hex editors: hexedit, bvi, xxd, ht, hexwalk

Dynamic analysis: strace, ltrace, qemu-user

Build tools: gcc, g++, clang, lldb, lld, llvm, cmake, nasm

Python: Python 3, pip, venv, ipython, ipdb, uv

Data processing: jq, yq

Extraction: upx, unblob, ropper

Node.js: Node.js 22

Agent CLIs: Claude Code, Codex CLI

Conditional: Binary Ninja headless + Python API (if zip provided) _or_ Ghidra + pyghidra

Runtime Configuration

MCP Integration

The en automatically selects and configures one MCP backend. Binary Ninja is recommended; Ghidra serves as a fallback when no Binary Ninja zip is provided.

The selected repo is cloned at runtime by run_docker.sh into mcp/. On container start, configure-agent-mcp.sh writes the project-scoped .mcp.json (Claude Code) and Codex config with the correct MCP ser.

O the upstream repos:

Malware Analysis Orchestrator

The malware-analysis-orchestrator skill drives a structured, multi-phase malware analysis workflow. It is a for both Claude Code and Codex CLI.

Workflow Stages

1. Intake and fingerprinting -- hashes, file type, packer/compiler detection, YARA scan, capa scan
2. Raw strings collection -- strings, rabin2, floss with source tags
3. Raw API/import collection -- rabin2, format-specific tools (PE/ELF/Mach-O)
4. Signal filtering and ranking -- score and rank interesting strings and imports by capability
5. Hypothesis generation -- cross-link e, generate behavior hypotheses with confidence and e
6. Component in and interaction modeling -- infer components, map data/control flow
7. Deep analysis planning and prioritization -- ordered tasks with target functions, expected findings, stop criteria
8. Reporting -- executi, technical findings, IOCs, open questions

Case Directory

Each analysis creates a persistent per-sample directory at status/<NNN>-<filename>/ containing 13 required artifact files:

| # | File | Content |
|---|------|---------|
| 1 | 00_sample_profile.md | Hashes, file type, packer, YARA, capa results |
| 2 | 01_strings_raw.txt | All extracted strings with source tags |
| 3 | 02_strings_interesting.md | Ranked interesting strings with categories |
| 4 | 03_imports_raw.txt | Full import tables with source tags |
| 5 | 04_imports_interesting.md | Suspicious API clusters by capability |
| 6 | 05_beha.md | Hypotheses with confidence and e |
| 7 | 06_component_in.md | Inferred components with roles and e |
| 8 | 07_interaction_model.md | Data and control flow between components |
| 9 | 08_deep_analysis_plan.md | Ordered deep-analysis tasks |
| 10 | 09_priority_queue.md | Priority queue with rationale and blockers |
| 11 | 10_reporting_draft.md | Executi and technical findings |
| 12 | INDEX.md | Artifact list, timestamps, missing items |
| 13 | CURRENT_STATE.json | Machine-readable phase and progress state |

This externalized state is what makes the workflow resilient to context-window compaction: the agent reads case files back from disk instead of relying on con history.

Helper Scripts

| Script | Purpose |
|--------|---------|
| init_status_tree.sh | Create or reuse a case directory for a sample |
| collect_strings.sh | Run strings, rabin2 -zz, floss and write raw output |
| collect_imports.sh | Run rabin2 -i and format-specific import tools |
| scan_yara.sh | Scan sample with bundled YARA rules |
| scan_capa.sh | Run capa for ATT&CK/MBC capability identification |
| rank_signals.py | Score and rank interesting strings and imports |
| build_hypothesis.py | Generate baseline behavior hypotheses (optional) |
| update_state.py | Update CURRENT_STATE.json with phase transitions |
| resol.sh | Resolve the latest case directory for a sample |

Bundled YARA Rules

Four rule sets from [Yara-Rules/rules][yara-rules] (GPL-2.0):

Roles

Agent Wrappers

Claude Code

Codex CLI

Customization

En

| | Default | Purpose |
|----------|---------|---------|
| BINARY_NINJA_ZIP | ./binaryninja.zip | Path to Binary Ninja Linux zip |
| BINARY_NINJA_USER_DIR | ~/.binaryninja-docker | BN license, settings, and plugins |
| CLAUDE_USER_DIR | ~/.claude-docker | Claude auth and state |
| CODEX_USER_DIR | ~/.codex-docker | Codex auth and state |
| BINJA_MCP_REPO_URL | | Binary Ninja MCP repo |
| GHIDRA_MCP_REPO_URL | | Ghidra MCP repo |

Running Specific Commands

Repository Layout

Note: mcp/ is cloned at runtime and is not part of the repository.

Limitations

Security

Contact

Tim Blazytko ()

[binary-ninja-headless-mcp]:
[ghidra-headless-mcp]:
[claude-code]:
[codex-cli]:
[blog-post]:
[yara-rules]:

项目信息

开发语言：YARA

Star 数：309

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Agentic malware analysis environment with MCP-connected disassemblers, RE tooling, and structured workflows for Claude Code and Codex CLI.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。