How Ghidra Powers Headless Binary Analysis in the reverse-skill Repository

The reverse-skill repository automates Ghidra headless binary analysis through the analyzeHeadless command and an optional ghidra-mcp bridge, enabling batch decompilation and CI/CD integration without GUI dependency.

The reverse-skill project treats Ghidra as its primary open-source reverse-engineering engine when IDA licenses are unavailable or batch processing is required. By encapsulating Ghidra's capabilities into a modular skill system, the framework enables automated binary analysis through both command-line batch operations and programmatic MCP protocol interactions. This architecture allows security researchers to integrate headless decompilation into automated vulnerability discovery pipelines.

Architecture of the Ghidra Integration

Capability Detection via Tool-Index

The framework maintains an auto-generated tool-index (produced by skills/scripts/refresh-tool-index.sh) that tracks Ghidra installation paths and the optional ghidra-mcp bridge status on port 8765. Before executing any analysis, the ghidra-reverse skill queries this index to verify tool availability and retrieve machine-specific paths to the analyzeHeadless binary.

As documented in skills/ghidra-reverse/SKILL.md, the skill checks the tool-index for the presence of ghidra and the MCP bridge during its initialization phase. This ensures that subsequent commands use the correct absolute paths rather than hard-coded locations that might vary across different machines.

Request Routing Configuration

Incoming requests for Ghidra analysis are routed through skills/config/routing.json, specifically the R22 "Ghidra / open-source reverse" entry that directs traffic to the ghidra-reverse skill handler. This routing mechanism ensures that headless analysis requests are processed by the correct skill module defined in skills/ghidra-reverse/SKILL.md.

Headless Analysis Workflow Implementation

Project Setup and Binary Import

According to the skill definition in skills/ghidra-reverse/SKILL.md, the workflow begins with creating a Ghidra project and importing target binaries through the standard actions outlined in the Project & Automatic Analysis section. This step initializes the analysis database that subsequent headless operations will process.

Batch Decompilation with analyzeHeadless

For CI/CD pipelines or bulk processing, the skill invokes Ghidra's analyzeHeadless command using paths dynamically retrieved from the tool-index. The command template specifies project directories, import targets, and post-analysis scripts such as ExportDecomp.py to extract decompiled functions, comments, and cross-references for downstream consumption by tools like ghidriff.

This approach allows the framework to perform unattended analysis on multiple binaries, exporting results in formats suitable for automated diffing or exploitation chain generation.

MCP Protocol Integration

When the ghidra-mcp bridge is available, the skill communicates over the MCP protocol (default port 8765) to request decompilation, cross-references, and other analysis functions without spawning new processes. This method avoids hard-coded ports by referencing the capability-status table in the tool-index, enabling real-time queries against an active Ghidra backend.

The MCP interaction pattern allows skills to programmatically retrieve analysis data while Ghidra runs as a persistent service, reducing the overhead of repeatedly launching the JVM for each analysis task.

Practical Implementation Examples

The following examples demonstrate the headless analysis patterns implemented in the reverse-skill framework.

First, ensure the tool-index knows your Ghidra installation location:

# Generate the tool-index (run once per machine)

bash skills/scripts/refresh-tool-index.sh

# Extract the analyzeHeadless path from the generated index

GHIDRA_HEADLESS=$(grep -i "analyzeHeadless" ~/.tool-index | awk '{print $2}')

# Execute headless analysis on a target binary

$GHIDRA_HEADLESS /tmp/my_project MyProject \
    -import ./sample.bin \
    -postScript ExportDecomp.py \
    -scriptPath ./scripts

If the ghidra-mcp bridge is installed, query analysis results programmatically:

import socket
import json

HOST = "127.0.0.1"
PORT = 8765  # Default MCP port verified via tool-index

def mcp_request(method, params):
    payload = json.dumps({
        "jsonrpc": "2.0",
        "id": 1,
        "method": method,
        "params": params
    })
    with socket.create_connection((HOST, PORT)) as s:
        s.sendall(payload.encode())
        resp = s.recv(4096)
    return json.loads(resp.decode())

# Request decompilation of a specific function

result = mcp_request("decompile", {"address": "0x401000"})
print(result["result"])

Summary

• The tool-index.md auto-generates machine-specific Ghidra paths via refresh-tool-index.sh scripts, eliminating hard-coded dependencies
• The ghidra-reverse skill in skills/ghidra-reverse/SKILL.md defines the complete headless workflow from project creation to result export
• analyzeHeadless commands execute batch decompilation with custom post-scripts like ExportDecomp.py for automated data extraction
• ghidra-mcp bridge integration on port 8765 enables programmatic analysis via JSON-RPC, avoiding CLI overhead for frequent queries
• routing.json handles R22 requests to route Ghidra operations to the appropriate skill handler, maintaining clean separation between routing logic and analysis implementation

Frequently Asked Questions

What is the purpose of the tool-index in reverse-skill?

The tool-index serves as a capability registry that stores per-machine paths to Ghidra installations and tracks whether the ghidra-mcp bridge is available on port 8765. This allows the framework to dynamically adapt commands like analyzeHeadless to specific system configurations without hard-coding absolute paths in the skill definitions.

How does the framework handle Ghidra requests without a GUI?

The framework uses Ghidra's analyzeHeadless command-line interface for batch processing, as defined in the skill's workflow documentation in skills/ghidra-reverse/SKILL.md. This mode executes analysis scripts and exports results programmatically, making it suitable for CI/CD pipelines and automated security testing environments where no display server is available.

What is ghidra-mcp and how does it integrate with the skill?

Ghidra-mcp is an optional bridge that exposes Ghidra's analysis capabilities through the MCP protocol, allowing skills to request decompilation and cross-references via socket communication on port 8765. The skill checks the tool-index for this capability before attempting MCP-based queries, falling back to headless CLI execution if the bridge is unavailable, ensuring robust operation across different installation scenarios.

Where is the Ghidra skill routing configured?

Request routing is defined in skills/config/routing.json under the R22 entry labeled "Ghidra / open-source reverse", which maps incoming analysis requests to the skills/ghidra-reverse/ directory. This configuration ensures that binary analysis tasks are handled by the appropriate skill modules with access to the correct tool-index entries and command templates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}