Huai-Tian / GnptHooks

# GnptHooks
简体中文 | English | AI collaboration doc
## 📖 Introduction
**GnptHooks** is a kernel-function hook framework for Windows (Windows 10 x64) on **AMD** processors, built as a Type-1 hypervisor (AMD SVM + nested paging).
It virtualizes the running system and intercepts function execution through **per-core dual NPT views** — your driver can hook any kernel function **without modifying a single byte of the original memory, and with zero VM-Exits per hit in steady state**. Measured: 4.6M+ interceptions on physical hardware with the NPF exit counter pinned at one-per-core for the entire run.
> **Using an AI assistant (Copilot / Claude / GPT ...) for development on this project?** Read README_AGENT.md first — it contains the project's counter-intuitive safety designs, hard red lines, and bugcheck case studies. Skipping it and editing code directly is very likely to introduce bugcheck-grade defects.
> **Intel machine?** This is the AMD/SVM sibling of GeptHooks (Intel VT-x/EPT). Independent projects, zero symbol overlap; designs are cross-referenced, code is not shared.
## ✨ Three hook modes
Pick a mode per target (`Hook.Flags` at install time); all three co-exist on the same machine:
| | Normal (CodePage) | TRANSPARENT (DR) | NX-FENCE |
|---|---|---|---|
| Flag | `0` | `HOOK_TRANSPARENT` | `HOOK_NXFENCE` |
| Mechanism | shadow page via NPT views | hardware execution breakpoint (DR0-3) | page NX + re-arm on return |
| Read transparency | no — shadow view is readable | **structural** (original page untouched) | **structural** (both views carry original bytes) |
| PatchGuard-covered targets | forbidden (0x109 bugcheck) | safe | safe |
| Steady-state exits per call | **0** | 1 | 2 |
| Capacity | one hook per page (first-match) | ≤ 4 per core (DR hardware count) | unlimited (entry count only; must own its page) |
| Best for | cold, non-PG-covered targets | hot targets (≥100/s) and PG-covered targets | PG-covered targets at scale, or when intercept semantics are needed |
**Normal mode (CodePage)** — the signature zero-exit hook. The *Primary* view maps the hook page non-executable (data reads/writes stay perfectly normal); the *Secondary* view remaps it to a shadow copy carrying a 14-byte absolute jump at the target offset. The first fetch on that page costs one NPF exit per core; every later hit is pure guest-mode translation with **no exit at all**. Guest writes to the shadow view fault and are forwarded to the real page — bookkeeping stays coherent while callers never observe the shadow. A fail-loud reject gate refuses targets whose prologue is shorter than the patch (a control-transfer instruction inside the 14-byte window = install-time rejection), so out-of-bounds writes into neighboring code are structurally impossible.
**TRANSPARENT mode (DR)** — arms a hardware execution breakpoint (DR0-3, execute-only) on the target's entry linear address. The original page is never touched: any external reader (PatchGuard, kernel scanners) sees original byte