OGhidra conecta Modelos de Linguagem Grandes (LLMs) via Ollama com a plataforma de engenharia reversa Ghidra, possibilitando análise binária orientada por IA por meio de linguagem natural. Interaja com o Ghidra usando consultas conversacionais e automatize fluxos de trabalho complexos de engenharia reversa.
# OGhidra 3 - Engenharia Reversa com IA usando Ghidra
Para a versão que usa um Orchestrator inspirado no Claude, veja https://github.com/llnl/OGhidra/tree/orchestrator
**OGhidra** conecta Grandes Modelos de Linguagem à plataforma de engenharia reversa do Ghidra, permitindo análise binária orientada por IA através de linguagem natural. Analise binários de forma conversacional, automatize fluxos de trabalho complexos e mantenha privacidade total com modelos de IA locais.
Tutorial de Configuração no YouTube
[](https://www.youtube.com/watch?v=hBD92FUgR0Y)
---
## O que é OGhidra?
OGhidra aprimora o Ghidra com capacidades de IA, permitindo que você:
- **Análise em Linguagem Natural** - Faça perguntas sobre funções, strings e imports em inglês simples
- **Fluxos de Trabalho Automatizados** - Renomeie funções, detecte padrões, gere relatórios abrangentes
- **Modelos de IA Locais** - Privacidade completa com modelos rodando em seu hardware (Ollama)
- **Suporte a IA na Nuvem** - Conecte-se a APIs externas (OpenAI, Google Gemini, Anthropic Claude)
- **Detecção de Malware** - Correspondência automática de padrões para mais de 12 técnicas de evasão e injeção
- **Enumeração Inteligente** - Construa grafos de conhecimento consultáveis a partir da análise binária
- **Análise Multi-Instância** - Execute múltiplas instâncias do Ghidra para análise paralela
### Como Funciona
```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
```
**Loop Agente**: OGhidra usa um sistema de planejamento adaptativo. Após cada ciclo de execução, os resultados são revisados e a IA pode optar por coletar mais informações ou refinar sua análise antes de fornecer a resposta final.
---
## Início Rápido
### Pré-requisitos
1. **Python 3.12+** - Verifique a versão: `python --version`
2. **Ghidra 12.0.3** (Recomendado) - Baixe em [Ghidra Releases](https://github.com/NationalSecurityAgency/ghidra/releases)
- O caminho de construção/instalação do plugin está documentado para o Ghidra 12.0.3
- Testado com: Ghidra 11.0.3, 11.3.2, 12.0.2, 12.0.3
3. **Java 21** - Necessário para construir a extensão do Ghidra 12.0.3: `java -version`
4. **Ollama** (opcional, para modelos locais) - Instale de [ollama.com](https://ollama.com/)
### Instalação
```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
# Edite .env com suas configurações
```
### Configurar Plugin do Ghidra
As etapas de construção do plugin OGhidraMCP abaixo têm como alvo o Ghidra 12.0.3 (recomendado).
Há também um tutorial em vídeo no YouTube: https://www.youtube.com/watch?v=hBD92FUgR0Y
#### Construindo a Extensão GhidraMCP
Como desenvolvedor, você precisará construir a extensão GhidraMCP antes de instalá-la no Ghidra:
1. **Pré-requisitos**:
- Ghidra 12.0.3 instalado
- Java 21
2. **Opção 1: Usando os scripts de construção automatizados**:
- 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. **Opção 2: Processo de construção manual**:
- Crie/atualize `OGhidraMCP/gradle.properties` com o caminho de instalação do Ghidra:
```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. **Localize a extensão construída**:
- O arquivo zip da extensão é criado em `OGhidraMCP/dist/`
- O nome do arquivo será algo como `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`
#### Instalando a Extensão GhidraMCP
Após ter construído a extensão com sucesso:
1. **Instale no Ghidra**:
- Abra o Ghidra -> **File** -> **Install Extensions**
- Clique em **Add Extension** (ícone de mais verde)
- Navegue até o diretório `OGhidraMCP/dist/`
- Selecione o arquivo zip da extensão recém-construída (ex.: `ghidra_12.0.3_PUBLIC_YYYYMMDD_OGhidraMCP.zip`)
- Reinicie o Ghidra
2. **Ative o plugin**:
- Abra um projeto do Ghidra
- **File** → **Configure** → **Enable Developer**
- Ative o plugin `OGhidraMCP`
- O servidor iniciará em `http://localhost:8080/methods`
> **VOCÊ PRECISA TER O CODE BROWSER ABERTO**
### Baixar Modelos de IA
```bash
# Para Ollama (modelos locais)
ollama pull gemma3:27b # Bom equilíbrio (20GB RAM)
ollama pull nomic-embed-text # Modelo de embedding para RAG
# Modelos alternativos
ollama pull gpt-oss:120b # Alta qualidade (80GB RAM)
ollama pull devstral-2:123b # Alta qualidade (80GB RAM)
ollama pull devstral-2:123b-cloud # Modelo na Nuvem
```
### Iniciar OGhidra
```bash
# Modo GUI (recomendado)
uv run main.py --ui
# CLI Interativa
uv run main.py --interactive
# Na CLI interativa, teste a conexão
health
```
Se você iniciou o modo GUI, use:
```bash
curl http://localhost:8080/methods
```
---
## Configuração
Edite `.env` para configurar seu provedor de IA:
### Opção 1: Modelos Locais (Ollama)
```env
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434/
OLLAMA_MODEL=gemma3:27b
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
```
### Opção 2: APIs Externas
```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
```
### Opção 3: API Personalizada Compatível com 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
```
### Configurações de Gerenciamento de Contexto
Ajuste com base na janela de contexto do seu modelo:
```env
# Orçamento de contexto em tokens (ajuste conforme o limite do seu modelo)
CONTEXT_BUDGET=100000 # 100K tokens para modelos de médio porte
# 200K+ para modelos de ponta
# Configurações de execução
MAX_EXECUTION_STEPS=5 # Passos por ciclo de planejamento
MAX_AGENTIC_CYCLES=3 # Quantos ciclos de planejar-executar-revisar
AGENTIC_LOOP_ENABLED=true # Ativar replanejamento adaptativo
```
---
## Principais Funcionalidades
### 1. Botões de Ferramentas Inteligentes (GUI)
Acesso com um clique a tarefas comuns de engenharia reversa:
| Ferramenta | Descrição |
| ----------------------------- | ------------------------------------------------ |
| **Analyze Current Function** | Aprofundamento no comportamento da função selecionada |
| **Rename Current Function** | IA sugere nomes significativos com base na análise |
| **Rename All Functions** | Renomeação em massa com opções Smart/Full/Rename-Only |
| **Analyze Imports** | Identifica bibliotecas e dependências externas |
| **Analyze Strings** | Encontra URLs, credenciais, dados de configuração |
| **Generate Report** | Avaliação abrangente de segurança |
### 2. Modos de Tarefa
Defina metas de análise especializadas:
```python
# Na GUI: Use o menu suspenso "Task Mode"
# Na CLI: defina task_mode <mode>
task_mode malware # Análise de malware com detecção de padrões
task_mode vuln # Foco em pesquisa de vulnerabilidades
task_mode general # Engenharia reversa geral
```
### 3. Detecção de Padrões de Malware
Detecção automática de mais de 12 padrões de malware:
- **Evasão**: PEB Walking, Resolução Dinâmica de API, Anti-Debug, Anti-VM
- **Injeção**: Injeção de Processo (Local/Remoto)
- **Persistência**: Registro, Ganchos do Sistema de Arquivos
- **Ofuscação**: Codificação de Strings, Hashing de API
- **Escalação de Privilégios**: Manipulação de Token, bypass de UAC
Os padrões disparam alertas automáticos no contexto da IA com mapeamentos MITRE ATT&CK.
### 4. Enumeração Inteligente
Construa conhecimento rico e consultável a partir da análise binária:
```
# Enumere todas as funções com resumos da IA
# Escolha entre:
- Rename Only: Processa apenas nomes genéricos de funções
- Smart Enumeration: Foco em funções relevantes para segurança
- Full Enumeration: Analisa todas as funções no binário
```
Recursos:
- Extração de metadados estruturados (LOC, complexidade, operações)
- Otimização de busca semântica
- Montagem de contexto baseada em intenção
- Suporte a múltiplos vetores para recuperação precisa
### 5. Gerenciamento de Sessão
Salve e restaure sessões de análise:
```python
# Salvar progresso
File → Save Session
# Carregar trabalho anterior
File → Load Session
# Salvamento automático após operações em massa
# As sessões incluem:
- Funções analisadas com resumos
- Vetores RAG para busca semântica
- Estatísticas de desempenho
- Estado da interface
```
---
## Configuração do Backend
OGhidra suporta dois tipos de backend:
- **MCP** — Integra-se ao servidor GhidraMCP e requer que o cliente Ghidra esteja em execução durante a análise
- **PyGhidra** — Suporta análise headless sem o cliente Ghidra e remove o componente de servidor exigido pelo MCP
### Selecionando um Backend
Use a seguinte opção de linha de comando para escolher um backend:
```bash
--ghidra-backend={http,pyghidra}
```
| Opção de Backend | Descrição |
|------------------|-----------|
| `http` | Usa o backend GhidraMCP |
| `pyghidra` | Usa o backend PyGhidra |
---
## Configuração do PyGhidra
### Usando um Projeto Ghidra Existente
Especifique um arquivo de projeto Ghidra (`.gpr`) ao iniciar o OGhidra:
```bash
--pyghidra-project=/path/to/project.gpr
```
PyGhidra requer um projeto Ghidra válido para iniciar o OGhidra.
---
### Selecionando um Programa
Especifique qual binário dentro do projeto Ghidra deve ser analisado:
```bash
--pyghidra-program=<program_name>
```
exemplo de chamada para selecionar um programa em um projeto Ghidra:
```bash
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-project=/path/to/project.gpr --pyghidra-program=<program_name>
```
Requisitos:
- O nome do programa deve corresponder exatamente ao nome mostrado na GUI do projeto Ghidra
- Esta opção é necessária ao usar um projeto existente
- A falha em especificar um programa impedirá que o OGhidra seja iniciado
---
### Iniciando um Binário Diretamente
Você também pode fornecer um caminho de binário diretamente:
```bash
--pyghidra-binary=/path/to/binary
```
Quando esta opção é usada, PyGhidra automaticamente:
1. Cria um novo projeto Ghidra (`.gpr`)
2. Importa o binário
3. Inicia o binário no OGhidra para análise
exemplo de chamada para iniciar um binário diretamente:
uv run main.py --ui --ghidra-backend=pyghidra --pyghidra-binary=/path/to/binary
---
## Fluxos de Trabalho Comuns
### Analisar um Binário Suspeito
1. **Carregue o binário no Ghidra** e abra no CodeBrowser
2. **Ative o plugin OGhidraMCP** (File → Configure)
3. **Inicie o OGhidra**: `uv run main.py --ui`
4. **Defina o modo de tarefa**: Selecione "malware" no menu suspenso
5. **Execute a Enumeração Inteligente**: Clique em "Rename All Functions" → "Smart Enumeration"
6. **Faça perguntas**: "Quais são as funções de alto risco?" ou "Mostre-me comunicação de rede"
### Gerar Relatório de Segurança
```bash
# Na GUI: Clique no botão "Generate Report"
# O relatório inclui:
- Resumo Executivo
- Inventário de Funções (funções renomeadas com comportamento)
- Análise de Segurança (funções de alto risco, padrões)
- Análise de Imports
- Análise de Strings
- Recomendações
```
### Investigar Função Específica
1. **Navegue até a função no Ghidra**
2. **Clique em "Analyze Current Function"**
3. **Faça perguntas complementares**:
- "O que essa função faz?"
- "Isso é vulnerável a estouro de buffer?"
- "Que outras funções chamam isso?"
---
## Funcionalidades Avançadas
### RAG (Geração Aumentada por Recuperação)
OGhidra usa embeddings vetoriais para busca semântica sobre funções analisadas:
```env
# Ativar no .env
RESULT_CACHE_ENABLED=true
TIERED_CONTEXT_ENABLED=true
```
Benefícios:
- Lembrar análises anteriores entre sessões
- Encontrar funções semelhantes semanticamente
- Reduzir chamadas redundantes ao LLM
### Otimização de Contexto
A compressão de contexto em camadas mantém informações relevantes:
```env
CURRENT_LOOP_MAX_CHARS=2000 # Recente: detalhes completos
PREV_LOOP_MAX_CHARS=400 # Anterior: resumos
OLDER_LOOP_MAX_CHARS=100 # Mais antigo: apenas referências
```
### Registro de LLM
Rastreie todas as interações com IA para depuração:
```env
LLM_LOGGING_ENABLED=true
LLM_LOG_FILE=logs/llm_interactions.log
LLM_LOG_FORMAT=json
```
---
## Solução de Problemas
### Problemas de Conexão com o Ghidra
```bash
# Verifique se o plugin está carregado
# Abra o codebrowser!
# Verifique se o servidor está em execução
curl http://localhost:8080/methods
```
### Problemas de Conexão com o Ollama
```bash
# Verifique se o Ollama está em execução
ollama list
# Verifique a conectividade
curl http://localhost:11434/api/tags
# Reinicie o serviço do Ollama
ollama serve
```
### Respostas Vazias / Estouro de Contexto
```env
# Reduza o orçamento de contexto
CONTEXT_BUDGET=50000
# Ative a compactação
COMPACTION_ENABLED=true
COMPACTION_THRESHOLD=0.75
```
### Desempenho Lento
1. **Use modelos menores**: Mude para `gemma3:9b`
2. **Reduza workers paralelos**: Defina `max_workers=2` em operações em massa
3. **Desative embeddings vetoriais**: `RESULT_CACHE_ENABLED=false`
4. **Aumente o atraso da requisição**: `CUSTOM_API_REQUEST_DELAY=2.0`
---
## Visão Geral da Arquitetura
```
┌─────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
---
## Contribuindo
Aceitamos contribuições! Áreas de interesse:
- **Novos padrões de malware** para detecção
- **Integrações de provedores de LLM**
- **Melhorias de UI/UX**
- **Otimizações de desempenho**
- **Documentação** e exemplos
Veja [CODE_OF_CONDUCT.md](https://github.com/llnl/oghidra/blob/main/CODE_OF_CONDUCT.md) para as diretrizes da comunidade.
---
## Citação
Se você usar OGhidra em sua pesquisa, por favor cite:
```bibtex
@software{oghidra2025,
title = {OGhidra: AI-Powered Reverse Engineering with Ghidra},
author = {Enoch Wang},
year = {2025},
url = {https://github.com/LLNL/OGhidra}
}
```
---
## Agradecimentos
OGhidra se baseia em excelentes projetos de código aberto:
- **[Ghidra](https://github.com/NationalSecurityAgency/ghidra)** - Plataforma de engenharia reversa da NSA
- **[Ollama](https://ollama.com/)** - Runtime local de LLM
- **[LaurieWired/GhidraMCP](https://github.com/LaurieWired/GhidraMCP)** - Plugin Ghidra MCP original
- **[starsong/GhydraMCP](https://github.com/starsong/GhydraMCP)** - Implementação MCP aprimorada
---
## Licença
OGhidra é distribuído sob os termos da licença BSD 3-Clause com uma alternativa de licença comercial.
Veja [LICENSE](https://github.com/llnl/oghidra/blob/main/LICENSE) e [NOTICE.md](https://github.com/llnl/oghidra/blob/main/NOTICE.md) para detalhes.
**LLNL-CODE-2013290**
---
## Suporte
- **Issues**: [GitHub Issues](https://github.com/LLNL/OGhidra/issues)
- **Discussões**: [GitHub Discussions](https://github.com/LLNL/OGhidra/discussions)
- **Me Envie um E-mail Diretamente**: [email protected]