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

> Discover how Ghidra powers headless binary analysis in the reverse-skill repository using analyzeHeadless and ghidra-mcp for automated decompilation and CI/CD integration without a GUI.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-25

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```bash

# 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:

```python
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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/refresh-tool-index.sh) scripts, eliminating hard-coded dependencies
- The **ghidra-reverse** skill in [`skills/ghidra-reverse/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.