Skip to content
maci0Public

About

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

Topics

Resources

Contributing

Security policy

Stars

15 stars

Watchers

1 watching

Forks

Latest commit

 

History

4,712 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Rebrew mascot

Rebrew

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

Rebrew recompiles your C with the compiler that built the target and compares the bytes against the target, function by function; a function is done when they are identical (EXACT, or RELOC after masking relocations). One Python CLI carries the compile-compare loop, a genetic-algorithm matcher, the function metadata store, and the verifier.

What it covers

  • Function authoring, byte diffs, compiler flag search, GA matching, and bounded symbolic proofs.
  • Library identification, globals/types, data layout, and whole-binary verification.
  • Prioritized work and separate file, executable-byte, and stored data-verdict accounting.
  • BinSync field reconciliation and provenance, plus live Ghidra structural operations.
  • Symbol exports: splat symbol_addrs, and a synthetic PDB stamped with the target's own debug-record GUID/age (rebrew export pdb, needs llvm-pdbutil).
  • Config-driven toolchains, compile caching, and six packaged agent workflows.

See the documentation index for guides, reference contracts, and integrations. The CLI reference owns command flags; toolchain documentation owns compiler/platform support.

Quick Start

Use Python 3.15+ and Linux x86_64 with Docker (default) or Podman for shipped compiler profiles. Wine, DOSBox, and native compiler runtimes live inside their images; missing images require rebrew toolchain pull <profile> or an authorized build from recompile-toolchains.

# Preferred: rebrew-*.whl from https://github.com/maci0/rebrew/releases.
# Installing it builds python-flirt from source, so it needs a Rust toolchain
# unless you override it with the exact published native wheel (see Development).
uv tool install ./rebrew-*.whl
# Fallback: from source (same Rust requirement).
uv tool install git+https://github.com/maci0/rebrew.git
mkdir my-decomp && cd my-decomp
rebrew intake /path/to/server.dll        # scaffold, detect compiler, discover, document stubs
rebrew doctor                           # resolve relevant prerequisite failures
rebrew toolchain list                    # inspect the detected profile
rebrew status --json                     # inspect accounting
rebrew todo --json                       # choose a scoped action

Use rebrew <command> for every tool, including CMake and objdiff build hooks; see the CLI reference. rebrew schema prints the clispec 0.3 document, needs no project, and stays JSON under rebrew -o text. For every other command, rebrew -o json <command> selects JSON and rebrew -o text stays text. Each command's own --json selects the same JSON output; it is declared per command, so it must follow the command name. A pipe stays text until one of those is set.

Symbolic proving needs the optional extra in the environment running Rebrew: uv tool install --reinstall 'rebrew[prove] @ git+https://github.com/maci0/rebrew.git'. BinSync needs the binsync extra; combine extras as rebrew[prove,binsync] when using both. Contributor checkouts use make setup.

intake does not run library detection or build coverage documents. Continue with Getting started. Project commands find rebrew-project.toml by walking up from the working directory; standalone binary inspection commands can accept a binary path.

For a manually configured project, use rebrew init --target server --binary server.dll, place the binary in original/, then follow rebrew doctor. Target names normally use the binary stem (server); binary filenames keep the extension (server.dll).

Working on a function

rebrew todo --json                       # select an existing stub or uncovered function
rebrew test src/server/fcn_10003da0.c --json
rebrew diff src/server/fcn_10003da0.c --json
rebrew verify --compare --json
rebrew lint --json
rebrew coverage export --output snapshots/                          # optional portable snapshots for offline viewing

intake names its stubs fcn_<VA>.c; for a catalog VA with no source, rebrew skeleton 0xVA prints the file it creates.

Check library attribution before implementing a function. test and verify earn byte verdicts, including regressions. EXACT and RELOC count as matched; a RELOC function whose bytes in the raw link equal the reference becomes EXACT through rebrew verify --text --raw-link (linked EXACT); PROVEN records semantic evidence under the proof's assumptions and earns no byte-match credit. See match types.

Function/data metadata are CLI/API-managed. Never hand-edit their TOMLs or write STATUS in C. Function identity and state live in format-3 MODULE.0xVA metadata rows; addressless evidence and support purposes live under [source] in the same store. Source can include optional /* ADDRESS: MODULE 0xVA */ anchors immediately above definitions. Retired source tags and old metadata formats are rejected. See metadata ownership.

For integration sync, preview a concrete state directory first:

rebrew sync pull --state-dir ./binsync-state --dry-run --json
rebrew binsync diff ./binsync-state --json

Apply incoming changes within the requested scope. Publishing state with --git-push, uploading source to decomp.me, and starting persistent watch/server processes require an explicit request. See BinSync integration.

Agent and library use

rebrew init copies AGENTS.md, PRINCIPLES.md, and packaged skills into a project. rebrew skills list --json lists the effective packaged/user-overlaid skills; load the skill matching the task and only the references needed for it. rebrew init --check detects scaffold drift; --refresh-agents regenerates it and keeps anything after the <!-- rebrew: project rules below, kept by --refresh-agents --> line.

The Python API guide covers library imports, registry views, structured errors, and injectable clients. The CLI/config compatibility policy and Python/API versioning policy are in CONTRIBUTING.md.

For component authors, the Cordis guide owns the composition contracts; its runnable tutorial demonstrates provider replacement and teardown.

Development

The maintained FLIRT binding builds from an immutable, hash-verified source archive and requires a Rust toolchain (qualified with Rust 1.99.1 and maturin 1.15.0). Normal CPython 3.15 wheels for qualified Linux glibc, macOS ARM64, and Windows AMD64 hosts are available in the maintained binding release. The Rebrew wheel and source archive are distributed through GitHub releases; the direct source dependency is not compatible with Warehouse/PyPI publishing. Managed fixed-platform deployments can override this requirement with the exact published native wheel using tool.uv.override-dependencies; its hash must be checked before installation. Free-threaded Python and musl are not qualified. The optional binsync extra needs a JDK and Apache Ant on PATH to build JPype 1.7.1 on Python 3.15 (qualified with OpenJDK 27 and Ant 1.10.18).

A contributor checkout also needs a sibling resembl checkout at ../resembl (tag v5.3.0) and the host tools listed in CONTRIBUTING.md, which also says which gate needs each one. From the directory that will hold both checkouts:

git clone https://github.com/maci0/rebrew.git
cd rebrew/
make doctor                # report every missing prerequisite and its fix (read-only)
make clone-resembl         # clone the pinned resembl into ../resembl
make setup                 # uv sync --locked --all-extras --group similarity + pre-commit hooks
make test-one T=tests/test_annotation_roundtrip.py   # single-file edit-test loop
make test                  # full suite
make pr-check              # the local CI gates, before a pull request

make help lists the contributor targets.

Flag-axis refresh from decomp.me (maintainer, needs network): make gen-flags (FLAGS_REF=<commit-or-tag> to sync a pinned ref instead of the default branch, make gen-flags-check to report upstream drift). The generated header's Synced: date follows SOURCE_DATE_EPOCH, so re-syncing one upstream commit writes the same file.

Ecosystem

ECOSYSTEM.md maps public compiler, similarity, coverage and third-party interoperability boundaries. Integration details belong in the topical guides linked from the documentation index.

License

MIT. See LICENSE. Optional dependency grants and required notices are recorded in NOTICE.

About

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

Topics

Resources

Contributing

Security policy

Stars

15 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages