ida-cli

Strumento CLI IDA headless e toolkit skill-first per l'analisi binaria su macOS e Linux. ida-cli seleziona automaticamente un backend runtime, avvia automaticamente un server locale quando necessario ed espone la stessa superficie come CLI piatta, trasporto MCP stdio e trasporto MCP HTTP Streamable.

中文说明

Due punti di ingresso per l'utente

• il binario locale ida-cli (client e servizio in un unico eseguibile)
• la skill ida-cli installabile (skill/SKILL.md) per ambienti agente

Il livello di servizio worker/router sottostante viene avviato e arrestato automaticamente dalla CLI. Devi eseguire esplicitamente serve / serve-http solo quando vuoi un servizio di lunga durata e indirizzabile esternamente.

Matrice di supporto

Piattaforme host

• Supportate: macOS, Linux
• Non supportate: Windows

Policy del runtime IDA

La selezione del backend viene effettuata a runtime da probe-runtime. La compilazione richiede comunque un IDA SDK perché il livello nativo incluso nel progetto è collegato ad esso; a runtime la CLI apre IDA direttamente da IDADIR o da un percorso di installazione comune normalizzato.

Funzionalità attuali

Sui runtime IDA 9.x supportati, ida-cli può:

• aprire binari PE / ELF / Mach-O grezzi e riutilizzare i database .i64 in cache
• elencare e risolvere funzioni, disassemblare per indirizzo o nome, decompilare tramite Hex-Rays
• interrogare segmenti, stringhe, import, export, punti di ingresso e simboli globali
• risolvere il contesto indirizzo ↔ segmento / funzione / simbolo
• leggere byte / stringhe / interi, applicare gli helper read_* e convert_number
• interrogare gli xref verso / da un indirizzo (inclusi gli xref a stringhe e campi di struct)
• costruire callgraph, blocchi di base e percorsi di flusso di controllo
• cercare testo, immediati, byte, istruzioni, operandi e pseudocodice
• dichiarare / applicare tipi, rinominare simboli e variabili locali, impostare commenti
• eseguire snippet IDAPython tramite run_script

Questioni aperte: alcune operazioni di scrittura intensiva e di modifica avanzata dei tipi sono ancora parziali su idat-compat. Consulta docs/TOOLS.md per l'elenco degli strumenti generati.

Avvio rapido

Consigliato: installa la skill

Il punto di ingresso predefinito è la skill ida-cli, non un'installazione manuale della CLI.

# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list

# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global

Dopo l'installazione, la skill include il proprio wrapper di bootstrap:

~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20

Se ida-cli manca, il wrapper lo installa tramite l'installer del repository prima di inoltrare il comando.

Installazione diretta della CLI (opzionale)

Usala solo se vuoi la CLI standalone senza passare dalla skill.

curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path

Varianti utili:

# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path

# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path

Note:

• L'installer colloca il launcher in ~/.local/bin/ida-cli di default.
• --add-path aggiunge quella directory bin al file rc della tua shell.
• Se non sono impostati né IDASDKDIR né IDALIB_SDK e serve una build locale, l'installer clona automaticamente l'HexRaysSA/ida-sdk open-source.
• Quando sono presenti più installazioni di IDA, esporta esplicitamente IDADIR prima di installare o eseguire ida-cli.

Compilare dal sorgente

git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help

Usare la CLI

ida-cli è client-first. Qualsiasi sottocomando client avvia automaticamente un server Streamable-HTTP locale in ascolto su una porta casuale e scrive /tmp/ida-cli.socket per il discovery:

./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'

I comandi il cui primo argomento è un sottocomando di servizio (serve, serve-http, serve-worker, probe-runtime) entrano invece in modalità servizio:

./target/debug/ida-cli serve                          # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime

Esempio di output del probe del backend:

{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}

{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}

Per la superficie completa della CLI, consulta skill/references/cli-tool-reference.md.

Requisiti di compilazione

• Rust 1.87+
• LLVM / Clang
• host macOS o Linux
• Un'installazione di IDA tramite IDADIR (il supporto runtime inizia da IDA 9.0)
• Un IDA SDK tramite IDASDKDIR o IDALIB_SDK

Il percorso dell'SDK può puntare a uno dei due layout:

• /path/to/ida-sdk
• /path/to/ida-sdk/src

Note sul runtime

idat-compat

Backend di compatibilità per IDA 9.0–9.2. Richiama idat come sottoprocesso, esegue brevi script IDAPython e restituisce JSON strutturato al runtime della CLI.

native-linked

Backend per IDA 9.3+. Si collega alla linea idalib inclusa nel progetto e apre i database in-process.

Percorsi della cache e del runtime locale

• Cache dei database: ~/.ida/idb/
• Log: ~/.ida/logs/server.log
• Socket Unix del server: ~/.ida/server.sock
• File PID del server: ~/.ida/server.pid
• File di discovery della CLI (mappa la CLI piatta al socket attivo): /tmp/ida-cli.socket
• Cache per le risposte JSON di grandi dimensioni: /tmp/ida-cli-out/

CI e release

GitHub Actions compila e testa l'albero su runner ospitati usando l'HexRaysSA/ida-sdk open-source, quindi la CI non dipende da alcuna configurazione di macchina privata.

Comportamento attuale del workflow:

• push e pull request verso master eseguono la validazione
• push con tag come v0.9.3 compilano gli archivi di release per Linux e macOS
• le release allegano install.sh e gli archivi di piattaforma

I binari delle release sono compilati contro gli stub dell'SDK. Al momento dell'installazione, il launcher generato da install.sh risolve il tuo runtime IDA locale tramite IDADIR o un insieme normalizzato di percorsi di installazione comuni prima di invocare ida-cli.

Documentazione

• docs/BUILDING.md — compilazione dal sorgente
• docs/ARCHITECTURE.md — router, backend, federazione
• docs/TRANSPORTS.md — stdio, HTTP streamable, multi-IDB
• docs/TOOLS.md — catalogo degli strumenti generati
• docs/TESTING.md — test di integrazione e unitari
• skill/SKILL.md — bootstrap della skill e policy d'uso
• skill/references/cli-tool-reference.md — superficie completa della CLI

Licenza

MIT