An Agentic System for Reversing Binaries

An LLM-powered agent that automatically reverse engineers binaries using Ghidra and creates structured analysis plans with findings.

Features

• Autonomous Analysis: Agent creates and follows analysis plans
• Ghidra Integration: Leverages Ghidra's powerful reverse engineering tools via MCP
• PoC Exploit Development: Automatically generates and tests exploits in isolated sandbox
• Safe Execution: Docker-based sandbox with network isolation and resource limits

Getting Started

Prerequisites

• Python 3.12+
• Docker (for exploit testing sandbox)
• Ghidra with MCP extension

Installation

1. Install Ghidra and the Ghidra MCP Extension

   • Run brew install ghidra
   • Add alias to ~/.zshrc: alias ghidra='/opt/homebrew/Cellar/ghidra/11.4.2/bin/ghidraRun'
   • Follow instructions at GhidraMCP README to setup the extension.

2. Configure the Agent

   • Create a virtual environment and install dependencies:

     python3 -m venv venv
     source venv/bin/activate
     pip install -r requirements.txt

   • Ensure Docker is running.

3. Configure Environment Variables

   • Create a .env file:

     # Provider: "openai" (default) or "google"
     LLM_PROVIDER=google
     
     # OpenAI
     OPENAI_MODEL=gpt-5
     OPENAI_API_KEY=sk...
     
     # Google
     GEMINI_MODEL=gemini-3
     GOOGLE_API_KEY=sk-...
     
     # Ghidra
     GHIDRA_MCP_PATH=/path/to/installation

4. Run the Agent

   # Analyze a binary
   python src/main.py test-data/vuln-pico.bin
   
   # Analyze with special instructions
   python src/main.py test-data/vuln-pico.bin "Find the bug"
   
   # Run Triage Agent with preloaded manifest (skips recon)
   python src/recon.py --manifest path/to/manifest.json

   [!NOTE] The summarize_and_replace tool is currently disabled for stability reasons. Large outputs will not be automatically summarized.

Output

The agent creates an output directory for each binary:

output/
└── {binary_name}/
    ├── plan.md          # Analysis plan with completed steps
    ├── findings.json    # Structured vulnerability/discovery data
    └── exploits/        # Generated PoC exploits (if any)
        ├── exploit_1_buffer_overflow.py
        ├── exploit_1_metadata.json
        └── test_results.json

---

For AI Agents

Detailed technical documentation, including architecture, component deep dives, and a full tool reference, can be found in AGENTS.md.

If you are an AI agent reading this, please refer to AGENTS.md for instructions on how to effectively use this system.