🛡️ HookGuard 0.9.1 — risk scanning for Uniswap v4 hooks, four ways

[chaosxcode]

🛡️ HookGuard 0.9.1 — risk scanning for Uniswap v4 hooks, four ways

TL;DR — pip install hookguard · drop one line into CI · comment a repo name · or scan code right in your browser. Every result ships an itemized receipt: severity, rule, line, and the exact weights behind the risk score. Nothing hidden, ever.

⚠️ Heuristic pattern scanner — not an audit. Findings mean "worth a look," never "vulnerable."

---

📊 What the data says (measured, not marketed)

315 real deployed hook contracts analyzed	registry + off-registry Unichain production hooks
56% come back completely clean	precision over recall — a scanner that flags everything is worthless
2 HIGH findings ecosystem-wide	both upgradeable-proxy class; one proven by reading its EIP-1967 slot on-chain
486 → 551 registry entries in one week	nobody announced it; we watch it weekly now
7 opaque implementations behind 17 proxy-shell hooks on Unichain	found via bytecode classification — standard tooling sees none of it

Full methodology, firing rates, five published corrections, and what the numbers do not claim: docs/precision.md

---

🚀 Four ways to run it

1 · CI — one line in your workflow

- uses: chaosxcode/hookguard@v1
  with:
    paths: src

Line annotations on every PR, one summary comment. fail-on: HIGH default — heuristics advise, they don't gate.

2 · CLI — scan anything right now

pip install hookguard
hookguard scan https://github.com/owner/v4-hooks --html report.html
hookguard scan ./contracts --local          # offline mode

3 · Browser — zero install, zero upload
Paste Solidity or drop .sol files → instant findings + score.
🔒 Code never leaves your tab — the engine runs entirely client-side.
👉 scan.html

4 · Comment bot — free public scans
Comment /hookguard-scan owner/repo on the pinned scan-request thread and the bot replies with a full scored report.

---

🧾 The receipt philosophy

Every score ships its factors:

+15  HIGH finding          +25  no published source
 +7  MEDIUM finding        +20  delegates into unreadable bytecode
+10  no audit recorded     -12  author confirms pattern intended

Weights live in public (src/score.py), confidence tiers travel with every band, absence of evidence never inflates certainty, and author confirmations subtract. Machine-readable records follow the HookScore spec draft.

---

🗺️ Where this goes

The pipeline is automated end-to-end: full-history discovery → census → source & bytecode analysis → cross-chain attribution → author outreach (public ledger) → status feed → weekly drift watcher. The roadmap adds EAS attestations, multi-chain censuses, and the underwriting layer that "Hook Safety as a Service" needs underneath it.

ROADMAP · Live dashboard · Advisory ledger

---

Builders shipping v4 hooks: scan your project, tell us what you find — false-positive reports are the single most valuable contribution here (five shipped fixes so far came from exactly that). If HookGuard catches something real in your code, that's a story we'd love to document with you.