Reconstrução do código-fonte de Rats! com LLMs locais

Este repositório é uma reconstrução em andamento do código-fonte do RATS.EXE, a versão original para Windows de Rats! (1994) de Sean O'Connor. Ele compila um executável Win32 com Microsoft Visual C++ 4.1 sob wibo e pode ser testado no DREAMM.

O experimento explora até onde LLMs locais podem levar a reconstrução de código-fonte em uma base de código pequena, porém realista, em vez de um exemplo de brinquedo. A fidelidade da correspondência permanece desigual, o que é útil aqui: o objetivo é apresentar uma visão realista do processo e de suas limitações atuais, e não esconder funções difíceis.

A reconstrução de funções é restrita a LLMs locais. Codex e Claude são usados para a configuração do repositório e a orquestração de benchmarks, mas não têm permissão para escrever ou editar o código-fonte reconstruído.

Salvo indicação em contrário, todos os experimentos usaram o Qwen3.8 27B BF16 em um MacBook Pro de 2024 com Apple M4 Max (CPU de 16 núcleos, GPU de 40 núcleos) e 128 GB de memória. A abordagem funciona — de forma imperfeita, mas útil: as 36 funções mantidas levaram, cada uma, um tempo médio registrado de 2m 32.1s para reconstruir.

Configuração

Clone com submódulos ou inicialize-os após o clone:

git submodule update --init --recursive

O executável original não está incluído. Baixe a versão gratuita para Windows da página oficial de Rats! e coloque o RATS.EXE na raiz do repositório para usar os alvos original-executable e binary-comparison.

Comandos comuns

make                 # build out/RATS_RE.EXE, .map, .obj, and .asm
make toolchain       # download, extract, and verify Microsoft Visual C++ 4.1
make run             # launch the rebuilt executable in DREAMM
make run-original    # launch the preserved original RATS.EXE
make test            # bounded DREAMM smoke test of the rebuilt executable
make test-original   # bounded DREAMM smoke test of the original executable
make debug           # start the rebuilt executable in DREAMM's debugger
make report          # report similarity for every reconstructed function
make compare-func FUNC=SaveHighScores ADDR=00409092

O arquivo MSVC 4.1 com checksum fixado, as bibliotecas MSVC 4.1 necessárias, o msvcrt40.dll compatível com o wibo e o DREAMM 4.0x21 são baixados sob demanda. Eles permanecem como dependências locais de build ignoradas e não são commitados.

Fluxo de trabalho de reconstrução

O diretório ghidra/ versionado contém exportações de assembly e do decompilador para todas as 177 funções internas. O assembly é a autoridade de comparação; o C descompilado é apenas uma semente semântica.

Instale o binary-recons uma vez e execute-o a partir da raiz do repositório:

python3 -m pip install -e /path/to/binary-recons
binary-recons --next-function           # reconstruct the next safe missing target
binary-recons --address 0x409092        # reconstruct or improve a specific target

A ferramenta descobre o Qwen automaticamente no cache padrão do Hugging Face; BINARY_RECONS_MODEL_PATH pode substituí-lo. O binary-recons.toml mantém a seleção automática dentro dos intervalos de código do jogo, inicia e encerra o llama.cpp e define os arquivos transacionais e o comando binary-comp. Cada execução limitada semeia uma função a partir do Ghidra, pede ao Qwen reparos focados de compilação ou diff de assembly e retém o melhor candidato seguro que compila. Use --target-score 95 para uma passagem mais profunda ou --dry-run-prompt para inspecionar o prompt sem carregar o Qwen.

Execuções medidas com modelo local são registradas em docs/MODEL_RESULTS.md.

Agradecimentos

Agradecimentos especiais a:

• Sean O'Connor por criar Rats! e continuar disponibilizando sua versão original para Windows na página oficial do jogo.