Ryan Malloy
04f3011413
Some checks are pending
Build Ghidra Plugin / build (push) Waiting to run
- Punchy hero section with terminal-style demo - Feature table showing all 64 tools across 12 categories - Docker quickstart as primary path (easiest) - Clear usage patterns: current instance, Docker workflow, pagination - Concise tool reference grouped by category - Architecture notes explaining AI-agent design decisions - Removed outdated v2.1 references and verbose API examples
303 lines
9.9 KiB
Markdown
303 lines
9.9 KiB
Markdown
# GhydraMCP
|
|
|
|
**AI-native reverse engineering.** Give Claude (or any MCP client) direct access to Ghidra's analysis engine.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ "Analyze the authentication bypass in this firmware" │
|
|
│ │
|
|
│ Claude: I'll decompile the auth functions and trace the validation logic. │
|
|
│ │
|
|
│ [functions_list grep="auth|login|verify"] │
|
|
│ [functions_decompile name="verify_password"] │
|
|
│ [xrefs_list to_addr="0x0040156c"] │
|
|
│ [analysis_get_dataflow address="0x00401234" direction="backward"] │
|
|
│ │
|
|
│ Found it. The password check at 0x401580 compares against a hardcoded │
|
|
│ hash, but there's a debug backdoor at 0x401590 that bypasses validation │
|
|
│ when the username starts with "debug_". Let me show you the call graph... │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
## What You Get
|
|
|
|
**64 MCP tools** across 12 categories:
|
|
|
|
| Category | Tools | What it does |
|
|
|----------|-------|--------------|
|
|
| **Functions** | 11 | Decompile, disassemble, rename, set signatures, list variables |
|
|
| **Data** | 8 | Create/modify data items, list strings, set types |
|
|
| **Structs** | 7 | Create structs, add/update fields, manage data types |
|
|
| **Symbols** | 9 | Create labels, rename symbols, list imports/exports |
|
|
| **Analysis** | 6 | Call graphs, data flow, cross-references, run analysis |
|
|
| **Memory** | 2 | Read/write raw bytes |
|
|
| **Variables** | 4 | List/rename function variables, set types |
|
|
| **Bookmarks** | 3 | Create/list/delete analysis bookmarks |
|
|
| **Enums/Typedefs** | 4 | Create enum and typedef data types |
|
|
| **Namespaces** | 2 | List namespaces and classes |
|
|
| **Segments** | 1 | List memory segments with permissions |
|
|
| **Docker** | 7 | Auto-start containers, health checks, session management |
|
|
|
|
**13 analysis prompts** for common RE workflows:
|
|
- `malware_triage` — Quick capability assessment
|
|
- `identify_crypto` — Find crypto functions and constants
|
|
- `find_authentication` — Locate auth, license checks, credentials
|
|
- `analyze_protocol` — Reverse network/file protocols
|
|
- `trace_data_flow` — Taint analysis through functions
|
|
- And 8 more specialized prompts...
|
|
|
|
**11 MCP resources** for quick enumeration without tool calls.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Docker (Easiest)
|
|
|
|
No Ghidra installation needed. Analyze binaries in isolated containers.
|
|
|
|
```bash
|
|
# Build the image (once)
|
|
cd GhydraMCP && docker build -t ghydramcp:latest -f docker/Dockerfile .
|
|
|
|
# Add to your MCP config
|
|
claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp
|
|
```
|
|
|
|
Then in Claude:
|
|
```
|
|
Analyze /path/to/suspicious.exe
|
|
```
|
|
|
|
Claude will auto-start a container, wait for analysis, and begin work.
|
|
|
|
### Option 2: Native Ghidra
|
|
|
|
1. **Install the Ghidra plugin:**
|
|
- Download latest [release](https://github.com/starsong-consulting/GhydraMCP/releases)
|
|
- In Ghidra: `File → Install Extensions → +` → select the `.zip`
|
|
- Restart Ghidra
|
|
- Enable in `File → Configure → Developer → GhydraMCPPlugin`
|
|
|
|
2. **Add MCP server:**
|
|
```bash
|
|
claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp
|
|
```
|
|
|
|
3. **Open a binary in Ghidra**, then ask Claude to analyze it.
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
```
|
|
┌──────────────┐ MCP ┌──────────────┐ HTTP ┌──────────────┐
|
|
│ Claude │◄────────────►│ GhydraMCP │◄────────────►│ Ghidra │
|
|
│ (or other │ stdio │ (Python) │ REST API │ Plugin │
|
|
│ MCP client) │ │ │ │ (Java) │
|
|
└──────────────┘ └──────────────┘ └──────────────┘
|
|
```
|
|
|
|
- **Ghidra Plugin**: Exposes Ghidra's analysis via HTTP REST API (HATEOAS)
|
|
- **GhydraMCP Server**: Translates MCP tool calls to API requests
|
|
- **Multi-instance**: Analyze multiple binaries simultaneously on different ports
|
|
- **Session isolation**: Docker containers get unique ports, preventing conflicts
|
|
|
|
---
|
|
|
|
## Usage Patterns
|
|
|
|
### Set Current Instance (Then Forget About Ports)
|
|
|
|
```python
|
|
instances_list() # Discover running Ghidra instances
|
|
instances_use(port=8192) # Set as current
|
|
functions_list() # No port needed!
|
|
data_list_strings(grep="password") # Uses current instance
|
|
```
|
|
|
|
### Docker Workflow
|
|
|
|
```python
|
|
# Start container (returns immediately)
|
|
result = docker_auto_start(binary_path="/path/to/malware.exe")
|
|
# → {port: 8195, message: "Poll docker_health(port=8195)..."}
|
|
|
|
# Poll until ready
|
|
while True:
|
|
health = docker_health(port=8195)
|
|
if health["healthy"]:
|
|
break
|
|
# Can check docker_logs() while waiting
|
|
|
|
# Register and use
|
|
instances_use(port=8195)
|
|
functions_list() # Ready to analyze
|
|
```
|
|
|
|
### Cursor-Based Pagination
|
|
|
|
Large binaries can have 100K+ functions. Use cursors:
|
|
|
|
```python
|
|
result = functions_list(page_size=100)
|
|
# → {items: [...], cursor_id: "abc123", has_more: true}
|
|
|
|
# Get next page
|
|
cursor_next(cursor_id="abc123")
|
|
|
|
# Or filter server-side
|
|
functions_list(grep="crypto|encrypt", page_size=50)
|
|
```
|
|
|
|
### Analysis Prompts
|
|
|
|
Built-in prompts for common workflows:
|
|
|
|
```
|
|
/prompt malware_triage
|
|
/prompt identify_crypto
|
|
/prompt find_authentication
|
|
```
|
|
|
|
These guide Claude through systematic analysis with progress reporting.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `GHIDRA_HYDRA_HOST` | `localhost` | Ghidra instance host |
|
|
| `GHIDRA_HYDRA_PORT` | `8192` | Default port |
|
|
|
|
### MCP Config Examples
|
|
|
|
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ghydramcp": {
|
|
"command": "uv",
|
|
"args": ["run", "--directory", "/path/to/GhydraMCP", "ghydramcp"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Claude Code**:
|
|
```bash
|
|
claude mcp add ghydramcp -- uv run --directory /path/to/GhydraMCP ghydramcp
|
|
```
|
|
|
|
---
|
|
|
|
## Tool Reference
|
|
|
|
### Instance Management
|
|
```
|
|
instances_list # Discover Ghidra instances (use this first!)
|
|
instances_use # Set current working instance
|
|
instances_current # Show current instance info
|
|
```
|
|
|
|
### Function Analysis
|
|
```
|
|
functions_list # List functions (supports grep, pagination)
|
|
functions_get # Get function details by name or address
|
|
functions_decompile # Decompile to C pseudocode
|
|
functions_disassemble # Get assembly instructions
|
|
functions_rename # Rename a function
|
|
functions_set_signature # Set function prototype
|
|
functions_set_comment # Add decompiler comment
|
|
functions_create # Create function at address
|
|
functions_variables # List local variables and parameters
|
|
```
|
|
|
|
### Data Operations
|
|
```
|
|
data_list # List defined data items
|
|
data_list_strings # List strings (with grep filtering)
|
|
data_create # Define data at address
|
|
data_rename # Rename data item
|
|
data_set_type # Change data type
|
|
data_delete # Remove data definition
|
|
```
|
|
|
|
### Cross-References & Analysis
|
|
```
|
|
xrefs_list # Find cross-references to/from address
|
|
analysis_get_callgraph # Generate call graph
|
|
analysis_get_dataflow # Trace data flow forward/backward
|
|
analysis_run # Trigger Ghidra auto-analysis
|
|
```
|
|
|
|
### Structs & Types
|
|
```
|
|
structs_list # List struct definitions
|
|
structs_get # Get struct with all fields
|
|
structs_create # Create new struct
|
|
structs_add_field # Add field to struct
|
|
structs_update_field # Modify existing field
|
|
structs_delete # Remove struct
|
|
enums_list / enums_create
|
|
typedefs_list / typedefs_create
|
|
```
|
|
|
|
### Docker Management
|
|
```
|
|
docker_auto_start # Start container for binary (auto port allocation)
|
|
docker_health # Check if container API is responding
|
|
docker_status # List all containers and images
|
|
docker_start # Manual container start
|
|
docker_stop # Stop container (session-scoped)
|
|
docker_logs # Get container logs
|
|
docker_cleanup # Remove orphaned containers
|
|
```
|
|
|
|
See `--help` or the [API docs](GHIDRA_HTTP_API.md) for full parameter details.
|
|
|
|
---
|
|
|
|
## Building from Source
|
|
|
|
```bash
|
|
# Clone
|
|
git clone https://github.com/starsong-consulting/GhydraMCP
|
|
cd GhydraMCP
|
|
|
|
# Build Ghidra plugin
|
|
mvn clean package
|
|
# → target/GhydraMCP-[version].zip
|
|
|
|
# Build Docker image
|
|
docker build -t ghydramcp:latest -f docker/Dockerfile .
|
|
|
|
# Run MCP server (for development)
|
|
uv run ghydramcp
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
GhydraMCP is designed for AI agents:
|
|
|
|
- **Lazy registration**: `instances_use` doesn't block — validates on first real call
|
|
- **Non-blocking I/O**: All Docker/HTTP operations run in thread executors
|
|
- **Session isolation**: Each MCP session gets unique container ports
|
|
- **Cursor pagination**: Handle 100K+ item responses without context overflow
|
|
- **Server-side grep**: Filter results before they hit the wire
|
|
|
|
Based on [GhidraMCP by Laurie Wired](https://github.com/LaurieWired/GhidraMCP/), evolved into a comprehensive RE platform.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Apache 2.0
|