ida-cli

CLI de IDA sin interfaz gráfica y kit de herramientas centrado en skills para el análisis de binarios en macOS y Linux. ida-cli selecciona automáticamente un backend de runtime, inicia automáticamente un servidor local cuando es necesario y expone la misma superficie como un CLI plano, un transporte MCP stdio y un transporte MCP HTTP Streamable.

中文说明

Dos puntos de entrada orientados al usuario

• el binario local ida-cli (cliente + servicio en un solo ejecutable)
• la skill ida-cli instalable (skill/SKILL.md) para entornos de agentes

La capa de servicio subyacente de worker / router se inicia y se apaga automáticamente mediante el CLI. Solo necesitas ejecutar serve / serve-http explícitamente cuando realmente quieras un servicio de larga duración y direccionable externamente.

Matriz de compatibilidad

Plataformas anfitrionas

• Compatible: macOS, Linux
• No compatible: Windows

Política de runtime de IDA

La selección del backend se realiza en tiempo de ejecución mediante probe-runtime. La compilación sigue requiriendo un IDA SDK porque la capa nativa incluida se enlaza contra él; en tiempo de ejecución, el CLI abre IDA por sí mismo desde IDADIR o una ruta de instalación común normalizada.

Capacidades actuales

En runtimes IDA 9.x compatibles, ida-cli puede:

• abrir binarios PE / ELF / Mach-O sin procesar y reutilizar bases de datos .i64 en caché
• listar y resolver funciones, desensamblar por dirección o nombre, descompilar mediante Hex-Rays
• consultar segmentos, cadenas, importaciones, exportaciones, puntos de entrada y símbolos globales
• resolver el contexto dirección ↔ segmento / función / símbolo
• leer bytes / cadenas / enteros, aplicar los helpers read_* y convert_number
• consultar xrefs hacia / desde una dirección (incluidos xrefs a cadenas y campos de estructuras)
• construir grafos de llamadas, bloques básicos y rutas de flujo de control
• buscar texto, inmediatos, bytes, instrucciones, operandos y pseudocódigo
• declarar / aplicar tipos, renombrar símbolos y variables locales, establecer comentarios
• ejecutar fragmentos IDAPython mediante run_script

Pendientes: algunas operaciones de escritura intensiva y edición avanzada de tipos siguen siendo parciales en idat-compat. Consulta docs/TOOLS.md para ver la lista de herramientas generada.

Inicio rápido

Recomendado: instalar la skill

El punto de entrada predeterminado es la skill ida-cli, no una instalación manual del 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

Después de la instalación, la skill incluye su propio envoltorio de arranque:

~/.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 no está presente, el envoltorio lo instala mediante el instalador del repositorio antes de reenviar el comando.

Instalación directa del CLI (opcional)

Úsalo solo si quieres el CLI independiente sin pasar por la skill.

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

Variantes útiles:

# 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

Notas:

• El instalador coloca el lanzador en ~/.local/bin/ida-cli de forma predeterminada.
• --add-path añade ese directorio bin a tu archivo rc de shell.
• Si no se establecen ni IDASDKDIR ni IDALIB_SDK y se requiere una compilación local, el instalador clona automáticamente el HexRaysSA/ida-sdk de código abierto.
• Cuando hay varias instalaciones de IDA, exporta IDADIR explícitamente antes de instalar o ejecutar ida-cli.

Compilar desde el código fuente

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

Uso del CLI

ida-cli está orientado al cliente. Cualquier subcomando de cliente inicia automáticamente un servidor local Streamable-HTTP vinculado a un puerto aleatorio y escribe /tmp/ida-cli.socket para el descubrimiento:

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

Los comandos cuyo primer argumento es un subcomando de servicio (serve, serve-http, serve-worker, probe-runtime) entran en modo servicio en su lugar:

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

Ejemplo de salida de la sonda de 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}

Para ver la superficie completa del CLI, consulta skill/references/cli-tool-reference.md.

Requisitos de compilación

• Rust 1.87+
• LLVM / Clang
• Host macOS o Linux
• Una instalación de IDA mediante IDADIR (el soporte de runtime comienza en IDA 9.0)
• Un IDA SDK mediante IDASDKDIR o IDALIB_SDK

La ruta del SDK puede apuntar a cualquiera de estas estructuras:

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

Notas de runtime

idat-compat

Backend de compatibilidad para IDA 9.0–9.2. Ejecuta idat externamente, lanza scripts IDAPython cortos y devuelve JSON estructurado al runtime del CLI.

native-linked

Backend para IDA 9.3+. Enlaza contra la línea idalib incluida y abre las bases de datos dentro del proceso.

Rutas de caché y runtime local

• Caché de bases de datos: ~/.ida/idb/
• Registros: ~/.ida/logs/server.log
• Socket Unix del servidor: ~/.ida/server.sock
• Archivo PID del servidor: ~/.ida/server.pid
• Archivo de descubrimiento del CLI (asigna el CLI plano al socket activo): /tmp/ida-cli.socket
• Caché de respuestas JSON grandes: /tmp/ida-cli-out/

CI y lanzamientos

GitHub Actions compila y prueba el árbol en runners alojados contra el HexRaysSA/ida-sdk de código abierto, por lo que el CI no depende de ninguna disposición privada de máquinas.

Comportamiento actual del flujo de trabajo:

• los pushes y las pull requests contra master ejecutan la validación
• los pushes etiquetados como v0.9.3 generan archivos de lanzamiento para Linux y macOS
• los lanzamientos adjuntan install.sh junto con los archivos de cada plataforma

Los binarios de lanzamiento se compilan contra stubs del SDK. En el momento de la instalación, el lanzador generado por install.sh resuelve tu runtime local de IDA mediante IDADIR o un conjunto normalizado de rutas de instalación comunes antes de invocar a ida-cli.

Documentación

• docs/BUILDING.md — compilar desde el código fuente
• docs/ARCHITECTURE.md — router, backends, federación
• docs/TRANSPORTS.md — stdio, HTTP Streamable, multi-IDB
• docs/TOOLS.md — catálogo de herramientas generado
• docs/TESTING.md — pruebas de integración y unitarias
• skill/SKILL.md — arranque de la skill y política de uso
• skill/references/cli-tool-reference.md — superficie completa del CLI

Licencia

MIT