$ show simonlindholm/decomp-permuter
This repository is a specialized tool for automated C code permutation to match a target compiled binary, primarily used in video game decompilation projects (e.g., Nintendo 64). The core loop reads a C source file and a target object file, then repeatedly mutates the C code using a set of predefined random transformations, compiles it, disassembles the output, and scores the resulting assembly against the target. The goal is to produce a C source that compiles to identical or nearly identical assembly, reducing manual effort in reverse engineering. The architecture is a Python CLI application with support for multi-threading and distributed computing. The main entry points are `permuter.py` (local mode), `import.py` (project setup), and `pah.py` (network client for distributed 'permuter@home'). The system relies on a vendored fork of pycparser for C parsing and AST manipulation, and it integrates with external tools: a C compiler (GCC, IDO, or MWCC), `objdump` for disassembly, and optionally Docker for sandboxed remote evaluation. A Rust server (`src/net/controller`) manages the distributed network, and a Go systray helper provides a system tray icon for the network client. Data flows are iterative: the tool seeds a candidate, applies one or more random permutations (e.g., introducing temporaries, reordering declarations, transforming expressions), compiles the result, extracts assembly, scores it using a diff-based algorithm, and keeps the best candidate. The process repeats until a perfect match is found or the user stops it. The project demonstrates high craftsmanship in its modular design, with clean abstractions for permutations, scoring, AST utilities, and networking. The vendored pycparser is heavily patched for GNU C extensions, and the custom stubs ensure type safety.
The LLM identified 3 files worth highlighting for reuse:
Defines the Perm base class and its subclasses for representing C code transformations. Each Perm has a unique id, a deterministic seed-based evaluation method, and can be marked as random. The class hierarchy provides a clean, extensible framework for implementing new permutations (e.g., perm_expand_expr, perm_reorder_decls). The pattern is self-contained and could be extracted to build a general-purpose AST transformation library with weighted random selection.
Provides a comprehensive set of functions for parsing C code, normalizing ASTs, pruning unused declarations, inserting declarations and statements, and comparing ASTs. Includes helper functions like `make_decl`, `insert_decl`, `brace_nested_blocks`, `compute_node_indices`. This module is well-isolated (depends only on the vendored pycparser) and can be reused in any project that requires C AST manipulation, such as code transformation tools or static analysis.
Contains dictionaries (MIPS_SETTINGS, ARM32_SETTINGS) that map architecture-specific objdump flags, register sets, and instruction patterns. These are modular and could be extracted to build a configurable disassembly wrapper for multiple CPU architectures. The file also handles ELF relocation filtering and branch target extraction, providing a reusable base for assembly comparison tools.