Skip to content

Quick Start

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

Two parts: the bundled demo, which needs nothing but a build of pbeta, then the same steps on your own program. Build first: Installation.

1. The demo

examples/demo has two hand-written analyses (v1.json, v2.json) 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
CreateDocument     NEEDS REVIEW (insufficient_evidence): candidate 0x2000: checks passed but policy needs more evidence
ParseConfig        relocated 0x1200 -> 0x2300
ChecksumBlock      NEEDS REVIEW (ambiguous): 2 functions in the new build are equally plausible (0x2500, 0x2700); the engine will not pick one
SaveDocument       NEEDS REVIEW (signature_changed): matched 0x2900, but the signature changed; the hook may need adapting

1/4 hooks resolved
repaired manifest written to target/hooks.v2.toml
  • ParseConfig has no name in either build; its normalized code hash found it, and verification accepted it.
  • CreateDocument is criticality = "high", which needs behavioral evidence, and there is none.
  • ChecksumBlock has two identical copies in v2. pbeta won't pick one.
  • SaveDocument gained a parameter: the hook's prototype may need changing.

Exit code 1 means some hooks need review. List them:

cargo run -p permanent-beta-cli -- review list --store target/demo-store.json

Decide one, then repair again. The decision is honored:

cargo run -p permanent-beta-cli -- review accept ChecksumBlock:111111111111:222222222222 --candidate 0x2700 --reviewer you --store target/demo-store.json
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

2. Your own program

You need 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, x64 or x86. PDBs are optional; with them, matching and argument decoding are better.

Analyze both builds.

pbeta analyze old\app.exe --pdb old\app.pdb --out old.json
pbeta analyze new\app.exe --pdb new\app.pdb --out new.json

Describe your hooks in hooks.toml, with their RVAs in the old build (Hook Manifest):

[[hook]]
name = "SaveDocument"
detour = "log"
prototype = "int SaveDocument(Doc* doc, const wchar_t* path)"

[hook.target]
build = "old"        # placeholder; `bind` replaces it
rva = 0x1600

Bind it to the old build (sets build to the exe's SHA-256):

pbeta bind --hooks hooks.toml --binary old\app.exe

Repair it for the new build:

pbeta repair --old old.json --new new.json --hooks hooks.toml --new-binary new\app.exe --out hooks.new.toml --store store.json

Each hook comes out unchanged, relocated (with a fresh byte pattern, thanks to --new-binary) or needs review. Exit code 0: every hook resolved. 1: some need review (Review Queue). 2: an error.

Run the program with your hooks through the hook host:

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

For a 32-bit program, use the x86 host's pbeta-launch.exe (target/host-x86).

The host hashes the running exe and attaches only the hooks verified for that build. With detour = "log" each call and its decoded arguments go to pbeta-host.log next to the config. See Hook Host for skip, return <n> and your own handler code.

On the next release

Analyze it, repair from hooks.new.toml, and run host-config with every manifest. Nothing gets recompiled.

Already have a hook DLL?

pbeta header --hooks <manifests>... --out hooks.gen.h writes each build's RVAs and patterns as a C header, looked up by the exe's SHA-256.

Clone this wiki locally