ida-cli

Headless-IDA-CLI- und Skill-First-Toolkit für die Binäranalyse auf macOS und Linux. ida-cli wählt automatisch ein Laufzeit-Backend aus, startet bei Bedarf automatisch einen lokalen Server und bietet dieselbe Oberfläche als flache CLI, als Stdio-MCP-Transport und als Streamable-HTTP-MCP-Transport.

Chinesische Anleitung

Zwei benutzerorientierte Einstiegspunkte

• das lokale ida-cli-Binary (Client + Dienst in einer ausführbaren Datei)
• der installierbare ida-cli-Skill (skill/SKILL.md) für Agent-Umgebungen

Die zugrunde liegende Worker-/Router-Diensteebene wird automatisch von der CLI gestartet und beendet. Sie müssen serve / serve-http nur dann explizit ausführen, wenn Sie tatsächlich einen langlebigen, extern erreichbaren Dienst wünschen.

Support-Matrix

Host-Plattformen

• Unterstützt: macOS, Linux
• Nicht unterstützt: Windows

IDA-Laufzeitrichtlinie

IDA-Version	Backend	Hinweise
< 9.0	nicht unterstützt	—
9.0 – 9.2	idat-compat	führt idat + IDAPython aus
9.3+	native-linked	verlinkt gegen die mitgelieferte idalib

Die Backend-Auswahl erfolgt zur Laufzeit durch probe-runtime. Zum Bauen wird weiterhin ein IDA-SDK benötigt, da die mitgelieferte native Schicht gegen dieses verlinkt ist; zur Laufzeit öffnet die CLI IDA selbst über IDADIR oder einen normalisierten, üblichen Installationspfad.

Aktuelle Funktionen

Auf unterstützten IDA-9.x-Laufzeiten kann ida-cli Folgendes:

• rohe PE- / ELF- / Mach-O-Binärdateien öffnen und zwischengespeicherte .i64-Datenbanken wiederverwenden
• Funktionen auflisten und auflösen, nach Adresse oder Name disassemblieren, über Hex-Rays dekompilieren
• Segmente, Zeichenketten, Importe, Exporte, Einstiegspunkte und globale Symbole abfragen
• Adress- ↔ Segment- / Funktions- / Symbolkontext auflösen
• Bytes / Zeichenketten / Ganzzahlen lesen, die read_*- und convert_number-Helfer anwenden
• Querverweise zu / von einer Adresse abfragen (einschließlich Querverweise auf Zeichenketten und Strukturfelder)
• Callgraphen, Basisblöcke und Kontrollflusspfade erstellen
• Text, Immediates, Bytes, Anweisungen, Operanden und Pseudocode durchsuchen
• Typen deklarieren / anwenden, Symbole und lokale Variablen umbenennen, Kommentare setzen
• IDAPython-Snippets über run_script ausführen

Offene Punkte: Einige schreibintensive und fortgeschrittene Typbearbeitungsvorgänge sind unter idat-compat noch unvollständig. Die Liste der generierten Werkzeuge finden Sie in docs/TOOLS.md.

Schnellstart

Empfohlen: Skill installieren

Der Standardeinstiegspunkt ist der ida-cli-Skill, nicht eine manuelle CLI-Installation.

# 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

Nach der Installation bringt der Skill seinen eigenen Bootstrap-Wrapper mit:

~/.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

Wenn ida-cli fehlt, installiert der Wrapper es über den Repository-Installer, bevor er den Befehl weiterleitet.

Direkte CLI-Installation (optional)

Verwenden Sie dies nur, wenn Sie die eigenständige CLI ohne den Skill nutzen möchten.

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

Nützliche Varianten:

# 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

Hinweise:

• Der Installer legt den Launcher standardmäßig unter ~/.local/bin/ida-cli ab.
• --add-path hängt dieses bin-Verzeichnis an Ihre Shell-rc-Datei an.
• Wenn weder IDASDKDIR noch IDALIB_SDK gesetzt ist und ein lokaler Build erforderlich ist, klont der Installer automatisch das Open-Source-HexRaysSA/ida-sdk.
• Wenn mehrere IDA-Installationen vorhanden sind, exportieren Sie IDADIR explizit, bevor Sie ida-cli installieren oder ausführen.

Aus dem Quellcode bauen

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

Die CLI verwenden

ida-cli ist client-orientiert. Jeder Client-Unterbefehl startet automatisch einen lokalen Streamable-HTTP-Server, der an einen zufälligen Port gebunden ist, und schreibt /tmp/ida-cli.socket zur Erkennung:

./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"}}'

Befehle, deren erstes Argument ein Dienst-Unterbefehl ist (serve, serve-http, serve-worker, probe-runtime), wechseln stattdessen in den Servicemodus:

./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

Beispielausgabe der Backend-Erkennung:

{"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}

Die vollständige CLI-Oberfläche finden Sie unter skill/references/cli-tool-reference.md.

Build-Voraussetzungen

• Rust 1.87+
• LLVM / Clang
• macOS- oder Linux-Host
• Eine IDA-Installation über IDADIR (Laufzeitunterstützung ab IDA 9.0)
• Ein IDA-SDK über IDASDKDIR oder IDALIB_SDK

Der SDK-Pfad kann auf eines der beiden Layouts verweisen:

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

Hinweise zur Laufzeit

idat-compat

Kompatibilitäts-Backend für IDA 9.0–9.2. Es ruft idat auf, führt kurze IDAPython-Skripte aus und gibt strukturiertes JSON an die CLI-Laufzeit zurück.

native-linked

Backend für IDA 9.3+. Verlinkt gegen die mitgelieferte idalib-Reihe und öffnet Datenbanken prozessintern.

Cache- und lokale Laufzeitpfade

• Datenbank-Cache: ~/.ida/idb/
• Logs: ~/.ida/logs/server.log
• Unix-Socket des Servers: ~/.ida/server.sock
• PID-Datei des Servers: ~/.ida/server.pid
• CLI-Erkennungsdatei (ordnet die flache CLI dem aktiven Socket zu): /tmp/ida-cli.socket
• Cache für große JSON-Antworten: /tmp/ida-cli-out/

CI und Releases

GitHub Actions kompiliert und testet den Quellbaum auf gehosteten Runnern gegen das Open-Source-HexRaysSA/ida-sdk, sodass CI nicht von einem privaten Maschinenlayout abhängt.

Aktuelles Workflow-Verhalten:

• Pushes und Pull Requests auf master führen Validierung aus
• getaggte Pushes wie v0.9.3 erstellen Release-Archive für Linux und macOS
• Releases fügen install.sh sowie Plattform-Archive bei

Die Release-Binärdateien werden gegen SDK-Stubs erstellt. Zur Installationszeit löst der von install.sh generierte Launcher Ihre lokale IDA-Laufzeit über IDADIR oder eine normalisierte Menge üblicher Installationspfade auf, bevor er ida-cli aufruft.

Dokumentation