Repository navigation
Hook Host
One Detours DLL that hooks any x64 or x86 (32-bit) program at the addresses pbeta found. No addresses in your code, and for logging or short-circuiting a function, no code at all. Full reference: harness/host/README.md.
pbeta repair ... -> repaired hook manifests (one per build)
pbeta host-config ... -> pbeta-host.toml
pbeta-launch pbeta-host.toml app.exe
On load, pbeta-host.dll hashes the exe it's in and attaches only the hooks listed for that build, each after its
pattern matches. A build the config doesn't list gets no hooks. A hook in review stays listed for the build where it
was verified, so it's never attached in the new one.
Build it with pwsh harness/host/build.ps1 (Installation), or pwsh harness/host/build.ps1 -Arch x86 for
32-bit programs (into target/host-x86).
pbeta host-config --hooks hooks.toml --hooks hooks.new.toml --analysis old.json --analysis new.json --out pbeta-host.tomlPass every manifest of the release line. --analysis (from analyze --pdb) supplies PDB signatures for hooks
without a prototype, so their arguments can be decoded.
Set with each hook's detour (Hook Manifest), then run host-config again:
detour |
On each call |
|---|---|
log (or none) |
Logs the arguments and result; the original runs. |
skip |
Logs the call; returns 0 without running the original. |
return <n> |
Logs the call; returns n without running the original (integer or pointer results). |
<file.dll>!<export> |
Your handler runs instead. The path is relative to the config's folder. |
Built-in actions work for any prototype up to 12 parameters, except variadic functions, and up to 64 hooks per process (handlers don't count).
A handler is only the function body:
#include <pbeta_handler.h>
PBETA_HOOK(int, SaveDocument, (Doc* doc, const wchar_t* path)) {
pbeta_log("saving %ls", path);
return PBETA_ORIGINAL(SaveDocument)(doc, path);
}The prototype must match the hooked function exactly, and nothing checks it at load, so let pbeta write the declarations:
pbeta handler-stubs --hooks hooks.toml --hooks hooks.new.toml --analysis new.json --out handlers.cpp
cl /LD /I<repo>\target\host\include handlers.cppEach stub calls the original, so the DLL compiles and changes nothing until you edit a body. handler-stubs won't
overwrite a file without --force.
pbeta-launch [--log <file>] pbeta-host.toml app.exe [app args...]The app starts suspended with the host in its import table, so hooks attach before its own code runs. The log
defaults to pbeta-host.log next to the config. PBETA_HOST_CONFIG and PBETA_HOST_LOG set the same paths when
the host is loaded some other way.
Use the x86 build's pbeta-launch.exe and pbeta-host.dll. Run host-config with the build's analysis
(--analysis): it marks an x86 build's entries abi = "win32", with each hook's calling convention and stack size.
The x86 host refuses entries without the mark, and the x64 host entries with it.
-
skipandreturn <n>remove stack arguments as the convention says (__stdcall,__thiscall,__fastcall), so on x86 they need a prototype. - A handler uses the function's convention:
PBETA_HOOK_CCinpbeta_handler.h.handler-stubswrites it for you (a__thiscallmember as__fastcallwith an unused edx). -
pwsh harness/host/test.ps1 -Arch x86runs the end-to-end test on a 32-bit test app, with__stdcall,__fastcalland__thiscallhooks.
- x64 and x86. Attaching to a running process isn't built.
- x86: the thunk copies 32 stack words when it calls the original, so
host-configrefuses built-in actions on functions with more than 128 bytes of stack arguments (a handler has no limit). Functions/LTCGcompiled with a custom calling convention aren't supported. - The log is plain text, unbuffered: very hot functions slow the program.
Permanent Beta is Apache-2.0. Found something wrong on this page? Open an issue.
Getting started
Using it
Integrations
Project