Ghidra MCP Server

Se trovi utile questo progetto, metti ⭐ una stella al repository — aiuta altri a scoprirlo!

Se Ghidra MCP ti fa risparmiare tempo, considera di sponsorizzare il progetto. Il supporto una tantum e ricorrente aiuta a finanziare aggiornamenti di compatibilità, rafforzamento della produzione, documentazione e nuovi strumenti.

Un server Model Context Protocol (MCP) pronto per la produzione che collega le potenti capacità di reverse engineering di Ghidra con gli strumenti AI moderni e i framework di automazione. 271 strumenti MCP, workflow AI testati sul campo e la più completa integrazione Ghidra-MCP disponibile — ora con emulazione P-code, integrazione del debugger live e analisi del flusso di dati con PCode-graph.

Perché Ghidra MCP?

La maggior parte delle implementazioni Ghidra MCP offre una manciata di strumenti di sola lettura e basta. Questo progetto è diverso — è stato costruito da un reverse engineer che lo usa quotidianamente su binari reali, non come demo.

• 271 strumenti MCP — 3 volte più di qualsiasi altra implementazione concorrente. Non solo operazioni di lettura — accesso completo in scrittura per rinominare, tipizzare, commentare, creare strutture, eseguire script, emulare P-code e fare debug live.
• Workflow AI testati sul campo — Workflow di documentazione collaudati (V5) perfezionati su centinaia di funzioni. Include prompt passo-passo, riferimento alla notazione ungherese, guide per l'elaborazione batch e scoperta di codice orfano.
• Affidabilità da produzione — Transazioni atomiche, operazioni batch (93% di riduzione delle chiamate API), timeout configurabili e gestione elegante degli errori. Nessun fallimento silenzioso.
• Trasferimento di documentazione tra binari — L'hash delle funzioni SHA-256 propaga automaticamente la documentazione tra versioni del binario. Documenta una volta, applica ovunque.
• Integrazione completa con Ghidra Server — Collegati a server Ghidra condivisi, gestisci repository, versionamento, workflow di checkout/checkin e collaborazione multi-utente.
• Modalità headless e GUI — Esegui con o senza interfaccia grafica di Ghidra. Pronto per Docker in pipeline CI/CD e analisi automatizzate su larga scala.
• Opinionato per progettazione — v5.0 sposta le convenzioni di denominazione, la sicurezza dei tipi e gli standard di documentazione nel layer degli strumenti. Agenti AI e ingegneri umani producono output coerenti senza guide di stile in ogni prompt.

Applicazione delle convenzioni

Ti è mai capitato: sei mesi in un progetto e trovi ProcessItem, process_items, handleItem e ItemProc nella stessa codebase — quattro funzioni che fanno la stessa cosa, nominate da quattro sessioni o ingegneri diversi senza un contratto condiviso. Risolvere il problema richiede più tempo del dovuto, e il problema si ripresenterà.

v5.0 sposta le convenzioni da "cose da ricordare" nel layer degli strumenti, dove possono essere effettivamente applicate.

Per gli agenti AI, questo significa output coerente in ogni sessione, ogni modello, ogni esecuzione — senza dover incollare una guida di stile in ogni prompt. Lo strumento conosce le regole; il modello deve solo prendere la decisione.

Per i team, elimina l'intera classe di commenti in revisione che dice "questa non è la nostra convenzione di denominazione." L'arbitraggio delle convenzioni rimane nello strumento, non nella revisione del codice.

Per il lavoro individuale su larga scala, analyze_function_completeness restituisce un punteggio 0–100% che misura onestamente: le deduzioni strutturali (artefatti del compilatore non correggibili) vengono perdonate nel tuo punteggio effettivo, la scala logaritmica impedisce a una singola categoria negativa di seppellire tutto il resto, e la qualità dei commenti a livelli ti dice esattamente cosa manca e perché.

🌟 Caratteristiche

Integrazione MCP principale

• Piena compatibilità MCP — Implementazione completa del Model Context Protocol
• 271 strumenti MCP — Superficie API completa che copre ogni aspetto dell'analisi binaria
• Affidabilità da produzione — Transazioni atomiche, operazioni batch, timeout configurabili
• Analisi in tempo reale — Integrazione live con il motore di analisi di Ghidra

Nota sulla compatibilità: I nomi degli strumenti MCP sono normalizzati per GitHub Copilot CLI e la validazione CAPI. I nomi degli strumenti esposti usano solo lettere minuscole, cifre, underscore e trattini; i percorsi HTTP annidati come /debugger/status vengono pubblicizzati come nomi come debugger_status_2 quando necessario per evitare collisioni con gli strumenti bridge statici.

Capacità di analisi binaria

• Analisi delle funzioni — Decompilazione, grafi delle chiamate, cross-reference, punteggio di completezza
• Analisi del flusso di dati — Propagazione dei valori PCode-graph (avanti / indietro) da qualsiasi variabile o registro
• Scoperta di strutture dati — Creazione di struct/union/enum con analisi dei campi e suggerimenti di denominazione
• Estrazione di stringhe — Ricerca regex, filtraggio della qualità, scoperta di funzioni ancorate a stringhe
• Analisi import/export — Tabelle dei simboli, locazioni esterne, risoluzione import ordinali
• Ispezione memoria e dati — Letture raw di memoria, ricerca di pattern di byte, rilevamento dei confini degli array
• Documentazione tra binari — Hash delle funzioni e propagazione della documentazione tra versioni

Analisi dinamica (v5.4.0)

• Emulazione P-code — Esegui qualsiasi funzione in isolamento tramite EmulatorHelper di Ghidra; risolvi brute-force hash API in millisecondi
• Integrazione debugger live — 17 endpoint Java + 22 strumenti bridge Python tramite il framework TraceRmi di Ghidra (dbgeng su Windows PE, gdb/lldb altrimenti): attach, step, breakpoint, registri, letture memoria, tracciamento di funzioni non bloccante, traduzione di indirizzi statici↔dinamici con supporto ASLR

Workflow di reverse engineering basati su AI

• Workflow di documentazione delle funzioni V5 — Processo in 7 passi per la documentazione completa delle funzioni con notazione ungherese, audit dei tipi e punteggio di verifica automatica
• Documentazione batch — Invio di sotto-agenti paralleli per documentare più funzioni contemporaneamente
• Scoperta di codice orfano — Scanner automatico che trova funzioni nascoste negli spazi tra codice noto
• Indagine sui tipi di dati — Workflow sistematici per scoprire strutture e analizzare i campi
• Corrispondenza tra versioni — Hash delle funzioni per abbinare funzioni tra diverse versioni del binario

Sviluppo e automazione

• Gestione script Ghidra — Crea, esegui, aggiorna ed elimina script Ghidra interamente tramite MCP
• Supporto multi-programma — Passa da un programma all'altro e confrontane più aperti
• Operazioni batch — Ridenominazione, commenti, tipizzazione e gestione delle etichette in blocco (93% in meno di chiamate API)
• Server headless — Analisi completa senza interfaccia grafica Ghidra — pronto per Docker e CI/CD
• Progetto e versionamento — Crea progetti, gestisci file, integrazione con Ghidra Server
• Controllo delle analisi — Elenca, configura e attiva gli analizzatori di Ghidra a livello di programmazione

🚀 Avvio rapido

Prerequisiti

• Java 21 LTS (consigliato OpenJDK)
• Apache Maven 3.9+
• Ghidra 12.1.2 (o versione compatibile)
• Python 3.10+ con uv (consigliato) o pip + venv

Utenti di Ghidra Server condiviso: i client Ghidra 12.1.2 richiedono un Ghidra Server alla versione 12.1, 12.0.5 o una versione più recente compatibile. Aggiorna il server prima di usare questo plugin da un client 12.1.

Ghidra 12.1.2 include Jython come estensione opzionale. Gli script Java funzionano per impostazione predefinita, ma gli script .py in ghidra_scripts/ richiedono l'installazione dell'estensione Jython da File > Install Extensions e il riavvio di Ghidra.

Installazione

Consigliato per tutte le piattaforme: usa direttamente python -m tools.setup.

ensure-prereqs installa i requisiti Python runtime più i JAR Ghidra necessari nel repository Maven locale. deploy copia l'output della build, installa l'estensione nel profilo utente e corregge la configurazione utente di Ghidra.

1. Clona il repository: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Consigliato: eseguire prima il preflight dell'ambiente: ```text python -m tools.setup preflight --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

3. Crea e distribuisci in Ghidra: ```text python -m tools.setup ensure-prereqs --ghidra-path "F:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

deploy salva/chiude un'istanza di Ghidra corrispondente già in esecuzione quando necessario, installa l'estensione, avvia Ghidra, attende lo stato MCP, ed esegue i controlli di fumo dello schema.

4. Modalità rigorosa/manuale opzionale (avanzato): ```text

   Skip automatic prerequisite setup

   python -m tools.setup build python -m tools.setup deploy --ghidra-path "F:\ghidra_12.1.2_PUBLIC"
   root@kitploit:~

5. Mostra aiuto del comando: ```text python -m tools.setup --help
   root@kitploit:~

6. Modalità solo build opzionale (avanzato/risoluzione dei problemi): ```text python -m tools.setup build
   root@kitploit:~

Percorso di build supportato: python -m tools.setup build utilizza Maven internamente ed è il flusso di lavoro canonico utilizzato dai compiti e dalla documentazione del repository. ```bash

Manual Maven build (requires Ghidra deps already installed in local .m2)

mvn clean package assembly:single -DskipTests

</div>   ```bash
# Secondary/manual Gradle build path only (not used by tools.setup or VS Code tasks)
GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension

Installazione (Linux — Ubuntu/Debian)

1. Clona il repository: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

2. Installa i prerequisiti di sistema (se non già installati): ```bash sudo apt update && sudo apt install -y openjdk-21-jdk maven python3 python3-pip python3-venv curl jq unzip
   root@kitploit:~

Nota per Debian/Kali/Ubuntu 23.04+ (PEP 668): queste distribuzioni contrassegnano il Python di sistema come gestito esternamente, quindi un semplice pip install fallisce con error: externally-managed-environment. Non aggirarlo con --break-system-packages — potrebbe danneggiare strumenti gestiti da apt. Usa invece uv (consigliato — crea e gestisce automaticamente un .venv locale al progetto, ed è ciò che usano i comandi di questo repository):

root@kitploit:~

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run bridge-mcp-ghidra    # risolve le dipendenze in .venv e avvia il bridge

oppure un ambiente virtuale classico:

root@kitploit:~

python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

3. Esegui il preflight dell'ambiente: ```bash python -m tools.setup preflight --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

4. Costruisci e distribuisci su Ghidra (comando singolo): ```bash python -m tools.setup ensure-prereqs --ghidra-path ~/ghidra_12.1.2_PUBLIC python -m tools.setup build python -m tools.setup deploy --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

This will:

• Install Ghidra JAR dependencies into your local ~/.m2/repository
• Build GhidraMCP-<version>.zip with Maven
• Extract the extension to ~/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/
• Update preferences with LastExtensionImportDirectory
• Install Python requirements

5. Opzionale: configura solo le dipendenze Maven: ```bash python -m tools.setup install-ghidra-deps --ghidra-path ~/ghidra_12.1.2_PUBLIC
   root@kitploit:~

6. Mostra l'aiuto del comando: ```bash python -m tools.setup --help
   root@kitploit:~

Percorsi Linux: L'estensione è installata in $HOME/.config/ghidra/ghidra_<version>_PUBLIC/Extensions/GhidraMCP/. I file di configurazione di Ghidra si trovano in $HOME/.config/ghidra/ghidra_<version>_PUBLIC/.

Installazione (macOS — Homebrew)

1. Installa i prerequisiti: ```bash brew install openjdk@21 maven python ghidra
   root@kitploit:~

2. Clona il repository: ```bash git clone https://github.com/bethington/ghidra-mcp.git cd ghidra-mcp
   root@kitploit:~

3. Installa i JAR di Ghidra nel Maven locale: ```bash python -m tools.setup install-ghidra-deps
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

4. Costruisci e distribuisci: ```bash python -m tools.setup ensure-prereqs
   --ghidra-path /opt/homebrew/opt/ghidra/libexec python -m tools.setup build python -m tools.setup deploy
   --ghidra-path /opt/homebrew/opt/ghidra/libexec
   root@kitploit:~

L'estensione è installata in ~/Library/ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/.

Nota: --ghidra-version è richiesto quando si utilizza il percorso Homebrew perché il percorso non contiene alcuna stringa di versione.

5. Avvia Ghidra e abilita il plugin: ```bash /opt/homebrew/opt/ghidra/libexec/ghidraRun
   root@kitploit:~

Nella finestra principale del progetto: Tools > GhidraMCP > Start MCP Server

6. Configura Cursor/Claude MCP (~/.cursor/mcp.json): ```json { "mcpServers": { "ghidra": { "command": "uv", "args": ["run", "--directory", "/path/to/ghidra-mcp", "bridge-mcp-ghidra"] } } }
   root@kitploit:~

Installazione (Arch Linux — AUR)

@Pandoriaantje mantiene i pacchetti AUR della comunità:

• ghidra-mcp-git — segue main
• ghidra-mcp — segue le release taggate

Installa con il tuo helper AUR preferito, ad esempio:```bash yay -S ghidra-mcp # or ghidra-mcp-git

### Utilizzo di base

#### Opzione 1: Trasporto Stdio (Consigliato per strumenti AI)```bash
uv run bridge-mcp-ghidra          # or: python -m bridge_mcp_ghidra

Per aggiungere il bridge a Autohand Code da un checkout clonato:```bash autohand mcp add ghidra uv run --directory /path/to/ghidra-mcp bridge-mcp-ghidra

Aggiungi `--scope project` prima di `ghidra` per salvare il server nella configurazione `.autohand` del progetto corrente invece della configurazione utente.

#### Opzione 2: Trasporto HTTP Streamable (Consigliato per client web/HTTP)```bash
uv run bridge-mcp-ghidra --transport streamable-http --mcp-host 127.0.0.1 --mcp-port 8081

Configurazione client MCP per il trasporto HTTP (aggiungi al file di configurazione MCP del tuo client):```json { "mcpServers": { "ghidra-mcp-http": { "url": "http://127.0.0.1:8081/mcp" } } }

Client basati su browser (es. [MCP Inspector](https://github.com/modelcontextprotocol/inspector))
funzionano immediatamente: i trasporti HTTP rispondono alle richieste CORS preflight (`OPTIONS`) ed espongono
le intestazioni `mcp-session-id` / `mcp-protocol-version` agli script. Le origini consentite seguono la
politica dell'header Host — il loopback su qualsiasi porta è sempre permesso, insieme all'host di bind e a
qualsiasi host elencato in `GHIDRA_MCP_ALLOWED_HOSTS`.

#### Opzione 3: SSE Transport (Deprecato — usare streamable-http invece)```bash
uv run bridge-mcp-ghidra --transport sse --mcp-host 127.0.0.1 --mcp-port 8081

Bridge advanced flags

Routing rigoroso dei programmi (sicurezza multi-programma)

Imposta GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 per fare in modo che il bridge rifiuti qualsiasi chiamata con ambito programma che ometta un selettore di programma, restituendo un errore chiaro invece di lasciare che la chiamata sfrutti il "programma corrente" condiviso del server (quello su cui operano switch_program e la scheda GUI attiva).```bash export GHIDRA_MCP_REQUIRE_PROGRAM_SELECTORS=1 uv run bridge-mcp-ghidra

Senza questo, una chiamata che omette `program=` viene eseguita contro il programma corrente, il che va bene per un flusso di lavoro a programma singolo ma diventa pericoloso una volta che più programmi sono aperti: la chiamata può leggere o modificare il binario sbagliato senza alcun errore. Il pericolo è maggiore quando più client condividono un server, poiché ciascuno sposta il globale del programma corrente da sotto gli altri.

Con la modalità rigorosa attivata, ogni chiamata con ambito programma deve nominare il proprio target. Questo copre ogni selettore che sceglie un programma aperto: il semplice `program=` e gli strumenti cross-program `source_program`/`target_program` o `program_a`/`program_b` (dichiarati obbligatori, ma il server ricade ancora sul programma corrente quando uno arriva vuoto). Un selettore dimenticato si manifesta come un errore evidente sulla prima chiamata errata, invece di una scrittura silenziosa sul binario sbagliato. Gli strumenti senza selettore di programma (`open_program` e `close_program` prendono `path`/`name`) non sono interessati. Disattivato per impostazione predefinita: con la variabile non impostata, il bridge invia le chiamate invariate.

#### Ridurre il sovraccarico del contesto degli strumenti

Il bridge espone un ampio catalogo. Per mantenere piccola la superficie degli strumenti del modello, esegui con `--lazy` (carica solo `listing,function,program` alla connessione) e lascia che il modello **scopra** il resto su richiesta invece di registrare tutto:

- `search_tools("rename function")` — cerca per parola chiave l'**intero** catalogo, inclusi gli strumenti il cui gruppo non è caricato. Ogni risultato indica se è richiamabile ora e, in caso contrario, l'esatta chiamata `load_tool_group(...)` per abilitarlo.
- `list_tool_groups()` — elenca tutte le categorie e il loro stato di caricamento.
- `load_tool_group("datatype")` / `unload_tool_group("datatype")` — carica o rimuove una categoria a runtime.
- `check_tools("rename_or_label,batch_set_comments")` — conferma che strumenti specifici siano richiamabili in questo momento.

`search_tools` funziona sia in modalità eager che `--lazy`, quindi gli agenti che onorano `tools/list_changed` ottengono la scoperta completa senza il costo del contesto iniziale.

#### Opzionale: Avvia il server debugger standalone```bash
uv sync --group debugger
uv run python -m debugger

Il server di debug ascolta su http://127.0.0.1:8099/ di default ed è richiesto per gli strumenti proxy debugger_* esposti dal ponte MCP.

Flag del server di debug:

Imposta GHIDRA_DEBUGGER_URL in .env se modifichi la porta o l'host predefinito in modo che il ponte possa trovarlo.

In Ghidra

1. Avvia Ghidra e apri una finestra CodeBrowser
2. In CodeBrowser, abilita il plugin tramite File > Configure > Configure All Plugins > GhidraMCP
3. Opzionale: configura la porta personalizzata tramite CodeBrowser > Edit > Tool Options > GhidraMCP HTTP Server
4. Avvia il server tramite Tools > GhidraMCP > Start MCP Server
5. Il server viene eseguito su http://127.0.0.1:8089/ di default

Verifica che funzioni```bash

Quick health check

curl http://127.0.0.1:8089/check_connection

Expected: "Connected: GhidraMCP plugin running with program ''"

Get version info

curl http://127.0.0.1:8089/get_version

## Supporta Questo Progetto

Se Ghidra MCP ti fa risparmiare tempo in ingegneria o reverse-engineering, considera di [sponsorizzare il progetto](https://github.com/sponsors/bethington).

- La sponsorizzazione una tantum aiuta a finanziare correzioni, aggiornamenti di compatibilità e attività di rilascio.
- La sponsorizzazione ricorrente aiuta a mantenere aggiornamenti, documentazione e rafforzamento della produzione.
- Il supporto aziendale aiuta a dare priorità all'affidabilità a lungo termine per il bridge, il server headless, l'integrazione del debugger e gli strumenti di workflow.

## 🔒 Sicurezza

GhidraMCP è progettato per lo sviluppo **solo su localhost**. La configurazione predefinita — server HTTP associato a `127.0.0.1`, senza autenticazione — è sicura su una workstation fidata a singolo utente e corrisponde al comportamento pre-v5.4.1.

**Se esponi il server oltre il loopback, configura prima queste tre variabili d'ambiente.** Il server rifiuta di avviarsi su un bind non loopback senza un token.

| Variabile d'ambiente | Effetto |
|---|---|
| `GHIDRA_MCP_AUTH_TOKEN` | Quando impostata, ogni richiesta HTTP deve portare `Authorization: Bearer <token>`. Confronto a prova di timing. `/mcp/health`, `/health`, `/check_connection` sono esenti. |
| `GHIDRA_MCP_ALLOW_SCRIPTS` | Impostare a `1`, `true` o `yes` per abilitare `/run_script_inline` e `/run_ghidra_script`. **Disattivata per impostazione predefinita a partire da v5.4.1** — questi endpoint eseguono Java arbitrario contro il processo Ghidra. In modalità headless questo attiva anche l'inizializzazione di `BundleHost` OSGi all'avvio del server (framework Felix, ~centinaia di ms); lasciala disattivata se non hai bisogno di esecuzione di script. |
| `GHIDRA_MCP_FILE_ROOT` | Quando impostata a un percorso di directory, gli endpoint del percorso del filesystem (`/load_program`, `/import_file`, `/open_project`, `/delete_file`, ecc.) canonicalizzano l'input e richiedono che cada sotto questa radice. Previene il path-traversal. |

L'applicazione della qualità dei nomi è separata dalla sicurezza. Per impostazione predefinita, `rename_function_by_address` e gli endpoint di scrittura globale rifiutano nomi che non superano i controlli di qualità integrati, e le scritture di campi struct applicano la convenzione integrata del prefisso del campo. Disabilita il livello di convenzione integrato con **Edit > Tool Options > GhidraMCP HTTP Server > Strict Naming Enforcement**. La stessa casella di controllo delle Opzioni dello strumento copre `rename_data`, `rename_global_variable`, `set_global`, la protezione del prefisso/tipo di `apply_data_type`, e le correzioni automatiche del prefisso ungherese per i campi struct in `create_struct`, `add_struct_field` e `modify_struct_field`. L'impostazione viene letta all'avvio o al riavvio del server MCP. Gli avvisi di convenzione per funzioni/globali vengono comunque restituiti quando l'applicazione è disabilitata.

### Esempio: esposizione a una LAN privata con autenticazione```bash
export GHIDRA_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export GHIDRA_MCP_ALLOW_SCRIPTS=1     # only if your workflow needs it
export GHIDRA_MCP_FILE_ROOT=/srv/ghidra/inputs

java -jar GhidraMCPHeadless.jar --bind 0.0.0.0 --port 8089

Autenticazione del server Ghidra

Quando ci si connette a un server Ghidra condiviso, GhidraMCP può sopprimere automaticamente la finestra di dialogo per la password. Risolve le credenziali in questo ordine (vince il primo valore non vuoto):

Nota sulla compatibilità: i client Ghidra 12.1.2 richiedono Ghidra Server 12.1.2, 12.0.5 o un server compatibile più recente. I server condivisi meno recenti non sono sicuri per un aggiornamento del client 12.1.

1. Variabile d'ambiente GHIDRA_SERVER_PASSWORD (o file .env nella directory di installazione di Ghidra o ~)
2. ~/.ghidra-cred — file password su una singola riga nella tua home directory
3. <ghidra-install-dir>/.ghidra-cred

Il nome utente viene risolto in modo simile: variabile d'ambiente GHIDRA_SERVER_USER → proprietà di sistema user.name.

Se non viene trovata alcuna password, Ghidra mostra la sua normale richiesta GUI. Imposta queste variabili in .env (vedi .env.template per il blocco completo) per abilitare l'autenticazione silenziosa.

Migrazione da v5.4.0 a v5.4.1

• Gli endpoint degli script ora sono disattivati per impostazione predefinita. Se facevi affidamento su /run_script_inline o /run_ghidra_script, esporta GHIDRA_MCP_ALLOW_SCRIPTS=1. Si tratta di un cambiamento deliberato che rompe la compatibilità; l'impostazione predefinita precedente non era sicura.
• Le distribuzioni solo su localhost non richiedono modifiche. Autenticazione, rifiuto del bind e controlli del path-root sono tutti facoltativi.

❓ Risoluzione dei problemi

Il menu "GhidraMCP" non appare in Strumenti

Causa: Plugin non abilitato o installato in modo errato.

Soluzione:

1. Verifica che l'estensione sia installata: File > Installa estensioni — GhidraMCP dovrebbe essere elencato
2. Abilita il plugin: File > Configura > Configura tutti i plugin > GhidraMCP (spunta la casella)
3. Riavvia Ghidra dopo l'installazione/abilitazione

Server non risponde / Connessione rifiutata

Causa: Server non avviato o porta errata.

Soluzione:

1. Assicurati di aver avviato il server: Strumenti > GhidraMCP > Avvia server MCP
2. Controlla la porta configurata: Modifica > Opzioni dello strumento > Server HTTP GhidraMCP
3. Controlla se la porta è in uso: ```bash

   Linux/macOS

   lsof -i :8089

   Windows

   netstat -ano | findstr :8089
   root@kitploit:~

4. Cerca errori nella console di Ghidra: Window > Console

pip install fallisce con error: externally-managed-environment

Causa: PEP 668. Le distribuzioni della famiglia Debian (Debian 12+, Kali, Ubuntu 23.04+) contrassegnano il Python di sistema come gestito esternamente, quindi pip install globale è bloccato per proteggere i pacchetti gestiti da apt.

Soluzione: Usa un ambiente virtuale — mai --break-system-packages. Il percorso consigliato è uv, che gestisce automaticamente un .venv locale al progetto:```bash curl -LsSf https://astral.sh/uv/install.sh | sh cd ghidra-mcp uv run bridge-mcp-ghidra

O un classico venv:```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
bridge-mcp-ghidra

python -m debugger fallisce con ModuleNotFoundError per pybag o comtypes

Causa: Il server del debugger standalone utilizza dipendenze Python opzionali solo per Windows che non sono installate per impostazione predefinita.

Soluzione:```text uv sync --group debugger uv run python -m debugger

Se hai sia un Python globale che un venv di progetto, assicurati di installare
ed eseguire dallo stesso interprete.

### 500 Errori Interni del Server

**Causa:** Eccezione lato server, spesso dovuta a dati mancanti del programma.

**Soluzione:**
1. Assicurati che un binario sia caricato in CodeBrowser
2. Esegui prima l'analisi automatica: **Analysis > Auto Analyze**
3. Controlla la console di Ghidra (**Window > Console**) per eccezioni Java
4. Alcune operazioni richiedono binari completamente analizzati

### 404 Errori Non Trovato

**Causa:** Endpoint inesistente o URL errato.

**Soluzione:**
1. Verifica che l'endpoint esista: `curl http://127.0.0.1:8089/get_version`
2. Controlla eventuali errori di digitazione nel nome dell'endpoint
3. Assicurati di usare il metodo HTTP corretto (GET vs POST)

### Gli script Python di Ghidra falliscono con "No script provider found"

**Causa:** In Ghidra 12.1.2, il supporto Jython non è più abilitato per impostazione predefinita. Gli script `.py` necessitano dell'estensione Jython inclusa; gli script Python 3 dovrebbero usare PyGhidra invece di Ghidra Script Manager.

**Soluzione:**
1. Nel Front End di Ghidra, apri **File > Install Extensions**.
2. Spunta **Jython**, riavvia Ghidra, quindi aggiorna Script Manager.
3. Per nuove automazioni, preferisci script Java di Ghidra o PyGhidra.

### Estensione non visualizzata in Install Extensions

**Causa:** File JAR in posizione errata.

**Soluzione:**
1. Posizione di installazione manuale: `~/.ghidra/ghidra_12.1.2_PUBLIC/Extensions/GhidraMCP/lib/GhidraMCP.jar`
2. Oppure usa: **File > Install Extensions > Add** e seleziona il file ZIP
3. Assicurati che JAR/ZIP sia stato compilato per la tua versione di Ghidra

### La build fallisce con "Ghidra dependencies not found"

**Causa:** JAR di Ghidra non installati nel repository Maven locale.

**Soluzione:**```text
# Windows (recommended)
python -m tools.setup install-ghidra-deps --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

📊 Prestazioni di Produzione

• Strumenti MCP: 271 strumenti completamente implementati
• Velocità: Risposta sub-secondo per la maggior parte delle operazioni
• Efficienza: Riduzione del 93% delle chiamate API tramite operazioni batch
• Affidabilità: Transazioni atomiche con semantica tutto-o-niente
• Flussi di lavoro AI: Prompt di documentazione comprovati raffinati su centinaia di funzioni reali
• Deployment: Script di distribuzione automatizzato consapevole della versione

🛠️ Riferimento API

271 strumenti MCP supportati da endpoint HTTP, raggruppati per categoria di catalogo. Generato da tests/endpoints.json da python -m tools.gen_readme_api_reference --write; lo schema live su /mcp/schema è autorevole in fase di esecuzione. Modelli di utilizzo: docs/prompts/TOOL_USAGE_GUIDE.md.

Gestione Programma e Sessione

• analysis_status - Ottiene lo stato dell'analisi automatica per i programmi aperti
• close_program - Chiude un programma aperto tramite percorso del progetto o nome
• create_property_map - Crea una mappa di proprietà utente per memorizzare valori tipizzati con chiave per indirizzo
• delete_property_map - Elimina una mappa di proprietà utente e tutti i valori che contiene
• exit_ghidra - Salva ed esce da Ghidra
• get_address_spaces - Elenca tutti gli spazi di indirizzi fisici e overlay nel programma (gli overlay includono il flag is_overlay e il nome overlayed_space)
• get_current_program_info - Ottiene le informazioni sul programma corrente
• get_language_metadata - Scarica la descrizione del linguaggio del programma: spazi di indirizzi, registri, simboli predefiniti, endianness, dimensione del puntatore (issue #192)
• get_program_options - Legge tutte le opzioni in un gruppo di opzioni del programma con tipi, valori correnti, valori predefiniti e descrizioni
• get_property - Legge il valore memorizzato a un indirizzo in una mappa di proprietà

Organizzazione Progetto

• create_folder - Crea una cartella nel progetto
• delete_file - Elimina un file dal progetto
• delete_project - Elimina un progetto Ghidra
• list_projects - Elenca i progetti Ghidra disponibili
• move_file - Sposta un file in un'altra cartella del progetto
• move_folder - Sposta una cartella in un'altra posizione
• project_info - Ottiene informazioni dettagliate sul progetto inclusi strumenti in esecuzione e programmi aperti

Ciclo di Vita del Progetto e Programma Headless

Disponibile sul server headless autonomo (GhidraMCPHeadlessServer).

• archive_project - Archivia il progetto attualmente aperto in un file .gar nativo di Ghidra
• checkin_program - Verifica il rientro di un programma aperto nel server Ghidra condiviso come nuova versione
• close_project - Chiude il progetto attualmente aperto
• create_project - Crea un nuovo progetto Ghidra
• export_program - Esporta un programma aperto o residente nel progetto in un file ZIP Ghidra (.gzf)
• get_project_info - Ottiene informazioni sul progetto attualmente aperto
• import_program - Importa un file ZIP Ghidra (.gzf) nel progetto attualmente aperto come nuovo DomainFile in target_folder (predefinito '/')
• load_program - Carica un file binario nel server headless per l'analisi
• load_program_from_project - Carica un programma dal progetto Ghidra (headless)
• open_project - Apre un progetto Ghidra esistente (file .gpr o directory)
• restore_project - Ripristina un archivio .gar Ghidra in un nuovo progetto su disco in

Elenco ed Enumerazione

• list_bookmarks - Elenca i segnalibri
• list_calling_conventions - Elenca le convenzioni di chiamata disponibili
• list_classes - Elenca i nomi di namespace/classi
• list_data_items - Elenca i dati definiti
• list_data_items_by_xrefs - Elenca i dati ordinati per numero di riferimenti incrociati
• list_exports - Elenca i simboli esportati
• list_external_locations - Elenca le posizioni esterne
• list_functions - Elenca le funzioni con indirizzi
• list_functions_enhanced - Elenca le funzioni con metadati
• list_globals - Elenca le variabili globali
• list_imports - Elenca i simboli importati
• list_methods - Elenca tutti i nomi di funzione con paginazione

Contesto e Ricerche

• get_current_address - Ottiene l'indirizzo del cursore (solo GUI)
• get_current_function - Ottiene la funzione al cursore (solo GUI)
• get_current_selection - Ottiene gli intervalli di indirizzi evidenziati nell'elenco di CodeBrowser (solo GUI)
• get_entry_points - Ottiene i punti di ingresso del programma
• get_enum_values - Ottiene i valori di enumerazione
• get_external_location - Ottiene i dettagli di una posizione esterna
• get_full_call_graph - Ottiene il grafo delle chiamate completo
• get_function_by_address - Ottiene la funzione a un indirizzo
• get_function_call_graph - Ottiene il grafo delle chiamate
• get_function_callees - Ottiene le funzioni chiamate
• get_function_callers - Ottiene le funzioni chiamanti

Ricerca

• find_similar_functions - Trova funzioni simili
• search_byte_patterns - Cerca pattern di byte
• search_data_types - Cerca tipi di dati
• search_functions - Cerca funzioni per nome
• search_functions_enhanced - Ricerca avanzata di funzioni
• search_strings - Cerca stringhe definite tramite un pattern regex/sottostringa

Decompilazione e Disassemblaggio

• decompile_function - Decompila una funzione
• disassemble_bytes - Disassembla un intervallo di byte
• disassemble_function - Disassembla una funzione
• force_decompile - Forza una nuova decompilazione

Tag Funzione, Variabili e Attributi

• add_function_tag - Associa uno o più tag a una funzione
• batch_add_function_tags - Associa tag a molte funzioni in una singola transazione
• batch_remove_function_tags - Rimuove tag da molte funzioni in una singola transazione
• clear_flow_and_repair - Esegue l'azione GUI 'Clear Flow and Repair' di Ghidra su un intervallo seed: cancella il flusso di istruzioni raggiungibile dal seed, quindi ripara i corpi delle funzioni e ri-disassembla il flusso mantenuto (ClearFlowAndRepairCmd con clear_data=false, clear_labels=false, repair=true)
• create_function_tag - Crea una definizione di tag funzione a livello di programma con un commento opzionale
• delete_function_tag - Elimina una definizione di tag funzione a livello di programma
• get_function_tags - Elenca tutti i tag assegnati a una funzione specifica
• list_class_members - Elenca le funzioni membro di una classe C++
• list_function_tags - Elenca tutte le definizioni di tag funzione a livello di programma con i loro conteggi di utilizzo
• remove_function_tag - Rimuove uno o più tag da una funzione

Riferimenti Incrociati

• add_memory_reference - Crea un riferimento incrociato definito dall'utente tra due indirizzi di memoria che l'analizzatore automatico non può dedurre (tabelle di puntatori popolate a runtime, vtable, puntatori a funzione vincolati tardivamente, tabelle di salto/caso mancate)
• get_bulk_xrefs - Ottiene riferimenti incrociati per più indirizzi
• get_function_xrefs - Ottiene i riferimenti incrociati di una funzione
• get_xrefs_from - Ottiene i riferimenti da un indirizzo
• get_xrefs_to - Ottiene i riferimenti a un indirizzo
• remove_reference - Rimuove uno o più riferimenti incrociati di memoria da un indirizzo a un altro — l'inverso di add_memory_reference

Tipi di Dati e Strutture

• add_struct_field - Aggiunge un campo a una struttura
• analyze_global_completeness - Valuta la completezza della documentazione di una variabile globale su una scala 0-100 con budget — l'analogo per indirizzo dati di analyze_function_completeness
• apply_data_type - Applica un tipo di dato
• audit_global - Verifica lo stato della documentazione di una variabile globale
• audit_globals_in_function - Verifica ogni variabile globale referenziata all'interno di una funzione in una singola chiamata
• batch_set_variable_types - Imposta più tipi di variabili
• clone_data_type - Clona un tipo di dato
• create_array_type - Crea un tipo array
• create_data_type_category - Crea una categoria di tipi di dati
• create_enum - Crea un'enumerazione
• create_function_signature - Crea un tipo firma di funzione

Ridenominazione ed Etichette

• batch_create_labels - Crea più etichette
• batch_delete_labels - Elimina più etichette
• batch_rename_function_components - Rinomina in batch i componenti di una funzione
• create_label - Crea un'etichetta
• delete_label - Elimina un'etichetta a un indirizzo
• rename_data - Rinomina un simbolo di dato
• rename_external_location - Rinomina una posizione esterna
• rename_function - Rinomina una funzione per nome
• rename_function_by_address - Rinomina una funzione per indirizzo
• rename_global_variable - Rinomina una variabile globale
• rename_label - Rinomina un'etichetta
• rename_or_label - Rinomina o crea un'etichetta

Commenti e Segnalibri

• batch_set_comments - Imposta più commenti
• clear_function_comments - Cancella tutti i commenti di una funzione
• delete_bookmark - Elimina un segnalibro
• get_comment - Ottiene i commenti dell'elenco (piastra/pre/eol/post/ripetibili) a QUALSIASI indirizzo, inclusi gli indirizzi di dati (a differenza di get_plate_comment che richiede una funzione)
• get_plate_comment - Ottiene il commento a piastra
• set_bookmark - Imposta un segnalibro
• set_comment - Imposta un commento dell'elenco di un tipo specificato (piastra/pre/eol/post/ripetibile) a QUALSIASI indirizzo, inclusi gli indirizzi di dati
• set_decompiler_comment - Imposta PRE_COMMENT
• set_disassembly_comment - Imposta EOL_COMMENT
• set_plate_comment - Imposta il commento a piastra

Analisi

• analyze_api_call_chains - Analizza le catene di chiamate API
• analyze_call_graph - Analizza i pattern del grafo delle chiamate di funzione
• analyze_control_flow - Analizza il flusso di controllo
• analyze_data_region - Analizza una regione di dati
• analyze_dataflow - Traccia la propagazione dei valori attraverso una funzione (grafo PCode, avanti/indietro)
• analyze_for_documentation - Analisi composita della documentazione RE (decompila + classifica + variabili + completezza)
• analyze_function_complete - Analisi completa di una funzione in una singola chiamata
• analyze_function_completeness - Analizza la completezza della documentazione
• analyze_struct_field_usage - Analizza l'utilizzo dei campi di struttura
• apply_data_classification - Applica la classificazione dei dati
• batch_analyze_completeness - Analizza in batch la completezza per più funzioni

Documentazione e Archivio Cross-Binary

• archive_ingest_function - Inserisce la documentazione di una singola funzione nell'archivio cross-version (re_kb.functions su bsim Postgres)
• archive_ingest_program - Inserisce in blocco ogni funzione in un programma nell'archivio di documentazione cross-version
• batch_string_anchor_report - Report delle stringhe del file sorgente e delle loro funzioni FUN_*
• bulk_fuzzy_match - Corrispondenza fuzzy bulk cross-binary di funzioni
• find_similar_functions_fuzzy - Corrispondenza fuzzy cross-binary di funzioni
• merge_program_documentation - Unione bulk: copia tutta la documentazione RE (nomi di funzione, firme, commenti a piastra, commenti di istruzione a EOL/PRE/POST, etichette non predefinite e simboli globali) da un programma a un altro agli stessi indirizzi

Utilità e Trasferimento Documentazione

• apply_function_documentation - Applica la documentazione di una funzione
• check_connection - Endpoint di controllo salute
• compare_programs_documentation - Confronta la documentazione tra programmi
• convert_number - Converte un numero tra basi
• diff_functions - Confronta due funzioni
• find_undocumented_by_string - Trova funzioni non documentate che fanno riferimento a una stringa
• get_bulk_function_hashes - Ottiene hash di funzioni in blocco
• get_function_documentation - Esporta la documentazione di una funzione
• get_function_hash - Ottiene l'hash di una funzione
• get_function_signature - Ottiene la firma caratteristica di una funzione
• get_metadata - Ottiene i metadati del programma

Emulazione

• emulate_function - Emula una singola funzione con input di registro/memoria controllati
• emulate_hash_batch - Risoluzione brute-force di hash API

Scripting

• run_ghidra_script - Esegue uno script con cattura dell'output
• run_script_inline - Esegue codice script inline

Server Ghidra e Controllo Versione

• server_admin_set_permissions - Imposta i permessi utente su un repository
• server_admin_terminate_all_checkouts - Termina tutti i check-in in una cartella in modo ricorsivo
• server_admin_terminate_checkout - Termina tutti i check-in su un singolo file
• server_admin_users - Elenca tutti gli utenti sul server
• server_authenticate - Registra le credenziali del server per l'autenticazione programmatica
• server_checkouts - Elenca tutti i file in check-out in una cartella, inclusi i check-in lato server
• server_connect - Si connette a un server Ghidra
• server_disconnect - Si disconnette dal server Ghidra
• server_repositories - Elenca i repository sul server connesso
• server_repository_create - Crea un nuovo repository sul server
• server_repository_file - Ottiene informazioni su un file da un repository del server

Debugger (Ghidra TraceRmi — solo GUI)

Su host Windows dove il proxy del debugger WinDbg del bridge è attivo (GHIDRA_DEBUGGER_URL), i nomi in conflitto ricevono un suffisso _2 (es. debugger_status_2).

• debugger_dynamic_to_static - Traduce un indirizzo dinamico a runtime dalla traccia corrente in un indirizzo statico del programma Ghidra
• debugger_interrupt - Interrompe (entra in) il target in esecuzione
• debugger_launch - Lancia un eseguibile tramite il launcher del debugger Trace RMI di Ghidra
• debugger_launch_offers - Elenca le opzioni disponibili per lanciare/collegare il debugger per il programma corrente
• debugger_list_breakpoints - Elenca tutti i punti di interruzione nella traccia corrente
• debugger_modules - Elenca i moduli (DLL/EXE) caricati nel processo sottoposto a debug
• debugger_read_memory - Legge la memoria dal processo sottoposto a debug
• debugger_registers - Legge i registri della CPU dall'istantanea corrente della traccia di debug
• debugger_remove_breakpoint - Rimuove un punto di interruzione a un indirizzo
• debugger_resume - Riprende l'esecuzione del processo sottoposto a debug

Sistema

• prompt_policy - Abilita, disabilita o interroga temporaneamente la gestione dei prompt di automazione con ambito

Strumenti Statici BridgeDefinito nel ponte Python stesso (scoperta delle istanze, gestione dei gruppi di strumenti); sempre disponibile anche prima di una connessione a Ghidra. Il ponte funge anche da proxy per 22 strumenti WinDbg debugger_* quando GHIDRA_DEBUGGER_URL punta al server debugger standalone.

• check_tools - Segnala quali strumenti sono attualmente registrati e richiamabili
• connect_instance - Collega il ponte a una specifica istanza di Ghidra
• import_file - Importa un binario dal disco nel progetto corrente e lo apre
• list_instances - Scopre le istanze Ghidra MCP in esecuzione (UDS + scansione porta TCP)
• list_tool_groups - Elenca i gruppi di strumenti e il loro stato di caricamento
• load_tool_group - Registra gli strumenti dinamici di un gruppo di strumenti con il client MCP
• search_tools - Cerca nell'intero catalogo degli strumenti per parola chiave
• unload_tool_group - Annulla la registrazione degli strumenti dinamici di un gruppo di strumenti

Vedi CHANGELOG.md per la cronologia delle versioni.

🏗️ Architettura```

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI/Automation │◄──►│ MCP Bridge │◄──►│ Ghidra Plugin │ │ Tools │ │ (bridge_mcp_ │ │ (GhidraMCP.jar) │ │ (Claude, etc.) │ │ ghidra/) │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ MCP Protocol HTTP REST Ghidra API (stdio/streamable-http) (localhost:8089) (Program, Listing)

### Componenti

- **python/bridge_mcp_ghidra/** — Pacchetto server MCP Python (distribuito come wheel `ghidra-mcp-bridge`; script console `bridge-mcp-ghidra`) che traduce il protocollo MCP in chiamate HTTP (225 voci di catalogo)
- **GhidraMCP.jar** — Plugin Ghidra che espone le capacità di analisi tramite HTTP (175 endpoint GUI)
- **GhidraMCPHeadlessServer** — Server headless standalone — 183 endpoint, nessuna GUI richiesta
- **ghidra_scripts/** — Raccolta di script di automazione per attività comuni

## 🔧 Sviluppo

### Compilazione dal Sorgente```bash
# Recommended: direct Python-first workflow
python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC"
python -m tools.setup build
python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

# Version bump (updates all maintained version references atomically)
python -m tools.setup bump-version --new X.Y.Z

Il sistema di build autorevole oggi è Maven. tools.setup, le attività di VS Code e il flusso di deploy documentato compilano tutti tramite pom.xml e scrivono gli artefatti in target/. build.gradle rimane nel repo come fallback manuale per gli utenti diretti di Ghidra/Gradle, ma non è il percorso principale.

Command Reference

Flag comuni accettati dalla maggior parte dei comandi:

I livelli di test di deploy sono facoltativi perché i livelli benchmark possono importare/resettare Benchmark.dll e BenchmarkDebug.exe nel progetto Ghidra attivo. Usa --test release prima di rilasciare, o imposta GHIDRA_MCP_DEPLOY_TESTS=release in un .env locale quando desideri che ogni deploy sulla tua macchina esegua la regressione live del benchmark. Vedi Test e Regressione dei Rilasci.```text

Standard first-time setup and deploy

python -m tools.setup ensure-prereqs --ghidra-path "C:\ghidra_12.1.2_PUBLIC" python -m tools.setup build python -m tools.setup deploy --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Preflight check before deploying

python -m tools.setup preflight --strict --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

Version bump and tag

python -m tools.setup bump-version --new X.Y.Z --tag

Run offline Java tests

python -m tools.setup run-tests

Show full help

python -m tools.setup --help

### Struttura del Progetto```
ghidra-mcp/
├── pyproject.toml           # uv project (ghidra-mcp-bridge wheel + dependency groups)
├── python/bridge_mcp_ghidra/ # MCP server package (Python, 225 catalog entries)
├── src/main/java/           # Ghidra plugin + headless server (Java)
│   └── com/xebyte/
│       ├── GhidraMCPPlugin.java         # GUI plugin (196 endpoints)
│       ├── headless/                    # Headless server (183 endpoints)
│       └── core/                        # Shared service layer (12 services)
├── debugger/                # Optional standalone debugger server (port 8099)
├── ghidra_scripts/          # Automation scripts for batch workflows
├── tests/                   # Python unit tests + endpoint catalog
│   ├── unit/               # Catalog consistency, schema, tool function tests
│   └── endpoints.json      # Endpoint specification (225 entries)
├── docs/                    # Documentation
│   ├── prompts/            # AI workflow prompts (V5 documentation workflows)
│   ├── releases/           # Version release notes
│   └── project-management/ # Contributor planning docs (Gradle migration, etc.)
├── tools/setup/             # Build and deployment CLI (python -m tools.setup)
├── fun-doc/                 # Internal RE curation tool — not part of the MCP plugin
│                            #   Priority-queue worker, LLM scoring, web dashboard.
│                            #   See fun-doc/README.md for details.
└── .github/workflows/      # CI/CD pipelines

Dipendenze delle Librerie

I JAR di Ghidra devono essere installati nel repository Maven locale (~/.m2/repository) prima della compilazione. Questa è una configurazione una tantum per macchina, da ripetere quando la versione di Ghidra cambia. -Deploy ora installa queste dipendenze automaticamente per impostazione predefinita.

Lo strumento impone la coerenza di versione tra:

• pom.xml (ghidra.version)
• Il segmento di versione di --ghidra-path (es. ghidra_12.1.2_PUBLIC)

Se questi non corrispondono, il deployment fallisce immediatamente con un errore chiaro.

Risoluzione dei Problemi: Mancata Corrispondenza di Versione

Se visualizzi un errore di mancata corrispondenza di versione, allinea entrambi i valori:

1. pom.xml → ghidra.version
2. Il segmento di versione di --ghidra-path (ghidra_X.Y.Z_PUBLIC)

Quindi esegui di nuovo:```text python -m tools.setup preflight --ghidra-path "C:\ghidra_12.1.2_PUBLIC"

The chunk doesn’t appear to have been fully provided, but I'll process what's there.```text
# Windows
python -m tools.setup install-ghidra-deps --ghidra-path "C:\path\to\ghidra_12.1.2_PUBLIC"

Librerie Richieste (14 JARs, ~37 MB):

Nota: le librerie NON sono incluse nel repository (vedi .gitignore). È necessario installarle dalla propria installazione di Ghidra prima della compilazione.

Punto di ingresso per automazione:

• python -m tools.setup è l'interfaccia supportata per setup/build/deploy/versioning
• usa ensure-prereqs, build, deploy, preflight, clean-all e bump-version direttamente
• questi comandi attualmente utilizzano Maven come backend di compilazione Java canonico

Funzionalità di Sviluppo

• Distribuzione automatizzata: Script di distribuzione consapevole della versione
• Operazioni batch: Riduce le chiamate API del 93%
• Transazioni atomiche: Semantica tutto-o-niente
• Registrazione completa: Capacità di debug e tracciamento

📚 Documentazione

Documentazione principale

• Indice della documentazione - Navigazione completa della documentazione
• Struttura del progetto - Guida all'organizzazione del progetto
• Test e regressione di rilascio - Test locali, CI, regressione live di Ghidra e gate di rilascio
• Convenzioni di denominazione - Standard di denominazione del codice
• Notazione ungherese - Guida alla denominazione delle variabili

Prompt per workflow AI

• Documentazione funzioni V5 — Workflow principale: processo in 7 passaggi con notazione ungherese, audit dei tipi e punteggio di verifica
• Documentazione batch V5 — Invio parallelo di subagenti per elaborazione multi-funzione
• Scoperta codice orfano — Scanner automatico per funzioni non scoperte
• Indagine sui tipi di dati — Scoperta sistematica delle strutture
• Corrispondenza tra versioni — Corrispondenza funzioni basata su hash
• Prompt di avvio rapido — Workflow semplificato per principianti
• Tutti i prompt — Indice completo dei prompt

Cronologia delle versioni

• Changelog completo - Note di rilascio di tutte le versioni
• Note di rilascio - Documentazione dettagliata dei rilasci

🐳 Server Headless (Docker)

GhidraMCP include una modalità server headless per l'analisi automatizzata senza la GUI di Ghidra.

Avvio rapido con Docker```bash

Build and run

docker-compose up -d ghidra-mcp

Test connection

curl http://localhost:8089/check_connection

Connection OK - GhidraMCP Headless Server v5.17.0

### Workflow API senza testa```bash
# 1. Load a binary
curl -X POST -d "file=/data/program.exe" http://localhost:8089/load_program

# 2. Run auto-analysis (identifies functions, strings, data types)
curl -X POST http://localhost:8089/run_analysis

# 3. List discovered functions
curl "http://localhost:8089/list_functions?limit=20"

# 4. Decompile a function
curl "http://localhost:8089/decompile_function?address=0x401000"

# 5. Get metadata
curl http://localhost:8089/get_metadata

Endpoint headless principali

Configurazione

Variabili d'ambiente per Docker:

• GHIDRA_MCP_PORT - Porta del server (default: 8089)
• GHIDRA_MCP_BIND_ADDRESS - Indirizzo di bind (default: 0.0.0.0 in Docker)
• JAVA_OPTS - Opzioni JVM (default: -Xmx4g -XX:+UseG1GC)

🤝 Contributi

Vedi CONTRIBUTING.md per le linee guida dettagliate sui contributi.

Avvio rapido

1. Forka il repository
2. Crea un branch di funzionalità (git checkout -b feature/amazing-feature)
3. Compila e testa le tue modifiche (mvn clean package assembly:single -DskipTests or GHIDRA_INSTALL_DIR=/path/to/ghidra gradle buildExtension)
4. Aggiorna la documentazione se necessario
5. Committa le tue modifiche (git commit -m 'Add amazing feature')
6. Carica sul branch (git push origin feature/amazing-feature)
7. Apri una Pull Request

📄 Licenza

Questo progetto è concesso in licenza sotto la Apache License 2.0 - consulta il file LICENSE per i dettagli.

🏆 Stato di produzione

Vedi CHANGELOG.md per la cronologia delle versioni e le note di rilascio.

🙏 Riconoscimenti

Questo progetto deriva originariamente da LaurieWired/GhidraMCP nell'agosto 2025 ed è stato successivamente riscritto ed esteso in modo sostanziale. Riconosciamo il lavoro originale di LaurieWired come punto di partenza. Vedi NOTICE per l'attribuzione della licenza.

👥 Collaboratori

Questo progetto ha beneficiato del lavoro di collaboratori dedicati:

Collaboratori principali

@heeen — Contributi significativi tra cui:

• Matching fuzzy di funzioni e diff strutturato per confronto tra binari (#13)
• Miglioramenti all'esecuzione di script e correzioni di bug (#12)
• Nuovi endpoint API: save_program, exit_ghidra, delete_function, create_memory_block, run_script_inline (#11)
• Visione architetturale: design basato su annotazioni, trasporto UDS, proposte di ottimizzazione del bridge Python

@huehuehuehueing — Contributi significativi tra cui:

• Supporto del prefisso dello spazio degli indirizzi — aggiunta della sintassi <spazio>:<hex> (es. mem:1000, code:ff00) al parsing degli indirizzi su tutta la superficie degli endpoint, sbloccando obiettivi multi-spazio come firmware embedded (#84, chiude #65)

• Parametro program opzionale + correzioni schema required-param — ha reso program opzionale su ogni endpoint con un fallback sensato a currentProgram, e ha corretto diversi bug di schema required-vs-optional ereditati dal catalogo (#92)

• Ha generato #44 (strumenti per tipi di dati/enum) — l'issue che ha motivato il layer di enforcement di enum e strutture v5.0

• Team di Ghidra - Per l'incredibile piattaforma di reverse engineering

• Model Context Protocol - Per il framework standardizzato di integrazione AI

• Collaboratori - Per test, feedback e miglioramenti

🔗 Progetti correlati

• re-universe — Piattaforma Ghidra BSim PostgreSQL per analisi di similarità binaria su larga scala. Si abbina perfettamente con GhidraMCP per flussi di lavoro di reverse engineering guidati dall'AI.
• cheat-engine-server-python — Server MCP per analisi dinamica della memoria e debugging.

Pronto per il deployment in produzione con affidabilità di livello enterprise e capacità complete di analisi binaria.