Permanent Beta

permanent beta

Keep function hooks working when the program they hook is rebuilt or updated.

For Windows PE binaries, x64 and x86, built with MSVC. Free and open source (Apache-2.0).

What it does

A hook (Microsoft Detours, MinHook, …) patches a function at an address in one specific build. When the program is rebuilt, every address moves and the hooks break, and normally someone re-finds each function by hand in a disassembler.

pbeta does that part. It finds each hooked function in the new build, verifies it's the same function, and rewrites your hook list with the new addresses. Anything it isn't sure about goes to a review queue instead of being guessed. A generic hook DLL, the hook host, then attaches your hooks in whichever build is running, so you don't write hook plumbing or hard-code addresses.

  1. Analyze the old and new builds, with PDBs if you have them.
  2. Repair your hook manifest: each hook is unchanged, relocated, or sent to review.
  3. Run the program through the hook host, which attaches only hooks verified for that build.

Principles

  • Wrong is worse than unknown. A hook is never patched at a guessed address.
  • Matching proposes, verification judges. Every candidate passes the same independent checks.
  • Evidence is kept. Mappings and review decisions are stored with their evidence.
  • Local by default. Nothing leaves the machine unless you opt in.

Tested on six open-source projects across release tags and optimization settings, for both x64 and x86, with zero wrong matches on all 136 variants.

Getting started

You need the stable Rust toolchain (rustup.rs). The hook host also needs Visual Studio's C++ toolset and git.

git clone https://github.com/ryancole/permanent-beta
cd permanent-beta
cargo build --release
pwsh harness/host/build.ps1

Try the demo

Two hand-written analyses and a manifest whose four hooks each show one outcome:

cargo run -p permanent-beta-cli -- repair --old examples/demo/v1.json --new examples/demo/v2.json --hooks examples/demo/hooks.toml --out target/hooks.v2.toml --store target/demo-store.json
cargo run -p permanent-beta-cli -- review list --store target/demo-store.json

Use it on your own program

Take two builds of a program you have the right to instrument: old\app.exe, the one your hooks were written for, and new\app.exe. Describe your hooks in hooks.toml, then:

pbeta analyze old\app.exe --pdb old\app.pdb --out old.json
pbeta analyze new\app.exe --pdb new\app.pdb --out new.json
pbeta bind --hooks hooks.toml --binary old\app.exe
pbeta repair --old old.json --new new.json --hooks hooks.toml --new-binary new\app.exe --out hooks.new.toml --store store.json
pbeta host-config --hooks hooks.toml --hooks hooks.new.toml --analysis old.json --analysis new.json --out pbeta-host.toml
pbeta-launch pbeta-host.toml new\app.exe

The Quick Start covers each step, and the Hook Manifest page shows how to write hooks.toml.