\n The only scanner laser-focused on webhook signature verification. \n Local. Deterministic. Zero-network. JS/TS + Python + PHP + Go. Five minutes from npx to fix.\n
\n\n
\n \n \n \n \n \n \n \n \n \n \n \n
\n\n
\n \n
\n\n```bash\nnpx hookwarden scan ./your-app\n```\n\nNo traffic leaves your machine. No telemetry. No SaaS sign-up required.\n\n๐ **Full documentation: [docs.hookwarden.dev](https://github.com/Hookwarden/hookwarden/tree/main/apps/docs/src/content/docs)**\n\n\n\n### Found in the wild\n\nEvery Sunday at 22:00 UTC, this repo's CI runs `hookwarden` against **45 popular open-source projects** โ currently cal.com, documenso, formbricks, twenty, plane, unkey, typebot, papermark ([full target list](./.github/scripts/wild-targets.txt), combined โ 190k+) โ to prove the scanner works on real production code.\n\n**Latest sweep โ 2026-06-09** ยท 20/45 projects clean (zero critical/high)\n\n| Provider | ๐จ critical | โ ๏ธ high | ๐ก manual-review | Rules that fired |\n|---|---:|---:|---:|---|\n| n8n integrations | 81 | 0 | 0 | `n8n/missing-signature-verification` (ร78) `n8n/raw-body-misuse` (ร3) |\n| Slack integrations | 7 | 1 | 0 | `slack/missing-signature-verification` (ร7) `slack/verify-after-side-effect` (ร1) |\n| Standard Webhooks integrations | 7 | 0 | 0 | `standardwebhooks/missing-signature-verification` (ร3) `standardwebhooks/raw-body-misuse` (ร4) |\n| Stripe integrations | 6 | 0 | 0 | `stripe/hardcoded-secret-prefix` (ร2) `stripe/missing-signature-verification` (ร4) |\n| GitHub integrations | 0 | 0 | 0 | โ |\n| Shopify integrations | 0 | 0 | 0 | โ |\n| Square integrations | 0 | 0 | 0 | โ |\n| Twilio integrations | 0 | 0 | 0 | โ |\n\n_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._\n\n_Coverage note: the engine couldn't parse **238** 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._\n\n_Hookwarden checks **11 rule classes** across **21 providers** โ most of the corpus handles webhooks correctly, hence the short list. The full rule catalog lives in the [docs](https://github.com/Hookwarden/hookwarden/tree/main/apps/docs/src/content/docs/rules)._\n\nPer-target findings are never published before responsible disclosure โ see [methodology](./bugs-in-the-wild.md). To run the same scan against your own code:\n\n```bash\nnpx hookwarden scan ./your-app\n```\n\n\n\n---\n\n## Why\n\n**Every dollar of fraud that flows through a webhook starts with a verification bug โ and verification bugs hide in plain sight.**\n\nA 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.\n\nhookwarden does one thing. It walks your repo, parses every webhook handler across 11 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 (21 named providers โ Stripe, GitHub, Shopify, Slack, Twilio, Square, Sentry, Zendesk, DocuSign, PagerDuty, Notion, Auth0, HubSpot, Intercom, Linear, Zoom, Calendly, Bitbucket, Mailchimp, Postmark, 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.\n\n**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 the false-positive rate stays honest (<5%, measured against a 200-repo OSS corpus). A tool that reports every gray area as a bug isn't a security tool; it's noise. โ [How the verdict works](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/rules/index.mdx)\n\n---\n\n## Install\n\n```bash\nnpx hookwarden scan . # works everywhere, no install\n```\n\n> 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.)\n\nOr install natively:\n\n| OS | Recommended | Alternates |\n|---|---|---|\n| **Linux** | `brew install Hookwarden/tap/hookwarden` | `npm i -g hookwarden` ยท `pip install hookwarden` ยท direct binary |\n| **macOS** | `brew install Hookwarden/tap/hookwarden` | `npm i -g hookwarden` ยท `npx hookwarden` |\n| **Windows** | `scoop bucket add hookwarden https://github.com/Hookwarden/scoop-bucket && scoop install hookwarden` | `npm i -g hookwarden` ยท `pip install hookwarden` |\n\nNode 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](https://github.com/Hookwarden/hookwarden/tree/main/apps/docs/src/content/docs)\n\n### Update\n\n```bash\nhookwarden --version # check what you have\n```\n\n| Channel | Command |\n|---|---|\n| **brew** (macOS/Linux) | `brew upgrade hookwarden` |\n| **scoop** (Windows) | `scoop update hookwarden` |\n| **npm** (global) | `npm i -g hookwarden@latest` |\n| **pip** | `pip install -U hookwarden` |\n| **npx** (no install) | `npx hookwarden@latest scan .` โ `@latest` bypasses the npx cache |\n| **direct binary** | re-download from [Releases](https://github.com/Hookwarden/hookwarden/releases/latest) |\n\nRule pack versions move with the CLI (engine, rules, and CLI ship as a fixed group โ `0.7.5` everywhere). Pin in CI with `npx hookwarden@0.7.5 scan .` if you want byte-stable verdicts across runs.\n\n---\n\n## Quickstart\n\n```bash\n# Scan โ no install required\nnpx hookwarden scan ./your-app\n\n# Fail CI on high+ findings, machine-readable output\nnpx hookwarden scan ./your-app --fail-on high --format json\n# Exit codes: 0 clean ยท 1 findings at threshold ยท 2 engine error ยท 3 config error ยท 4 parse coverage below floor\n\n# Adopt on a non-greenfield repo โ accept existing findings, gate only NEW ones\nnpx hookwarden scan ./your-app --baseline write\nnpx hookwarden scan ./your-app --fail-on high\n\n# List every detected webhook handler (no rules run) โ useful for audits\nnpx hookwarden inventory ./your-app\n```\n\n`--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](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/cli/ci.mdx).\n\n### Git history scan (`--history`)\n\nBy default `scan` only looks at your working tree. `--history` also walks the\ngit history โ including files that were **committed then deleted** before HEAD โ\nso a secret that was force-pushed away is still found. It's off by default and\nbounded to the last 1000 commits; narrow it with `--since `:\n\n```bash\nnpx hookwarden scan --history # last 1000 commits\nnpx hookwarden scan --history --since v1.0.0 # since a tag/ref\nnpx hookwarden scan --history --since 2026-01-01\n```\n\n`--history` is fully open-source and never requires a token.\n\n### Live verification (`--verify-secrets`)\n\n`--verify-secrets` checks whether a leaked **API-key-class** credential is still\n*alive* by making a single read-only call to the secret's **own** provider\n(Stripe / GitHub) directly from your machine โ hookwarden never sees the secret.\nA `live` leak is escalated to `critical`; a `dead` (rotated/revoked) one is\ndowngraded to `info`. It's **paid** (team tier), off by default, and explicit\nopt-in only.\n\n```bash\n# Mint a token from the dashboard (Settings โ CLI tokens) on a team workspace:\nHOOKWARDEN_TOKEN=hw_โฆ npx hookwarden scan --verify-secrets\n```\n\n- The credential is held in-memory only and redacted in all output.\n- The entitlement check transmits **only** your token โ never the secret.\n- A webhook **signing** secret (`whsec_`, GitHub webhook secret) is always\n reported `unverified` โ no provider can confirm a signing secret's liveness.\n- Without a valid `HOOKWARDEN_TOKEN`, findings are reported `unverified` and no\n provider call is made.\n\n---\n\n## Auto-fix\n\nhookwarden 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 188 rules are architectural and emit per-finding fix prose instead.\n\n```bash\nnpx hookwarden fix ./your-app # dry-run โ prints a unified diff, writes nothing\nnpx hookwarden fix ./your-app --write # atomic staging, re-scan, then rename into place\n```\n\nEvery rewrite lands in a staging dir and is re-scanned before replacing the original; the fixer never edits inside strings or comments. โ [hookwarden fix](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/cli/fix.mdx) ยท [Safety levels](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/cli/safety-levels.mdx)\n\n---\n\n## Real output\n\nCaptured 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:\n\n```\n$ hookwarden scan ./your-app\nร critical server.js:10:1 stripe/express-middleware-ordering not-verified\n Express webhook handler for Stripe has `express.json()` registered before the webhook route. JSON\n middleware consumes the request body; by the time the Stripe handler runs, the raw bytes used for\n HMAC are gone and `stripe.webhooks.constructEvent` cannot reproduce the signature.\n fix โบ register `express.json()` AFTER the webhook route, OR mount `express.raw(...)` on the path only.\n docs โบ https://docs.stripe.com/webhooks#verify-events\n refs โบ https://expressjs.com/en/guide/using-middleware.html\n https://www.svix.com/blog/common-failure-modes-for-webhook-signatures/\n\nร critical server.js:10:1 stripe/missing-signature-verification not-verified\n Stripe webhook handler does not appear to verify the signature header before processing the event โฆ\n\nร critical server.js:10:1 stripe/raw-body-misuse not-verified\n Stripe webhook handler reads the signature header but does not appear to receive the body as raw bytes โฆ\n\nโโโโโโโโโโโโ\nFound 3 critical ยท 0 high ยท 0 medium ยท 0 low ยท 0 info ยท 0 manual-review โ 1 webhook handler across 1 file\nScanned in 3 ms ยท 1 / 1 candidates parsed (100.0% coverage)\n```\n\n| Glyph | Severity | SARIF level | Counts toward `--fail-on`? |\n|---|---|---|---|\n| `ร` | `critical` | `error` | yes |\n| `!` | `high` | `error` | yes |\n| `โฒ` | `medium` | `warning` | yes |\n| `ยท` | `low` | `note` | yes |\n| `i` | `info` | `note` | no โ informational (e.g. `library-verified`) |\n\nThe `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](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/cli/ci.mdx)\n\n---\n\n## Languages, frameworks & providers\n\n**4 languages ยท 15 frameworks ยท 21 providers ยท 230 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).\n\n| Language | Frameworks |\n|---|---|\n| **JavaScript / TypeScript** | Express ยท Hono ยท Fastify ยท Next.js |\n| **Python** | Flask ยท FastAPI ยท Django |\n| **PHP** | Laravel ยท Symfony ยท Slim ยท vanilla single-file |\n| **Go** | net/http ยท chi ยท gin ยท echo |\n\n
\n \n \n \n \n \n \n
\n\nEvery rule carries fix guidance quoted from the provider's canonical security docs. Full per-rule reference and coverage matrix: **[docs.hookwarden.dev/rules](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/rules/index.mdx)**.\n\n---\n\n## CI integration\n\n```yaml\n# .github/workflows/hookwarden.yml\nname: hookwarden\non: [pull_request, push]\npermissions:\n contents: read\n pull-requests: write\n security-events: write\njobs:\n scan:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n with: { fetch-depth: 0 }\n - uses: Hookwarden/hookwarden-action@v1\n with:\n fail-on: high\n```\n\nUploads SARIF to Code Scanning automatically; findings appear as PR annotations. Raw-CLI + SARIF-upload recipe, exit-code matrix, and diff-only PR scans: โ [CI integration guide](https://github.com/Hookwarden/hookwarden/blob/main/apps/docs/src/content/docs/cli/ci.mdx).\n\n---\n\n## vs. other tools\n\nhookwarden is **specialized on purpose.** The general-purpose scanners below are excellent โ they're just not in this fight.\n\n| Tool | What it does well | Webhook verification |\n|---|---|---|\n| **semgrep** | General-purpose SAST; flexible rules | Low signal โ generic matching misses body-parsing order, timing-safe paths, SDK flows |\n| **snyk Code** | Broad vuln detection (paid SaaS) | No webhook rules; doesn't model HMAC reachability |\n| **GitGuardian / TruffleHog** | Secret-leak detection | Finds hardcoded secrets; doesn't audit whether verification is correct |\n| **Datadog Static Analysis** | Broad SAST; good cloud signal | No webhook specialization; low-signal for this bug class |\n| **hookwarden** | Webhook verification logic only | 230 rules (100% cited), 21 providers, three-state verdicts, <5% FP on a 200-repo corpus |\n\nhookwarden 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.\n\n---\n\n## AI agents (Claude Code, Cursor, Continue)\n\n`@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.\n\n```bash\nnpx @hookwarden/mcp init # auto-detects Claude Desktop / Cursor / Continue and writes the config\n```\n\nThe 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](https://www.npmjs.com/package/@hookwarden/mcp)\n\n---\n\n## Architecture\n\nA 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.\n\n| Package | Purpose | License |\n|---|---|---|\n| [`@hookwarden/engine`](./packages/engine) | Handler discovery, reachability analysis, evidence collection. Pure-functional, browser-safe. | Apache 2.0 |\n| [`@hookwarden/rules`](./packages/rules) | Provider catalog, YAML rule packs, parameterized predicate factories. | Apache 2.0 |\n| [`@hookwarden/fix`](./packages/fix) | Auto-remediation โ bounded location for AST mutation (Babel traverse + generator). | Apache 2.0 |\n| [`@hookwarden/mcp`](./packages/mcp) | Model Context Protocol server โ `scan_handler` tool for AI coding agents. | Apache 2.0 |\n| [`hookwarden`](./packages/cli) | CLI binary โ reads config, drives the engine, renders text/JSON/SARIF. | Apache 2.0 |\n\n`dependency-cruiser` enforces the engine's I/O boundary in every PR.\n\n---\n\n## Roadmap\n\n- **โ v0.8 โ `@hookwarden/mcp` developer preview** (Model Context Protocol server exposing `scan_handler` to Claude Code, Cursor, Continue, and the Anthropic Agent SDK โ pasted handler code returns a 3-state verdict locally, zero-network, deterministic). โ [MCP server](https://www.npmjs.com/package/@hookwarden/mcp)\n- **โ v0.7.2 โ references visible in output** (text renderer gains a `refs โบ` block per finding; JSON envelope gains `scan.findings[].references: string[]`. v0.7.1 cited every rule; v0.7.2 makes citations actually visible to scan consumers).\n- **โ v0.7.1 โ rule-pack polish** (references backfilled on 142 grandfathered rules โ 230 cited; test-path severity overrides on 219 rules โ test fixtures no longer false-fire as critical/high).\n- **โ v0.7 โ Rule Depth** (5 new rule classes: VAS / BYP / ERS / LEAK / RPL families across 21 providers; rule pack grew 142 โ 230).\n- **โ v0.6 โ rule-pack expansion** (15 new provider rule packs incl. Zendesk, DocuSign, PagerDuty, Bitbucket, Notion, Calendly, Zoom; Standard Webhooks spec sweep covers Clerk, Resend, Mux, Lob, etc.; CVE-2026-41432 Stripe empty-secret detector).\n- **โ v0.5 โ `hookwarden fix`** auto-remediation (mechanical AST rewrites, safe/manual-only per rule).\n- **โ v0.4 โ PHP support** (Laravel, Symfony, Slim, vanilla) + `--provider` filter for phased rollout.\n\n---\n\n## Contributing\n\nRule-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/`](./packages/rules/rules) as worked examples, and [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n```bash\npnpm install && pnpm -r build && pnpm -r test\n```\n\nBug reports & feature requests: [open an issue](https://github.com/Hookwarden/hookwarden/issues). Docs: [docs.hookwarden.dev](https://github.com/Hookwarden/hookwarden/tree/main/apps/docs/src/content/docs) ยท [hookwarden.dev](https://hookwarden.dev).\n\n\n\n\n> To add yourself after a merged PR, comment `@all-contributors please add @ for `.\n\n---\n\n## Star history\n\n\n \n \n \n \n \n\n\n---\n\n## License\n\nApache 2.0 โ see [`LICENSE`](./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](https://hookwarden.dev).\n",
"bytes": 22960,
"sha": "216362fd8cf259767e58b9aa769be68f402404debbe49e8788a42e4ba60750ce",
"repo_slug": "hookwarden/hookwarden",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_hookwarden_mcp_8d64a61b/readme"
}
![\"hookwarden\"](\"./assets/brand/social/readme-banner.svg\")
\n![\"npm](\"https://img.shields.io/npm/v/hookwarden?color=6366F1&label=npm&style=flat-square\")
![\"npm](\"https://img.shields.io/npm/dm/hookwarden?color=6366F1&style=flat-square\")
![\"PyPI](\"https://img.shields.io/pypi/v/hookwarden?color=6366F1&label=PyPI&style=flat-square&logo=pypi&logoColor=white\")
![\"License:](\"https://img.shields.io/badge/license-Apache%202.0-6366F1?style=flat-square\"){kind=icon}
![\"Node](\"https://img.shields.io/badge/node-%E2%89%A522-6366F1?style=flat-square\"){kind=icon}
![\"PHP](\"https://img.shields.io/badge/PHP-%E2%89%A58.0-6366F1?style=flat-square\"){kind=icon}
![\"Python](\"https://img.shields.io/badge/Python-%E2%89%A53.10-6366F1?style=flat-square\"){kind=icon}
![\"Go](\"https://img.shields.io/badge/Go-%E2%89%A51.21-6366F1?style=flat-square\"){kind=icon}
![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/Hookwarden/hookwarden/ci.yml?branch=main&color=6366F1&label=CI&style=flat-square\")
![\"GitHub](\"https://img.shields.io/github/stars/Hookwarden/hookwarden?color=6366F1&style=flat-square\")
![\"SARIF](\"https://img.shields.io/badge/SARIF-2.1.0-6366F1?style=flat-square\"){kind=icon}
![\"hookwarden](\"./assets/brand/demo-showcase.gif\")
\n![\"Stripe\"](\"https://img.shields.io/badge/Stripe-6366F1?style=for-the-badge&logo=stripe&logoColor=white\"){kind=icon}
![\"GitHub\"](\"https://img.shields.io/badge/GitHub-6366F1?style=for-the-badge&logo=github&logoColor=white\"){kind=icon}
![\"Shopify\"](\"https://img.shields.io/badge/Shopify-6366F1?style=for-the-badge&logo=shopify&logoColor=white\"){kind=icon}
![\"Slack\"](\"https://img.shields.io/badge/Slack-6366F1?style=for-the-badge&logo=slack&logoColor=white\"){kind=icon}
![\"Twilio\"](\"https://img.shields.io/badge/Twilio-6366F1?style=for-the-badge&logo=twilio&logoColor=white\"){kind=icon}
![\"Square\"](\"https://img.shields.io/badge/Square-6366F1?style=for-the-badge&logo=square&logoColor=white\"){kind=icon}