# OGhidra 3 - 基于 Ghidra 的 AI 驱动逆向工程
如需使用受 Claude 启发的 Orchestrator 版本，请参阅 https://github.com/llnl/OGhidra/tree/orchestrator
**OGhidra** 将大型语言模型与 Ghidra 的逆向工程平台连接起来，通过自然语言实现 AI 驱动的二进制分析。您可以以对话方式分析二进制文件、自动化复杂工作流，并通过本地 AI 模型保持完全隐私。
YouTube 设置教程
[](https://www.youtube.com/watch?v=hBD92FUgR0Y)
---
## 什么是 OGhidra？
OGhidra 为 Ghidra 增添 AI 能力，使您能够：
- **自然语言分析** - 使用自然语言询问有关函数、字符串、导入的问题
- **自动化工作流** - 重命名函数、检测模式、生成全面的报告
- **本地 AI 模型** - 模型在您的硬件上运行（Ollama），保证完全隐私
- **云端 AI 支持** - 连接外部 API（OpenAI、Google Gemini、Anthropic Claude）
- **恶意软件检测** - 对 12 种以上的规避与注入技术进行自动模式匹配
- **智能枚举** - 从二进制分析构建可查询的知识图谱
- **多实例分析** - 运行多个 Ghidra 实例以进行并行分析
### 工作原理
```mermaid
graph TD
A[User Query] --> B[Planning Phase]
B --> C{Execution Phase}
C -- Tool Calls --> D[Ghidra/LLM]
D --> C
C --> E[Review Phase]
E -- Agentic Loop --> B
E --> F[Final Response]
style E fill:#f9f,stroke:#333,stroke-width:2px
style B fill:#bbf,stroke:#333,stroke-width:2px
```
**智能代理循环（Agentic Loop）**：OGhidra 采用自适应规划系统。每次执行周期结束后，都会对结果进行审查，AI 可以选择收集更多信息或优化分析，然后再给出最终响应。
---
## 快速开始
### 前置条件
1. **Python 3.12+** - 检查版本：`python --version`
2. **Ghidra 12.0.3**（推荐）- 从 [Ghidra Releases](https://github.com/NationalSecurityAgency/ghidra/releases) 下载
- 插件构建/安装路径已为 Ghidra 12.0.3 提供文档说明
- 已在以下版本上测试：Ghidra 11.0.3、11.3.2、12.0.2、12.0.3
3. **Java 21** - 构建 Ghidra 12.0.3 扩展所必需：`java -version`
4. **Ollama**（可选，用于本地模型）- 从 [ollama.com](https://ollama.com/) 安装
### 安装
```bash
# Clone repository
git clone https://github.com/LLNL/OGhidra.git
cd OGhidra
# Install dependencies (choose one)
uv sync # Using UV (recommended)
pip install -r requirements.txt # Using pip
# Configure environment
cp .env.example .env
# Edit .env with your settings
```
### 设置 Ghidra 插件
以下 OGhidraMCP 插件构建步骤面向 Ghidra 12.0.3（推荐）。
另附 YouTube 视频教程：https://www.youtube.com/watch?v=hBD92FUgR0Y
#### 构建 GhidraMCP 扩展
作为开发者，您需要先构建 GhidraMCP 扩展，然后才能将其安装到 Ghidra：
1. **前置条件**：
- 已安装 Ghidra 12.0.3
- Java 21
2. **选项 1：使用自动化构建脚本**：
- Windows：
```bat
# Set the path to your Ghidra installation (will attempt to find last run copy of Ghidra if not set)
set GHIDRA_INSTALL_DIR=C:\path\to\ghidra_12.0.3_PUBLIC
# Run the build script
build_ghidra_plugin.bat
```
- Unix/Linux/Mac：
```bash
# Set the path to your Ghidra installation (will attempt to find the last run copy of Ghidra if not set)
export GHIDRA_INSTALL_DIR=/path/to/ghidra_12.0.3_PUBLIC
# Run the build script (make it executable first if needed)
chmod +x build_ghidra_plugin.sh
./build_ghidra_plugin.sh
```
3. **选项 2：手动构建流程**：
- 在 `OGhidraMCP/gradle.properties` 中创建/更新您的 Ghidra 安装路径：
```properties
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.0.3_PUBLIC
```
- 在 Unix/Linux/macOS 上：
```bash
cd OGhidraMCP
$GHIDRA_INSTALL_DIR/support/gradle/gradlew buildExtension --info
```
- 在 Windows 上：
```bat
cd OGhidraMCP
"%GHIDRA_INSTALL_DIR%\support\gradle\gradlew.bat" buildExtension --info
```
4. **查找构建好的扩展**：
- 扩展 zip 文件生成在 `OGhidraMCP/dist/` 目录中
- 文件名类似 `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`
#### 安装 GhidraMCP 扩展
成功构建扩展后：
1. **在 Ghidra 中安装**：
- 打开 Ghidra -> **File（文件）** -> **Install Extensions（安装扩展）**
- 点击 **Add Extension（添加扩展）**（绿色加号图标）
- 浏览到您的 `OGhidraMCP/dist/` 目录
- 选择新构建的扩展 zip 文件（例如 `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`）
- 重启 Ghidra
2. **启用插件**：
- 打开一个 Ghidra 项目
- **File（文件）** → **Configure（配置）** → **Enable Developer（启用开发者）**
- 启用 `OGhidraMCP` 插件
- 服务器将启动于 `http://localhost:8080/methods`
> **您需要保持代码浏览器（Code Browser）处于打开状态**
### 拉取 AI 模型
```bash
# For Ollama (local models)
ollama pull gemma3:27b # Good balance (20GB RAM)
ollama pull nomic-embed-text # Embedding model for RAG
# Alternative models
ollama pull gpt-oss:120b # High quality (80GB RAM)
ollama pull devstral-2:123b # High quality (80GB RAM)
ollama pull devstral-2:123b-cloud # Cloud Model
```
### 启动 OGhidra
```bash
# GUI Mode (recommended)
uv run main.py --ui
# Interactive CLI
uv run main.py --interactive
# In interactive CLI, test connection
health
```
如果您启动了 GUI 模式，请使用：
```bash
curl http://localhost:8080/methods
```
---
## 配置
编辑 `.env` 以配置您的 AI 提供商：
### 选项 1：本地模型（Ollama）
```env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/
OLLAMA_MODEL=gemma3:27b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```
### 选项 2：外部 API
```env
LLM_PROVIDER=external
EXTERNAL_PROVIDER=google
EXTERNAL_API_KEY=your-api-key-here
EXTERNAL_MODEL=gemini-3.1-flash-lite-preview
EXTERNAL_EMBEDDING_MODEL=gemini-embedding-001
```
### 选项 3：自定义 OpenAI 兼容 API
```env
LLM_PROVIDER=custom_api
CUSTOM_API_URL=https://api.example.com/v1/chat/completions
CUSTOM_API_KEY=your-api-key-here
CUSTOM_API_MODEL=your-model-name
CUSTOM_API_EMBEDDING_MODEL=your-embedding-model
```
### 上下文管理设置
根据您模型的上下文窗口进行调整：
```env
# Context budget in tokens (adjust to your model's limit)
CONTEXT_BUDGET=100000 # 100K tokens for mid-size models
# 200K+ for frontier models
# Execution settings
MAX_EXECUTION_STEPS=5 # Steps per planning cycle
MAX_AGENTIC_CYCLES=3 # How many plan-execute-review loops
AGENTIC_LOOP_ENABLED=true # Enable adaptive replanning
```
---
## 主要功能
### 1. 智能工具按钮（GUI）
一键访问常见逆向工程任务：
| 工具 | 描述 |
| ---------------------------- | ----------------------------------------------- |
| **Analyze Current Function（分析当前函数）** | 深入分析所选函数的行为 |
| **Rename Current Function（重命名当前函数）** | AI 根据分析建议有意义的名称 |
| **Rename All Functions（重命名所有函数）** | 批量重命名，提供智能/完整/仅重命名选项 |
| **Analyze Imports（分析导入）** | 识别库和外部依赖项 |
| **Analyze Strings（分析字符串）** | 查找 URL、凭据、配置数据 |
| **Generate Report（生成报告）** | 全面的安全评估 |
### 2. 任务模式
设置专门的分析目标：
```python
# In GUI: Use "Task Mode" dropdown
# In CLI: set task_mode <mode>
task_mode malware # Malware analysis with pattern detection
task_mode vuln # Vulnerability research focus
task_mode general # General reverse engineering
```
### 3. 恶意软件模式检测
自动检测 12 种以上的恶意软件模式：
- **规避**：PEB Walking、动态 API 解析、反调试、反虚拟机
- **注入**：进程注入（本地/远程）
- **持久化**：注册表、文件系统挂钩
- **混淆**：字符串编码、API 哈希
- **权限提升**：令牌操作、UAC 绕过
这些模式会在 AI 上下文中触发自动警报，并附带 MITRE ATT&CK 映射。
### 4. 智能枚举
从二进制分析构建丰富、可查询的知识：
```
# Enumerate all functions with AI summaries
# Choose from:
- Rename Only: Only process generic function names
- Smart Enumeration: Focus on security-relevant functions
- Full Enumeration: Analyze every function in the binary
```
功能特性：
- 结构化元数据提取（代码行数、复杂度、操作）
- 语义搜索优化
- 基于意图的上下文组装
- 多向量支持，实现精准检索
### 5. 会话管理
保存和恢复分析会话：
```python
# Save progress
File → Save Session
# Load previous work
File → Load Session
# Auto-save after bulk operations
# Sessions include:
- Analyzed functions with summaries
- RAG vectors for semantic search
- Performance statistics
- UI state
```
---
## 后端设置
OGhidra 支持两种后端类型：
- **MCP** — 与 GhidraMCP 服务器集成，分析期间需要 Ghidra 客户端保持运行
- **PyGhidra** — 无需 Ghidra 客户端即可进行无头（headless）分析，并移除了 MCP 所需的服务器组件
### 选择后端
使用以下命令行选项选择后端：
```bash
--ghidra-backend={http,pyghidra}
```
| 后端选项 | 描述 |
|----------------|-------------|
| `http` | 使用 GhidraMCP 后端 |
| `pyghidra` | 使用 PyGhidra 后端 |
---
## PyGhidra 配置
### 使用现有 Ghidra 项目
启动 OGhidra 时指定 Ghidra 项目文件（`.gpr`）：
```bash
--pyghidra-project=/path/to/project.gpr
```
PyGhidra 需要有效的 Ghidra 项目才能启动 OGhidra。
---
### 选择程序
指定应分析 Ghidra 项目中的哪个二进制文件：
```bash
--pyghidra-program=<program_name>
```
在 Ghidra 项目中选择程序的示例调用：
```bash
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-project=/path/to/project.gpr --pyghidra-program=<program_name>
```
要求：
- 程序名称必须与 Ghidra 项目 GUI 中显示的名称完全一致
- 使用现有项目时必须指定此选项
- 未指定程序将导致 OGhidra 无法启动
---
### 直接启动二进制文件
您也可以直接提供二进制文件路径：
```bash
--pyghidra-binary=/path/to/binary
```
使用此选项时，PyGhidra 会自动：
1. 创建新的 Ghidra 项目（`.gpr`）
2. 导入二进制文件
3. 在 OGhidra 中启动该二进制文件以供分析
直接启动二进制文件的示例调用：
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-binary=/path/to/binary
---
## 常见工作流
### 分析可疑二进制文件
1. **在 Ghidra 中加载二进制文件**，并在 CodeBrowser 中打开
2. **启用 OGhidraMCP 插件**（File（文件）→ Configure（配置））
3. **启动 OGhidra**：`uv run main.py --ui`
4. **设置任务模式**：从下拉菜单中选择“malware”
5. **运行智能枚举**：点击“Rename All Functions（重命名所有函数）” → “Smart Enumeration（智能枚举）”
6. **提问**：“哪些是高危函数？”或者“显示网络通信”
### 生成安全报告
```bash
# In GUI: Click "Generate Report" button
# Report includes:
- Executive Summary
- Function Inventory (renamed functions with behavior)
- Security Analysis (high-risk functions, patterns)
- Import Analysis
- String Analysis
- Recommendations
```
### 调查特定函数
1. **在 Ghidra 中导航到该函数**
2. **点击“Analyze Current Function（分析当前函数）”**
3. **提出后续问题**：
- “这个函数是做什么的？”
- “它是否存在缓冲区溢出漏洞？”
- “还有哪些函数调用它？”
---
## 高级功能
### RAG（检索增强生成）
OGhidra 使用向量嵌入对已分析的函数进行语义搜索：
```env
# Enable in .env
RESULT_CACHE_ENABLED=true
TIERED_CONTEXT_ENABLED=true
```
优势：
- 跨会话记住之前的分析结果
- 通过语义查找相似函数
- 减少冗余的 LLM 调用
### 上下文优化
分层上下文压缩可保留相关信息：
```env
CURRENT_LOOP_MAX_CHARS=2000 # Recent: full detail
PREV_LOOP_MAX_CHARS=400 # Previous: summaries
OLDER_LOOP_MAX_CHARS=100 # Older: references only
```
### LLM 日志记录
跟踪所有 AI 交互以用于调试：
```env
LLM_LOGGING_ENABLED=true
LLM_LOG_FILE=logs/llm_interactions.log
LLM_LOG_FORMAT=json
```
---
## 故障排除
### Ghidra 连接问题
```bash
# Verify plugin is loaded
# Open up codebrowser!
# Check server is running
curl http://localhost:8080/methods
```
### Ollama 连接问题
```bash
# Verify Ollama is running
ollama list
# Check connectivity
curl http://localhost:11434/api/tags
# Restart Ollama service
ollama serve
```
### 空响应 / 上下文溢出
```env
# Reduce context budget
CONTEXT_BUDGET=50000
# Enable compaction
COMPACTION_ENABLED=true
COMPACTION_THRESHOLD=0.75
```
### 性能缓慢
1. **使用更小的模型**：切换到 `gemma3:9b`
2. **减少并行工作线程数**：在批量操作中设置 `max_workers=2`
3. **禁用向量嵌入**：`RESULT_CACHE_ENABLED=false`
4. **增大请求延迟**：`CUSTOM_API_REQUEST_DELAY=2.0`
---
## 架构概览
```
┌─────────────────────────────────────────────────────────────┐
│ OGhidra UI │
│ (GUI / Interactive CLI) │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Bridge (src/bridge.py) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ • Agentic Loop: Plan → Execute → Review → Replan │ │
│ │ • Tool Router: Ghidra client, LLM client, CAG manager │ │
│ │ • Context Manager: Budget allocation, compression │ │
│ └────────────────────────────────────────────────────────┘ │
└───────────┬────────────────────────┬────────────────────────┘
│ │
▼ ▼
┌───────────────────────┐ ┌─────────────────────────┐
│ Ghidra Client │ │ LLM Clients │
│ • GhidraMCP Plugin │ │ • Ollama (local) │
│ • Binary operations │ │ • External APIs │
│ • Decompilation │ │ • Custom endpoints │
└───────────────────────┘ └─────────────────────────┘
│ │
└────────────┬───────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ CAG Manager (Knowledge System) │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ • Vector Store: Semantic search over functions │ │
│ │ • Pattern Detector: 12+ malware techniques │ │
│ │ • Metadata Extractor: Structured function analysis │ │
│ │ • Session Store: Persistent analysis state │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## 贡献
我们欢迎各种贡献！感兴趣的方向包括：
- **新的恶意软件模式**（用于检测）
- **LLM 提供商集成**
- **UI/UX 改进**
- **性能优化**
- **文档**和示例
社区准则请参阅 [CODE_OF_CONDUCT.md](https://github.com/llnl/oghidra/blob/main/CODE_OF_CONDUCT.md)。
---
## 引用
如果您在研究中使用 OGhidra，请按以下方式引用：
```bibtex
@software{oghidra2025,
title = {OGhidra: AI-Powered Reverse Engineering with Ghidra},
author = {Enoch Wang},
year = {2025},
url = {https://github.com/LLNL/OGhidra}
}
```
---
## 致谢
OGhidra 基于以下出色的开源项目构建：
- **[Ghidra](https://github.com/NationalSecurityAgency/ghidra)** - NSA 的逆向工程平台
- **[Ollama](https://ollama.com/)** - 本地 LLM 运行时
- **[LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)** - 原始 Ghidra MCP 插件
- **[starsong/GhydraMCP](https://github.com/starsong/GhydraMCP)** - 增强版 MCP 实现
---
## 许可证
OGhidra 依据 BSD 3-Clause 许可证条款分发，并提供商业许可证替代方案。
详情请参阅 [LICENSE](https://github.com/llnl/oghidra/blob/main/LICENSE) 和 [NOTICE.md](https://github.com/llnl/oghidra/blob/main/NOTICE.md)。
**LLNL-CODE-2013290**
---
## 支持
- **问题反馈**：[GitHub Issues](https://github.com/LLNL/OGhidra/issues)
- **讨论交流**：[GitHub Discussions](https://github.com/LLNL/OGhidra/discussions)
- **也可直接给我发邮件**：[email protected]
