JoasASantos/Malvex

Reverse engineer malware with agents, from packed droppers down to memory-resident payloads.

Malvex is a local-first orchestration harness that connects AI agents to 126 reverse-engineering and malware-analysis tools through MCP (Model Context Protocol). Point it at a binary, a memory dump, a document, or a packet capture. Malvex triages the sample, fans out parallel agents over IDA, Ghidra, radare2, Frida, volatility3, YARA, and dozens of other backends, and returns evidence-grounded findings — IOCs, MITRE ATT&CK mappings, detection rules, and attack-chain graphs — without uploading anything.

Analysis runs locally. Results include the evidence and limitations behind each conclusion.

Important rule: LLM output is not evidence. The model may propose hypotheses, likely function names, algorithm matches, or ATT&CK mappings. Malvex treats those as analyst leads until they are tied to static or runtime evidence.

./setup.sh                           # install Rust + tools + MCP servers + Claude Code
malvex doctor                        # what analysis tools + MCP servers are available
malvex doctor --install              # install missing open-source tools
malvex mcp-setup --install           # wire RE MCP servers into Claude Code
malvex run /path/to/sample --dry-run # print the plan + agent commands (0 tokens)
malvex run /path/to/sample           # full pipeline

Malvex drives analysis through your preferred AI agent. Choose your runtime:

# Claude Code (default)
malvex run sample.exe

# Codex CLI
malvex run sample.exe --runtime codex

# Custom provider (OpenRouter, LiteLLM, etc.)
MALVEX_CUSTOM_CMD="./my-llm-wrapper.sh" malvex run sample.exe --runtime custom

# Hermes (deepseek, qwen, kimi, glm, grok)
malvex run sample.exe --runtime hermes --hermes-provider deepseek --hermes-model deepseek-chat

# Ollama (local, offline / air-gapped)
MALVEX_OLLAMA_MODEL=llama3.1 malvex run sample.exe --runtime ollama

Runtime profiles are documented in config/runtime-profiles.yaml.

sample ──▶ TRIAGE ──▶ STATIC ──▶ DYNAMIC ──▶ NETWORK ──▶ INTELLIGENCE ──▶ VALIDATE ──▶ report

Six stages, each spawning parallel agents. Agents share state through MCP (muster blackboard + claude-mem). No finding reaches confirmed without independent evidence reproduction.

The full pipeline SVG is available in the web UI at /settings.

Malvex can auto-install and wire these MCP servers into your AI agent via malvex mcp-setup --install:

Verify with claude mcp list after setup. Commercial backends (IDA, Binary Ninja) are detected and reported, never auto-installed.

Malvex automatically installs and integrates REA for base reverse engineering capabilities. REA provides:

• Binary analysis: Ghidra, IDA Pro, radare2, Binary Ninja — disassembly, decompilation, function listing, xrefs
• Dynamic analysis: Frida hooking, runtime instrumentation
• .NET: Assembly decompilation and analysis
• Android: APK analysis via JADX/apktool
• Browser/Electron: Web app and Electron inspection

Malvex adds malware-specific layers on top of REA:

• Detection engineering: YARA/Sigma rule generation and validation
• Memory forensics: Volatility3 injection detection, RWX scanning, config extraction
• Sandbox integration: CAPE/Cuckoo automated detonation and behavioral analysis
• Threat intelligence: MISP, VirusTotal, MalwareBazaar, OSINT lookups
• Evidence-driven pipeline: 15 specialized agents with hypothesis-evidence-verification model
• 200+ malware analysis tools: from triage to advanced forensics

malvex setup                    # installs everything including REA
npx rea-agents setup            # or manually configure REA for Claude Code

When REA is available, Malvex agents automatically prefer REA's unified MCP interface for disassembly, decompilation, and cross-reference analysis — falling back to direct tool invocation only when REA is not installed.

malvex serve exposes 30 analysis tools over MCP (JSON-RPC 2.0, stdio transport). Any AI agent — Claude Code, Cursor, Windsurf, Cline, Codex — can connect and use them directly.

# Register with Claude Code
claude mcp add malvex -- malvex serve

# Or run standalone
malvex serve --transport stdio

Each tool automatically selects the best available backend (e.g. malvex_disasm tries radare2, then Ghidra, then IDA) and returns structured output. Tools that require external backends report exactly what to install if missing.

After malvex setup, use these prompts directly in your editor. Malvex runs headless via MCP.

Use Malvex to analyze suspicious.exe — full triage, static RE, and IOC extraction
Use Malvex to decompile the main function of dropper.dll and explain the C2 protocol
Use Malvex to list imports of ransomware.exe and flag crypto API usage
Use Malvex to scan payload.bin with YARA and map findings to MITRE ATT&CK
Use Malvex to triage packed.exe — detect packer, entropy, and embedded strings
Use Malvex to extract IOCs from cobalt_beacon.bin — IPs, domains, URLs, hashes

Use Malvex to extract and analyze VBA macros from invoice.docm
Use Malvex to parse malicious.pdf for embedded JavaScript, /Launch, and /OpenAction
Use Malvex to check report.rtf for embedded OLE objects and shellcode
Use Malvex to triage spreadsheet.xlsm — macros, auto-open, suspicious strings
Use Malvex to analyze phishing.docx for template injection and remote URLs

Use Malvex to analyze memory.dmp — injections, hollowed processes, decrypted config
Use Malvex to analyze traffic.pcap — C2 beaconing, DNS tunneling, exfiltration
Use Malvex to scan memory dump for RWX regions and reflective DLL loading

Use Malvex to run a full analysis pipeline on sample.exe with 3 parallel agents
Use Malvex to plan (dry-run) analysis of installer.msi — show what it would do
Use Malvex to check tool health — what analysis tools and MCPs are available
Use Malvex to list my previous analysis sessions

Use Malvex to hash sample.exe — MD5, SHA1, SHA256, ssdeep, imphash
Use Malvex to run capa on loader.dll and show ATT&CK capabilities
Use Malvex to disassemble function at 0x401000 in backdoor.exe
Use Malvex to extract strings from firmware.bin — URLs, IPs, paths, registry keys

Malvex drives 15 orchestrated agent roles, each with a specific mission and owned vectors:

One agent invokes many skills. See agents/ for the full system prompts.

61 active malware-analysis skills aligned to the MITRE ATT&CK matrix. Each skill is a concrete procedure: which tool to run, what to grep, what pattern proves the vector, and what evidence to return.

See SKILLS.md for the full skill index and usage guide.

Highlights: triage-initial, static-analysis, disassembly-decompilation, packing-obfuscation, debugging, dynamic-analysis, process-memory-analysis, network-analysis, persistence-analysis, credential-data-access, defense-evasion, command-and-control, exfiltration-analysis, anti-analysis, malware-configuration, capability-mapping, ioc-extraction, detection-engineering, threat-intelligence, malware-lineage, ai-assisted-re.

Every session produces in sessions/<id>/:

target.json              identified target (hashes, format, shielding)
findings.json            evidence-backed findings (source of truth)
summary.md               severity tally + finding list
attack-graph.md          chained exploitation paths (mermaid)
attack-graph.json        machine-readable attack graph
session.log              structured log of every event
<stage>-<agent>.out.json raw agent output per stage

Optional (when evidence supports):

• iocs.json — hashes, domains, IPs, URLs, registry keys, mutexes, services, certificates
• detections/yara/ — generated + validated YARA rules
• detections/sigma/ — Sigma detection rules
• memory/ — memory dump artifacts
• pcap/ — captured network traffic

Every conclusion must point to one or more of:

• File offsets, RVA / VA, section names + entropy
• Import/export symbols, strings, decoded strings
• Disassembly or pseudocode loci, xrefs, graph relationships
• Debugger traces, memory artifacts
• Files, registry keys, services, tasks, pipes, mutexes
• DNS / HTTP / TLS observations
• Generated detections (YARA/Sigma with validation results)

The workflow: hypothesis → evidence → verification → confidence.

Similarity is not attribution. ATT&CK mappings, family matches, and lineage are derived outputs — they never substitute for primary evidence.

crates/
  malvex-core           shared types (Target, Finding, Severity, Tool)
  malvex-doctor         tool detection + install + MCP registry
  malvex-orchestrator   pipeline orchestration, execution, parsing, PoC validation
  malvex-cli            `malvex` binary
  malvex-web            web UI (axum upload + session review)
agents/               15 agent system prompts (markdown)
skills/               61 SKILL.md procedures aligned to the malware analysis matrix
vulns/
  taxonomy.yaml       analysis vectors owned by the active agents
  attack-chains.yaml  curated exploitation chains
config/
  headless-tooling.yaml    tool preferences per platform
  runtime-profiles.yaml    agent runtime configurations
tools/
  yara_mcp.py         YARA MCP compatibility shim
plugins/
  ida/                IDA Pro analysis plugins
setup.sh / .ps1 / .bat    environment bootstrap scripts

./setup.sh

Idempotent. Installs (in order): Rust toolchain, open-source RE tools (radare2, Ghidra, YARA, binwalk, mitmproxy, lief, capstone, frida-tools, capa, FLOSS, volatility3, oletools, unicorn, angr), Claude Code CLI, uv/pipx helpers. Then builds malvex, runs malvex setup, and starts malvex-web.

setup.bat

Launches setup.ps1 (elevated). Installs via winget/choco/pip: radare2, rizin, x64dbg, WinDbg, Ghidra, Frida, YARA, lief, 7zip, Claude Code. Builds malvex.exe.

malvex setup and malvex doctor --install auto-detect Kali via /etc/os-release and install a broad apt-based malware-analysis bundle (38 packages) in addition to per-tool installs.

• On macOS, several packages depend on Homebrew and should be run as a non-root user.
• Commercial tools (IDA, Binary Ninja, WinDbg) are detected and reported, never auto-installed.
• Headless tool preferences are in config/headless-tooling.yaml.
• MCP bridges may show as configured before they show as healthy. Backends need their local tool active.

Static reverse engineering is host-independent — IDA (via idalib MCP), Ghidra, radare2, and lief all parse Windows PE from macOS. The full static pipeline runs on a Mac against .exe/.dll/.msi targets. malvex extract unpacks MSI/CAB on macOS.

Dynamic instrumentation runs natively when the host OS matches the target platform. Cross-host, agents emit a concrete needs-<platform>-runtime plan with exact steps, hooks, breakpoints, and expected artifacts — never fabricated evidence.

cargo build --release
cargo test --release -p malvex-orchestrator
./target/release/malvex doctor

Malvex provides tools for lawful malware analysis, reverse-engineering research, and detection engineering. You are responsible for obtaining any required authorization and complying with applicable laws. Analysis runs locally on your machine.

MIT