wagonbomb/kawaiidra-mcp

# Kawaiidra MCP [](https://ghidra-sre.org/) [](https://modelcontextprotocol.io/) [](LICENSE) **关键词：** `ghidra` `mcp` `ghidra-mcp` `model-context-protocol` `binary-analysis` `reverse-engineering` `decompiler` `disassembler` `claude` `claude-code` 一个通用的 **Ghidra MCP server**，将 Ghidra 无头分析器和反编译器的强大功能带给 Claude Code 及其他兼容 MCP 的 AI 助手。 ## 功能 ### 核心功能 - **分析任意二进制文件**：PE (Windows), ELF (Linux), Mach-O (macOS) 以及原生固件 - **反编译函数**：从编译后的二进制文件获取 C 代码 - **反汇编**：查看汇编列表 - **交叉引用**：查找函数调用者和被调用者 - **字符串分析**：搜索和列出二进制文件中的字符串 - **导出结果**：将分析结果保存为 JSON 以便后续处理 - **多项目支持**：将分析组织到独立的 Ghidra 项目中 ### 高级分析 (LLM 优化) - **调用图**：提取层级化的函数关系 - **库检测**：识别 OpenSSL, zlib, Qt, Windows API 等 - **语义搜索**：根据行为查找代码（文件 I/O、网络、加密、内存操作） - **上下文提取**：获取函数及其所有依赖项以获得完整理解 - **数据结构**：提取结构体/类定义和枚举 - **控制流图**：通过基本块分析函数逻辑 - **漏洞检测**：基于模式的安全分析及 CWE 映射 - **函数相似度**：基于结构指纹查找代码复用 - **智能命名**：根据使用模式建议更好的符号名称 ### iOS 安全研究工具 - **KPP/KTRR 检测**：识别内核补丁保护机制 - **Mach trap 分析**：分析系统调用表和 trap 处理程序 - **PAC gadget 查找器**：定位 ARM64e 的指针认证 gadget - **沙箱分析**：检查沙箱操作和策略检查 - **IOKit 类查找器**：映射 IOKit 类层次结构和用户客户端 - **权限检查**：检测权限验证代码路径 - **内核符号**：查找和分析 XNU 内核符号 - **Mach port 分析**：分析 IPC 和端口操作 ### Android 与移动端分析工具 - **加密常量**：查找 AES S-boxes, CRC 表和加密魔数 - **JNI 方法**：分析 JNI_OnLoad, Java_* 导出和 RegisterNatives 调用 - **API 端点**：提取 URL、主机名、IP 地址和 API 路径 - **硬编码机密**：查找 API 密钥、令牌、密码和凭据 - **二进制比较**：对比两个二进制文件以查找已添加/已删除/已修改的函数 ### GUI 模式与上下文跟踪 - **双模式支持**：可在无头模式和 GUI 连接模式下工作 - **上下文跟踪**：自动跟踪工具操作中的当前地址/函数 - **GUI 集成**：通过 ghidra_bridge 连接到运行中的 Ghidra GUI 以获取实时选择 - **光标感知分析**：获取/设置当前地址和函数以保持工作流连续性 ## 性能 Kawaiidra 支持两种执行模式： | 模式 | 速度 | 设置 | |------|-------|-------| | **JPype Bridge** (默认) | ~1-50ms/次调用 | 需要 Java JDK 17+ | | Subprocess (回退) | ~5-15s/次调用 | 开箱即用 | JPype bridge 保持 JVM 在进程内运行，消除了每次操作启动 `analyzeHeadless` 的约 5-15 秒启动开销。**对于顺序操作，这要快 100-1000 倍。** ``` ┌────────────────────────────────────────────────────┐ │ 10 function decompilations: │ │ │ │ Subprocess mode: ~2-3 minutes │ │ JPype Bridge: ~0.5 seconds │ └────────────────────────────────────────────────────┘ ``` ## 需求 - **Python 3.10+** - **Ghidra 11.0+**（已在 11.x 和 12.0 版本上测试，完全兼容 Ghidra 12.0） - **MCP Python package**: `pip install mcp` ### 为了获得最佳性能（推荐） - **Java JDK 17+**（用于 JPype bridge） - **JPype1**: `pip install JPype1` ## 快速开始 ### 1. 安装 Ghidra **选项 A: Homebrew (macOS/Linux) - 推荐** ``` # macOS brew install ghidra # Linux (Homebrew) brew install ghidra ``` **选项 B: 手动安装** 从 [ghidra-sre.org](https://ghidra-sre.org/) 下载 Ghidra 并解压。 ### 2. 安装依赖 ``` cd kawaiidra-mcp pip install -r requirements.txt ``` ### 2b. 启用快速模式（推荐） 为了实现 100-1000 倍更快的操作，安装 JPype 并确保 Java 可用： ``` # 安装 JPype pip install JPype1 # 验证已安装 Java JDK 17+ java -version ``` **如有需要，安装 Java：** ``` # macOS brew install openjdk@17 # Ubuntu/Debian sudo apt install openjdk-17-jdk # Windows (winget) winget install EclipseAdoptium.Temurin.17.JDK ``` 当 JPype 和 Java 都可用时，bridge 会自动启用。使用 `bridge_status` 工具进行验证。 ### 3. 配置 Ghidra 路径（可选） 服务器会自动检测常见位置的 Ghidra 安装。如果自动检测失败或您想使用特定版本，请设置 `GHIDRA_INSTALL_DIR`： **Homebrew 安装（通常会自动检测）：** ``` # macOS (Apple Silicon) export GHIDRA_INSTALL_DIR=/opt/homebrew # macOS (Intel) export GHIDRA_INSTALL_DIR=/usr/local # Linux export GHIDRA_INSTALL_DIR=/home/linuxbrew/.linuxbrew ``` **手动安装：** ``` # Windows set GHIDRA_INSTALL_DIR=C:\ghidra_11.2_PUBLIC # Linux/macOS export GHIDRA_INSTALL_DIR=/opt/ghidra export GHIDRA_INSTALL_DIR=/Applications/ghidra_11.2_PUBLIC ``` ### 4. 配合 Claude Code 使用 在 Claude Code 中打开 `kawaiidra-mcp` 文件夹。MCP server 将从 `.mcp.json` 自动加载。 或者添加到您的 Claude Code 配置中： ``` { "mcpServers": { "kawaiidra": { "type": "stdio", "command": "python", "args": ["/path/to/kawaiidra-mcp/run_server.py"], "env": { "GHIDRA_INSTALL_DIR": "/path/to/ghidra" } } } } ``` ### 5. 分析二进制文件 1. 将您的二进制文件放在 `binaries/` 文件夹中，或使用绝对路径 2. 使用 `analyze_binary` 工具导入并分析 3. 使用其他工具探索分析结果 ## 可用工具 ### 核心分析工具 | 工具 | 描述 | |------|-------------| | `analyze_binary` | 导入并分析二进制文件 | | `list_analyzed_binaries` | 列出当前项目中的二进制文件 | | `list_functions` | 列出二进制文件中的所有函数 | | `find_functions` | 按名称模式搜索函数 | | `get_function_decompile` | 将函数反编译为 C 代码 | | `get_function_disassembly` | 获取汇编列表 | | `get_function_xrefs` | 获取指向/来自函数的交叉引用 | | `search_strings` | 按模式搜索字符串 | | `list_strings` | 列出所有已定义的字符串 | | `get_binary_info` | 获取二进制元数据（架构、格式等） | | `get_memory_map` | 获取内存段/节 | | `export_analysis` | 将分析结果导出为 JSON 文件 | | `cache_stats` | 查看缓存命中率和性能统计 | | `cache_clear` | 清除缓存结果 | | `bridge_status` | 检查快速 JPype bridge 模式是否激活 | | `generate_report` | 生成综合二进制分析报告 | | `list_exports` | 列出导出的函数和符号 | | `list_imports` | 列出从外部库导入的函数 | | `list_data_items` | 列出已定义的数据标签和值 | | `list_namespaces` | 列出所有命名空间和类 | | `rename_function` | 在分析中重命名函数 | | `rename_data` | 重命名地址处的数据标签 | | `rename_variable` | 重命名函数内的局部变量 | | `set_comment` | 在特定地址添加注释 | | `set_function_prototype` | 设置函数签名 | | `set_local_variable_type` | 设置局部变量的类型 | ### 高级分析工具 (LLM 优化) | 工具 | 描述 | |------|-------------| | `get_call_graph` | 提取显示函数关系的调用层次结构 | | `detect_libraries` | 识别标准库、框架和第三方代码 | | `semantic_code_search` | 根据行为搜索代码（文件 I/O、网络、加密等） | | `get_function_with_context` | 获取函数及其所有依赖项以供 LLM 完整理解 | | `get_data_structures` | 提取结构体/类定义和数据类型 | | `get_control_flow_graph` | 提取带有基本块的 CFG 以进行逻辑流分析 | | `detect_vulnerabilities` | 使用模式分析检测安全漏洞 | | `find_similar_functions` | 根据结构查找与参考相似的函数 | | `get_annotated_disassembly` | 获取带有交叉引用和注释的丰富注释反汇编 | | `suggest_symbol_names` | 根据使用情况建议更好的变量/函数名称 | ### iOS 安全研究工具 | 工具 | 描述 | |------|-------------| | `detect_kpp_ktrr` | 检测 KPP、KTRR、PPL 和 AMFI 内核保护 | | `analyze_mach_traps` | 分析 Mach trap 表和系统调用处理程序 | | `find_pac_gadgets` | 查找 ARM64e 的 PAC 签名/认证 gadget | | `analyze_sandbox_ops` | 分析沙箱操作和策略执行 | | `find_iokit_classes` | 查找 IOKit 类、vtable 和用户客户端 | | `detect_entitlement_checks` | 检测权限验证和 AMFI 检查 | | `find_kernel_symbols` | 通过模式匹配查找内核符号 | | `analyze_mach_ports` | 分析 Mach port 操作和 IPC 模式 | ### Android 与移动端分析工具 | 工具 | 描述 | |------|-------------| | `find_crypto_constants` | 查找 AES S-boxes, CRC 表和加密魔数 | | `analyze_jni_methods` | 查找 JNI 方法（JNI_OnLoad, Java_*, RegisterNatives） | | `extract_api_endpoints` | 提取 URL、主机名、IP 地址和 API 路径 | | `find_hardcoded_secrets` | 查找 API 密钥、令牌、密码和凭据 | | `compare_binaries` | 比较两个二进制文件以查找已添加/已删除/已修改的函数 | ### GUI/上下文工具 | 工具 | 描述 | |------|-------------| | `get_current_address` | 获取当前地址（来自 GUI 光标或上下文跟踪器） | | `get_current_function` | 获取当前函数（来自 GUI 光标或上下文跟踪器） | | `set_current_address` | 为无头工作流设置当前地址上下文 | | `set_current_function` | 为无头工作流设置当前函数上下文 | | `get_current_selection` | 从 Ghidra GUI 获取选择范围（仅限 GUI 模式） | | `gui_status` | 检查 GUI 模式连接状态和上下文跟踪器状态 | ## 工具示例 ### 分析 Windows 可执行文件 ``` analyze_binary file_path: "C:\path\to\target.exe" ``` ### 分析原生固件 ``` analyze_binary file_path: "firmware.bin" processor: "ARM:LE:32:v7" base_address: "0x08000000" ``` ### 反编译函数 ``` get_function_decompile binary_name: "target.exe" function_name: "main" ``` ### 按模式查找函数 ``` find_functions pattern: "crypt" binary_name: "target.exe" ``` ### 获取交叉引用 ``` get_function_xrefs binary_name: "target.exe" function_name: "main" direction: "from" ``` ### 获取调用图 ``` get_call_graph binary_name: "target.exe" function_name: "main" depth: 3 direction: "callees" ``` ### 检测库 ``` detect_libraries binary_name: "target.exe" detailed: true ``` ### 搜索加密代码 ``` semantic_code_search binary_name: "target.exe" pattern: "crypto" ``` ### 获取带有完整上下文的函数 ``` get_function_with_context binary_name: "target.exe" function_name: "process_data" include_callees: true include_data_types: true ``` ### 检测漏洞 ``` detect_vulnerabilities binary_name: "target.exe" severity: "high" ``` ### 获取控制流图 ``` get_control_flow_graph binary_name: "target.exe" function_name: "main" include_instructions: true ``` ### 查找相似函数 ``` find_similar_functions binary_name: "target.exe" function_name: "encrypt_block" threshold: 0.7 ``` ### 生成综合报告 ``` generate_report binary_name: "target.exe" depth: "full" ``` 深度选项：`quick`（仅元数据），`standard`（+ 函数/字符串），`full`（+ 反编译），`exhaustive`（所有内容） ### 检测内核保护 (iOS) ``` detect_kpp_ktrr binary_name: "kernelcache" ``` ### 分析 Mach Traps (iOS/macOS) ``` analyze_mach_traps binary_name: "kernelcache" include_handlers: true ``` ### 查找 PAC Gadgets (ARM64e) ``` find_pac_gadgets binary_name: "kernelcache" gadget_type: "signing" max_results: 50 ``` ### 查找 IOKit 类 ``` find_iokit_classes binary_name: "IOKit.kext" include_vtables: true include_user_clients: true ``` ### 检测权限检查 ``` detect_entitlement_checks binary_name: "amfid" include_context: true ``` ### 查找内核符号 ``` find_kernel_symbols binary_name: "kernelcache" pattern: "proc_" symbol_type: "function" ``` ### 分析 Mach Ports ``` analyze_mach_ports binary_name: "launchd" include_dangerous: true ``` ### 查找加密常量 ``` find_crypto_constants binary_name: "libcrypto.so" include_context: true ``` ### 分析 JNI 方法 ``` analyze_jni_methods binary_name: "libnative.so" include_signatures: true ``` ### 提取 API 端点 ``` extract_api_endpoints binary_name: "app.so" include_params: true ``` ### 查找硬编码机密 ``` find_hardcoded_secrets binary_name: "libnative.so" sensitivity: "high" ``` ### 比较二进制文件 ``` compare_binaries binary_name_a: "app_v1.so" binary_name_b: "app_v2.so" include_similarity: true ``` ### 获取当前地址（上下文感知） ``` get_current_address ``` 从以下位置返回当前地址： - Ghidra GUI（如果启用 GUI 模式且已连接） - 上下文跟踪器（最后反编译/分析的地址） ### 获取当前函数 ``` get_current_function ``` 从以下位置返回当前函数： - Ghidra GUI 光标位置 - 上下文跟踪器（最后反编译的函数） ### 设置当前地址（头工作流） ``` set_current_address address: "0x401000" binary_name: "target.exe" ``` ### 检查 GUI 状态 ``` gui_status ``` 显示 GUI 模式配置、连接状态和上下文跟踪器状态。 ## 配置 ### 环境变量 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `GHIDRA_INSTALL_DIR` | Ghidra 安装路径 | 自动检测 | | `KAWAIIDRA_PROJECT_DIR` | Ghidra 项目存储位置 | `./projects` | | `KAWAIIDRA_BINARIES_DIR` | 输入二进制文件存储位置 | `./binaries` | | `KAWAIIDRA_EXPORTS_DIR` | 导出文件写入位置 | `./exports` | | `KAWAIIDRA_LOG_DIR` | 日志写入位置 | `./logs` | | `KAWAIIDRA_TIMEOUT` | 分析超时时间（秒） | `300` | | `KAWAIIDRA_DECOMPILE_TIMEOUT` | 反编译超时时间（秒） | `180` | | `KAWAIIDRA_MAX_MEMORY` | JVM 最大内存 | `4G` | ### 缓存设置 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `KAWAIIDRA_CACHE_ENABLED` | 启用结果缓存 | `true` | | `KAWAIIDRA_CACHE_DIR` | 缓存存储位置 | `~/.kawaiidra/cache` | | `KAWAIIDRA_CACHE_MAX_SIZE_MB` | 最大缓存大小 | `500` | ### JPype Bridge 设置（性能） | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `KAWAIIDRA_USE_BRIDGE` | 启用快速 JPype bridge | `true` | | `KAWAIIDRA_BRIDGE_CACHE_PROGRAMS` | 将程序保留在内存中 | `true` | | `KAWAIIDRA_BRIDGE_MAX_PROGRAMS` | 最大缓存程序数 | `5` | ### GUI 模式设置 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `KAWAIIDRA_GUI_MODE` | 启用 GUI 模式（连接到运行中的 Ghidra） | `false` | | `KAWAIIDRA_GUI_HOST` | ghidra_bridge 连接的主机 | `127.0.0.1` | | `KAWAIIDRA_GUI_PORT` | ghidra_bridge 连接的端口 | `4768` | | `KAWAIIDRA_GUI_TIMEOUT` | GUI bridge 操作超时时间（秒） | `10` | #### 启用 GUI 模式 GUI 模式允许 Kawaiidra 连接到运行中的 Ghidra GUI 实例，从而实现对光标位置和选择的实时访问。这对于交互式分析工作流非常有用。 **设置步骤：** 1. **启用 GUI 模式：** # Windows set KAWAIIDRA_GUI_MODE=true # Linux/macOS export KAWAIIDRA_GUI_MODE=true 2. **安装 ghidra_bridge（可选依赖）：** pip install ghidra_bridge 3. **在 Ghidra 中安装 bridge server：** python -m ghidra_bridge.install_server ~/ghidra_scripts 4. **在 Ghidra 中启动 bridge server：** - 在 Ghidra 中：`Tools > Ghidra Bridge > Run in Background` - 或者从 Script Manager 手动运行脚本 5. **验证连接：** gui_status **注意：** 即使未启用 GUI 模式，上下文跟踪也可在无头模式下工作。`get_current_address` 和 `get_current_function` 工具会自动跟踪您工具操作中的上下文（例如，最后反编译的函数成为当前函数）。 ## 测试 Kawaiidra 包含一个包含 166 个测试的综合测试套件，涵盖所有主要模块： ``` # 运行所有测试 uv run pytest tests/ -v # 运行特定测试文件 uv run pytest tests/test_cache.py -v ``` | 测试文件 | 测试数 | 覆盖范围 | |-----------|-------|----------| | `test_cache.py` | 57 | 缓存操作、TTL、LRU 淘汰 | | `test_index_parsing.py` | 30 | Ghidra 索引解析、正则表达式模式 | | `test_config.py` | 26 | 配置、环境变量、路径检测 | | `test_mcp_tools.py` | 22 | 工具定义、schema、工具 | | `test_mcp_handlers.py` | 22 | MCP handler 集成 | | `test_bridge.py` | 17 | Bridge 可用性、后端操作 | ## 目录结构 ``` kawaiidra-mcp/ ├── .mcp.json # MCP server configuration ├── README.md # This file ├── requirements.txt # Python dependencies ├── run_server.py # Server entry point ├── src/ │ └── kawaiidra_mcp/ │ ├── server.py # MCP server implementation │ ├── config.py # Configuration management │ ├── cache.py # Result caching system │ ├── bridge/ # JPype bridge for fast execution │ │ ├── __init__.py │ │ ├── jpype_bridge.py # JVM lifecycle & Ghidra API │ │ └── backend.py # High-level backend abstraction │ └── scripts/ # Ghidra headless scripts (fallback) ├── tests/ # Unit test suite (166 tests) ├── projects/ # Ghidra project storage (gitignored) ├── binaries/ # Input binaries (gitignored) ├── exports/ # Exported analysis (gitignored) └── logs/ # Runtime logs (gitignored) ``` ## 支持的二进制格式 | 格式 | 扩展名 | 自动检测 | |--------|------------|---------------| | PE (Windows) | .exe, .dll, .sys | 是 | | ELF (Linux) | .so, .o, (无) | 是 | | Mach-O (macOS) | .dylib, (无) | 是 | | Raw Binary | .bin, .fw | 否（需指定处理器） | ## 常用处理器 ID 对于原生二进制文件，需手动指定处理器： | 架构 | 处理器 ID | |--------------|--------------| | x86 32-bit | `x86:LE:32:default` | | x86 64-bit (AMD64) | `x86:LE:64:default` | | ARM 32-bit | `ARM:LE:32:v7` | | ARM 64-bit (AArch64) | `AARCH64:LE:64:default` | | MIPS 32-bit BE | `MIPS:BE:32:default` | | MIPS 32-bit LE | `MIPS:LE:32:default` | | PowerPC 32-bit | `PowerPC:BE:32:default` | | RISC-V 32-bit | `RISCV:LE:32:default` | ## 故障排除 ### "未找到 Ghidra" 确保 `GHIDRA_INSTALL_DIR` 指向包含 `support/analyzeHeadless` 脚本的有效 Ghidra 安装。 ### "未安装 MCP SDK" ``` pip install mcp ``` ### 分析超时 使用环境变量增加超时时间： ``` # Windows set KAWAIIDRA_TIMEOUT=600 # Linux/macOS export KAWAIIDRA_TIMEOUT=600 ``` ### 大型二进制文件内存问题 增加 JVM 内存： ``` set KAWAIIDRA_MAX_MEMORY=8G ``` ### 函数未找到 - 确保首先使用 `analyze_binary` 分析了二进制文件 - 尝试使用函数地址而不是名称（例如 `0x401000`） - 检查函数是否位于项目中的不同二进制文件中 ### JPype Bridge 未启动 检查 bridge 状态： ``` bridge_status ``` 如果 bridge 显示为不可用： 1. **安装 JPype:** pip install JPype1 2. **安装 Java JDK 17+:** # macOS brew install openjdk@17 # Ubuntu/Debian sudo apt install openjdk-17-jdk 3. **验证 Java 是否在 PATH 中:** java -version 4. **检查 JAVA_HOME（如有必要）:** export JAVA_HOME=/path/to/jdk 如果 JPype 不可用，服务器会自动回退到子进程模式。 ### Bridge 模式比预期慢 - 每个二进制文件的第一次调用需要 2-5 秒（程序加载） - 后续调用应在 ~1-50ms - 使用 `bridge_status` 验证 bridge 是否激活 - 检查是否设置了 `KAWAIIDRA_BRIDGE_CACHE_PROGRAMS=true` ## 分析报告 使用 Kawaiidra MCP 生成的二进制分析报告可存储在 [`md/`](md/) 文件夹中。有关报告结构指南，请参阅 [md/README.md](md/README.md)。 ## 为什么叫 "Kawaiidra"？ 因为逆向工程应该是有趣的！这是一个包裹在严肃工具外的可爱外壳。 *Kawaii*（日语：可爱）+ *Ghidra* = **Kawaiidra** ## 许可证 MIT License ## 另请参阅 - [Ghidra](https://ghidra-sre.org/) - NSA 的逆向工程框架 - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范 - [Claude Code](https://claude.ai/code) - AI 编程助手

标签：API识别, Claude Code, DAST, ELF分析, Findomain, Ghidra, iOS安全, JS文件枚举, LLM工具, Mach-O, MCP服务器, PE分析, Wayback Machine, 二进制分析, 云安全监控, 云安全运维, 云资产清单, 人工智能安全, 内核分析, 反汇编, 反编译器, 合规性, 固件分析, 恶意软件分析, 控制流图, 模型上下文协议, 网络安全, 逆向工具, 逆向工程, 隐私保护, 静态分析