unidbg

Позволяет эмулировать нативную библиотеку Android, а также экспериментальную эмуляцию iOS.

Это образовательный проект, чтобы узнать больше о форматах файлов ELF/MachO и ассемблере ARM.

Используйте его на свой страх и риск!

Возможности

• Поддержка MCP (Model Context Protocol) для отладки с помощью ИИ в Cursor и других ИИ-инструментах.
• Эмуляция JNI Invocation API, чтобы можно было вызывать JNI_OnLoad.
• Поддержка JavaVM, JNIEnv.
• Эмуляция инструкций syscalls.
• Поддержка ARM32 и ARM64.
• Inline-хуки благодаря Dobby.
• Хуки импортов Android благодаря xHook.
• iOS fishhook, substrate и whale хуки.
• Бэкенд unicorn с поддержкой простого консольного отладчика, gdb stub, трассировки инструкций, трассировки чтения/записи памяти.
• Поддержка iOS objc и swift runtime.
• Поддержка быстрого бэкенда dynarmic.
• Поддержка гипервизора Apple M1 — самый быстрый ARM64-бэкенд.
• Поддержка Linux KVM бэкенда с Raspberry Pi B4.
• Обнаружение утечек памяти для эмулируемого нативного кода с гостевой трассировкой стека и трассировкой стека хоста.

MCP-отладчик (интеграция с ИИ)

unidbg поддерживает Model Context Protocol (MCP) для отладки с помощью ИИ. Когда отладчик активен, введите mcp в консоли, чтобы запустить MCP-сервер, к которому могут подключаться ИИ-инструменты (например, Cursor).

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

unidbg MCP имеет два режима работы:

Режим 1: Отладка по точкам останова — Подключите отладчик и запустите свой код. При срабатывании точки останова Breaker.debug() приостанавливает эмулятор — введите mcp в консоли, чтобы запустить MCP-сервер и позволить ИИ помочь с анализом. Доступны все инструменты отладки (регистры, память, дизассемблирование, выполнение по шагам, трассировка и т.д.). После возобновления выполнения при следующей точке останова отладчик снова остановится. Когда выполнение завершится без срабатывания точек останова, процесс завершится и MCP остановится.

Debugger debugger = emulator.attach();
debugger.addBreakPoint(address);
// run your emulation logic — debugger pauses when breakpoint is hit

Режим 2: Пользовательские инструменты (повторяемые) — Используйте McpToolkit для регистрации пользовательских инструментов и позвольте ИИ повторно запускать целевые функции с разными параметрами. Нативная библиотека загружается один раз; после каждого выполнения процесс остаётся активным, и MCP остаётся доступным для следующего запуска.

McpToolkit toolkit = new McpToolkit();
toolkit.addTool(new McpTool() {
    @Override public String name() { return "encrypt"; }
    @Override public String description() { return "Run encryption"; }
    @Override public String[] paramNames() { return new String[]{"input"}; }
    @Override public void execute(String[] params) {
        String input = params.length > 0 ? params[0] : "default";
        // call encryption with input
    }
});
toolkit.run(emulator.attach());

Когда отладчик останавливается, введите mcp (или mcp 9239, чтобы указать порт) в консоли. Затем добавьте в настройки MCP в Cursor:

{
  "mcpServers": {
    "unidbg-mcp-server": {
      "url": "http://localhost:9239/sse"
    }
  }
}

Доступные MCP-инструменты

Статус и информация

Инструмент	Описание
check_connection	Статус эмулятора: семейство, архитектура, возможности бэкенда, isRunning, загруженные модули
list_modules / get_module_info	Перечислить загруженные модули, получить подробную информацию, включая количество экспортируемых символов и зависимости
list_exports	Перечислить экспортируемые/динамические символы модуля с опциональным фильтром и деманглингом C++
find_symbol	Найти символ по имени или ближайший символ по адресу
get_threads	Перечислить все потоки/задачи в эмуляторе

Регистры и дизассемблирование

Инструмент	Описание
get_registers / get_register / set_register	Чтение/запись регистров ЦП
disassemble	Дизассемблировать инструкции по адресу (адреса переходов автоматически аннотируются именами символов)
assemble	Ассемблировать текст инструкции в машинный код
get_callstack	Получить текущий стек вызовов (backtrace)

Память

Инструмент	Описание
read_memory / write_memory	Чтение/запись сырых байтов памяти
read_string / read_std_string	Чтение C-строки или C++ std::string (с определением SSO)
read_pointer	Чтение цепочки указателей с разрешением символов
read_typed	Чтение памяти как типизированных значений (int8–int64, float, double, pointer)
search_memory	Поиск байтовых паттернов в памяти с фильтрами по области/правам доступа
list_memory_map	Перечислить все отображения памяти с правами доступа
allocate_memory / free_memory / list_allocations	Выделение (malloc/mmap) с опциональными начальными данными, освобождение и отслеживание блоков памяти
patch	Записать ассемблированные инструкции в память

Точки останова и выполнение

Инструмент	Описание
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Добавить точки останова по адресу, символу или модуль+смещение
remove_breakpoint / list_breakpoints	Удалить или перечислить точки останова (с дизассемблированием)
continue_execution	Возобновить выполнение. Используйте poll_events для ожидания breakpoint_hit или execution_completed
step_over / step_into / step_out	Шаг с обходом, шаг с заходом (на N инструкций), шаг из функции
next_block	Остановиться на следующем базовом блоке (только Unicorn)
step_until_mnemonic	Остановиться на следующей инструкции, соответствующей мнемонике, например bl, ret (только Unicorn)
poll_events	Опрашивать события breakpoint_hit, execution_completed, trace

Трассировка

Инструмент	Описание
trace_code	Трассировать инструкции со значениями чтения/записи регистров (regs_read, prev_write)
trace_read / trace_write	Трассировать чтение/запись памяти в диапазоне адресов

Вызовы функций

Инструмент	Описание
call_function	Вызвать нативную функцию по адресу с типизированными аргументами (hex, string, bytes, null). Возвращает значение с разрешением символов и предпросмотром памяти
call_symbol	Вызвать экспортируемую функцию по модулю + имени символа, например libc.so + malloc

Только iOS (доступно, когда Family=iOS)

Инструмент	Описание
inspect_objc_msg	Проверить вызов objc_msgSend: показать имя класса получателя и селектор, например -[NSString length]
get_objc_class_name	Получить имя класса ObjC объекта по заданному адресу (только разбор памяти, без изменения состояния)
dump_objc_class	Дамп определения класса ObjC (свойства, методы, протоколы, ivars)
dump_gpb_protobuf	Дамп схемы сообщения GPB protobuf в формате .proto (только 64-бит)

Пользовательские MCP-инструменты

Используйте McpToolkit для регистрации пользовательских инструментов, каждый из которых реализует интерфейс McpTool. Это заменяет ручную диспетчеризацию if-else чистыми самодостаточными классами инструментов. К этому моменту нативная библиотека полностью загружена (JNI_OnLoad / точка входа уже выполнены), поэтому код внутри execute() каждого инструмента — это логика целевой функции для анализа. ИИ может устанавливать точки останова и трассировки перед запуском пользовательского инструмента, а затем проверять результаты выполнения с разными входными данными без перезапуска процесса.