Metadata-Version: 2.5
Name: oghidra
Version: 0.0.0
Summary: AI-Powered Reverse Engineering with Ghidra - Bridge LLMs via Ollama with Ghidra for natural language binary analysis
Project-URL: Homepage, https://github.com/llnl/OGhidra
Project-URL: Repository, https://github.com/llnl/OGhidra
Project-URL: Issues, https://github.com/llnl/OGhidra/issues
Author-email: ezrealenoch <enochsurge@gmail.com>
License: BSD-3-Clause
License-File: LICENSE
License-File: NOTICE.md
Keywords: ai,binary-analysis,ghidra,llm,ollama,reverse-engineering,security
Requires-Python: >=3.12
Requires-Dist: flask<3.1,>=3.0.3
Requires-Dist: httpx>=0.24.0
Requires-Dist: ijson>=3.2.0
Requires-Dist: matplotlib-stubs>=0.3.11
Requires-Dist: numpy>=1.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings>=2.2.1
Requires-Dist: pydantic>=2.7.1
Requires-Dist: pyghidra>=3.0.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.26.0
Requires-Dist: rich>=13.7.1
Requires-Dist: tenacity>=9.0.0
Requires-Dist: ttkbootstrap>=1.10.0
Description-Content-Type: text/markdown

# OGhidra 3 - AI-Powered Reverse Engineering with Ghidra

For the version using a Claude-inspired Orchestrator, see https://github.com/llnl/OGhidra/tree/orchestrator

![Python Version](https://img.shields.io/badge/python-3.12%2B-blue?logo=python)
![License](https://img.shields.io/badge/license-BSD--3--Clause-green)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)

**OGhidra** bridges Large Language Models with Ghidra's reverse engineering platform, enabling AI-driven binary analysis through natural language. Analyze binaries conversationally, automate complex workflows, and maintain complete privacy with local AI models.

YouTube Setup Tutorial

[![OGhidra Introduction](https://img.youtube.com/vi/hBD92FUgR0Y/0.jpg)](https://www.youtube.com/watch?v=hBD92FUgR0Y)

---

## What is OGhidra?

OGhidra enhances Ghidra with AI capabilities, allowing you to:

- **Natural Language Analysis** - Ask questions about functions, strings, imports in plain English
- **Automated Workflows** - Rename functions, detect patterns, generate comprehensive reports
- **Local AI Models** - Complete privacy with models running on your hardware (Ollama)
- **Cloud AI Support** - Connect to external APIs (OpenAI, Google Gemini, Anthropic Claude)
- **Malware Detection** - Automatic pattern matching for 12+ evasion and injection techniques
- **Smart Enumeration** - Build queryable knowledge graphs from binary analysis
- **Multi-Instance Analysis** - Run multiple Ghidra instances for parallel analysis

### How It Works

```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 uses an adaptive planning system. After each execution cycle, results are reviewed and the AI can choose to gather more information or refine its analysis before providing the final response.

---

## Quick Start

### Prerequisites

1. **Python 3.12+** - Check version: `python --version`
2. **Ghidra 12.0.3** (Recommended) - Download from [Ghidra Releases](https://github.com/NationalSecurityAgency/ghidra/releases)
   - Plugin build/install path is documented for Ghidra 12.0.3
   - Tested with: Ghidra 11.0.3, 11.3.2, 12.0.2, 12.0.3
3. **Java 21** - Required to build the Ghidra 12.0.3 extension: `java -version`
4. **Ollama** (optional, for local models) - Install from [ollama.com](https://ollama.com/)

### Installation

```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
```

### Setup Ghidra Plugin

The OGhidraMCP plugin build steps below target Ghidra 12.0.3 (recommended).
There's also a YouTube video tutorial: https://www.youtube.com/watch?v=hBD92FUgR0Y

#### Building the GhidraMCP Extension

As a developer, you'll need to build the GhidraMCP extension before installing it in Ghidra:

1. **Prerequisites**:
   - Ghidra 12.0.3 installed
   - Java 21

2. **Option 1: Using the automated build scripts**:
   - 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. **Option 2: Manual build process**:
   - Create/update `OGhidraMCP/gradle.properties` with your Ghidra install path:

     ```properties
     GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.0.3_PUBLIC
     ```

   - On Unix/Linux/macOS:
     ```bash
     cd OGhidraMCP
     $GHIDRA_INSTALL_DIR/support/gradle/gradlew buildExtension --info
     ```

   - On Windows:
     ```bat
     cd OGhidraMCP
     "%GHIDRA_INSTALL_DIR%\support\gradle\gradlew.bat" buildExtension --info
     ```

4. **Locate the built extension**:
   - The extension zip file is created in `OGhidraMCP/dist/`
   - The filename will be something like `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`

#### Installing the GhidraMCP Extension

Once you've successfully built the extension:

1. **Install in Ghidra**:
   - Open Ghidra -> **File** -> **Install Extensions**
   - Click **Add Extension** (green plus icon)
   - Browse to your `OGhidraMCP/dist/` directory
   - Select the newly built extension zip file (e.g., `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`)
   - Restart Ghidra

2. **Enable the plugin**:
   - Open a Ghidra project
   - **File** → **Configure** → **Enable Developer**
   - Enable the `OGhidraMCP` plugin
   - The server will start on `http://localhost:8080/methods`

   > **YOU NEED TO HAVE CODE BROWSER OPEN**

### Pull AI Models

```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
```

### Launch OGhidra

```bash
# GUI Mode (recommended)
uv run main.py --ui

# Interactive CLI
uv run main.py --interactive

# In interactive CLI, test connection
health
```

If you launched GUI mode, use:
```bash
curl http://localhost:8080/methods
```

---

## Configuration

Edit `.env` to configure your AI provider:

### Option 1: Local Models (Ollama)

```env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/
OLLAMA_MODEL=gemma3:27b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```

### Option 2: External APIs

```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
```

### Option 3: Custom OpenAI-Compatible 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
```

### Context Management Settings

Adjust based on your model's context window:

```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
```

---

## Key Features

### 1. Smart Tool Buttons (GUI)

One-click access to common reverse engineering tasks:

| Tool                         | Description                                     |
| ---------------------------- | ----------------------------------------------- |
| **Analyze Current Function** | Deep dive into selected function's behavior     |
| **Rename Current Function**  | AI suggests meaningful names based on analysis  |
| **Rename All Functions**     | Bulk rename with Smart/Full/Rename-Only options |
| **Analyze Imports**          | Identify libraries and external dependencies    |
| **Analyze Strings**          | Find URLs, credentials, configuration data      |
| **Generate Report**          | Comprehensive security assessment               |

### 2. Task Modes

Set specialized analysis goals:

```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. Malware Pattern Detection

Automatic detection of 12+ malware patterns:
- **Evasion**: PEB Walking, Dynamic API Resolution, Anti-Debug, Anti-VM
- **Injection**: Process Injection (Local/Remote)
- **Persistence**: Registry, File System Hooks
- **Obfuscation**: String Encoding, API Hashing
- **Privilege Escalation**: Token manipulation, UAC bypass

Patterns trigger automatic alerts in the AI's context with MITRE ATT&CK mappings.

### 4. Smart Enumeration

Build rich, queryable knowledge from binary analysis:

```
# 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
```

Features:
- Structured metadata extraction (LOC, complexity, operations)
- Semantic search optimization
- Intent-based context assembly
- Multi-vector support for precise retrieval

### 5. Session Management

Save and restore analysis sessions:

```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
```

---

## Backend Setup

OGhidra supports two backend types:

- **MCP** — Integrates with the GhidraMCP server and requires the Ghidra client to be running during analysis
- **PyGhidra** — Supports headless analysis without the Ghidra client and removes the server component required by MCP

### Selecting a Backend

Use the following command-line option to choose a backend:

```bash
--ghidra-backend={http,pyghidra}
```

| Backend Option | Description |
|----------------|-------------|
| `http` | Uses the GhidraMCP backend |
| `pyghidra` | Uses the PyGhidra backend |

---

## PyGhidra Configuration

### Using an Existing Ghidra Project

Specify a Ghidra project file (`.gpr`) when launching OGhidra:

```bash
--pyghidra-project=/path/to/project.gpr
```

PyGhidra requires a valid Ghidra project in order to launch OGhidra.

---

### Selecting a Program

Specify which binary inside the Ghidra project should be analyzed:

```bash
--pyghidra-program=<program_name>
```

example call for selecting a program in a Ghidra project:

```bash
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-project=/path/to/project.gpr --pyghidra-program=<program_name>
```

Requirements:

- The program name must exactly match the name shown in the Ghidra project GUI
- This option is required when using an existing project
- Failure to specify a program will prevent OGhidra from launching

---

### Launching a Binary Directly

You can also provide a binary path directly:

```bash
--pyghidra-binary=/path/to/binary
```

When this option is used, PyGhidra automatically:

1. Creates a new Ghidra project (`.gpr`)
2. Imports the binary
3. Launches the binary in OGhidra for analysis

example call for launching a binary directly:

uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-binary=/path/to/binary

---

## Common Workflows

### Analyze a Suspicious Binary

1. **Load binary in Ghidra** and open in CodeBrowser
2. **Enable OGhidraMCP plugin** (File → Configure)
3. **Launch OGhidra**: `uv run main.py --ui`
4. **Set task mode**: Select "malware" from dropdown
5. **Run Smart Enumeration**: Click "Rename All Functions" → "Smart Enumeration"
6. **Ask questions**: "What are the high-risk functions?" or "Show me network communication"

### Generate Security Report

```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
```

### Investigate Specific Function

1. **Navigate to function in Ghidra**
2. **Click "Analyze Current Function"**
3. **Ask follow-up questions**:
   - "What does this function do?"
   - "Is this vulnerable to buffer overflow?"
   - "What other functions call this?"

---

## Advanced Features

### RAG (Retrieval-Augmented Generation)

OGhidra uses vector embeddings for semantic search over analyzed functions:

```env
# Enable in .env
RESULT_CACHE_ENABLED=true
TIERED_CONTEXT_ENABLED=true
```

Benefits:
- Remember previous analysis across sessions
- Find similar functions semantically
- Reduce redundant LLM calls


### Context Optimization

Tiered context compression keeps relevant information:

```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 Logging

Track all AI interactions for debugging:

```env
LLM_LOGGING_ENABLED=true
LLM_LOG_FILE=logs/llm_interactions.log
LLM_LOG_FORMAT=json
```

---

## Troubleshooting

### Ghidra Connection Issues

```bash
# Verify plugin is loaded
# Open up codebrowser!

# Check server is running
curl http://localhost:8080/methods
```


### Ollama Connection Issues

```bash
# Verify Ollama is running
ollama list

# Check connectivity
curl http://localhost:11434/api/tags

# Restart Ollama service
ollama serve
```

### Empty Responses / Context Overflow

```env
# Reduce context budget
CONTEXT_BUDGET=50000

# Enable compaction
COMPACTION_ENABLED=true
COMPACTION_THRESHOLD=0.75
```

### Slow Performance

1. **Use smaller models**: Switch to `gemma3:9b`
2. **Reduce parallel workers**: Set `max_workers=2` in bulk operations
3. **Disable vector embeddings**: `RESULT_CACHE_ENABLED=false`
4. **Increase request delay**: `CUSTOM_API_REQUEST_DELAY=2.0`

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                        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             │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## Contributing

We welcome contributions! Areas of interest:

- **New malware patterns** for detection
- **LLM provider integrations**
- **UI/UX improvements**
- **Performance optimizations**
- **Documentation** and examples

See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

---

## Citation

If you use OGhidra in your research, please cite:

```bibtex
@software{oghidra2025,
  title = {OGhidra: AI-Powered Reverse Engineering with Ghidra},
  author = {Enoch Wang},
  year = {2025},
  url = {https://github.com/LLNL/OGhidra}
}
```

---

## Acknowledgments

OGhidra builds upon excellent open-source projects:

- **[Ghidra](https://github.com/NationalSecurityAgency/ghidra)** - NSA's reverse engineering platform
- **[Ollama](https://ollama.com/)** - Local LLM runtime
- **[LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)** - Original Ghidra MCP plugin
- **[starsong/GhydraMCP](https://github.com/starsong/GhydraMCP)** - Enhanced MCP implementation

---

## License

OGhidra is distributed under the terms of the BSD 3-Clause license with a commercial license alternative.

See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md) for details.

**LLNL-CODE-2013290**

---

## Support

- **Issues**: [GitHub Issues](https://github.com/LLNL/OGhidra/issues)
- **Discussions**: [GitHub Discussions](https://github.com/LLNL/OGhidra/discussions)
- **Just Email Me Directly**: enochsurge@gmail.com
