Skip to content

How It Works

Ryan Cole edited this page Nov 15, 2026 · 2 revisions

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 ─┘

Analysis

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

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.

Verification

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).

Acceptance policy

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.

Repair

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.

The store

--store store.json keeps accepted mappings and review items with their evidence, append-only. Review decisions in it are honored by every later repair.

How well it works

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.

Clone this wiki locally