Content
# GEF MCP Server v2.0
**Black Screen Security Team - guaidao2 Development** 🛡️
**GDB Enhanced Features**' Model Context Protocol (MCP) Server implementation, supporting remote debugging via SSE or stdio. Optimized for security testing and CTF competitions.
## Features
- **GEF/GDB Integration**: Automatically loads GEF plugin, providing enhanced debugging capabilities
- **Multi-Session**: Up to 4 concurrent debugging sessions
- **SSE + stdio Dual-Mode**: Remote HTTP SSE or local Claude Desktop stdio
- **PTY Terminal**: Real terminal emulation, supporting interactive debugging
- **41 Dedicated Tools**: Covering debugging, memory operations, binary analysis, CTF exploit development, and more
- **CTF-Oriented Enhancements**: checksec, ROP search, format-string detection, patch, assemble, etc.
- **Security Protections**: Path injection elimination, newline protection, output size limitation
- **Background Zombie Recycling**: Automatic cleanup of crashed sessions
## Installation
```bash
cd /root/Desktop/gef-mcp
pip install -r requirements.txt
```
### Install GEF (if not installed)
```bash
bash -c "$(curl -fsSL https://gef.blah.cat/sh)"
```
## Usage
```bash
# SSE Mode (default :8000)
python server.py
# Specify address and port
python server.py --host 127.0.0.1 --port 8080
# stdio Mode (Claude Desktop)
python server.py --transport stdio
```
### MCP Endpoints
- SSE Endpoint: `http://localhost:8000/sse`
- Message Endpoint: `http://localhost:8000/messages/`
## Tool List
### Session Management
| Tool | Description |
|------|-------------|
| `create_session` | Create a new debugging session |
| `list_sessions` | List all active sessions |
| `close_session` | Close a session |
### File and Startup
| Tool | Description |
|------|-------------|
| `load_file` | Load the target binary |
| `start_debugging` | Load file + display GEF context |
### Breakpoints
| Tool | Description |
|------|-------------|
| `set_breakpoint` | Set a breakpoint (function/address/file:line) |
| `delete_breakpoint` | Delete a breakpoint by number |
| `list_breakpoints` | List all breakpoints/watchpoints |
| `watchpoint` | Set a data breakpoint (read/write/access) |
### Execution Control
| Tool | Description |
|------|-------------|
| `run` | Run the program (with arguments) |
| `continue` | Continue execution |
| `step` | Step into |
| `next` | Step over |
### Registers / Stack
| Tool | Description |
|------|-------------|
| `get_registers` | Get CPU registers |
| `get_backtrace` | Function call backtrace |
| `info_frame` | Detailed information about the current stack frame |
### Disassembly
| Tool | Description |
|------|-------------|
| `disassemble` | Disassemble code |
### Memory Operations
| Tool | Description |
|------|-------------|
| `examine_memory` | Examine memory (x/16xg) |
| `write_memory` | Write a value to memory |
| `patch_byte` | GEF patch modify byte |
| `hexdump` | Hexadecimal + ASCII view |
| `telescope` | Recursive dereference (telescope) |
| `search_pattern` | Search for a memory pattern |
| `search_strings` | Search for printable strings |
### GEF Enhancements
| Tool | Description |
|------|-------------|
| `vmmap` | Virtual memory mapping |
| `heap` | Heap information |
| `checksec` | 🔐 Security mitigation checks |
| `got_plt` | GOT/PLT information |
| `get_context` | Complete debugging context |
| `get_sections` | Section information |
| `get_entry_point` | Entry point address |
| `elf_info` | ELF file header information |
| `reset_cache` | Reset GEF cache |
### CTF Specific 🔥
| Tool | Description |
|------|-------------|
| `rop_search` | Search for ROP gadgets |
| `rop_search_all` | List all gadgets |
| `attach_process` | Attach to a process |
| `detach_process` | Detach from a process |
| `format_string_helper` | Detect format string vulnerabilities |
| `assemble` | Write assembly instructions |
| `nop_sled` | Write NOP chain |
| `execute_command` | Arbitrary GEF/GDB command |
## Integration with Claude Desktop
```json
{
"mcpServers": {
"gef": {
"command": "python",
"args": ["/root/Desktop/gef-mcp/server.py", "--transport", "stdio"]
}
}
}
```
## Security Notes
- `filepath` parameter is subject to injection elimination, rejecting paths containing `!` `;` `|` and other shell metacharacters
- `pattern` parameter rejects newline characters to prevent command injection
- `execute_command` executes arbitrary commands by design - ensure the caller is trusted
- All session output has a 50KB size limit to prevent memory expansion
## Debugging Workflow Example (CTF)
```python
# 1. Create a session
session = await call_tool("create_session", {})
sid = session["session_id"]
# 2. Load the target
await call_tool("load_file", {"session_id": sid, "filepath": "./vuln"})
# 3. Security check
sec = await call_tool("checksec", {"session_id": sid})
# → NX: enabled | PIE: disabled | Canary: enabled ...
# 4. View memory layout
map = await call_tool("vmmap", {"session_id": sid})
# 5. Breakpoint + run
await call_tool("set_breakpoint", {"session_id": sid, "location": "main"})
await call_tool("run", {"session_id": sid})
# 6. Search for ROP gadgets
gadgets = await call_tool("rop_search", {"session_id": sid, "gadget": "pop rdi"})
# 7. Check GOT
got = await call_tool("got_plt", {"session_id": sid})
# 8. Modify memory
await call_tool("write_memory", {
"session_id": sid,
"address": "0x601040",
"value": "0xdeadbeef"
})
```
## License
MIT
