Sarks0/binary-mcp
GitHub: Sarks0/binary-mcp
为 AI 助手提供二进制分析能力的 MCP 服务器，整合 Ghidra 静态分析、x64dbg 动态调试和 WinDbg 内核调试，支持跨平台恶意软件分析和逆向工程。
Stars: 6 | Forks: 4
# Binary MCP Server
[](https://github.com/sarks0/binary-mcp/actions)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
为 AI 助手提供全面二进制分析能力的 MCP server。它将静态分析（Ghidra, ILSpyCmd）、用户模式调试（x64dbg）和内核级调试（WinDbg）整合到一个统一接口中，用于安全研究、逆向工程和漏洞发现。
## 功能特性
- **静态分析**：原生二进制文件和 .NET 程序集
- **用户模式调试**：x64dbg 集成，支持断点、追踪和内存检查
- **内核调试**：通过 Pybag COM API 使用 WinDbg/KD，支持驱动分析、IOCTL 研究和崩溃转储分析
- **智能缓存**：基于 SHA256 的缓存，重新分析速度提升 30-120 倍
- **会话管理**：跨对话的持久化分析追踪，支持自动恢复
- **模式检测**：100+ 种 Windows API 模式和加密常量
- **结构化错误**：50+ 种带有可操作解决建议的错误代码
## 快速开始
### Windows
```
# 运行交互式安装程序 (以管理员身份)
irm https://raw.githubusercontent.com/Sarks0/binary-mcp/main/install.ps1 | iex
```
自动安装：Python, Java, .NET, Ghidra, x64dbg，并配置 Claude。
若需 WinDbg/内核调试支持：
```
pip install binary-mcp[windbg]
```
需要 [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)（包含 `cdb.exe` 和 `kd.exe`）。要获得完整的本地内核访问权限，请以管理员身份启用调试模式：`bcdedit -debug on` 然后重启（参见 [故障排除](#troubleshooting)）。
### Linux / macOS
```
# 运行交互式安装程序
curl -sSL https://raw.githubusercontent.com/Sarks0/binary-mcp/main/install.py | python3 -
```
通过包管理器自动安装前置依赖。
### 手动安装
```
# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh
# 克隆并安装
git clone https://github.com/Sarks0/binary-mcp.git
cd binary-mcp
uv sync
# 可选：WinDbg 支持 (仅限 Windows)
uv sync --extra windbg
```
## 配置
### Claude Code
通过命令行直接添加 MCP server：
```
claude mcp add binary-analysis -- uv --directory /absolute/path/to/binary-mcp run python -m src.server
```
或手动编辑 `~/.claude/settings.json`（全局）或 `.claude/settings.json`（每个项目）：
```
{
"mcpServers": {
"binary-analysis": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/binary-mcp", "run", "python", "-m", "src.server"],
"env": {"GHIDRA_HOME": "/path/to/ghidra"}
}
}
}
```
### Claude Desktop
编辑 Claude Desktop 配置文件：
| 平台 | 配置路径 |
|----------|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
```
{
"mcpServers": {
"binary-analysis": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/binary-mcp", "run", "python", "-m", "src.server"],
"env": {"GHIDRA_HOME": "/path/to/ghidra"}
}
}
}
```
保存后重启 Claude Desktop。
## 使用
**静态分析：**
```
Analyze the binary at /path/to/sample.exe
Show me all functions in the binary
Decompile the function at address 0x401000
Find all suspicious Windows API calls
```
**.NET 分析：**
```
Analyze the .NET assembly at /path/to/app.exe
Decompile the type MyNamespace.MyClass
```
**用户模式调试 (x64dbg)：**
```
Connect to x64dbg and set a breakpoint at 0x401000
Step through the function and show me the registers
```
**内核调试：**
```
Connect to the kernel debugger on port 50000
Show me the dispatch table for \\Driver\\MyDriver
Decode IOCTL code 0x9C402408
Analyze the crash dump at C:\Windows\MEMORY.DMP
List all loaded kernel drivers
```
## 可用工具
### 静态分析（27 个工具）
**核心：**
- `analyze_binary` - 运行 Ghidra 分析
- `check_binary` - 检查二进制兼容性
- `get_functions` - 列出函数
- `get_imports` - 提取导入
- `get_strings` - 提取字符串
- `decompile_function` - 反编译为伪代码
- `get_xrefs` - 获取交叉引用
**模式检测：**
- `find_api_calls` - 识别 Windows API 使用情况
- `detect_crypto` - 查找加密常量
- `generate_iocs` - 提取 IP, 域名, URL
**高级：**
- `get_call_graph` - 函数调用图
- `get_memory_map` - 内存布局
- `search_bytes` - 字节模式搜索
- `rename_function` - 在缓存中重命名函数
**.NET（7 个工具）：**
- `analyze_dotnet` - 列出程序集类型
- `get_dotnet_types` - 过滤类型
- `decompile_dotnet_type` - 反编译为 C#
- `decompile_dotnet_assembly` - 完整反编译
- `search_dotnet_types` - 按模式搜索
- `get_dotnet_il` - IL 反汇编
### 动态分析 - x64dbg（14 个工具）
- `x64dbg_connect`, `x64dbg_status`, `x64dbg_run`, `x64dbg_pause`
- `x64dbg_step_into`, `x64dbg_step_over`
- `x64dbg_set_breakpoint`, `x64dbg_delete_breakpoint`, `x64dbg_list_breakpoints`
- `x64dbg_get_registers`, `x64dbg_read_memory`, `x64dbg_disassemble`
- `x64dbg_trace_execution`, `x64dbg_run_to_address`
### 内核调试 - WinDbg（20 个工具）
**连接：**
- `windbg_connect_kernel` - 通过 KDNET 连接（端口 + 密钥）
- `windbg_open_dump` - 打开崩溃转储
- `windbg_disconnect` - 断开与目标的连接
- `windbg_status` - 调试器状态摘要
**执行控制：**
- `windbg_run`, `windbg_pause`, `windbg_step_into`, `windbg_step_over`
- `windbg_run_and_wait` - 运行直到断点
- `windbg_wait_paused` - 等待中断
**断点：**
- `windbg_set_breakpoint` - 设置断点（地址或符号）
- `windbg_delete_breakpoint` - 移除断点
- `windbg_list_breakpoints` - 列出所有断点
- `windbg_set_conditional_breakpoint` - 带命令的条件断点
**检查：**
- `windbg_get_registers` - 读取所有寄存器
- `windbg_read_memory` - 读取指定地址的内存
- `windbg_write_memory` - 写入内存
- `windbg_disassemble` - 在指定地址反汇编
- `windbg_get_modules` - 列出已加载的模块/驱动
- `windbg_execute_command` - 执行原始 WinDbg 命令
### 会话管理（7 个工具）
- `start_analysis_session` - 开始追踪
- `save_session` - 持久化数据
- `list_sessions` - 列出所有会话
- `load_session_section` - 加载特定输出
- `delete_session` - 清理
## 支持的格式
| 格式 | 引擎 | 状态 |
|--------|--------|--------|
| PE (.exe, .dll, .sys) | Ghidra | 完全支持 |
| .NET Assembly | ILSpyCmd | 完全支持 |
| ELF (Linux) | Ghidra | 完全支持 |
| Mach-O (macOS) | Ghidra | 完全支持 |
| Kernel Drivers (.sys) | Ghidra + WinDbg | 完全支持 |
| Crash Dumps (.dmp) | WinDbg | 完全支持 |
| Raw Binary | Ghidra | 有限支持 |
## 架构
```
MCP Client (Claude Desktop / Claude Code)
|
FastMCP Server (stdio)
/ | \
Static Analysis Dynamic Analysis Kernel Debugging
/ \ | |
Ghidra ILSpyCmd x64dbg WinDbg/KD
(headless) (.NET) (HTTP bridge) (Pybag COM API)
| |
C++ Plugin DbgEng COM
| |
User Process Kernel Target
```
## 故障排除
**找不到 Ghidra：**
```
export GHIDRA_HOME=/path/to/ghidra
diagnose_setup
```
**找不到 ILSpyCmd：**
```
dotnet tool install -g ilspycmd
diagnose_dotnet_setup
```
**找不到 WinDbg：**
```
# 安装 Windows SDK (包含 Debugging Tools)
# 或手动设置路径：
set WINDBG_PATH=C:\Program Files (x86)\Windows Kits\10\Debuggers\x64
```
**内核调试设置：**
本地内核调试需要启用调试模式并重启：
```
# 以管理员身份运行：
bcdedit -debug on
shutdown /r /t 0
```
如果没有执行 `bcdedit -debug on`，本地内核访问将受限 —— 符号查找（`x`, `dt`, `u`, `lm`）可以通过 KD 工作，但寄存器、内存读取、`!process` 和调用栈将失败。
**KDNET 远程内核调试：**
```
# 在目标机器上 (启用 KDNET)：
bcdedit /debug on
bcdedit /dbgsettings net hostip: port:50000 key:1.2.3.4
# 然后在 Claude 中：
# "通过端口 50000 连接内核调试器，密钥为 1.2.3.4"
```
**分析超时：**
```
export GHIDRA_TIMEOUT=1200
```
## 开发
```
# 运行测试
uv run pytest
# 带有覆盖率
uv run pytest --cov=src
# Lint
make lint
# Format
make format
```
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `GHIDRA_HOME` | Ghidra 安装路径 | 自动检测 |
| `GHIDRA_PROJECT_DIR` | 项目目录 | `~/.ghidra_projects` |
| `GHIDRA_TIMEOUT` | 分析超时（秒） | 600 |
| `X64DBG_PATH` | x64dbg 可执行文件路径 | 自动检测 |
| `WINDBG_PATH` | WinDbg/CDB 安装路径 | 从 Windows SDK 自动检测 |
| `WINDBG_MODE` | 操作模式：`kernel`, `user`, `dump` | `kernel` |
| `WINDBG_SYMBOL_PATH` | 符号服务器路径 | Microsoft 公共符号 |
| `WINDBG_TIMEOUT` | 命令超时（秒） | 30 |
## 贡献
欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。
## 资源
- **文档**：[docs/](docs/)
- **WinDbg/内核调试指南**：[docs/windbg-kernel-debugging.md](docs/windbg-kernel-debugging.md)
- **问题反馈**：[github.com/Sarks0/binary-mcp/issues](https://github.com/Sarks0/binary-mcp/issues)
- **MCP Protocol**：[modelcontextprotocol.io](https://modelcontextprotocol.io/)
## 许可证
Apache 2.0 - 详见 LICENSE 文件。
标签：AI安全, Amass, API模式识别, Chat Copilot, Claude Desktop, Crash Dump分析, CTF工具, DAST, Ghidra, IDA替代, ILSpy, JS文件枚举, LLM工具集成, MCP服务器, .NET逆向, Python安全工具, WinDbg, 二进制分析, 二进制安全, 云安全监控, 云安全运维, 云资产清单, 内核调试, 多人体追踪, 恶意软件分析, 模型上下文协议, 漏洞搜索, 自动化分析, 自定义密码套件, 跨站脚本, 逆向工具, 逆向工程, 静态分析, 驱动分析