ida-pro-mcp

Server MCP deterministico e local-first per IDA Pro/Home: 109 operazioni di reverse engineering con schema rigoroso, risultati supportati da evidenze e modifiche all'IDB controllate da policy.

La versione corrente è 1.0.0a3. Questo è software alpha. I nomi pubblici delle operazioni ida_*, gli schemi e il formato del workspace possono cambiare prima di una release stabile 1.0.0. La superficie client predefinita contiene 109 operazioni con schema esatto. Usa la discovery live per il contratto completo: tools/list enumera ogni operazione con il suo schema, e ida_help(topic="...") restituisce gli argomenti esatti e un esempio per una singola operazione.

Prima di installare

Ti serve:

• IDA Pro o IDA Home 9.2 o successivo, con un eseguibile idat/idat64 utilizzabile. Le evidenze dei test live del repository coprono IDA 9.3 e 9.4; 9.2 è la soglia di compatibilità dichiarata.
• Python 3.11 o successivo per l'host e l'installer.
• Il permesso di eseguire IDA sui binari che intendi ispezionare, e spazio su disco sufficiente per un ambiente Python gestito, i file di sessione e le copie dell'IDB.
• Un client MCP che supporti un server stdio locale, come Claude Code, Codex, OpenCode, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Gemini CLI o Antigravity.

L'analisi normale non richiede un modello linguistico o un modello di embedding. Le funzionalità opzionali di ricerca semantica usano un modello locale per impostazione predefinita e restano disabilitate quando nessun modello è configurato.

Il runtime predefinito è idat: un processo IDA headless per sessione. Il backend idalib è sperimentale, richiede un'installazione IDA 9.3 o successiva con il pacchetto idapro attivato, e non è necessario per una prima installazione.

Installazione dal checkout sorgente

L'installer crea un ambiente gestito sotto la root di installazione, vi installa una copia congelata del checkout e scrive la configurazione del client per le posizioni client supportate. Dalla root del repository, esegui:

Per un'installazione IDA nota, passala esplicitamente:

Per un'esecuzione non interattiva:

L'installer può anche trovare IDA tramite IDADIR, IDA_DIR, gli eseguibili IDA nel PATH e le directory di installazione comuni. --ida-version seleziona una versione quando è presente più di un'installazione. Usa --dry-run per ispezionare prima le modifiche pianificate.

L'installer non scarica un modello di embedding a meno che tu non ne selezioni o richieda uno. Può creare o aggiornare file di configurazione per ogni posizione client nella sua mappa client integrata, inclusi i client che non sono installati sulla tua macchina. Controlla install-report.json nella root di installazione e rimuovi le voci inutilizzate se necessario. I file di configurazione regolari esistenti vengono salvati prima di essere modificati; i file malformati, symlink o non regolari vengono rifiutati anziché sovrascritti.

Riavvia il client MCP dopo l'installazione in modo che ricarichi la sua configurazione.

Gli harness degli agent scoprono la superficie degli strumenti in tempo reale: tools/list enumera ogni operazione con il suo schema, e ida_help(topic="...") restituisce argomenti esatti e un esempio. Non vengono installati file di skill statici.

La root di installazione predefinita è:

• Linux e macOS: ~/.local/share/ida-pro-mcp
• Windows: %LOCALAPPDATA%/ida-pro-mcp

Imposta IDA_PRO_MCP_HOME o passa --install-root per scegliere un'altra posizione.

Installazione da un artefatto di release

Le release alpha sono costruite da GitHub Actions e pubblicate manualmente come prerelease. Quando una release è disponibile, scarica l'asset bundle.zip o bundle.tar.gz e il suo file SHA256SUMS dalla pagina delle release. Verifica il checksum, estrai il bundle ed esegui l'installer dalla sua directory di primo livello:

La release contiene anche un wheel e una distribuzione sorgente per installazioni Python scriptate. Il bundle è la via più semplice perché include l'installer e tutti i file di progetto necessari per configurare un client MCP. Le release sono di qualità alpha; conserva il binario originale e l'IDB e leggi le note di release prima di aggiornare.

Connessione di un client MCP

L'installer scrive la voce del server per i percorsi di configurazione client che conosce. Supporta Gemini CLI, Antigravity, Antigravity IDE, Antigravity CLI, Claude Code, Codex, Copilot CLI, OpenCode, Claude Desktop, Cursor, VS Code, Windsurf, Cline e Roo Code. OpenCode e i client della famiglia Copilot usano forme di configurazione diverse; lascia che l'installer scriva quei file o segui la guida di setup di OpenCode.

Per un client che usa il formato JSON comune, la voce è equivalente a:

Su Windows, usa l'interprete gestito in <install-root>/.venv/Scripts/python.exe. I dettagli importanti sono l'interprete gestito, -u -m ida_pro_mcp.host.server, la directory IDA selezionata e IDA_MCP_TOOL_SURFACE=agent. Non puntare il client a install.py; quel file è l'installer, non il server MCP.

Dopo aver modificato la configurazione di un client, riavvia completamente il client e verifica che ida_help compaia tra le sue operazioni disponibili. Se il client mostra solo una vecchia interfaccia ampia tool(action=...), verifica che l'ambiente selezioni la superficie predefinita agent anziché IDA_MCP_TOOL_SURFACE=legacy.

Una prima sessione utile

Usa prima un percorso assoluto verso un binario di test. L'apertura di un binario normalmente attende che l'analisi iniziale di IDA sia completata; un binario di grandi dimensioni può richiedere tempo.

Usa ida_help(topic="ida_decompile") ogni volta che ti serve lo schema esatto degli argomenti. Gli schemi pubblici delle operazioni sono rigorosi: gli argomenti sconosciuti vengono rifiutati. Gli indirizzi possono essere accettati come interi o stringhe secondo il singolo contratto dell'operazione; usa la forma mostrata da ida_help per l'operazione nel tuo client.

Per un piccolo registro di indagine, le operazioni sui findings del workspace sono:

I findings del workspace sono mantenuti separatamente dalle modifiche all'IDB. Se la policy attiva consente la scrittura nel workspace, ida_write_finding registra un finding localmente; altrimenti il server restituisce un errore di policy. ida_publish_findings(dry_run=true) mostra in anteprima le modifiche all'IDB. Pubblicazione, rinomina, patching e altre mutazioni dell'IDB sono controllate dalla policy e richiedono la presa d'atto documentata dell'operazione dove l'operazione ne espone una.

Panoramica delle operazioni

La pagina principale resta orientata ai compiti, ma questo indice compatto mantiene la superficie pubblica facile da scorrere. Ogni nome sotto è preceduto da ida_ quando viene chiamato. Gli schemi completi e gli esempi sono disponibili in tempo reale tramite tools/list e ida_help(topic="...").

Cosa è sicuro e cosa non lo è

La policy di base del server è assist. Una sessione può rendere più restrittiva la policy di base dell'operatore ma non può allentarla. La policy è deterministica; non decide che un'operazione rischiosa è sicura perché un client la richiede.

L'ispezione in sola lettura è il normale punto di partenza. Esempi includono ida_overview, ida_find, ida_list_functions, ida_list_strings, ida_list_imports, ida_decompile, ida_disassemble, ida_xrefs_to, ida_callers, ida_callees, ida_callgraph, ida_read_bytes e le operazioni di calcolo. Queste consumano comunque file locali e risorse IDA, e il client MCP riceve i loro risultati.

Le seguenti azioni modificano stato durevole o eseguono codice e dovrebbero essere trattate come ad alto impatto:

• ida_rename, ida_comment, ida_patch_bytes, modifiche a funzioni/tipi/segmenti/dati, applicazione di firme, ida_save_idb, snapshot e operazioni di undo/restore possono modificare l'IDB o lo stato correlato.
• ida_publish_findings scrive i findings nell'IDB. Esegui prima la sua forma dry-run; la forma non dry-run è controllata.
• ida_close_session smantella il runtime IDA live ed è distruttiva dal punto di vista della sessione.
• ida_python esegue Python arbitrario nel processo IDA attivo. È bloccata in modalità safe e richiede una presa d'atto esplicita del rischio con la policy normale.
• ida_emulate è utile per controlli controllati, ma le azioni mutanti dell'emulatore richiedono la presa d'atto corrispondente.
• ida_til_export e ida_til_import accedono al filesystem e sono controllate. I percorsi del filesystem sono vincolati dalla root di memoria configurata dove quella protezione si applica.

Non usare --disable-policy come flag di comodo. Imposta IDA_MCP_POLICY_MODE=off e disabilita tutti i gate della policy, incluse le prese d'atto di scrittura e altri controlli del workflow. Se una chiamata viene negata, leggi la voce ida_help dell'operazione e fornisci l'argomento di presa d'atto esatto solo quando lo schema di quell'operazione lo supporta.

Mentre IDA sta ancora eseguendo l'analisi iniziale, la modalità safe blocca alcune operazioni di analisi full-binary, indicizzazione e script. È pensata per mantenere le chiamate di inizio sessione ristrette; esegui il polling di ida_session_status o ida_session_health anziché aggirare la protezione.

Il bridge ascolta su loopback e usa un token per sessione. Non è un servizio di rete: non esporre o inoltrare la porta del bridge a una rete non attendibile. Tratta script, trace, binari, dati di corpus e richieste client importati come input non attendibile.

Privacy e gestione dei dati

Il normale percorso host-to-IDA è locale. Il progetto non esegue un servizio LLM integrato nel percorso di analisi, e l'embedding locale è opt-in. Ciò non rende automaticamente offline l'intero workflow:

• Il client MCP connesso riceve percorsi, simboli, stringhe, byte, decompilazione, findings e altri risultati. Il client o il suo provider di modello può trasmettere quel contesto secondo le proprie impostazioni di account, modello e conservazione. IDA Pro MCP non può controllare quei trasferimenti.
• Se selezioni esplicitamente il backend di embedding Gemini, il server invia una firma comportamentale compatta a Google anziché una decompilazione completa. La firma può comunque contenere chiamate derivate dal codice, costanti, stringhe letterali e informazioni sul flusso di controllo. Non abilitarlo per binari che devono rimanere sulla workstation.
• I download delle dipendenze dell'installer, i download opzionali di modelli e llama-server, i download opzionali di corpus di minacce e le integrazioni esterne Rizin/radare2 possono effettuare richieste di rete quando abilitati.
• Cache locale, log, metadati di sessione, IDB gestiti e la blackboard possono contenere percorsi, metadati di analisi e findings. Proteggi le directory di installazione/dati. Se passi una chiave Gemini AI Studio all'installer, la chiave può essere scritta nel blocco di ambiente del client MCP generato; preferisci una credenziale basata su variabili d'ambiente e rivedi la configurazione del client.

Per un setup solo locale, usa il runtime locale predefinito, lascia disabilitati Gemini e gli altri download opzionali, e configura il client MCP e il suo modello secondo la policy dei dati della tua organizzazione. "Solo locale" richiede comunque di verificare cosa il client invia al proprio provider di modello.

Risoluzione dei problemi comuni

L'installer non riesce a trovare IDA

Passa esplicitamente la directory di installazione:

Puoi anche impostare IDADIR o IDA_DIR. Se vengono trovate più installazioni, usa --ida-version 9.3 o --no-ida-prompt per controllare la selezione. Conferma che la directory selezionata contenga un idat o idat64 eseguibile.

Il client non mostra IDA Pro MCP

Riavvia il client e ispeziona la sua voce di configurazione. Conferma che il suo comando usi il Python del venv gestito e -u -m ida_pro_mcp.host.server, e che il blocco env contenga il IDADIR corretto. Rivedi install-report.json; l'installer registra i fallimenti di aggiornamento del client e mantiene i backup accanto ai file modificati. Le forme di configurazione di OpenCode e della famiglia Copilot differiscono dall'esempio JSON comune.

L'apertura di un binario richiede molto tempo o sembra bloccata

La normale chiamata ida_open_binary attende l'analisi iniziale. Controlla ida_session_status e ida_session_health, concedi più tempo per un binario di grandi dimensioni e controlla i log per sessione sotto la directory di installazione/dati. L'operazione di apertura in background è disponibile, ma è pensata per casi in cui comprendi il suo comportamento asincrono e le restrizioni della modalità safe.

Un'operazione di scrittura viene negata

Di solito è la policy che funziona come configurato. Usa ida_help per ispezionare lo schema esatto dell'operazione e il suo requisito di presa d'atto. Non aggiungere argomenti arbitrari: gli schemi sono rigorosi. Rivedi IDA_MCP_POLICY_MODE e il file di policy dell'operatore prima di modificare la policy. Disabilitare tutti i gate della policy è una scelta separata e deliberatamente non sicura.

La ricerca semantica non è disponibile

La ricerca semantica è opzionale e richiede un indice e un backend di embedding compatibile. L'elenco ordinario, la ricerca, la decompilazione e il lavoro di cross-reference non la richiedono. Per configurare il percorso locale opzionale, usa le opzioni esplicite dell'embedder dell'installer, ad esempio:

L'installer può anche eseguire --embedder-doctor, usare un percorso di modello esplicito o scaricare un modello selezionato e llama-server quando richiesto. Le licenze dei modelli, l'uso del disco e i download di rete sono tua responsabilità. Se il modello è mancante, il server dovrebbe segnalare la ricerca semantica come non disponibile anziché fingere che sia stata eseguita.

L'installer rifiuta una configurazione client

Correggi la sintassi JSON, JSONC o TOML segnalata e riesegui l'installer. Rifiuta anche percorsi di configurazione symlink e non regolari per evitare di sovrascrivere un target inatteso. I file regolari esistenti vengono salvati; il comportamento di rollback predefinito dell'installer può ripristinare quei backup se una fase successiva fallisce.

Una sessione o un runtime IDA fallisce

Controlla ida_session_health, il log della sessione e il log del bridge. Conferma che il client stia usando la stessa root di installazione e lo stesso IDADIR che l'installer ha registrato. Il backend idat predefinito assegna a ogni sessione il proprio processo; non passare all'idalib sperimentale mentre diagnostichi un'installazione di base.

Materiale di riferimento

• Wiki del progetto — guide orientate ai compiti per installazione, indagine, modifica e risoluzione dei problemi.
• Pagine wiki locali — lo stesso materiale scritto a mano fornito per lo strumento wiki integrato.
• Discovery live delle operazioni — tools/list e ida_help espongono ogni operazione pubblica, schema ed esempio.
• Modello di sicurezza — confini di fiducia, modalità di policy, trasporto loopback, proprietà della sessione e protezioni del filesystem.
• Workspace di indagine — findings, evidenze, target ed esportazioni.
• Intelligence ed embedding — backend di retrieval locali e opzionali Gemini.
• Setup di OpenCode — configurazione di OpenCode.
• Architettura — host, runtime IDA e flusso dei dati per i lettori che necessitano di dettagli implementativi.
• Policy di sicurezza — segnalazione e guida alla sicurezza.
• Test live di IDA — cosa i test del repository dimostrano e non dimostrano su un'installazione IDA reale.
• Versioning e checklist di release e il changelog — stato alpha e cronologia delle release.
• Indice della documentazione — la mappa completa delle guide mantenute, riferimenti, pagine wiki e note di ricerca.

Per i nomi esatti delle operazioni, usa il riferimento generato o chiedi al server in esecuzione con ida_help. Il vecchio backend tool(action=...) resta disponibile per compatibilità ed è selezionato con IDA_MCP_TOOL_SURFACE=legacy; le nuove integrazioni dovrebbero usare la superficie ida_* con schema esatto.