ida-cli

CLI IDA headless et boîte à outils orientée skill pour l'analyse binaire sur macOS et Linux. ida-cli sélectionne automatiquement un backend d'exécution, démarre automatiquement un serveur local si nécessaire et expose la même surface sous forme de CLI plate, de transport MCP stdio et de transport MCP HTTP Streamable.

中文说明

Deux points d'entrée utilisateur

• le binaire local ida-cli (client + service dans un seul exécutable)
• le skill ida-cli installable (skill/SKILL.md) pour les environnements d'agents

La couche de service worker / routeur sous-jacente est démarrée et arrêtée automatiquement par la CLI. Vous n'avez besoin d'exécuter explicitement serve / serve-http que lorsque vous souhaitez réellement un service durable et adressable depuis l'extérieur.

Matrice de prise en charge

Plateformes hôtes

• Pris en charge : macOS, Linux
• Non pris en charge : Windows

Politique de runtime IDA

La sélection du backend est effectuée à l'exécution par probe-runtime. La compilation nécessite toujours un SDK IDA, car la couche native intégrée est liée à celui-ci ; à l'exécution, la CLI ouvre elle-même IDA à partir de IDADIR ou d'un chemin d'installation courant normalisé.

Fonctionnalités actuelles

Sur les runtimes IDA 9.x pris en charge, ida-cli peut :

• ouvrir des binaires bruts PE / ELF / Mach-O et réutiliser les bases .i64 mises en cache
• lister et résoudre les fonctions, désassembler par adresse ou par nom, décompiler via Hex-Rays
• interroger les segments, les chaînes, les imports, les exports, les points d'entrée, les symboles globaux
• résoudre le contexte adresse ↔ segment / fonction / symbole
• lire des octets / chaînes / entiers, appliquer les helpers read_* et convert_number
• interroger les xrefs vers / depuis une adresse (y compris les xrefs vers des chaînes et des champs de structure)
• construire des graphes d'appels, des blocs de base et des chemins de flux de contrôle
• rechercher du texte, des immédiats, des octets, des instructions, des opérandes, du pseudocode
• déclarer / appliquer des types, renommer des symboles et des variables locales, définir des commentaires
• exécuter des extraits IDAPython via run_script

Points restants : certaines opérations d'écriture intensive et d'édition avancée de types restent partielles sur idat-compat. Voir docs/TOOLS.md pour la liste des outils générés.

Démarrage rapide

Recommandé : installer le skill

Le point d'entrée par défaut est le skill ida-cli, et non une installation manuelle de la 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

Après l'installation, le skill est livré avec son propre wrapper d'amorçage :

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

Si ida-cli est manquant, le wrapper l'installe via l'installateur du dépôt avant de transmettre la commande.

Installation directe de la CLI (optionnel)

Utilisez cette option uniquement si vous souhaitez la CLI autonome sans passer par le skill.

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

Variantes utiles :

# 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

Remarques :

• L'installateur place le lanceur dans ~/.local/bin/ida-cli par défaut.
• --add-path ajoute ce répertoire bin à votre fichier rc du shell.
• Si ni IDASDKDIR ni IDALIB_SDK n'est défini et qu'une compilation locale est requise, l'installateur clone automatiquement le dépôt open-source HexRaysSA/ida-sdk.
• Lorsque plusieurs installations d'IDA sont présentes, exportez IDADIR explicitement avant d'installer ou d'exécuter ida-cli.

Compilation depuis les sources

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

Utiliser la CLI

ida-cli est orienté client. Toute sous-commande client démarre automatiquement un serveur Streamable-HTTP local lié à un port aléatoire et écrit /tmp/ida-cli.socket pour la découverte :

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

Les commandes dont le premier argument est une sous-commande de service (serve, serve-http, serve-worker, probe-runtime) passent en mode service :

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

Exemple de sortie du sondage du 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}

Pour la surface complète de la CLI, voir skill/references/cli-tool-reference.md.

Prérequis de compilation

• Rust 1.87+
• LLVM / Clang
• Hôte macOS ou Linux
• Une installation IDA via IDADIR (la prise en charge runtime commence à IDA 9.0)
• Un SDK IDA via IDASDKDIR ou IDALIB_SDK

Le chemin du SDK peut pointer vers l'une ou l'autre de ces structures :

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

Notes sur le runtime

idat-compat

Backend de compatibilité IDA 9.0–9.2. Il délègue à idat, exécute de courts scripts IDAPython et renvoie du JSON structuré au runtime de la CLI.

native-linked

Backend IDA 9.3+. Il se lie à la lignée idalib intégrée et ouvre les bases in-process.

Cache et chemins runtime locaux

• Cache de bases de données : ~/.ida/idb/
• Journaux : ~/.ida/logs/server.log
• Socket Unix du serveur : ~/.ida/server.sock
• Fichier PID du serveur : ~/.ida/server.pid
• Fichier de découverte de la CLI (fait correspondre la CLI plate à la socket active) : /tmp/ida-cli.socket
• Cache des grandes réponses JSON : /tmp/ida-cli-out/

CI et versions

GitHub Actions compile et teste l'arborescence sur des runners hébergés avec le HexRaysSA/ida-sdk open-source, de sorte que la CI ne dépend d'aucune configuration machine privée.

Comportement actuel des workflows :

• les pushs et pull requests vers master exécutent une validation
• les pushs tagués tels que v0.9.3 construisent les archives de release pour Linux et macOS
• les releases joignent install.sh et les archives par plateforme

Les binaires de release sont compilés contre des stubs du SDK. Au moment de l'installation, le lanceur généré par install.sh résout votre runtime IDA local via IDADIR ou un ensemble normalisé de chemins d'installation courants avant d'invoquer ida-cli.

Documentation

• docs/BUILDING.md — compilation depuis les sources
• docs/ARCHITECTURE.md — routeur, backends, fédération
• docs/TRANSPORTS.md — stdio, HTTP streamable, multi-IDB
• docs/TOOLS.md — catalogue des outils générés
• docs/TESTING.md — tests d'intégration et unitaires
• skill/SKILL.md — amorçage du skill et politique d'utilisation
• skill/references/cli-tool-reference.md — surface complète de la CLI

Licence

MIT