ida-pro-mcp

Локальный, детерминированный MCP-сервер для IDA Pro/Home: 109 строго типизированных операций обратного инжиниринга, выводы с подтверждением доказательствами и редактирование IDB с контролем политик.

Текущая версия — 1.0.0a3. Это альфа-версия. Публичные имена операций ida_*, схемы и формат рабочего пространства могут измениться до стабильного релиза 1.0.0. Поверхность клиента по умолчанию содержит 109 операций с точными схемами. Используйте живое обнаружение для получения полного контракта: tools/list перечисляет каждую операцию с её схемой, а ida_help(topic="...") возвращает точные аргументы и пример для одной операции.

Перед установкой

Вам потребуется:

• IDA Pro или IDA Home 9.2 или новее с рабочим исполняемым файлом idat/idat64. Живые тестовые данные репозитория охватывают IDA 9.3 и 9.4; 9.2 — это заявленный минимальный уровень совместимости.
• Python 3.11 или новее для хоста и установщика.
• Разрешение на запуск IDA для бинарных файлов, которые вы планируете исследовать, и достаточно места на диске для управляемого окружения Python, файлов сессий и копий IDB.
• MCP-клиент, поддерживающий локальный stdio-сервер, например Claude Code, Codex, OpenCode, Claude Desktop, Cursor, VS Code/Copilot, Windsurf, Cline, Roo Code, Gemini CLI или Antigravity.

Обычный анализ не требует языковой модели или модели эмбеддингов. Необязательные функции семантического поиска по умолчанию используют локальную модель и остаются отключёнными, если модель не настроена.

Среда выполнения по умолчанию — idat: один headless-процесс IDA на сессию. Бэкенд idalib экспериментальный, требует установки IDA 9.3 или новее с активированным пакетом idapro и не нужен для первой установки.

Установка из исходного репозитория

Установщик создаёт управляемое окружение в корне установки, устанавливает в него зафиксированную копию репозитория и записывает конфигурацию клиента для поддерживаемых расположений клиентов. Из корня репозитория выполните:

Для известной установки IDA укажите её явно:

Для неинтерактивного запуска:

Установщик также может найти IDA через IDADIR, IDA_DIR, исполняемые файлы IDA в PATH и стандартные каталоги установки. --ida-version выбирает версию, когда присутствует более одной установки. Используйте --dry-run, чтобы сначала просмотреть планируемые изменения.

Установщик не загружает модель эмбеддингов, если вы не выбрали или не запросили её. Он может создавать или обновлять конфигурационные файлы для каждого расположения клиента во встроенной карте клиентов, включая клиенты, которые не установлены на вашей машине. Проверьте install-report.json в корне установки и удалите неиспользуемые записи при необходимости. Существующие обычные конфигурационные файлы создаются резервные копии перед изменением; некорректные, символические или необычные файлы отклоняются, а не перезаписываются.

Перезапустите MCP-клиент после установки, чтобы он перезагрузил свою конфигурацию.

Агентные обвязки обнаруживают поверхность инструментов в реальном времени: tools/list перечисляет каждую операцию с её схемой, а ida_help(topic="...") возвращает точные аргументы и пример. Статические файлы навыков не устанавливаются.

Корень установки по умолчанию:

• Linux и macOS: ~/.local/share/ida-pro-mcp
• Windows: %LOCALAPPDATA%/ida-pro-mcp

Задайте IDA_PRO_MCP_HOME или передайте --install-root, чтобы выбрать другое расположение.

Установка из релизного артефакта

Альфа-релизы собираются GitHub Actions и публикуются вручную как пререлизы. Когда релиз доступен, скачайте ресурс bundle.zip или bundle.tar.gz и его файл SHA256SUMS со страницы релизов. Проверьте контрольную сумму, распакуйте пакет и запустите установщик из его каталога верхнего уровня:

Релиз также содержит wheel и исходный дистрибутив для скриптовых установок Python. Пакет — самый простой путь, поскольку он включает установщик и все файлы проекта, необходимые для настройки MCP-клиента. Релизы имеют альфа-качество; сохраните оригинальный бинарный файл и IDB и прочитайте примечания к релизу перед обновлением.

Подключение MCP-клиента

Установщик записывает запись сервера для известных ему путей конфигурации клиентов. Он поддерживает Gemini CLI, Antigravity, Antigravity IDE, Antigravity CLI, Claude Code, Codex, Copilot CLI, OpenCode, Claude Desktop, Cursor, VS Code, Windsurf, Cline и Roo Code. OpenCode и клиенты семейства Copilot используют разные формы конфигурации; позвольте установщику записать эти файлы или следуйте руководству по настройке OpenCode.

Для клиента, использующего общий формат JSON, запись эквивалентна:

В Windows используйте управляемый интерпретатор по пути <install-root>/.venv/Scripts/python.exe. Важные детали — это управляемый интерпретатор, -u -m ida_pro_mcp.host.server, выбранный каталог IDA и IDA_MCP_TOOL_SURFACE=agent. Не указывайте клиенту на install.py; этот файл — установщик, а не MCP-сервер.

После изменения конфигурации клиента полностью перезапустите клиент и проверьте, что ida_help появляется в его доступных операциях. Если клиент показывает только устаревший широкий интерфейс tool(action=...), проверьте, что окружение выбирает поверхность agent по умолчанию, а не IDA_MCP_TOOL_SURFACE=legacy.

Первая полезная сессия

Сначала используйте абсолютный путь к тестовому бинарному файлу. Открытие бинарного файла обычно ожидает завершения начального анализа IDA; большой бинарный файл может занять время.

Используйте ida_help(topic="ida_decompile"), когда вам нужна точная схема аргументов. Публичные схемы операций строгие: неизвестные аргументы отклоняются. Адреса могут приниматься как целые числа или строки в соответствии с индивидуальным контрактом операции; используйте форму, показанную ida_help для операции в вашем клиенте.

Для небольшой записи расследования операции находок рабочего пространства таковы:

Находки рабочего пространства хранятся отдельно от правок IDB. Если активная политика разрешает запись в рабочее пространство, ida_write_finding записывает находку локально; в противном случае сервер возвращает ошибку политики. ida_publish_findings(dry_run=true) предварительно просматривает изменения IDB. Публикация, переименование, патчинг и другие мутации IDB контролируются политикой и требуют документированного подтверждения операции там, где операция его предоставляет.

Операции с первого взгляда

Главная страница остаётся ориентированной на задачи, но этот компактный указатель делает публичную поверхность легко просматриваемой. Каждое имя ниже при вызове имеет префикс ida_. Полные схемы и примеры доступны в реальном времени через tools/list и ida_help(topic="...").

Что безопасно, а что нет

Базовая политика сервера — assist. Сессия может ужесточить базовую политику оператора, но не может её ослабить. Политика детерминирована; она не решает, что рискованная операция безопасна, потому что клиент её запрашивает.

Инспекция только для чтения — обычная отправная точка. Примеры включают ida_overview, ida_find, ida_list_functions, ida_list_strings, ida_list_imports, ida_decompile, ida_disassemble, ida_xrefs_to, ida_callers, ida_callees, ida_callgraph, ida_read_bytes и операции вычислений. Они всё равно потребляют локальные файлы и ресурсы IDA, и MCP-клиент получает их результаты.

Следующие действия изменяют долговременное состояние или выполняют код и должны рассматриваться как высокоimpactные:

• ida_rename, ida_comment, ida_patch_bytes, изменения функций/типов/сегментов/данных, применение сигнатур, ida_save_idb, снимки и операции отмены/восстановления могут изменить IDB или связанное состояние.
• ida_publish_findings записывает находки в IDB. Сначала запустите его форму dry-run; форма без dry-run контролируется.
• ida_close_session разрушает живую среду выполнения IDA и деструктивна с точки зрения сессии.
• ida_python выполняет произвольный Python в активном процессе IDA. Он заблокирован в безопасном режиме и требует явного подтверждения риска при обычной политике.
• ida_emulate полезен для контролируемых проверок, но мутирующие действия эмулятора требуют соответствующего подтверждения.
• ida_til_export и ida_til_import обращаются к файловой системе и контролируются. Пути файловой системы ограничены настроенным корнем памяти там, где эта защита применяется.

Не используйте --disable-policy как флаг удобства. Он устанавливает IDA_MCP_POLICY_MODE=off и отключает все политические шлюзы, включая подтверждения записи и другие средства управления рабочим процессом. Если вызов отклонён, прочитайте запись ida_help операции и укажите точный подтверждённый аргумент только тогда, когда схема этой операции его поддерживает.

Пока IDA всё ещё выполняет начальный анализ, безопасный режим блокирует некоторые операции полного анализа бинарного файла, индексации и скриптов. Он предназначен для сохранения узких вызовов на ранней сессии; опрашивайте ida_session_status или ida_session_health, а не обходите защиту.

Мост слушает на loopback и использует токен для каждой сессии. Это не сетевой сервис: не открывайте и не перенаправляйте порт моста в недоверенную сеть. Рассматривайте импортированные скрипты, трассировки, бинарные файлы, данные корпуса и клиентские запросы как недоверенный ввод.

Конфиденциальность и обработка данных

Обычный путь хост-IDA локален. Проект не запускает встроенный сервис LLM в пути анализа, а локальные эмбеддинги включаются по желанию. Это не делает весь рабочий процесс автоматически офлайн:

• Подключённый MCP-клиент получает пути, символы, строки, байты, декомпиляцию, находки и другие результаты. Клиент или его поставщик модели может передавать этот контекст в соответствии со своими собственными настройками учётной записи, модели и хранения. IDA Pro MCP не может контролировать эти передачи.
• Если вы явно выбираете бэкенд эмбеддингов Gemini, сервер отправляет компактную поведенческую сигнатуру в Google, а не полную декомпиляцию. Сигнатура всё ещё может содержать производные от кода вызовы, константы, строковые литералы и информацию о потоке управления. Не включайте её для бинарных файлов, которые должны оставаться на рабочей станции.
• Загрузки зависимостей установщика, необязательные загрузки модели и llama-server, необязательные загрузки корпуса угроз и внешние интеграции Rizin/radare2 могут выполнять сетевые запросы при включении.
• Локальный кэш, журналы, метаданные сессии, управляемые IDB и доска объявлений могут содержать пути, метаданные анализа и находки. Защищайте каталоги установки/данных. Если вы передаёте ключ Gemini AI Studio установщику, ключ может быть записан в сгенерированный блок окружения MCP-клиента; предпочитайте учётные данные на основе окружения и проверьте конфигурацию клиента.

Для локальной настройки используйте локальную среду выполнения по умолчанию, оставьте Gemini и другие необязательные загрузки отключёнными и настройте MCP-клиент и его модель в соответствии с политикой данных вашей организации. «Только локально» всё ещё требует проверки того, что клиент отправляет своему собственному поставщику модели.

Частые проблемы

Установщик не может найти IDA

Укажите каталог установки явно:

Вы также можете задать IDADIR или IDA_DIR. Если найдено несколько установок, используйте --ida-version 9.3 или --no-ida-prompt для управления выбором. Убедитесь, что выбранный каталог содержит исполняемый idat или idat64.

Клиент не показывает IDA Pro MCP

Перезапустите клиент и проверьте его запись конфигурации. Убедитесь, что его команда использует управляемый Python из venv и -u -m ida_pro_mcp.host.server, и что блок env содержит правильный IDADIR. Проверьте install-report.json; установщик записывает сбои обновления клиента и сохраняет резервные копии рядом с изменёнными файлами. Формы конфигурации OpenCode и семейства Copilot отличаются от общего примера JSON.

Открытие бинарного файла занимает много времени или выглядит зависшим

Обычный вызов ida_open_binary ожидает начального анализа. Проверьте ida_session_status и ida_session_health, дайте больше времени для большого бинарного файла и проверьте журналы каждой сессии в каталоге установки/данных. Операция фонового открытия доступна, но она предназначена для случаев, когда вы понимаете её асинхронное поведение и ограничения безопасного режима.

Операция записи отклонена

Обычно это политика, работающая как настроено. Используйте ida_help для проверки точной схемы операции и её требования подтверждения. Не добавляйте произвольные аргументы: схемы строгие. Проверьте IDA_MCP_POLICY_MODE и файл политики оператора перед изменением политики. Отключение всех политических шлюзов — это отдельный, намеренно небезопасный выбор.

Семантический поиск недоступен

Семантический поиск необязателен и требует индекса и совместимого бэкенда эмбеддингов. Обычный листинг, поиск, декомпиляция и перекрёстные ссылки не требуют его. Чтобы настроить необязательный локальный путь, используйте явные опции эмбеддера установщика, например:

Установщик также может запустить --embedder-doctor, использовать явный путь к модели или загрузить выбранную модель и llama-server по запросу. Лицензии моделей, использование диска и сетевые загрузки — ваша ответственность. Если модель отсутствует, сервер должен сообщить, что семантический поиск недоступен, а не делать вид, что он выполнялся.

Установщик отклоняет конфигурацию клиента

Исправьте указанный синтаксис JSON, JSONC или TOML и перезапустите установщик. Он также отклоняет символические и необычные пути конфигурации, чтобы избежать перезаписи неожиданной цели. Существующие обычные файлы создаются резервные копии; поведение отката установщика по умолчанию может восстановить эти резервные копии, если более поздняя фаза завершится неудачей.

Сессия или среда выполнения IDA даёт сбой

Проверьте ida_session_health, журнал сессии и журнал моста. Убедитесь, что клиент использует тот же корень установки и IDADIR, которые записал установщик. Бэкенд idat по умолчанию даёт каждой сессии свой собственный процесс; не переключайтесь на экспериментальный idalib при диагностике базовой установки.

Справочные материалы

• Вики проекта — ориентированные на задачи руководства по установке, исследованию, редактированию и устранению неполадок.
• Локальные страницы вики — тот же написанный вручную материал, поставляемый для встроенного инструмента вики.
• Живое обнаружение операций — tools/list и ida_help раскрывают каждую публичную операцию, схему и пример.
• Модель безопасности — границы доверия, режимы политики, loopback-транспорт, владение сессией и защиты файловой системы.
• Рабочее пространство расследования — находки, доказательства, цели и экспорты.
• Интеллект и эмбеддинги — локальные и необязательные бэкенды извлечения Gemini.
• Настройка OpenCode — конфигурация OpenCode.
• Архитектура — хост, среда выполнения IDA и поток данных для читателей, которым нужны детали реализации.
• Политика безопасности — отчётность и рекомендации по безопасности.
• Живое тестирование IDA — что тесты репозитория доказывают и не доказывают о реальной установке IDA.
• Версионирование и контрольный список релиза и журнал изменений — альфа-статус и история релизов.
• Указатель документации — полная карта поддерживаемых руководств, справочников, страниц вики и исследовательских заметок.

Для точных имён операций используйте сгенерированный справочник или спросите работающий сервер с помощью ida_help. Старый бэкенд tool(action=...) остаётся доступным для совместимости и выбирается с помощью IDA_MCP_TOOL_SURFACE=legacy; новые интеграции должны использовать поверхность ida_* с точными схемами.