OGhidra collega i Grandi Modelli Linguistici (LLM) tramite Ollama con la piattaforma di reverse engineering Ghidra, consentendo l'analisi binaria basata sull'intelligenza artificiale attraverso il linguaggio naturale. Interagisci con Ghidra mediante query conversazionali e automatizza complessi flussi di lavoro di reverse engineering.
# OGhidra 3 - Reverse Engineering potenziato dall'IA con Ghidra
Per la versione che utilizza un Orchestrator ispirato a Claude, vedi https://github.com/llnl/OGhidra/tree/orchestrator
**OGhidra** collega i Large Language Models con la piattaforma di reverse engineering di Ghidra, consentendo l'analisi binaria guidata dall'IA attraverso il linguaggio naturale. Analizza i binari in modo conversazionale, automatizza flussi di lavoro complessi e mantieni la completa privacy con modelli IA locali.
Tutorial di Configurazione su YouTube
[](https://www.youtube.com/watch?v=hBD92FUgR0Y)
---
## Cos'è OGhidra?
OGhidra potenzia Ghidra con funzionalità IA, permettendoti di:
- **Analisi in Linguaggio Naturale** - Fai domande su funzioni, stringhe e importazioni in un inglese semplice
- **Flussi di Lavoro Automatizzati** - Rinomina funzioni, rileva pattern, genera report completi
- **Modelli IA Locali** - Privacy completa con modelli eseguiti sul tuo hardware (Ollama)
- **Supporto IA Cloud** - Connettiti a API esterne (OpenAI, Google Gemini, Anthropic Claude)
- **Rilevamento Malware** - Pattern matching automatico per oltre 12 tecniche di evasione e iniezione
- **Enumerazione Intelligente** - Costruisci grafi di conoscenza interrogabili dall'analisi binaria
- **Analisi Multi-Istanza** - Esegui più istanze di Ghidra per l'analisi parallela
### Come Funziona
```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
```
**Ciclo Agentico**: OGhidra utilizza un sistema di pianificazione adattivo. Dopo ogni ciclo di esecuzione, i risultati vengono revisionati e l'IA può scegliere di raccogliere ulteriori informazioni o affinare la propria analisi prima di fornire la risposta finale.
---
## Avvio Rapido
### Prerequisiti
1. **Python 3.12+** - Controlla la versione: `python --version`
2. **Ghidra 12.0.3** (Consigliata) - Scarica da [Ghidra Releases](https://github.com/NationalSecurityAgency/ghidra/releases)
- Il percorso di build/installazione del plugin è documentato per Ghidra 12.0.3
- Testata con: Ghidra 11.0.3, 11.3.2, 12.0.2, 12.0.3
3. **Java 21** - Richiesto per compilare l'estensione di Ghidra 12.0.3: `java -version`
4. **Ollama** (opzionale, per modelli locali) - Installa da [ollama.com](https://ollama.com/)
### Installazione
```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
```
### Configurazione del Plugin Ghidra
I passaggi di build del plugin OGhidraMCP riportati di seguito riguardano Ghidra 12.0.3 (consigliata).
C'è anche un tutorial video su YouTube: https://www.youtube.com/watch?v=hBD92FUgR0Y
#### Compilazione dell'Estensione GhidraMCP
In qualità di sviluppatore, dovrai compilare l'estensione GhidraMCP prima di installarla in Ghidra:
1. **Prerequisiti**:
- Ghidra 12.0.3 installata
- Java 21
2. **Opzione 1: Utilizzo degli script di build automatizzati**:
- 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. **Opzione 2: Processo di build manuale**:
- Crea/aggiorna `OGhidraMCP/gradle.properties` con il percorso della tua installazione di Ghidra:
```properties
GHIDRA_INSTALL_DIR=/absolute/path/to/ghidra_12.0.3_PUBLIC
```
- Su Unix/Linux/macOS:
```bash
cd OGhidraMCP
$GHIDRA_INSTALL_DIR/support/gradle/gradlew buildExtension --info
```
- Su Windows:
```bat
cd OGhidraMCP
"%GHIDRA_INSTALL_DIR%\support\gradle\gradlew.bat" buildExtension --info
```
4. **Individua l'estensione compilata**:
- Il file zip dell'estensione viene creato in `OGhidraMCP/dist/`
- Il nome del file sarà simile a `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`
#### Installazione dell'Estensione GhidraMCP
Dopo aver compilato con successo l'estensione:
1. **Installa in Ghidra**:
- Apri Ghidra -> **File** -> **Install Extensions**
- Clicca su **Add Extension** (icona più verde)
- Sfoglia fino alla directory `OGhidraMCP/dist/`
- Seleziona il file zip dell'estensione appena compilata (ad es., `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`)
- Riavvia Ghidra
2. **Abilita il plugin**:
- Apri un progetto Ghidra
- **File** → **Configure** → **Enable Developer**
- Abilita il plugin `OGhidraMCP`
- Il server si avvierà su `http://localhost:8080/methods`
> **È NECESSARIO AVERE IL CODE BROWSER APERTO**
### Download dei Modelli IA
```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
```
### Avvio di OGhidra
```bash
# GUI Mode (recommended)
uv run main.py --ui
# Interactive CLI
uv run main.py --interactive
# In interactive CLI, test connection
health
```
Se hai avviato la modalità GUI, usa:
```bash
curl http://localhost:8080/methods
```
---
## Configurazione
Modifica `.env` per configurare il tuo provider IA:
### Opzione 1: Modelli Locali (Ollama)
```env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/
OLLAMA_MODEL=gemma3:27b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```
### Opzione 2: API Esterne
```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
```
### Opzione 3: API Personalizzata Compatibile con OpenAI
```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
```
### Impostazioni di Gestione del Contesto
Regola in base alla finestra di contesto del tuo modello:
```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
```
---
## Funzionalità Principali
### 1. Pulsanti Strumento Intelligenti (GUI)
Accesso con un clic alle comuni attività di reverse engineering:
| Tool | Descrizione |
| ---------------------------- | ----------------------------------------------- |
| **Analyze Current Function** | Analisi approfondita del comportamento della funzione selezionata |
| **Rename Current Function** | L'IA suggerisce nomi significativi in base all'analisi |
| **Rename All Functions** | Rinomina in blocco con opzioni Smart/Full/Rename-Only |
| **Analyze Imports** | Identifica librerie e dipendenze esterne |
| **Analyze Strings** | Trova URL, credenziali e dati di configurazione |
| **Generate Report** | Valutazione completa della sicurezza |
### 2. Modalità Task
Imposta obiettivi di analisi specializzati:
```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. Rilevamento di Pattern Malware
Rilevamento automatico di oltre 12 pattern di malware:
- **Evasione**: PEB Walking, Dynamic API Resolution, Anti-Debug, Anti-VM
- **Iniezione**: Process Injection (Locale/Remota)
- **Persistenza**: Registry, File System Hooks
- **Offuscamento**: String Encoding, API Hashing
- **Escalation dei Privilegi**: Manipolazione dei token, bypass UAC
I pattern attivano avvisi automatici nel contesto dell'IA con i mapping MITRE ATT&CK.
### 4. Enumerazione Intelligente
Costruisci una conoscenza ricca e interrogabile dall'analisi binaria:
```
# 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
```
Caratteristiche:
- Estrazione di metadati strutturati (LOC, complessità, operazioni)
- Ottimizzazione della ricerca semantica
- Assemblaggio del contesto basato sull'intento
- Supporto multi-vettore per un recupero preciso
### 5. Gestione delle Sessioni
Salva e ripristina le sessioni di analisi:
```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
```
---
## Configurazione del Backend
OGhidra supporta due tipi di backend:
- **MCP** — Si integra con il server GhidraMCP e richiede che il client Ghidra sia in esecuzione durante l'analisi
- **PyGhidra** — Supporta l'analisi headless senza il client Ghidra ed elimina il componente server richiesto da MCP
### Selezione di un Backend
Usa la seguente opzione da riga di comando per scegliere un backend:
```bash
--ghidra-backend={http,pyghidra}
```
| Backend Option | Descrizione |
|----------------|-------------|
| `http` | Usa il backend GhidraMCP |
| `pyghidra` | Usa il backend PyGhidra |
---
## Configurazione di PyGhidra
### Utilizzo di un Progetto Ghidra Esistente
Specifica un file di progetto Ghidra (`.gpr`) all'avvio di OGhidra:
```bash
--pyghidra-project=/path/to/project.gpr
```
PyGhidra richiede un progetto Ghidra valido per avviare OGhidra.
---
### Selezione di un Programma
Specifica quale binario all'interno del progetto Ghidra deve essere analizzato:
```bash
--pyghidra-program=<program_name>
```
esempio di comando per selezionare un programma in un progetto Ghidra:
```bash
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-project=/path/to/project.gpr --pyghidra-program=<program_name>
```
Requisiti:
- Il nome del programma deve corrispondere esattamente al nome mostrato nella GUI del progetto Ghidra
- Questa opzione è obbligatoria quando si utilizza un progetto esistente
- La mancata specifica di un programma impedirà l'avvio di OGhidra
---
### Avvio Diretto di un Binario
Puoi anche fornire direttamente il percorso di un binario:
```bash
--pyghidra-binary=/path/to/binary
```
Quando si utilizza questa opzione, PyGhidra automaticamente:
1. Crea un nuovo progetto Ghidra (`.gpr`)
2. Importa il binario
3. Apre il binario in OGhidra per l'analisi
esempio di comando per avviare direttamente un binario:
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-binary=/path/to/binary
---
## Flussi di Lavoro Comuni
### Analizzare un Binario Sospetto
1. **Carica il binario in Ghidra** e aprilo nel CodeBrowser
2. **Abilita il plugin OGhidraMCP** (File → Configure)
3. **Avvia OGhidra**: `uv run main.py --ui`
4. **Imposta la modalità task**: seleziona "malware" dal menu a tendina
5. **Esegui la Smart Enumeration**: clicca su "Rename All Functions" → "Smart Enumeration"
6. **Fai domande**: "Quali sono le funzioni ad alto rischio?" oppure "Mostrami le comunicazioni di rete"
### Generare un Report di Sicurezza
```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
```
### Indagare su una Funzione Specifica
1. **Naviga fino alla funzione in Ghidra**
2. **Clicca su "Analyze Current Function"**
3. **Fai domande di approfondimento**:
- "Cosa fa questa funzione?"
- "È vulnerabile a un buffer overflow?"
- "Quali altre funzioni chiamano questa?"
---
## Funzionalità Avanzate
### RAG (Retrieval-Augmented Generation)
OGhidra utilizza embedding vettoriali per la ricerca semantica sulle funzioni analizzate:
```env
# Enable in .env
RESULT_CACHE_ENABLED=true
TIERED_CONTEXT_ENABLED=true
```
Vantaggi:
- Ricorda le analisi precedenti tra le sessioni
- Trova funzioni simili a livello semantico
- Riduce le chiamate LLM ridondanti
### Ottimizzazione del Contesto
La compressione del contesto a livelli conserva le informazioni rilevanti:
```env
CURRENT_LOOP_MAX_CHARS=2000 # Recent: full detail
PREV_LOOP_MAX_CHARS=400 # Previous: summaries
OLDER_LOOP_MAX_CHARS=100 # Older: references only
```
### Registrazione Log LLM
Traccia tutte le interazioni IA per il debug:
```env
LLM_LOGGING_ENABLED=true
LLM_LOG_FILE=logs/llm_interactions.log
LLM_LOG_FORMAT=json
```
---
## Risoluzione dei Problemi
### Problemi di Connessione con Ghidra
```bash
# Verify plugin is loaded
# Open up codebrowser!
# Check server is running
curl http://localhost:8080/methods
```
### Problemi di Connessione con Ollama
```bash
# Verify Ollama is running
ollama list
# Check connectivity
curl http://localhost:11434/api/tags
# Restart Ollama service
ollama serve
```
### Risposte Vuote / Overflow del Contesto
```env
# Reduce context budget
CONTEXT_BUDGET=50000
# Enable compaction
COMPACTION_ENABLED=true
COMPACTION_THRESHOLD=0.75
```
### Prestazioni Lente
1. **Usa modelli più piccoli**: passa a `gemma3:9b`
2. **Riduci i worker paralleli**: imposta `max_workers=2` nelle operazioni in blocco
3. **Disabilita gli embedding vettoriali**: `RESULT_CACHE_ENABLED=false`
4. **Aumenta il ritardo delle richieste**: `CUSTOM_API_REQUEST_DELAY=2.0`
---
## Panoramica dell'Architettura
```
┌─────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## Come Contribuire
Accogliamo con piacere i contributi! Aree di interesse:
- **Nuovi pattern di malware** per il rilevamento
- **Integrazioni di provider LLM**
- **Miglioramenti UI/UX**
- **Ottimizzazioni delle prestazioni**
- **Documentazione** ed esempi
Consulta [CODE_OF_CONDUCT.md](https://github.com/llnl/oghidra/blob/main/CODE_OF_CONDUCT.md) per le linee guida della community.
---
## Citazione
Se utilizzi OGhidra nella tua ricerca, ti preghiamo di citare:
```bibtex
@software{oghidra2025,
title = {OGhidra: AI-Powered Reverse Engineering with Ghidra},
author = {Enoch Wang},
year = {2025},
url = {https://github.com/LLNL/OGhidra}
}
```
---
## Riconoscimenti
OGhidra si basa su eccellenti progetti open-source:
- **[Ghidra](https://github.com/NationalSecurityAgency/ghidra)** - La piattaforma di reverse engineering della NSA
- **[Ollama](https://ollama.com/)** - Runtime LLM locale
- **[LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)** - Plugin Ghidra MCP originale
- **[starsong/GhydraMCP](https://github.com/starsong/GhydraMCP)** - Implementazione MCP migliorata
---
## Licenza
OGhidra è distribuito secondo i termini della licenza BSD 3-Clause, con un'alternativa di licenza commerciale.
Consulta [LICENSE](https://github.com/llnl/oghidra/blob/main/LICENSE) e [NOTICE.md](https://github.com/llnl/oghidra/blob/main/NOTICE.md) per i dettagli.
**LLNL-CODE-2013290**
---
## Supporto
- **Issues**: [GitHub Issues](https://github.com/LLNL/OGhidra/issues)
- **Discussioni**: [GitHub Discussions](https://github.com/LLNL/OGhidra/discussions)
- **Scrivimi direttamente via email**: [email protected]