Skip to content

Hook Manifest

Ryan Cole edited this page Nov 14, 2026 · 1 revision

A hook manifest (hooks.toml) describes each hook and where its target is in one specific build. It's library-neutral: the Hook Host reads it, and pbeta header turns it into a C header for your own hook DLL.

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

[hook.target]
build   = "<sha256 of the build this locator is valid for>"
rva     = 0x1600
symbol  = "SaveDocument"
pattern = "48 89 5C 24 ?? 57 48 83 EC 20"

[[hook]]

Field Required Meaning
name yes Your name for the hook. Used in output and review item ids.
detour no For the Hook Host, the action: log, skip, return <n> or <file.dll>!<export>. For your own hook DLL, the detour's symbol.
criticality no low, normal (default) or high. Sets how much evidence a match needs (How It Works). high needs a behavioral pass.
prototype no The target's C prototype. Decodes arguments in the host's log, writes handler declarations, and lets repair notice a changed signature. Without it, a PDB signature is used where given.
trial no Set by repair --trial-out only. A manifest with trial hooks is never a repair result: repair and header refuse it.

[hook.target]

Field Required Meaning
build yes The build id (SHA-256 of the exe) the locator is valid for. Write a placeholder such as old and run pbeta bind.
rva yes, in practice The function's address relative to the image base.
symbol no The function's name, if known.
pattern no An AOB pattern: space-separated hex bytes, ?? for wildcards. The host checks it before attaching.

Lifecycle

  1. Write it for the build you hooked, with placeholder builds.
  2. Bind: pbeta bind --hooks hooks.toml --binary old\app.exe sets each placeholder to the exe's SHA-256, keeping comments and layout. It doesn't check that the RVAs are that build's.
  3. Repair: pbeta repair ... --out hooks.new.toml writes a manifest re-bound to the new build. Hooks in review keep their old binding. Patterns are dropped on re-binding (they were only checked against the old build) and regenerated with --new-binary.
  4. Next release: repair from hooks.new.toml. A hook still bound to an older build (sent to review earlier) is repaired from that build directly when you pass its analysis with --earlier.

Keep every repaired manifest: host-config and header take all of them and list each hook for the build it's bound to.

Patterns

pbeta pattern --rva 0x1600 app.exe prints the shortest unique pattern for a function: whole instructions from the entry, at least 8 bytes, with RIP-relative displacements, outgoing branches and in-image addresses as ??. If identical code exists elsewhere there's no pattern, never a shorter one that could match the copy.

Clone this wiki locally