unidbg

Permite emular uma biblioteca nativa do Android, além de uma emulação experimental de iOS.

Este é um projeto educacional para aprender mais sobre o formato de arquivo ELF/MachO e assembly ARM.

Use por sua conta e risco!

Recursos

• Suporte a MCP (Model Context Protocol) para depuração assistida por IA com Cursor e outras ferramentas de IA.
• Emulação da API de Invocação JNI para que JNI_OnLoad possa ser chamada.
• Suporte a JavaVM, JNIEnv.
• Emulação da instrução syscall.
• Suporte a ARM32 e ARM64.
• Hook inline, graças a Dobby.
• Hook de importação do Android, graças a xHook.
• Hook de fishhook, substrate e whale para iOS.
• Backend unicorn com suporte a console debugger simples, gdb stub, trace de instruções, trace de leitura/escrita de memória.
• Suporte ao runtime objc e swift do iOS.
• Suporte ao backend rápido dynarmic.
• Suporte ao hypervisor Apple M1, o backend ARM64 mais rápido.
• Suporte ao backend Linux KVM com Raspberry Pi B4.
• Detecção de vazamento de memória para código nativo emulado com backtrace do guest e stack trace do host.

Depurador MCP (Integração com IA)

unidbg suporta Model Context Protocol (MCP) para depuração assistida por IA. Quando o depurador estiver ativo, digite mcp no console para iniciar um servidor MCP ao qual ferramentas de IA (ex.: Cursor) podem se conectar.

Início Rápido

O MCP do unidbg tem dois modos de operação:

Modo 1: Depuração por Breakpoint — Anexe o depurador e execute seu código. Quando um breakpoint é atingido, Breaker.debug() pausa o emulador — digite mcp no console para iniciar o servidor MCP e deixar a IA ajudar na análise. Todas as ferramentas de depuração estão disponíveis (registradores, memória, desmontagem, stepping, rastreamento, etc.). Após retomar, se outro breakpoint for atingido, o depurador pausa novamente. Quando a execução termina sem atingir um breakpoint, o processo é encerrado e o MCP é desligado.

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

Modo 2: Ferramentas Personalizadas (Repetível) — Use McpToolkit para registrar ferramentas personalizadas e deixar a IA re-executar funções alvo com parâmetros diferentes. A biblioteca nativa é carregada uma única vez; após cada execução, o processo permanece ativo e o MCP continua disponível para a próxima execução.

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());

Quando o depurador pausar, digite mcp (ou mcp 9239 para especificar a porta) no console. Em seguida, adicione às configurações de MCP do Cursor:

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

Ferramentas MCP Disponíveis

Status e Informações

Ferramenta	Descrição
check_connection	Status do emulador: Family, arquitetura, capacidades do backend, isRunning, módulos carregados
list_modules / get_module_info	Lista módulos carregados, obtém detalhes incluindo contagem de símbolos exportados e dependências
list_exports	Lista símbolos exportados/dinâmicos de um módulo com filtro opcional e demangling de C++
find_symbol	Encontra símbolo por nome ou encontra o símbolo mais próximo de um endereço
get_threads	Lista todas as threads/tarefas no emulador

Registradores e Desmontagem

Ferramenta	Descrição
get_registers / get_register / set_register	Lê/escreve registradores da CPU
disassemble	Desmonta instruções em um endereço (alvos de branch anotados automaticamente com nomes de símbolos)
assemble	Monta texto de instrução em código de máquina
get_callstack	Obtém a pilha de chamadas atual (backtrace)

Memória

Ferramenta	Descrição
read_memory / write_memory	Lê/escreve bytes brutos de memória
read_string / read_std_string	Lê string C ou std::string de C++ (com detecção de SSO)
read_pointer	Lê cadeia de ponteiros com resolução de símbolos
read_typed	Lê memória como valores tipados (int8–int64, float, double, pointer)
search_memory	Busca padrões de bytes na memória com filtros de escopo/permissão
list_memory_map	Lista todos os mapeamentos de memória com permissões
allocate_memory / free_memory / list_allocations	Aloca (malloc/mmap) com dados iniciais opcionais, libera e rastreia blocos de memória
patch	Escreve instruções montadas na memória

Breakpoints e Execução

Ferramenta	Descrição
add_breakpoint / add_breakpoint_by_symbol / add_breakpoint_by_offset	Adiciona breakpoints por endereço, símbolo ou módulo+offset
remove_breakpoint / list_breakpoints	Remove ou lista breakpoints (com desmontagem)
continue_execution	Retoma a execução. Use poll_events para aguardar breakpoint_hit ou execution_completed
step_over / step_into / step_out	Passo por cima, para dentro (N instruções) ou para fora da função
next_block	Pausa no próximo bloco básico (somente Unicorn)
step_until_mnemonic	Pausa na próxima instrução que corresponda ao mnemônico, ex.: bl, ret (somente Unicorn)
poll_events	Consulta eventos de breakpoint_hit, execution_completed e trace

Rastreamento

Ferramenta	Descrição
trace_code	Rastreia instruções com valores de leitura/escrita de registradores (regs_read, prev_write)
trace_read / trace_write	Rastreia leituras/escritas de memória em um intervalo de endereços

Chamadas de Função

Ferramenta	Descrição
call_function	Chama função nativa por endereço com argumentos tipados (hex, string, bytes, null). Retorna o valor com resolução de símbolos e pré-visualização de memória
call_symbol	Chama função exportada por módulo + nome do símbolo, ex.: libc.so + malloc

Somente iOS (disponível quando Family=iOS)

Ferramenta	Descrição
inspect_objc_msg	Inspeciona a chamada objc_msgSend: mostra o nome da classe do receiver e o selector, ex.: -[NSString length]
get_objc_class_name	Obtém o nome da classe ObjC de um objeto em um endereço específico (somente parsing de memória, sem mudança de estado)
dump_objc_class	Gera dump da definição da classe ObjC (propriedades, métodos, protocolos, ivars)
dump_gpb_protobuf	Gera dump do esquema de mensagem GPB protobuf no formato .proto (somente 64 bits)

Ferramentas MCP Personalizadas

Use McpToolkit para registrar ferramentas personalizadas, cada uma implementando a interface McpTool. Isso substitui o despacho manual baseado em if-else por classes de ferramentas limpas e autocontidas. Neste ponto, a biblioteca nativa já está totalmente carregada (JNI_OnLoad / ponto de entrada já executados), então o código dentro de execute() de cada ferramenta é a lógica da função alvo a ser analisada. A IA pode definir breakpoints e traces antes de acionar uma ferramenta personalizada e, em seguida, inspecionar os resultados da execução com diferentes entradas sem reiniciar o processo.