Every Sunday at 22:00 UTC, this repo's CI runs against — currently cal.com, documenso, formbricks, twenty, plane, unkey, typebot, papermark (, combined ★190k+) — to prove the scanner works on real production code.
These are bugs in the webhook handlers that receive provider events — flaws in the integrating projects' integration code, not in the providers' own SDKs or services.
Coverage note: the engine couldn't parse 463 files across the corpus (broken syntax or language features the parser doesn't model). Those are scan-coverage diagnostics — not handler bugs — and are excluded from the table above.
Hookwarden checks 11 rule classes across 27 providers — most of the corpus handles webhooks correctly, hence the short list. The full rule catalog lives in the docs.
Per-target findings are never published before responsible disclosure — see methodology. To run the same scan against your own code:
npx hookwarden scan ./your-app
Why
Every dollar of fraud that flows through a webhook starts with a verification bug — and verification bugs hide in plain sight.
A handler that accepts an unsigned payload, compares HMACs with ==, or skips the signature check on a ?test=true path silently routes attacker traffic into your business logic. The bug is one line in a 50K-line app, and it looks plausible — not the shape general-purpose SAST tools are tuned to flag. They were built for SQL injection and prototype pollution; webhook verification falls between their default rule packs.
hookwarden does one thing. It walks your repo, parses every webhook handler across 15 frameworks, and labels each one verified, not-verified, or manual-review — with the exact file, line, and a fix quoted from provider docs. The catalog (27 providers — Stripe, GitHub, Shopify, Slack, Twilio, Square, Sentry, Zendesk, DocuSign, PagerDuty, Notion, Auth0, HubSpot, Intercom, Linear, Zoom, Calendly, Bitbucket, Mailchimp, Postmark, Discord, n8n, the Anthropic Agent SDK, PayPal, Braintree, NMI, plus Standard Webhooks conformant providers like Clerk, Resend, Mux) encodes signature quirks no generic scanner has the surface area to know: Stripe's 5-minute timestamp tolerance, Slack's v0:${ts}:${body} scheme, Twilio's SHA-1 outlier.
The three-state verdict is not a hedge.manual-review is what you get when hookwarden can't prove safety or unsafety from the source alone — a handler inside a middleware chain the analyzer couldn't unroll, say. It's how hookwarden avoids reporting guesses as bugs. A tool that reports every gray area as a bug isn't a security tool; it's noise. → How the verdict works
Install
npx hookwarden scan . # works everywhere, no install
hookwarden is a CLI, not a library — run it with npx hookwarden scan . or install globally with npm i -g hookwarden. (The plain npm i hookwarden that npm auto-suggests on the package page installs it as a local dependency, which isn't what you want for a command-line tool.)
Or install natively:
OS
Recommended
Alternates
Linux
brew install Hookwarden/tap/hookwarden
npm i -g hookwarden · pip install hookwarden · direct binary
Node 22+ is required for the npm/npx/macOS-brew paths; the standalone binaries (Linux x64/arm64, Windows x64) bundle the runtime. Direct binary downloads are intentionally unsigned (Gatekeeper / SmartScreen will warn) — prefer brew / scoop / npm / pip, which verify by SHA-256. → Install guide
Update
hookwarden --version # check what you have
Channel
Command
brew (macOS/Linux)
brew upgrade hookwarden
scoop (Windows)
scoop update hookwarden
npm (global)
npm i -g hookwarden@latest
pip
pip install -U hookwarden
npx (no install)
npx hookwarden@latest scan . — @latest bypasses the npx cache
Rule pack versions move with the CLI (engine, rules, and CLI ship as a fixed group — 0.7.5 everywhere). Pin in CI with npx [email protected] scan . if you want byte-stable verdicts across runs.
Quickstart
# Scan — no install required
npx hookwarden scan ./your-app
# Fail CI on high+ findings, machine-readable output
npx hookwarden scan ./your-app --fail-on high --format json
# Exit codes: 0 clean · 1 findings at threshold · 2 engine error · 3 config error · 4 parse coverage below floor
# Adopt on a non-greenfield repo — accept existing findings, gate only NEW ones
npx hookwarden scan ./your-app --baseline write
npx hookwarden scan ./your-app --fail-on high
# List every detected webhook handler (no rules run) — useful for audits
npx hookwarden inventory ./your-app
--diff-only, --provider stripe,github (phased rollout), --include/--exclude globs, --strict-suppressions, repo-level hookwarden.config.yaml, and more: npx hookwarden --help and the CLI docs.
Local UI & HTML report
Prefer clicking to the terminal? Open the findings in your browser, preview each fix as a diff, and apply the safe ones:
npx hookwarden ui ./your-app # serves on 127.0.0.1 only, opens your browser
npx hookwarden scan ./your-app --format html > report.html # one offline file to attach to a PR or email
hookwarden ui binds to 127.0.0.1, requires the per-launch token in the URL it prints, and only writes inside the folder you pass — through the same atomic staging as hookwarden fix --write. The HTML report is read-only and makes no network requests.
Git history scan (--history)
By default scan only looks at your working tree. --history also walks the
git history — including files that were committed then deleted before HEAD —
so a secret that was force-pushed away is still found. It's off by default and
bounded to the last 1000 commits; narrow it with --since <ref|date>:
npx hookwarden scan --history # last 1000 commits
npx hookwarden scan --history --since v1.0.0 # since a tag/ref
npx hookwarden scan --history --since 2026-01-01
--history is fully open-source and never requires a token.
Live verification (--verify-secrets)
--verify-secrets checks whether a leaked API-key-class credential is still
alive by making a single read-only call to the secret's own provider
(Stripe / GitHub) directly from your machine — hookwarden never sees the secret.
A live leak is escalated to critical; a dead (rotated/revoked) one is
downgraded to info. It's part of the paid team tier, which isn't open yet; off by default and
explicit opt-in only.
# Team tier — not open yet. Without a token the flag makes no provider calls.
HOOKWARDEN_TOKEN=hw_… npx hookwarden scan --verify-secrets
The credential is held in-memory only and redacted in all output.
The entitlement check transmits only your token — never the secret.
A webhook signing secret (whsec_, GitHub webhook secret) is always
reported unverified — no provider can confirm a signing secret's liveness.
Without a valid HOOKWARDEN_TOKEN, findings are reported unverified and no
provider call is made.
Auto-fix
hookwarden doesn't just name the fix — it applies it. The fix subcommand mechanically rewrites the safety: safe subset across JS/TS, Python, PHP, and Go (covering timing-unsafe comparisons → crypto.timingSafeEqual / hmac.compare_digest / hash_equals, and raw-body misuse). The other 203 rules are architectural and emit per-finding fix prose instead.
npx hookwarden fix ./your-app # dry-run — prints a unified diff, writes nothing
npx hookwarden fix ./your-app --write # atomic staging, re-scan, then rename into place
Every rewrite lands in a staging dir and is re-scanned before replacing the original; the fixer never edits inside strings or comments. → hookwarden fix · Safety levels
Real output
Captured verbatim — each line is what you'll see in your terminal, not a mockup. One Express middleware bug produces three findings, because that single mistake violates three distinct invariants; fixing one (re-ordering the middleware) clears all three:
$ hookwarden scan ./your-app
× critical server.js:10:1 stripe/express-middleware-ordering not-verified
Express webhook handler for Stripe has `express.json()` registered before the webhook route. JSON
middleware consumes the request body; by the time the Stripe handler runs, the raw bytes used for
HMAC are gone and `stripe.webhooks.constructEvent` cannot reproduce the signature.
fix › register `express.json()` AFTER the webhook route, OR mount `express.raw(...)` on the path only.
docs › https://docs.stripe.com/webhooks#verify-events
refs › https://expressjs.com/en/guide/using-middleware.html
https://www.svix.com/blog/common-failure-modes-for-webhook-signatures/
× critical server.js:10:1 stripe/missing-signature-verification not-verified
Stripe webhook handler does not appear to verify the signature header before processing the event …
× critical server.js:10:1 stripe/raw-body-misuse not-verified
Stripe webhook handler reads the signature header but does not appear to receive the body as raw bytes …
────────────
Found 3 critical · 0 high · 0 medium · 0 low · 0 info · 0 manual-review — 1 webhook handler across 1 file
Scanned in 3 ms · 1 / 1 candidates parsed (100.0% coverage)
Glyph
Severity
SARIF level
Counts toward --fail-on?
×
critical
error
yes
!
high
error
yes
▲
medium
warning
yes
·
low
note
yes
i
info
note
no — informational (e.g. library-verified)
The state column is the three-state verdict. Output is also available as byte-stable JSON and SARIF 2.1.0 (round-trips through GitHub Code Scanning, dedupes via partialFingerprints). → Output formats & JSON schema
Languages, frameworks & providers
4 languages · 15 frameworks · 27 providers · 270 rules · 100% cited. Every rule carries ≥1 external citation (CWE / RFC / Svix / Stripe spec) alongside the provider's own docs — auditors and reviewers can follow any finding back to a stable external source. JS/TS parse with Babel; Python, PHP, and Go with tree-sitter (WASM).
Language
Frameworks
JavaScript / TypeScript
Express · Hono · Fastify · Next.js
Python
Flask · FastAPI · Django
PHP
Laravel · Symfony · Slim · vanilla single-file
Go
net/http · chi · gin · echo
Every rule carries fix guidance quoted from the provider's canonical security docs. Full per-rule reference and coverage matrix: rule reference.
hookwarden is not a general-purpose SAST or DAST scanner — it won't find XSS, SQL injection, or memory-safety bugs, and it isn't trying to. Keep semgrep, CodeQL, or your DAST for those. Already running one? hookwarden is additive — it finds the one class of bug they weren't built to catch.
AI agents (Claude Code, Cursor, Continue)
@hookwarden/mcp is a Model Context Protocol server that gives AI coding agents the scan_handler tool. Paste in any webhook handler, get back the same 3-state verdict (verified / not-verified / manual-review) the CLI would emit — fully local, deterministic, no traffic leaves the agent's machine.
npx @hookwarden/mcp init # auto-detects Claude Desktop / Cursor / Continue and writes the config
The rule pack is bundled inline, content-hashed, and version-pinned to the engine — scan_handler cross-checks both on every call and fails loudly on drift. → @hookwarden/mcp on npm
Architecture
A pnpm monorepo with a strict, CI-enforced dependency boundary: the engine is pure-functional (no I/O, no filesystem, no network), so the same engine runs in the CLI, in CI, in the MCP server, and — eventually — in a browser playground without modification.
✅ v0.4 — PHP support (Laravel, Symfony, Slim, vanilla) + --provider filter for phased rollout.
Contributing
Rule-pack PRs are the highest-value contribution — adding a provider is a catalog edit plus N rule YAMLs, no new TypeScript in most cases. See the existing 21 in packages/rules/rules/ as worked examples, and CONTRIBUTING.md.
To add yourself after a merged PR, comment @all-contributors please add @<username> for <contribution>.
Star history
License
Apache 2.0 — see LICENSE. The CLI, engine, and rule packs are open source and will stay that way. A separate closed-source SaaS tier handles continuous monitoring, secret-leak scanning, automated rotation, and SOC 2 evidence export — hookwarden.dev.