feat(headless): Expand Python server to full API parity
Rewrite GhydraMCPServer.py from 348 to 2138 lines, implementing all 45
routes that the MCP client expects. Previously, most endpoints returned
{"error": "Not found"}, breaking tools like data_list, xrefs_list, and
memory_read.
Key changes:
- Regex-based routing table with method-aware dispatch
- Thread-safe Ghidra transactions via threading.Lock()
- Full read endpoints: functions, data, strings, memory, xrefs, structs
- Full write endpoints: rename, comment, signature, create function/data
- Analysis endpoints: callgraph traversal, dataflow, run analysis
- Jython/Python 2 compatible (no f-strings, type hints, or walrus ops)
Tested with Docker build and curl against all major endpoint groups.
MCP client integration verified working.
This commit is contained in:
parent
2d837d95fc
commit
4c112a2421
File diff suppressed because it is too large
Load Diff
197
docker/README.md
Normal file
197
docker/README.md
Normal file
@ -0,0 +1,197 @@
|
||||
# GhydraMCP Docker Setup
|
||||
|
||||
This directory contains Docker configuration for running GhydraMCP in headless mode.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build the image
|
||||
docker build -t ghydramcp:latest -f docker/Dockerfile .
|
||||
|
||||
# Analyze a binary
|
||||
docker run -p 8192:8192 -v /path/to/binaries:/binaries ghydramcp /binaries/sample.exe
|
||||
|
||||
# Check API health
|
||||
curl http://localhost:8192/
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
The Docker container includes:
|
||||
|
||||
1. **Ghidra 11.4.2** - Full headless installation
|
||||
2. **GhydraMCP Extension** - The Java plugin (installed in Extensions/)
|
||||
3. **GhydraMCPServer.py** - Headless HTTP server (Jython, full API parity)
|
||||
|
||||
### Why Two HTTP Servers?
|
||||
|
||||
The GhydraMCP plugin (`GhydraMCPPlugin.java`) is a full Ghidra GUI plugin that requires:
|
||||
- Ghidra's `PluginTool` framework
|
||||
- `ProgramManager` service for program access
|
||||
- GUI event handling
|
||||
|
||||
These GUI services don't exist in headless mode. Instead, the container uses `GhydraMCPServer.py`, a Jython script that:
|
||||
- Runs via `analyzeHeadless -postScript`
|
||||
- Has direct access to `currentProgram` from the script context
|
||||
- Provides **full API parity** with the GUI plugin (45 routes)
|
||||
- Supports all read and write operations
|
||||
|
||||
### Available Endpoints (Headless Mode)
|
||||
|
||||
The headless server implements the complete GhydraMCP HTTP API:
|
||||
|
||||
| Category | Endpoints | Description |
|
||||
|----------|-----------|-------------|
|
||||
| **Info** | `GET /`, `/info`, `/program` | API info, program metadata |
|
||||
| **Functions** | `GET /functions`, `/functions/{addr}`, `/functions/by-name/{name}` | List and detail |
|
||||
| **Decompile** | `GET /functions/{addr}/decompile`, `/functions/by-name/{name}/decompile` | C pseudocode |
|
||||
| **Disassembly** | `GET /functions/{addr}/disassembly`, `/functions/by-name/{name}/disassembly` | Assembly listing |
|
||||
| **Data** | `GET /data`, `/strings` | Defined data and strings |
|
||||
| **Memory** | `GET /memory`, `/memory/blocks` | Read bytes, list segments |
|
||||
| **Xrefs** | `GET /xrefs` | Cross-references (to/from) |
|
||||
| **Structs** | `GET /structs` | Data type structures |
|
||||
| **Symbols** | `GET /symbols`, `/imports`, `/exports` | Symbol tables |
|
||||
| **Analysis** | `GET /analysis/callgraph`, `/analysis/dataflow` | Static analysis |
|
||||
| **Write Ops** | `PATCH /functions/*`, `POST /data`, `POST /structs/*` | Rename, annotate, create |
|
||||
|
||||
See [GHIDRA_HTTP_API.md](../GHIDRA_HTTP_API.md) for the complete API specification.
|
||||
|
||||
## Container Modes
|
||||
|
||||
### Headless Mode (Default)
|
||||
|
||||
Imports a binary, analyzes it, and starts the HTTP API server:
|
||||
|
||||
```bash
|
||||
docker run -p 8192:8192 \
|
||||
-v ./samples:/binaries \
|
||||
ghydramcp /binaries/sample.exe
|
||||
```
|
||||
|
||||
### Server Mode
|
||||
|
||||
Opens an existing project and program:
|
||||
|
||||
```bash
|
||||
docker run -p 8192:8192 \
|
||||
-e GHYDRA_MODE=server \
|
||||
-v ./projects:/projects \
|
||||
ghydramcp program_name
|
||||
```
|
||||
|
||||
### Analyze Mode
|
||||
|
||||
Imports and analyzes without starting HTTP server:
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-e GHYDRA_MODE=analyze \
|
||||
-v ./samples:/binaries \
|
||||
-v ./projects:/projects \
|
||||
ghydramcp /binaries/sample.exe
|
||||
```
|
||||
|
||||
### Shell Mode
|
||||
|
||||
Interactive debugging:
|
||||
|
||||
```bash
|
||||
docker run -it \
|
||||
-e GHYDRA_MODE=shell \
|
||||
ghydramcp
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `GHYDRA_MODE` | `headless` | Container mode (headless, server, analyze, shell) |
|
||||
| `GHYDRA_PORT` | `8192` | HTTP API port |
|
||||
| `GHYDRA_MAXMEM` | `2G` | JVM heap memory |
|
||||
| `PROJECT_DIR` | `/projects` | Ghidra project directory |
|
||||
| `PROJECT_NAME` | `GhydraMCP` | Ghidra project name |
|
||||
|
||||
## Docker Compose
|
||||
|
||||
Use docker-compose for easier management:
|
||||
|
||||
```bash
|
||||
# Development mode (hot-reload scripts)
|
||||
docker compose --profile dev up ghydramcp-dev
|
||||
|
||||
# Production mode
|
||||
docker compose --profile prod up ghydramcp
|
||||
|
||||
# Interactive shell
|
||||
docker compose --profile debug run --rm ghydramcp-shell
|
||||
```
|
||||
|
||||
## MCP Integration
|
||||
|
||||
The GhydraMCP Python server includes Docker management tools:
|
||||
|
||||
```python
|
||||
# Check Docker status
|
||||
await docker_status()
|
||||
|
||||
# Start container for a binary
|
||||
await docker_start(binary_path="/path/to/binary.exe", port=8192)
|
||||
|
||||
# Wait for container to be ready
|
||||
await docker_wait(port=8192, timeout=300)
|
||||
|
||||
# Automatic mode - starts container if no Ghidra available
|
||||
await docker_auto_start(binary_path="/path/to/binary.exe")
|
||||
|
||||
# Get container logs
|
||||
await docker_logs("ghydramcp-server")
|
||||
|
||||
# Stop container
|
||||
await docker_stop("ghydramcp-server")
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
# Using Make
|
||||
make build
|
||||
|
||||
# Using Docker directly
|
||||
docker build -t ghydramcp:latest -f docker/Dockerfile .
|
||||
|
||||
# Build with specific Ghidra version
|
||||
docker build -t ghydramcp:latest \
|
||||
--build-arg GHIDRA_VERSION=11.4.2 \
|
||||
--build-arg GHIDRA_DATE=20250826 \
|
||||
-f docker/Dockerfile .
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container starts but API doesn't respond
|
||||
|
||||
Analysis takes time. Monitor progress with:
|
||||
```bash
|
||||
docker logs -f ghydramcp-server
|
||||
```
|
||||
|
||||
### Port already in use
|
||||
|
||||
Stop existing containers:
|
||||
```bash
|
||||
docker stop $(docker ps -q --filter "name=ghydramcp")
|
||||
```
|
||||
|
||||
### Memory issues with large binaries
|
||||
|
||||
Increase JVM heap:
|
||||
```bash
|
||||
docker run -e GHYDRA_MAXMEM=4G -p 8192:8192 ghydramcp /binaries/large.exe
|
||||
```
|
||||
|
||||
### Permission denied on volumes
|
||||
|
||||
The container runs as user `ghidra` (UID 1001). Ensure volume permissions:
|
||||
```bash
|
||||
sudo chown -R 1001:1001 /path/to/binaries
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user