☕ Rebrew

Compiler-in-the-loop decompilation workbench for binary-matching game reversing.

Rebrew is a reusable Python tooling package for reconstructing exact C source code from compiled binaries. It provides a genetic algorithm engine, source metadata pipeline, verification framework, and CLI tools.

✨ Features

Core Loop

Tool	What it does
rebrew test	Compile your C and diff it byte-by-byte against the original binary
rebrew match	GA engine — single file or batch (--all); brute-force compiler flags and mutate source to find exact byte matches
rebrew verify	Bulk compile + report match status; always auto-updates metadata; --compare for CI regression checks; --watch re-verifies on every change
rebrew prove	Symbolic equivalence via angr + Z3 — mathematically prove NEAR_MATCHING functions are equivalent
rebrew near-diag	Classify why a NEAR_MATCHING function misses: register allocation, equivalent instruction selection, relocation masking, or structural layout

Authoring

Tool	What it does
rebrew skeleton	Generate annotated .c stubs from VAs; --decomp for inline decompilation; --xrefs for caller context
rebrew rename	Rename a function across the entire codebase (symbol, filename, cross-references)
rebrew split	Break multi-function .c files into individual files; --va to extract one function
rebrew merge	Combine single-function files into one multi-function file
rebrew lint	Validate source marker correctness (E000–E023 errors, W003–W028 warnings, incl. W019 inline-metadata and W020 asm-dump warnings)

Analysis

Tool	What it does
rebrew todo	Prioritized action list: what to work on next
rebrew status	Per-target breakdown of EXACT / RELOC / NEAR_MATCHING / STUB counts
rebrew graph	Call graph from extern declarations (mermaid, DOT, summary)
rebrew data	Inventory .data/.rdata/.bss globals; detect dispatch tables and vtables
rebrew flirt	Identify known library functions via FLIRT signatures — no IDA required
rebrew crt-match	Cross-reference functions against CRT/library source directories
rebrew similar	Rank binary functions by structural similarity to a solved function — find which STUBs share its source family

Infrastructure

Tool	What it does
rebrew init	Scaffold a new project with config, directories, and agent skills
rebrew doctor	Validate project health (config, compiler, binary); --install-wibo
rebrew catalog	Build function catalog and coverage JSON
rebrew build-db	Build SQLite coverage database from catalog
rebrew cache	Compile cache management (stats, clear)
rebrew cfg	Read/write rebrew-project.toml settings
rebrew extract	Batch extract function bytes and disassembly
rebrew binsync-export	Export source markers and metadata to BinSync state directory (IDA/BinNinja import; real types + struct fields, --module, --git)
rebrew binsync-import	Import a BinSync state directory into rebrew metadata (names + prototypes + globals, --accept-binsync/--accept-local, --module)
rebrew round-trip	Splice matched functions back into the target PE and verify byte equality
rebrew asm	Quick offline disassembly
rebrew skills	List/show the bundled agent skills
rebrew sync	Push/pull source markers, metadata, labels, structs, and comments to Ghidra via ReVa MCP

Onboarding & Intelligence

Tool	What it does
rebrew intake	One-shot binary onboarding: init + toolchain detect + functions + document-unmatched in a single command
rebrew analyze	One-shot intelligence dossier for a binary — layout, toolchain, strings, imports, dispatch tables, FLIRT matches. Works standalone outside a project
rebrew discover-functions	Function enumeration (rizin aaa/aap + capstone sweep) with validated boundaries and sizes
rebrew document-unmatched	Write STUB skeletons + blockers for every function in the list that isn't documented yet (re-discovery workflow; idempotent)
rebrew identify-library	Identify library functions (FLIRT + imports + CRT) into library_*.h; --build-sigs generates the sigs from the toolchain .lib files first
rebrew pdb-info	Extract compiler version, exact command line (S_COMPILE3), and function names from a PDB

Design

• Config-driven — all tools read from rebrew-project.toml, zero manual path arguments
• Multi-target — PE, ELF, Mach-O, and 16-bit Windows NE across x86-16, x86, x64, ARM32/64 with --target selection
• Idempotent — every tool safe to re-run without side effects
• Composable — small single-purpose tools designed for scripting and AI agent chaining
• Compile cache — disk-backed SHA-256 cache avoids redundant recompilations
• Agent-friendly — bundled agent-skills/ copied to projects on rebrew init

Agent Skills

Five bundled skills for AI coding agent integration:

Skill	Purpose
rebrew-workflow	End-to-end reversing workflow and status tracking
rebrew-matching	GA matching engine, flag sweeps, diff analysis
rebrew-data-analysis	Global data scanning, BSS layout, dispatch tables
rebrew-intake	Binary onboarding, triage, and initial FLIRT scanning
rebrew-ghidra-sync	Ghidra ↔ Rebrew sync via ReVa MCP

🚀 Quick Start

Host requirements: Linux with Docker. Every Windows/DOS compiler profile executes inside its toolchain image (wine/DOSBox live in the image; there is no host wine path) — build or pull it with rebrew toolchain build <name> (see docs/TOOLCHAIN.md). Analysis-only commands (asm, analyze, flirt, catalog, …) are pure Python 3.12+ and have no host-OS requirement.

# 1. Install
uv tool install git+https://github.com/maci0/rebrew.git
# 2. Create a project
mkdir my-decomp &&cd my-decomp
rebrew init --target server --binary server.dll
# 3. Place your binary
cp /path/to/server.dll original/
# 4. Start reversing
rebrew doctor # verify setup
rebrew todo -c start-function # find easiest uncovered functions
rebrew skeleton 0x10003DA0 # generate first stub
rebrew test src/server/func_10003da0.c # compile and compare

rebrew init creates rebrew-project.toml, source/bin directories, and agent skills. All tools find the config by searching upward from the current directory (like git finds .git/).

💻 Usage & Workflow

All CLI tools must be run from within a project directory that contains a rebrew-project.toml config file.

cd /path/to/your-decomp-project # must contain rebrew-project.toml# Project Setup
rebrew init --target mygame --binary mygame.exe --compiler msvc6 # initialize project
rebrew cfg list-targets # list configured targets
rebrew cfg set-cflags ZLIB "/O3"# set cflags for origin
rebrew cfg set compiler.cflags "/O1"# set a config value
rebrew cfg show targets.main.arch # read a value (supports dotted target names)
rebrew cfg raw # dump config as JSON
rebrew cfg path # print config file path
rebrew cfg detect-crt --write # auto-detect MSVC CRT source directories# Development
rebrew skeleton 0x10003DA0 # generate C skeleton from disassembly
rebrew skeleton 0x10003DA0 --xrefs # skeleton with Ghidra cross-reference context
rebrew test src/target_name/f.c # test implementation against target
rebrew todo # see highest ROI action items
rebrew todo --stats # show overall progress statistics
rebrew todo -c fix-delta --json # tiny byte diffs (quick wins, sorted by ROI)
rebrew todo -c extract-error # symbols missing from .obj (marker/impl issue)
rebrew flirt --json # FLIRT scan: identify known library functions
rebrew crt-match 0x10006c00 # match a single VA against CRT source
rebrew crt-match --all --origin MSVCRT # match all MSVCRT functions
rebrew crt-match --fix-source --all # auto-write // SOURCE: markers
rebrew crt-match --index # show CRT source index
rebrew graph --cu-map # infer compilation unit boundaries
rebrew graph --cu-map --json # JSON output for scripting
rebrew lint # lint source markers in your files
rebrew split src/target_name/multi.c # split multi-function file into individual files
rebrew split --va 0x10003DA0 src/target_name/multi.c # extract one function into multi_c/
rebrew merge a.c b.c --output merged.c # merge files into one multi-function file
rebrew merge multi_c/ multi.c -o multi.c --force --delete # merge extracted function back
rebrew catalog # regenerate the function catalog and coverage JSON
rebrew catalog --data-json # write db/data_<target>.json
rebrew catalog --export-ghidra-labels # generate ghidra_data_labels.json from detected tables
rebrew build-db # build SQLite coverage database from catalog
rebrew binsync-export ./binsync_out # export source markers and metadata to BinSync state directory
rebrew binsync-import ./binsync_out --dry-run # import names + prototypes + globals from a BinSync state (dry-run)# Matching
rebrew match --diff-only src/target_name/f.c # side-by-side disassembly diff
rebrew match --diff-only --mm src/target_name/f.c # show only structural diffs (**)
rebrew match src/target_name/f.c # run the Genetic Algorithm Engine to resolve diffs
rebrew match --all # batch GA on all STUB functions
rebrew match --all --improve # batch GA on all NEAR_MATCHING functions
rebrew match --all --near-miss --threshold 5 # batch GA on NEAR_MATCHING with ≤5B delta
rebrew match --all --flag-sweep # batch flag sweep on all NEAR_MATCHING functions
rebrew match --all --flag-sweep --fix-cflags # targeted sweep, auto-update CFLAGS# Semantic Equivalence (requires angr: uv pip install -e ".[prove]")
rebrew prove src/server.dll/calculate_physics.c # prove NEAR_MATCHING function equivalent
rebrew prove src/server.dll/calculate_physics.c --json # JSON output
rebrew prove my_func --dry-run # find by symbol, preview only# Export & Sync
rebrew verify # bulk compile and auto-update STATUS/BLOCKER metadata
rebrew verify --json # structured JSON report to stdout
rebrew verify --compare # detect regressions against last saved report
rebrew split src/target_name/multi.c --dry-run # preview split without writing
rebrew split --va 0x10003DA0 --dry-run src/target_name/multi.c # preview single extraction
rebrew merge a.c b.c -o merged.c --delete # merge and delete originals
rebrew extract list # list un-reversed candidates
rebrew extract batch 20 # extract and disassemble first 20 smallest
rebrew asm # quick offline disassembly
rebrew cache stats # show compile cache hit rate and size
rebrew doctor --install-wibo # auto-download wibo (lightweight Wine alternative)# Ghidra Sync via ReVa MCP
rebrew sync --push # export source markers and metadata and push to Ghidra
rebrew sync --pull # fetch Ghidra renames into local files
rebrew sync --pull --accept-ghidra # fetch renames and automatically update cross-references
rebrew sync --pull-signatures # fetch Ghidra decompilation to update extern prototypes
rebrew sync --pull-structs # export Ghidra structs into types.h
rebrew sync --pull-comments # fetch Ghidra EOL/post analysis comments into source
rebrew sync --pull-data # fetch Ghidra data labels into rebrew_globals.h
rebrew sync --pull --dry-run # preview pull without modifying files

⚙️ Supported Platforms

Architecture	Binary Format	Compiler	Binary Loading	Object Parsing	GA Matching	Verification
x86 (16-bit)	NE (Windows 3.x)	Borland Delphi 1.0 / Turbo Pascal	✅	⬜	⬜	⬜
x86 (16-bit)	NE (Windows 3.x)	MSVC 16-bit (C 7.0 / VC 1.x)	✅	⬜	⬜	⬜
x86 (32-bit)	PE (.exe/.dll)	MSVC 5.0 / 6.0	✅	✅	✅	✅
x86 (32-bit)	PE	MSVC 7.x+	✅	✅	✅	✅
x86 (32-bit)	PE	MinGW GCC / Zig (gcc-pe profile)	✅	✅	✅	✅
x86 (32-bit)	PE	Watcom C	✅	✅ (OMF→COFF via objconv)	✅	⬜
x86 (32-bit)	ELF (.so/exec)	GCC/Clang	✅	✅	⬜	⬜
x86_64	PE	MSVC	✅	✅	⬜	⬜
x86_64	ELF	GCC/Clang	✅	✅	⬜	⬜
x86_64	Mach-O	Clang	✅	✅	⬜	⬜
ARM32	ELF	GCC/Clang	✅	✅	⬜	⬜
ARM64	ELF	GCC/Clang	✅	✅	⬜	⬜
ARM64	Mach-O	Clang	✅	✅	⬜	⬜

Legend: ✅ Supported ⬜ Planned / Not yet implemented

16-bit NE targets are parsed, enumerated, and analyzed natively (intake, analyze, asm, describe, data, report — see docs/TOOLCHAIN.md); byte matching and verification short-circuit with a notice because no 16-bit compiler profile exists yet (ADR-001).

Toolchain detection:rebrew intake/analyze auto-detect the compiler family and version — DIE (diec) signatures first, then PDB records, then structural heuristics (strings, imports, codegen style, section layout). 16-bit NE family comes from the Borland segment-marker convention (delphi vs MSVC-style markerless segments). When diec misses a compiler record, the Microsoft Linker version still pins the MSVC era.

Compiler profiles:msvc6 is the default — all Windows/DOS profiles (every msvc* from 1.0 through 11.0, borlandc55, tc16/tc20, watcom, delphi16) compile inside per-toolchain docker images (wine/DOSBox live in the image; there is no host wine/wibo path). gcc-pe targets MinGW GCC / Zig PE builds, gcc/clang cover ELF/x86_64, and watcom16 is the one native DOS profile. Service-pack variants (msvc600sp1–msvc600sp6, msvc700sp1, …) cover the pin-specific codegen differences. Profile selection happens automatically on rebrew intake from the detected family; the full list is rebrew toolchain list.

🛠️ Development

cd rebrew/
make setup # uv sync --frozen --all-extras + pre-commit hooks# or: uv sync --frozen --all-extras
uv run pytest tests/ -v # run tests
uv run ruff check src/ tests/ tools/
uv run ruff format src/ tests/ tools/
make build # sdist + wheel (SOURCE_DATE_EPOCH / TZ=UTC for deterministic wheels)
python tools/sync_decomp_flags.py # sync compiler flags from decomp.me

Flag Sweep Tiers

The flag sweep uses compiler flag definitions synced from decomp.me. The generate_flag_combinations(tier) function supports five effort levels: quick (192 combos), targeted (~1.2K combos), normal (~5.4K combos), thorough (~258K combos), and full (~6.2M combos; stride-sampled down to a 100K memory bound). The msvc6 compiler profile automatically excludes incompatible MSVC 7.x+ flags. See docs/FLAG_SWEEP_TIERS.md.

🌐 Ecosystem & Related Tools

Rebrew is part of a broader decompilation ecosystem. These are the notable projects it integrates with or draws from:

Integrated

Tool	Role	Integration
decomp.me	Collaborative decompilation platform	Flag axes synced via tools/sync_decomp_flags.py; powers rebrew match --flag-sweep
reccmp	Binary recompilation comparison framework	Source marker format compatibility; rebrew catalog --csv exports reccmp-compatible CSV
LIEF	Binary format parsing (PE/ELF/Mach-O)	Used for binary loading, format detection, and PE section analysis
Capstone	Disassembly engine	Powers rebrew asm, byte-diff scoring, relocation masking, and mnemonic comparison
angr	Binary analysis + symbolic execution	Powers rebrew prove for Z3-based semantic equivalence proving (optional dep)
ReVa	Ghidra MCP bridge	rebrew sync pushes/pulls source markers, metadata, labels, structs, and comments to Ghidra

Adjacent Tools

Tool	What it does	Relevance
asm-differ	Assembly diff with levenshtein alignment	Used by decomp.me for all diffs; rebrew has its own capstone-based differ
decomp-permuter	Source-level permutation finder for matching decompilation	Complementary to rebrew match's GA: explores semantic-preserving C rewrites (variable types, statement order, parenthesisation) until the compiler emits identical assembly. Candidate for integration as an alternative mutation engine or seed source for the GA.
objdiff	Rust GUI for object file diffing (COFF/ELF/Mach-O)	Visual companion for inspecting match differences
decomp-toolkit	GameCube/Wii decompilation toolkit	DOL/REL focused; similar split/link/diff workflow concepts
wibo	Lightweight Win32 PE loader	Faster alternative to Wine for running MSVC CL.EXE
Ghidra	NSA's reverse engineering suite	Primary disassembler/decompiler; connected via ReVa MCP
FLIRTDB	FLIRT signature database	Signatures for MSVC, Borland, MinGW used by rebrew flirt

Companion Projects

Project	What it is
recompile.online	Compiler-as-a-service API over the rebrew toolchain zoo — submit C + a toolchain id, get the compiled artifact (separate workspace: ../recompile)
recoverage	Coverage database / dashboard over rebrew build-db output

License

MIT