ghidra-mcp-zig

Ghidra MCP Zig Plugin

A Ghidra plugin that provides a bridge between Ghidra and a Zig-based MCP server for enhanced program analysis capabilities.

Features

• JNI-based communication between Ghidra and Zig
• Function decompilation and renaming
• Data symbol management
• Import/Export listing
• MCP server integration
• Comprehensive test suite
• Modern build system with Zig
• Efficient memory management
• Type-safe JNI bridge implementation
• Go client library for easy integration

Prerequisites

• Zig (version 0.13.0 or later)
• Ghidra (version 11.3.1 or later)
• Java Development Kit (JDK) 17 or later
• Go (version 1.22.4 or later)
• Gradle (version 8.13 or later)
• Make

Project Structure

ghidra-mcp-zig/
├── src/
│   ├── plugin/
│   │   ├── jni/
│   │   │   └── bridge.zig    # JNI interface implementation
│   │   ├── analysis.zig      # Program analysis logic
│   │   └── plugin.zig        # Plugin initialization
│   └── server/
│       └── main.zig          # MCP server implementation
├── java/                     # Ghidra plugin Java code
│   ├── build.gradle         # Gradle build configuration
│   ├── gradlew             # Gradle wrapper script
│   └── src/                # Java source files
├── pkg/
│   └── mcp/
│       └── client/         # Go MCP client library
│           ├── client.go   # Client implementation
│           └── client_test.go # Client tests
├── build.zig               # Build configuration
├── build.zig.zon          # Dependencies configuration
├── go.mod                 # Go module definition
└── Makefile              # Build automation

Dependencies

• zig-jni (v0.0.9) - JNI bindings for Zig

Building

1. Clone the repository:

   git clone https://github.com/yourusername/ghidra-mcp-zig.git
   cd ghidra-mcp-zig
   

2. Create a .env file with the following variables:

   GHIDRA_PATH=/path/to/ghidra_11.3.1_PUBLIC/Ghidra/Features/Base/lib/Base.jar
   JAVA_HOME=/path/to/your/jdk
   

3. Build the project:

   # Build everything
   make all
   
   # Or build specific components
   make build-server    # Build the MCP server
   make build-plugin   # Build the Ghidra plugin
   

4. Run the server:

   make run-server
   

Build Targets

Target	Description	Example Usage
all	Build all components	make all
build-server	Build MCP server	make build-server
build-plugin	Build Ghidra plugin	make build-plugin
clean	Clean all artifacts	make clean
clean-server	Clean server artifacts	make clean-server
clean-plugin	Clean plugin artifacts	make clean-plugin

Run Targets

Target	Description	Example Usage
run-server	Start MCP server	make run-server
run-plugin	Start Ghidra plugin	make run-plugin

Test Targets

Target	Description	Example Usage
test	Run all tests	make test
test-server	Run server tests	make test-server
test-plugin	Run plugin tests	make test-plugin

For a complete list of available targets, run:

make help

Installation

1. Build the plugin:

   make build-plugin
   

2. Copy the built plugin to your Ghidra plugins directory:

   cp zig-out/lib/libghidra-mcp-zig.dylib /path/to/ghidra/Extensions/Ghidra/ghidra-mcp-zig/
   

3. Restart Ghidra

Usage

1. Start Ghidra and open a program for analysis
2. The MCP plugin will be available in the Ghidra plugin manager
3. Use the plugin's features through the Ghidra interface

Available MCP Commands

Command	Description	Parameters
decompile	Decompile a function	address: u64
rename_function	Rename a function	address: u64, new_name: string
rename_data	Rename a data object	address: u64, new_name: string
list_functions	List all functions	None
list_data	List all data objects	None
list_imports	List all imports	None
list_exports	List all exports	None

Error Handling

The implementation includes comprehensive error handling with specific error types:

Error Type	Description
ConnectionError	Connection-related errors
MessageError	Message handling errors
ResponseError	Response parsing errors
InvalidAddress	Invalid memory address
InvalidFunction	Invalid function reference
InvalidData	Invalid data reference
DecompilationFailed	Function decompilation failed
RenameFailed	Rename operation failed
OutOfMemory	Memory allocation failed
InvalidProgram	Invalid program state
JNIError	JNI bridge errors

Development

Adding New Features

1. Update the JNI interface in src/plugin/jni/bridge.zig
2. Implement the corresponding functionality in src/plugin/analysis.zig
3. Update the server implementation in src/server/main.zig if needed
4. Rebuild and test

Debugging

• Use make clean to remove build artifacts
• Check the Ghidra log for plugin-related messages
• The server logs will be available in the console when running with make run-server

JNI Bridge Implementation

The JNI bridge provides a type-safe interface between Zig and Java:

• Memory management with proper allocation/deallocation
• JNI reference management with DeleteLocalRef
• Error handling with null checks
• Type conversion between Zig and Java types
• Array creation and element setting
• Object creation and field setting

Key Features

1. Memory Safety

   • Automatic cleanup of JNI references
   • Proper string handling with UTF-8 conversion
   • Safe memory allocation and deallocation

2. Type Safety

   • Strong typing for all JNI operations
   • Compile-time type checking
   • Safe type conversions

3. Error Handling

   • Comprehensive error types
   • Null checks for all JNI operations
   • Proper cleanup on error

4. Object Management

   • Safe object creation and destruction
   • Field access with type checking
   • Array handling with bounds checking

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.