ida-cli

Headless IDA CLI и инструментарий, основанный на навыках (skill-first), для анализа бинарных файлов на macOS и Linux. ida-cli автоматически выбирает бэкенд времени выполнения, при необходимости автоматически запускает локальный сервер и предоставляет один и тот же интерфейс в виде плоского CLI, stdio MCP-транспорта и потокового HTTP MCP-транспорта.

中文说明

Две пользовательские точки входа

• локальный бинарный файл ida-cli (клиент + сервис в одном исполняемом файле)
• устанавливаемый навык ida-cli (skill/SKILL.md) для агентных сред

Базовый сервисный слой worker/router запускается и останавливается CLI автоматически. Вам нужно запускать serve / serve-http явно только тогда, когда вы действительно хотите получить долгоживущий сервис, доступный извне.

Матрица поддержки

Платформы хостов

• Поддерживаются: macOS, Linux
• Не поддерживаются: Windows

Политика времени выполнения IDA

Выбор бэкенда выполняется во время выполнения командой probe-runtime. Для сборки по-прежнему требуется IDA SDK, поскольку вендоренный нативный слой линкуется с ним; во время выполнения CLI сам открывает IDA из IDADIR или нормализованного общего пути установки.

Текущие возможности

На поддерживаемых средах выполнения IDA 9.x ida-cli умеет:

• открывать сырые PE / ELF / Mach-O бинарные файлы и переиспользовать кэшированные базы .i64
• перечислять и разрешать функции, дизассемблировать по адресу или имени, декомпилировать через Hex-Rays
• запрашивать сегменты, строки, импорты, экспорты, точки входа, глобальные символы
• определять контекст адреса ↔ сегмент / функция / символ
• читать байты / строки / целые числа, применять хелперы read_* и convert_number
• запрашивать перекрёстные ссылки (xrefs) к адресу и от адреса (включая xrefs на строки и поля структур)
• строить графы вызовов, базовые блоки и пути управления потоком
• искать текст, непосредственные значения, байты, инструкции, операнды, псевдокод
• объявлять / применять типы, переименовывать символы и локальные переменные, устанавливать комментарии
• выполнять IDAPython-сниппеты через run_script

Открытые вопросы: некоторые операции с интенсивной записью и продвинутым редактированием типов на idat-compat реализованы лишь частично. Сгенерированный список инструментов см. в docs/TOOLS.md.

Быстрый старт

Рекомендуется: установите навык (skill)

Точка входа по умолчанию — навык ida-cli, а не ручная установка 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

После установки навык поставляется с собственной обёрткой начальной загрузки:

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

Если ida-cli отсутствует, обёртка устанавливает его через установщик репозитория, а затем передаёт команду дальше.

Прямая установка CLI (необязательно)

Используйте это, только если вам нужен автономный CLI без установки через навык.

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

Полезные варианты:

# 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

Примечания:

• Установщик по умолчанию помещает лаунчер в ~/.local/bin/ida-cli.
• --add-path добавляет этот каталог bin в ваш rc-файл оболочки.
• Если ни IDASDKDIR, ни IDALIB_SDK не заданы и требуется локальная сборка, установщик автоматически клонирует open-source HexRaysSA/ida-sdk.
• Если установлено несколько версий IDA, экспортируйте IDADIR явно перед установкой или запуском ida-cli.

Сборка из исходников

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

Использование CLI

ida-cli ориентирован на клиента. Любая клиентская подкоманда автоматически запускает локальный Streamable-HTTP сервер, привязанный к случайному порту, и записывает /tmp/ida-cli.socket для обнаружения:

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

Команды, первый аргумент которых является сервисной подкомандой (serve, serve-http, serve-worker, probe-runtime), вместо этого переходят в сервисный режим:

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

Пример вывода проверки бэкенда:

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

Полный интерфейс CLI см. в skill/references/cli-tool-reference.md.

Требования к сборке

• Rust 1.87+
• LLVM / Clang
• хост macOS или Linux
• установка IDA через IDADIR (поддержка во время выполнения начинается с IDA 9.0)
• IDA SDK через IDASDKDIR или IDALIB_SDK

Путь к SDK может указывать на любую из структур:

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

Примечания по времени выполнения

idat-compat

Бэкенд совместимости для IDA 9.0–9.2. Он вызывает idat, выполняет короткие IDAPython-скрипты и возвращает структурированный JSON в среду выполнения CLI.

native-linked

Бэкенд для IDA 9.3+. Линкуется с линией вендоренного idalib и открывает базы данных в своём процессе.

Кэш и локальные пути времени выполнения

• Кэш базы данных: ~/.ida/idb/
• Журналы: ~/.ida/logs/server.log
• Unix-сокет сервера: ~/.ida/server.sock
• PID-файл сервера: ~/.ida/server.pid
• Файл обнаружения CLI (сопоставляет плоский CLI с активным сокетом): /tmp/ida-cli.socket
• Кэш больших JSON-ответов: /tmp/ida-cli-out/

CI и релизы

GitHub Actions компилирует и тестирует проект на размещённых раннерах с использованием open-source HexRaysSA/ida-sdk, поэтому CI не зависит от частной конфигурации машин.

Текущее поведение workflow:

• пуши и pull request'ы в master запускают валидацию
• пуши с тегами, например v0.9.3, собирают релизные архивы для Linux и macOS
• к релизам прикрепляются install.sh и архивы для платформ

Релизные бинарные файлы собираются с использованием SDK-заглушек. При установке лаунчер, созданный install.sh, определяет вашу локальную среду выполнения IDA через IDADIR или нормализованный набор общих путей установки перед вызовом ida-cli.

Документация

• docs/BUILDING.md — сборка из исходников
• docs/ARCHITECTURE.md — маршрутизатор, бэкенды, федерация
• docs/TRANSPORTS.md — stdio, потоковый HTTP, multi-IDB
• docs/TOOLS.md — сгенерированный каталог инструментов
• docs/TESTING.md — интеграционные и модульные тесты
• skill/SKILL.md — начальная загрузка навыка и политика использования
• skill/references/cli-tool-reference.md — полный интерфейс CLI

Лицензия

MIT