Repository navigation
How It Works
The full design, with rationale and measurements, is docs/design.md. This page is the short version.
binary (+ PDB) ──analyze──► analysis JSON ─┐
├─► match ─► candidates ─► verify ─► accepted / review ─► repair
binary (+ PDB) ──analyze──► analysis JSON ─┘
pbeta analyze reads a PE x64 or x86 executable, with no symbols needed: functions from .pdata (x64), code
pointers in data, call targets and code after int3 padding. x86 has no .pdata, so its boundaries all come from
discovery: cold PGO blocks stay with their function, SEH filter and handler blocks with the function that registers
them, and jump tables and /RTCs frame descriptors are read as data, not code. x86 and x64 analyses are never
compared. Per function it records normalized and mnemonic hashes, callees in call
order, strings, constants, imports, inferred arguments (registers on x64; ecx/edx and stack words on x86) and
whether the entry can be hooked. With --pdb it
adds names, signatures and struct layouts, but only from the build's own PDB (GUID and age must match).
A build is identified by its executable's SHA-256 (the build id). Every locator, mapping and review item is tied to one.
Binaries that look packed or protected are refused.
Matching passes propose candidates, in order: name, normalized hash, strings, mnemonic hash, matched callees, call graph, vtable and function-table slots, and a weak similarity pass for edited functions. Matching never decides anything. When two new functions are equally plausible, the result is ambiguous: no candidate is picked.
Each candidate is checked independently of how it was found: parameters, strings, size, callers, callees, constants, imports and inferred arguments. Only evidence independent of the match counts (a hash match doesn't also count as a code check). Behavioral checks, scenario traces and replay of recorded calls, add independent evidence (Behavioral Evidence).
Set per hook by its criticality (Hook Manifest):
| Criticality | Independent passes needed | Behavioral pass required |
|---|---|---|
low |
1 | no |
normal (default) |
1 | no |
high |
2 | yes |
These numbers are not yet calibrated (tagged [Guess] in the design doc). For low and normal, a behavioral pass
counts as one independent pass.
Verdicts: two or more structural failures → rejected; one structural failure or a behavioral failure → needs review; policy satisfied → accepted; otherwise → needs review.
For each hook in a manifest:
| Outcome | Meaning |
|---|---|
unchanged |
Verified, same RVA. Re-bound to the new build. |
relocated |
Verified, new RVA. With --new-binary, a fresh unique byte pattern. |
needs review |
Unmatched, ambiguous, verification failed, insufficient evidence, signature changed, struct layout changed, not hookable, or a stale locator. The hook stays bound to the old build. |
A hook in review is never moved to a guessed address: it stays on the build where it was verified, so the Hook Host won't attach it in the new build until someone decides (Review Queue).
When a function's signature or a struct it takes changed, the review item carries a proposal: a new prototype and a
C++ shim that lets the existing detour run unchanged, or the new struct definition with offsetof constants. With
both builds' PDBs these are exact; without, they're inferred from register use and memory accesses, and marked as
guesses. Nothing applies them for you.
--store store.json keeps accepted mappings and review items with their evidence, append-only. Review decisions in
it are honored by every later repair.
Measured on zlib, Lua, zstd, TinyXML-2, yaml-cpp and JsonCpp across release tags and optimization settings (/O2,
/Od, identical-code folding, /LTCG, PGO), each built for x64 and x86: zero wrong matches on all 136 variants,
and zero wrong relocations in the hook-repair loop on both architectures. Numbers per project are in
docs/STATUS.md.
Permanent Beta is Apache-2.0. Found something wrong on this page? Open an issue.
Getting started
Using it
Integrations
Project