Repository navigation
Quick Start
Two parts: the bundled demo, which needs nothing but a build of pbeta, then the same steps on your own program.
Build first: Installation.
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.jsonCreateDocument 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
-
ParseConfighas no name in either build; its normalized code hash found it, and verification accepted it. -
CreateDocumentiscriticality = "high", which needs behavioral evidence, and there is none. -
ChecksumBlockhas two identical copies in v2. pbeta won't pick one. -
SaveDocumentgained 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.jsonDecide 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.jsonYou 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.jsonDescribe 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 = 0x1600Bind it to the old build (sets build to the exe's SHA-256):
pbeta bind --hooks hooks.toml --binary old\app.exeRepair 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.jsonEach 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.exeFor 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.
Analyze it, repair from hooks.new.toml, and run host-config with every manifest. Nothing gets recompiled.
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.
Permanent Beta is Apache-2.0. Found something wrong on this page? Open an issue.
Getting started
Using it
Integrations
Project