From 7b1337cb65a3dc136ad853d9e5781adff18ea890 Mon Sep 17 00:00:00 2001 From: Chris Portscheller Date: Sun, 15 Nov 2026 20:20:01 -0600 Subject: [PATCH 1/3] feat(node): add SSRF canary correlation API --- README.md | 191 ++++++++++++---------- packages/webdecoy/README.md | 153 +++++++++-------- packages/webdecoy/src/client.ts | 93 ++++++++++- packages/webdecoy/src/index.ts | 3 + packages/webdecoy/src/sdk.ts | 70 +++++--- packages/webdecoy/src/ssrf-canary.test.ts | 64 ++++++++ packages/webdecoy/src/types.ts | 25 +++ 7 files changed, 418 insertions(+), 181 deletions(-) create mode 100644 packages/webdecoy/src/ssrf-canary.test.ts diff --git a/README.md b/README.md index 06771f2..b78446e 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,10 @@ controlled request first, inspect the result, then add detection to your app. WebDecoy complements the edge controls you already use; it only observes requests that reach its middleware. -| Try it | What you will see | What you need | -| --- | --- | --- | -| [Express browser playground](https://stackblitz.com/github/WebDecoy/node/tree/main/playgrounds/express?file=app.mjs) | Send an ordinary request and a decoy request; compare the HTTP response with the local tripwire decision. | No account or API key. | -| [Next.js 16 on Vercel](https://webdecoy.com/blog/see-bots-ai-crawlers-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=node_demo_to_star&utm_content=nextjs_walkthrough) | Run the downloadable diagnostic app, send a labeled test and match its record in your dashboard. | Your own server-side WebDecoy API key for reporting. | +| Try it | What you will see | What you need | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [Express browser playground](https://stackblitz.com/github/WebDecoy/node/tree/main/playgrounds/express?file=app.mjs) | Send an ordinary request and a decoy request; compare the HTTP response with the local tripwire decision. | No account or API key. | +| [Next.js 16 on Vercel](https://webdecoy.com/blog/see-bots-ai-crawlers-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=node_demo_to_star&utm_content=nextjs_walkthrough) | Run the downloadable diagnostic app, send a labeled test and match its record in your dashboard. | Your own server-side WebDecoy API key for reporting. | The [25-second Vercel proof](https://youtu.be/W_mB8VX0vk0) animates the verified HTTP response and matching **Test → Logged, not blocked** record. This is a @@ -45,27 +45,27 @@ After you have tried an example, **[star WebDecoy/node](https://github.com/WebDe ## What you can do -| Need | Start here | -| --- | --- | -| Detect requests to hidden decoys and scanner-bait paths | [Honeypot tripwires](#why-add-tripwires) | -| Limit repeated requests to your app or API | [Local rules](#more-local-rules) and [shared rate limits](#rate-limits-across-more-than-one-process) | -| Check supported signed AI-agent identities | [Web Bot Auth verification](#verify-ai-agents-web-bot-auth) | -| Publish and enforce an AI crawler policy | [One bot policy](#one-bot-policy-published-and-enforced) | -| Add browser interaction evidence to server decisions | [Client signals](#catching-a-real-browser-that-isnt-a-real-user) | -| See server-side analysis and detections in a dashboard | [Optional WebDecoy platform](#optional-the-webdecoy-platform-api-key) | +| Need | Start here | +| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| Detect requests to hidden decoys and scanner-bait paths | [Honeypot tripwires](#why-add-tripwires) | +| Limit repeated requests to your app or API | [Local rules](#more-local-rules) and [shared rate limits](#rate-limits-across-more-than-one-process) | +| Check supported signed AI-agent identities | [Web Bot Auth verification](#verify-ai-agents-web-bot-auth) | +| Publish and enforce an AI crawler policy | [One bot policy](#one-bot-policy-published-and-enforced) | +| Add browser interaction evidence to server decisions | [Client signals](#catching-a-real-browser-that-isnt-a-real-user) | +| See server-side analysis and detections in a dashboard | [Optional WebDecoy platform](#optional-the-webdecoy-platform-api-key) | WebDecoy works alongside Cloudflare and other CDN protections. Server middleware observes requests that reach your application; requests served or blocked before it runs are outside its view. A crawler name is a claim until supported identity checks establish more. ## Choose your framework -| Your app | Package and setup | -| --- | --- | -| Express | [Express middleware](packages/express/README.md) | -| Fastify | [Fastify plugin](packages/fastify/README.md) | -| Next.js | [Next.js middleware](packages/nextjs/README.md) | -| Hono, Cloudflare Workers, Bun or Deno | [Hono middleware](packages/hono/README.md) | +| Your app | Package and setup | +| ------------------------------------------------ | ------------------------------------------------------------------- | +| Express | [Express middleware](packages/express/README.md) | +| Fastify | [Fastify plugin](packages/fastify/README.md) | +| Next.js | [Next.js middleware](packages/nextjs/README.md) | +| Hono, Cloudflare Workers, Bun or Deno | [Hono middleware](packages/hono/README.md) | | Astro, SvelteKit, Remix or another fetch handler | [`createFetchGuard()`](#any-other-fetch-runtime--no-package-needed) | -| A custom Node.js server | [Core SDK](packages/webdecoy/README.md) | +| A custom Node.js server | [Core SDK](packages/webdecoy/README.md) | The middleware starts in **monitor mode**: it records verdicts without blocking requests. A local rules setup needs no cloud connection; an API key is needed to send detections to the WebDecoy dashboard. @@ -104,8 +104,8 @@ tripwire({ prefixes: ['/.git/'], patterns: [/\/wp-admin\//], includeDefaults: true, // built-in scanner-bait paths (default: true) - action: 'DENY', // or 'THROTTLE' - dryRun: false, // log only, don't block (observe before enforcing) + action: 'DENY', // or 'THROTTLE' + dryRun: false, // log only, don't block (observe before enforcing) }); ``` @@ -144,10 +144,7 @@ const app = express(); app.use( webdecoy({ // No apiKey → purely local rules (tripwires + rate limiting). - rules: [ - tripwire({ paths: ['/.env', '/wp-config.php'] }), - rateLimit({ max: 100, window: 60 }), - ], + rules: [tripwire({ paths: ['/.env', '/wp-config.php'] }), rateLimit({ max: 100, window: 60 })], skipPaths: ['/health', '/public'], }) ); @@ -200,7 +197,7 @@ const guard = createFetchGuard({ mode: 'enforce', rules: [tripwire()] }); export default { async fetch(request: Request): Promise { const { response } = await guard.check(request); - if (response) return response; // denied + if (response) return response; // denied return guard.decorate(await handle(request)); // injects the honeytoken link }, }; @@ -215,8 +212,8 @@ import { WebDecoy, rateLimit, tripwire, filter } from '@webdecoy/node'; const wd = new WebDecoy({ rules: [ - rateLimit({ max: 100, window: 60 }), // 100 req / 60s per IP - tripwire({ paths: ['/.env', '/wp-config.php'] }), // honeypot paths + rateLimit({ max: 100, window: 60 }), // 100 req / 60s per IP + tripwire({ paths: ['/.env', '/wp-config.php'] }), // honeypot paths filter({ expression: 'ip.tor or ip.vpn', action: 'DENY' }), // needs an API key (IP enrichment) ], }); @@ -244,7 +241,8 @@ const wd = new WebDecoy({}); const verdict = await wd.detectBot(request); // a WHATWG Request, or { method, url, headers } // verdict.status: 'verified' | 'impersonation' | 'claimed' | 'none' if (verdict.status === 'impersonation') return new Response('Forbidden', { status: 403 }); -if (verdict.status === 'verified') console.log('verified agent:', verdict.agentName, verdict.category); +if (verdict.status === 'verified') + console.log('verified agent:', verdict.agentName, verdict.category); ``` Or drop it into the rules engine to deny impersonation automatically: @@ -280,7 +278,7 @@ Set `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` and `WEBDECOY_SENSOR_KEY` from ** Tripwire matching is deterministic, but a match does not guarantee malicious intent. Review these edge cases before enforcing: - **The honeytoken link** is rendered hidden and `rel=nofollow`, outside your normal sitemap and navigation. Those properties reduce ordinary discovery; they do not guarantee that legitimate software will never request it, or that a scraper will follow it. -- **Aggressive link-prefetchers and unfurl/preview bots** (e.g. some browsers' speculative prefetch, chat link previews) *can* fetch a hidden link. If you serve link previews or use prefetching, start with `dryRun: true` to measure before enforcing, or scope the trap to paths those bots won't touch. +- **Aggressive link-prefetchers and unfurl/preview bots** (e.g. some browsers' speculative prefetch, chat link previews) _can_ fetch a hidden link. If you serve link previews or use prefetching, start with `dryRun: true` to measure before enforcing, or scope the trap to paths those bots won't touch. - **The default scanner-bait paths** (`/.env`, `/.git/config`, …) can also be requested by your own security scanners, uptime checks or users troubleshooting a site. Exclude known legitimate activity or run `dryRun` first. The honest rule of thumb: enforce tripwires you control the surface of, and use `dryRun` to observe any path you're unsure about. @@ -317,6 +315,27 @@ if (!result.allowed) { } ``` +### Confirm an SSRF callback + +For a route that intentionally performs a server-side fetch, mint a short-lived +canary and report its initiation immediately before the fetch: + +```typescript +const canary = await wd.createSSRFCanary({ + routeTemplate: '/api/fetch/:id', + test: true, // controlled validation; excluded from production threat metrics +}); + +await wd.reportSSRFInitiation(canary); +await applicationFetch(canary.callbackUrl); +``` + +Use the callback URL only as the controlled destination for the fetch you are +testing. WebDecoy never fetches a supplied URL. A confirmed finding requires +both the trusted initiation and the matching single-use callback within 15 +minutes; either edge alone is not confirmed SSRF. Open the callback detection +in WebDecoy to see its **Correlated activity** evidence. + ### Getting an API key 1. Sign up at [app.webdecoy.com](https://app.webdecoy.com) @@ -325,22 +344,22 @@ if (!result.allowed) { ## How it works -| Tier | What | Needs a key? | -|------|------|:---:| -| **0 — Tripwires** | Requests for decoy and scanner-bait paths match before any scoring (recorded in monitor mode, refused in enforce mode). Deterministic matching; see [false positives](#what-counts-as-a-false-positive). | No | -| **1 — Local analysis** | Fast on-server heuristics: suspicious/missing headers, datacenter IPs, known bot user-agents, missing `Sec-CH-UA`. | No | -| **2 — Server verification** | Known-bot database, IP reputation, GeoIP (Tor/VPN/proxy), and JA3 TLS fingerprinting with TLS↔UA mismatch when `tls_info` is supplied. | Yes | +| Tier | What | Needs a key? | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------: | +| **0 — Tripwires** | Requests for decoy and scanner-bait paths match before any scoring (recorded in monitor mode, refused in enforce mode). Deterministic matching; see [false positives](#what-counts-as-a-false-positive). | No | +| **1 — Local analysis** | Fast on-server heuristics: suspicious/missing headers, datacenter IPs, known bot user-agents, missing `Sec-CH-UA`. | No | +| **2 — Server verification** | Known-bot database, IP reputation, GeoIP (Tor/VPN/proxy), and JA3 TLS fingerprinting with TLS↔UA mismatch when `tls_info` is supplied. | Yes | ## Packages -| Package | Version | Description | -|---------|---------|-------------| -| [@webdecoy/node](https://www.npmjs.com/package/@webdecoy/node) | [![npm](https://img.shields.io/npm/v/@webdecoy/node.svg)](https://www.npmjs.com/package/@webdecoy/node) | Core SDK + local rules (tripwire, rateLimit, filter) | -| [@webdecoy/express](https://www.npmjs.com/package/@webdecoy/express) | [![npm](https://img.shields.io/npm/v/@webdecoy/express.svg)](https://www.npmjs.com/package/@webdecoy/express) | Express.js middleware | -| [@webdecoy/fastify](https://www.npmjs.com/package/@webdecoy/fastify) | [![npm](https://img.shields.io/npm/v/@webdecoy/fastify.svg)](https://www.npmjs.com/package/@webdecoy/fastify) | Fastify plugin | -| [@webdecoy/nextjs](https://www.npmjs.com/package/@webdecoy/nextjs) | [![npm](https://img.shields.io/npm/v/@webdecoy/nextjs.svg)](https://www.npmjs.com/package/@webdecoy/nextjs) | Next.js middleware | -| [@webdecoy/hono](https://www.npmjs.com/package/@webdecoy/hono) | [![npm](https://img.shields.io/npm/v/@webdecoy/hono.svg)](https://www.npmjs.com/package/@webdecoy/hono) | Hono middleware (Workers, Bun, Deno) | -| [@webdecoy/client](https://www.npmjs.com/package/@webdecoy/client) | [![npm](https://img.shields.io/npm/v/@webdecoy/client.svg)](https://www.npmjs.com/package/@webdecoy/client) | Browser-side signal collector | +| Package | Version | Description | +| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| [@webdecoy/node](https://www.npmjs.com/package/@webdecoy/node) | [![npm](https://img.shields.io/npm/v/@webdecoy/node.svg)](https://www.npmjs.com/package/@webdecoy/node) | Core SDK + local rules (tripwire, rateLimit, filter) | +| [@webdecoy/express](https://www.npmjs.com/package/@webdecoy/express) | [![npm](https://img.shields.io/npm/v/@webdecoy/express.svg)](https://www.npmjs.com/package/@webdecoy/express) | Express.js middleware | +| [@webdecoy/fastify](https://www.npmjs.com/package/@webdecoy/fastify) | [![npm](https://img.shields.io/npm/v/@webdecoy/fastify.svg)](https://www.npmjs.com/package/@webdecoy/fastify) | Fastify plugin | +| [@webdecoy/nextjs](https://www.npmjs.com/package/@webdecoy/nextjs) | [![npm](https://img.shields.io/npm/v/@webdecoy/nextjs.svg)](https://www.npmjs.com/package/@webdecoy/nextjs) | Next.js middleware | +| [@webdecoy/hono](https://www.npmjs.com/package/@webdecoy/hono) | [![npm](https://img.shields.io/npm/v/@webdecoy/hono.svg)](https://www.npmjs.com/package/@webdecoy/hono) | Hono middleware (Workers, Bun, Deno) | +| [@webdecoy/client](https://www.npmjs.com/package/@webdecoy/client) | [![npm](https://img.shields.io/npm/v/@webdecoy/client.svg)](https://www.npmjs.com/package/@webdecoy/client) | Browser-side signal collector | ## Browser session clearance @@ -361,7 +380,7 @@ enforces it, from one object — so they cannot drift: import { WebDecoy, botPolicy } from '@webdecoy/node'; const policy = botPolicy({ - deny: ['training_crawler'], // or 'ai', a category, or an agent name + deny: ['training_crawler'], // or 'ai', a category, or an agent name allow: ['perplexitybot'], }); @@ -375,7 +394,7 @@ policy you believe is in force and is not. The reverse — enforcing against a crawler the published file invites — is how a site quietly leaves a search index. `robots.txt` is a request, honoured at the crawler's discretion. The registry -records whether each operator *documents* honouring it, and the generated file +records whether each operator _documents_ honouring it, and the generated file names the ones in your deny set that do not: ``` @@ -400,12 +419,14 @@ import { MemoryClientSignalStore, clientSignals, tripwire } from '@webdecoy/node const signalStore = new MemoryClientSignalStore(); app.use(webdecoyCaptcha({ secret: process.env.WEBDECOY_SECRET, signalStore })); -app.use(webdecoy({ - rules: [ - tripwire(), // intent — deterministic - clientSignals({ store: signalStore, dryRun: true }), // interaction — probabilistic - ], -})); +app.use( + webdecoy({ + rules: [ + tripwire(), // intent — deterministic + clientSignals({ store: signalStore, dryRun: true }), // interaction — probabilistic + ], + }) +); ``` `@webdecoy/client` collects behavioural, environmental and form signals in the @@ -426,8 +447,8 @@ what they send: ```typescript attackSignatures({ - inspect: ['path', 'query'], // default; 'body' and 'headers' are opt-in - exclude: ['traversal'], // signature ids + inspect: ['path', 'query'], // default; 'body' and 'headers' are opt-in + exclude: ['traversal'], // signature ids dryRun: false, }); ``` @@ -436,7 +457,7 @@ attackSignatures({ breadth is bought with false positives. This is a small curated set — SQL injection, XSS, traversal, command injection, `${jndi:` — chosen because each has no innocent reading in a path or query string. It composes with the deterministic -signals: a request carrying an injection payload *and* walking into a tripwire is +signals: a request carrying an injection payload _and_ walking into a tripwire is much stronger evidence than either alone. Bodies and headers are off by default, because a CMS saving an article and a URL @@ -484,16 +505,18 @@ The synchronous `evaluateRules()` cannot consume a networked store, and reports Rate limits, IP enrichment and every detection we record are keyed on the caller's address, so it matters that the address is real. `X-Forwarded-For` is written by the client for the first hop — the leftmost value in it is whatever the caller decided to send — so the middleware believes it only as far as you say it should, counted from the **right** of the chain, which is the end your own infrastructure wrote. ```typescript -app.use(webdecoy({ - trustProxy: 1, // one proxy in front of this app -})); +app.use( + webdecoy({ + trustProxy: 1, // one proxy in front of this app + }) +); ``` -| `trustProxy` | Meaning | -|---|---| -| `false` | Read no forwarding headers. The socket address is the client. | -| `1`, `2`, … | The number of proxies between the client and this app. | -| `'cloudflare'` | Use `CF-Connecting-IP`. Only safe if the origin is unreachable except through Cloudflare. | +| `trustProxy` | Meaning | +| ------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `false` | Read no forwarding headers. The socket address is the client. | +| `1`, `2`, … | The number of proxies between the client and this app. | +| `'cloudflare'` | Use `CF-Connecting-IP`. Only safe if the origin is unreachable except through Cloudflare. | | `['10.0.0.0/8', …]` | CIDRs of proxies you run. The chain is walked right to left and the first address that isn't yours is the client. | **Defaults.** Express and Fastify defer to `req.ip` / `request.ip`, which already honour the framework's own trust-proxy setting and otherwise resolve to the socket address — so if you've configured `app.set('trust proxy', …)` there's nothing to do here. Next.js middleware has no socket to fall back on, so it defaults to `1` trusted hop, which is correct on Vercel and on any single-proxy deployment. @@ -506,13 +529,13 @@ The same option is accepted by `webdecoyCaptcha()` / `createCaptchaHandler()`, a ```typescript const wd = new WebDecoy({ - apiKey: process.env.WEBDECOY_API_KEY, // optional — only for platform features - apiUrl: 'https://in.webdecoy.com', // optional (this is the default) - enableTLSFingerprinting: true, // optional (default: true) - threatScoreThreshold: 70, // optional, 0–100 (default: 80) - timeout: 5000, // optional, ms (default: 5000) - debug: false, // optional (default: false) - tlsRejectUnauthorized: true, // optional (default: true) + apiKey: process.env.WEBDECOY_API_KEY, // optional — only for platform features + apiUrl: 'https://in.webdecoy.com', // optional (this is the default) + enableTLSFingerprinting: true, // optional (default: true) + threatScoreThreshold: 70, // optional, 0–100 (default: 80) + timeout: 5000, // optional, ms (default: 5000) + debug: false, // optional (default: false) + tlsRejectUnauthorized: true, // optional (default: true) }); ``` @@ -537,29 +560,29 @@ Full analysis of a request. Returns a typed decision: ```typescript const d = await wd.protect(metadata); -d.conclusion // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' -d.allowed // true for ALLOW and ERROR (fail open) -d.id // 'dec_…', correlates with the dashboard -d.isDenied() // narrowing helpers -d.deniedBy('tripwire') // which rule, without string-matching -d.results // every rule, in order, and what it concluded -d.detection // the service's response, as before -d.edge // what the edge validator said +d.conclusion; // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' +d.allowed; // true for ALLOW and ERROR (fail open) +d.id; // 'dec_…', correlates with the dashboard +d.isDenied(); // narrowing helpers +d.deniedBy('tripwire'); // which rule, without string-matching +d.results; // every rule, in order, and what it concluded +d.detection; // the service's response, as before +d.edge; // what the edge validator said ``` `results` is the part worth knowing about. Every configured rule appears, with a `state`: -| `state` | Meaning | -|---|---| -| `RUN` | Evaluated, and its conclusion counts. | -| `DRY_RUN` | Evaluated; conclusion recorded but not enforced. | +| `state` | Meaning | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `RUN` | Evaluated, and its conclusion counts. | +| `DRY_RUN` | Evaluated; conclusion recorded but not enforced. | | `NOT_RUN` | Could not evaluate — a signal it needs was absent (a `filter()` with no IP enrichment, a `webBotAuth()` on a request with no host). | -| `CACHED` | Not evaluated; a prior decision for this key was reused. | +| `CACHED` | Not evaluated; a prior decision for this key was reused. | `NOT_RUN` is the one that used to be invisible: such a rule reported ALLOW, which reads as "checked and fine" rather than "never checked". A dry-run rule that -matched reports `conclusion: 'DENY'` with `state: 'DRY_RUN'` — what it *would* +matched reports `conclusion: 'DENY'` with `state: 'DRY_RUN'` — what it _would_ have done is the reason you turned it on. `ERROR` is not a synonym for `DENY`. It means no verdict was reached, and the @@ -614,7 +637,7 @@ Pass any object with `debug`/`info`/`warn`/`error`: ```typescript new WebDecoy({ logger: myLogger }); -new WebDecoy({ logger: fromPino(pino()) }); // pino's argument order is reversed +new WebDecoy({ logger: fromPino(pino()) }); // pino's argument order is reversed ``` `fromPino()` exists because passing a pino instance directly type-checks and then diff --git a/packages/webdecoy/README.md b/packages/webdecoy/README.md index 27a64ab..51f4384 100644 --- a/packages/webdecoy/README.md +++ b/packages/webdecoy/README.md @@ -17,13 +17,13 @@ Full documentation: [docs.webdecoy.com/sdk-plugins/node-sdk](https://docs.webdec Most apps should install a framework adapter alongside this package. The adapters handle request mapping, client IP, monitor mode and honeytoken injection for you. Install `@webdecoy/node` too: it is where `tripwire()`, `rateLimit()` and the other rules are imported from. -| Framework | Install | -|---|---| -| Express | `npm install @webdecoy/express @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/express)) | -| Fastify | `npm install @webdecoy/fastify @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/fastify)) | -| Next.js | `npm install @webdecoy/nextjs @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/nextjs)) | -| Hono (Workers, Bun, Deno, Node) | `npm install @webdecoy/hono @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/hono)) | -| Any other server or fetch runtime | `npm install @webdecoy/node` (this page) | +| Framework | Install | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| Express | `npm install @webdecoy/express @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/express)) | +| Fastify | `npm install @webdecoy/fastify @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/fastify)) | +| Next.js | `npm install @webdecoy/nextjs @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/nextjs)) | +| Hono (Workers, Bun, Deno, Node) | `npm install @webdecoy/hono @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/hono)) | +| Any other server or fetch runtime | `npm install @webdecoy/node` (this page) | ## Installation @@ -39,23 +39,25 @@ import { WebDecoy } from '@webdecoy/node'; const wd = new WebDecoy({ apiKey: process.env.WEBDECOY_API_KEY }); -http.createServer(async (req, res) => { - const decision = await wd.protect({ - method: req.method, - path: new URL(req.url, 'http://localhost').pathname, - ip: req.socket.remoteAddress ?? '', - user_agent: req.headers['user-agent'], - headers: Object.fromEntries( - Object.entries(req.headers).map(([name, value]) => [name, String(value)]) - ), - timestamp: Date.now(), - }); - - // protect() returns a decision and blocks nothing itself. - // Log decision.conclusion ('ALLOW', 'DENY', 'CHALLENGE' or 'ERROR') first; - // refuse with a 403 when decision.allowed is false only once you are ready. - res.end('ok'); -}).listen(3000); +http + .createServer(async (req, res) => { + const decision = await wd.protect({ + method: req.method, + path: new URL(req.url, 'http://localhost').pathname, + ip: req.socket.remoteAddress ?? '', + user_agent: req.headers['user-agent'], + headers: Object.fromEntries( + Object.entries(req.headers).map(([name, value]) => [name, String(value)]) + ), + timestamp: Date.now(), + }); + + // protect() returns a decision and blocks nothing itself. + // Log decision.conclusion ('ALLOW', 'DENY', 'CHALLENGE' or 'ERROR') first; + // refuse with a 403 when decision.allowed is false only once you are ready. + res.end('ok'); + }) + .listen(3000); ``` Behind a proxy, `req.socket.remoteAddress` is the proxy. Use `resolveClientIp()` from this package to read the real client address (see [Client IP behind a proxy](#client-ip-behind-a-proxy)). @@ -68,6 +70,23 @@ Behind a proxy, `req.socket.remoteAddress` is the proxy. Use `resolveClientIp()` To get a key: sign up at [app.webdecoy.com](https://app.webdecoy.com), add your site, then create a key on the **API Keys** page. Keys start with `sk_live_` (production) or `sk_test_` (testing); any other prefix throws when the SDK is constructed. Keep the key on the server and out of committed files. +### Confirm an SSRF callback + +```ts +const canary = await wd.createSSRFCanary({ + routeTemplate: '/api/fetch/:id', + test: true, +}); +await wd.reportSSRFInitiation(canary); +await applicationFetch(canary.callbackUrl); +``` + +The marker is property-scoped, single-use, and expires after 15 minutes. The +SDK reports only its marker ID and route template on the initiation edge. +WebDecoy never fetches a supplied URL; a finding is created only after the +matching callback arrives. Use `test: true` for controlled validation so it is +kept out of production threat metrics. + ### Monitor first `protect()` only returns a decision. It never writes a response, so nothing is blocked until your code acts on `decision.allowed`. The framework adapters and `createFetchGuard()` follow the same rule: they start in **monitor mode** (`mode: 'monitor'`), record the decision and serve every request. Set `mode: 'enforce'` only after you have reviewed what would have been blocked. @@ -79,26 +98,26 @@ To get a key: sign up at [app.webdecoy.com](https://app.webdecoy.com), add your ```ts const decision = await wd.protect(metadata); -decision.conclusion // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' -decision.allowed // true for ALLOW and ERROR (fails open), false for DENY and CHALLENGE -decision.id // 'dec_...' -decision.isDenied() // also isAllowed(), isChallenged(), isErrored() -decision.deniedBy('tripwire') // whether a named rule denied the request -decision.results // every configured rule, its state and its conclusion -decision.reason // the deciding reason, when there is one -decision.detection // { decision, confidence, threat_level, bot_detected, bot_type?, detection_id, rule_enforced } -decision.error // set when conclusion is 'ERROR' -decision.edge // what a WebDecoy edge validator said about this request, if one fronted it +decision.conclusion; // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' +decision.allowed; // true for ALLOW and ERROR (fails open), false for DENY and CHALLENGE +decision.id; // 'dec_...' +decision.isDenied(); // also isAllowed(), isChallenged(), isErrored() +decision.deniedBy('tripwire'); // whether a named rule denied the request +decision.results; // every configured rule, its state and its conclusion +decision.reason; // the deciding reason, when there is one +decision.detection; // { decision, confidence, threat_level, bot_detected, bot_type?, detection_id, rule_enforced } +decision.error; // set when conclusion is 'ERROR' +decision.edge; // what a WebDecoy edge validator said about this request, if one fronted it ``` Each entry in `results` has a `state`: -| `state` | Meaning | -|---|---| -| `RUN` | Evaluated, and its conclusion counts. | -| `DRY_RUN` | Evaluated; the conclusion is recorded but not enforced. | +| `state` | Meaning | +| --------- | -------------------------------------------------------------------------------------------------------------- | +| `RUN` | Evaluated, and its conclusion counts. | +| `DRY_RUN` | Evaluated; the conclusion is recorded but not enforced. | | `NOT_RUN` | Could not evaluate because a signal it needs was absent (for example a `filter()` rule with no IP enrichment). | -| `CACHED` | Not evaluated; a prior decision for this key was reused. | +| `CACHED` | Not evaluated; a prior decision for this key was reused. | `ERROR` is not a denial. It means no verdict was reached (for example WebDecoy could not be reached, or the request had no IP), and `allowed` is `true`. @@ -114,21 +133,21 @@ import { WebDecoy, tripwire, rateLimit, filter } from '@webdecoy/node'; const wd = new WebDecoy({ rules: [ tripwire({ paths: ['/admin-backup.zip'] }), // plus built-in paths such as /.env - rateLimit({ max: 100, window: 60 }), // 100 requests per 60 s per IP + rateLimit({ max: 100, window: 60 }), // 100 requests per 60 s per IP filter({ expression: 'ip.tor or ip.vpn' }), // needs an apiKey (IP enrichment) ], }); ``` -| Rule | What it does | Needs an API key? | -|---|---|---| -| `tripwire({ paths?, prefixes?, patterns?, includeDefaults?, action?, dryRun? })` | Matches requests for decoy and scanner-bait paths. | No | -| `honeytoken()` | Returns `{ path, linkHtml }`: a hidden decoy link and the path to arm with `tripwire({ paths: [path] })`. | No | -| `rateLimit({ max, window, algorithm?, keyBy?, store?, action?, dryRun? })` | Fixed or sliding window, keyed by IP by default. In-memory unless you pass a shared `store` (for example `upstashRateLimitStore()`). | No | -| `attackSignatures({ inspect?, exclude?, action?, dryRun? })` | Denies requests carrying unambiguous injection payloads. | No | -| `webBotAuth()` | Verifies Web Bot Auth (RFC 9421) agent signatures and denies impersonators of known agents. | No | -| `botPolicy({ deny, allow })` | One crawler policy that produces both your `robots.txt` and the rule that enforces it. | No | -| `filter({ expression, action?, dryRun? })` | Expressions over IP reputation and geo, such as `ip.tor` or `ip.country in ["CN", "RU"]`. | Yes | +| Rule | What it does | Needs an API key? | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | +| `tripwire({ paths?, prefixes?, patterns?, includeDefaults?, action?, dryRun? })` | Matches requests for decoy and scanner-bait paths. | No | +| `honeytoken()` | Returns `{ path, linkHtml }`: a hidden decoy link and the path to arm with `tripwire({ paths: [path] })`. | No | +| `rateLimit({ max, window, algorithm?, keyBy?, store?, action?, dryRun? })` | Fixed or sliding window, keyed by IP by default. In-memory unless you pass a shared `store` (for example `upstashRateLimitStore()`). | No | +| `attackSignatures({ inspect?, exclude?, action?, dryRun? })` | Denies requests carrying unambiguous injection payloads. | No | +| `webBotAuth()` | Verifies Web Bot Auth (RFC 9421) agent signatures and denies impersonators of known agents. | No | +| `botPolicy({ deny, allow })` | One crawler policy that produces both your `robots.txt` and the rule that enforces it. | No | +| `filter({ expression, action?, dryRun? })` | Expressions over IP reputation and geo, such as `ip.tor` or `ip.country in ["CN", "RU"]`. | Yes | A tripwire match is evidence, not proof of intent: link prefetchers, preview bots and your own security scanners can request a hidden or scanner-bait path. Use `dryRun: true` on a rule to observe it before enforcing. @@ -166,11 +185,11 @@ export const config = { }; ``` -| Variable | Turns on | Secret? | -|---|---|---| -| `WEBDECOY_API_KEY` | Detection: bots, tripwire hits and agents the bot registry names are reported to your dashboard. From the **API Keys** page. | Yes | -| `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` | The clearance gate, with the sensor key. From **Enforcement, Setup**. | No | -| `WEBDECOY_SENSOR_KEY` | The clearance gate. From **Enforcement, Setup**. | Yes | +| Variable | Turns on | Secret? | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------- | +| `WEBDECOY_API_KEY` | Detection: bots, tripwire hits and agents the bot registry names are reported to your dashboard. From the **API Keys** page. | Yes | +| `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` | The clearance gate, with the sensor key. From **Enforcement, Setup**. | No | +| `WEBDECOY_SENSOR_KEY` | The clearance gate. From **Enforcement, Setup**. | Yes | Either half works without the other; with neither, every request passes. Detection starts in monitor mode (the request is served and the verdict rides on the request as `x-webdecoy-decision`, `x-webdecoy-detection-id` and `x-webdecoy-would-block`), and the gate follows the site's mode in WebDecoy, monitor until you switch it. Every failure, WebDecoy unreachable included, lets the request through. Without `WEBDECOY_API_KEY` the middleware is the clearance gate alone, exactly as before. @@ -186,12 +205,12 @@ curl -A "WebDecoy-Test/1.0" https://your-site.vercel.app/ The SDK reads only these, and only in the features named: -| Variable | Read by | -|---|---| -| `WEBDECOY_API_KEY` | The Vercel middleware (`@webdecoy/node/vercel`, `createDetectAndGate()`), when `apiKey` is not passed. | +| Variable | Read by | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| `WEBDECOY_API_KEY` | The Vercel middleware (`@webdecoy/node/vercel`, `createDetectAndGate()`), when `apiKey` is not passed. | | `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID`, `WEBDECOY_SENSOR_KEY` | The clearance gate (`@webdecoy/node/vercel`, `createClearanceGate()`), when the matching option is not passed. | -| `WEBDECOY_INGEST` | The clearance gate, to override its ingest endpoint. Optional. | -| `NODE_ENV` | The self-hosted captcha: with `production`, a missing or default `secret` throws. | +| `WEBDECOY_INGEST` | The clearance gate, to override its ingest endpoint. Optional. | +| `NODE_ENV` | The self-hosted captcha: with `production`, a missing or default `secret` throws. | Everywhere else `WEBDECOY_API_KEY` is a naming convention used in these docs: pass its value as `apiKey`. @@ -200,14 +219,14 @@ Everywhere else `WEBDECOY_API_KEY` is a naming convention used in these docs: pa ```ts const wd = new WebDecoy({ apiKey: process.env.WEBDECOY_API_KEY, // optional; without it, local rules only - rules: [tripwire()], // optional; default [tripwire()], [] to opt out - apiUrl: 'https://in.webdecoy.com', // optional (default shown) - threatScoreThreshold: 80, // optional, 0-100 (default 80) - timeout: 5000, // optional, ms (default 5000) - enableTLSFingerprinting: true, // optional (default true) - tlsRejectUnauthorized: true, // optional (default true) - countAIReferrals: true, // optional (default true; aggregate counts, only with an apiKey) - debug: false, // optional (default false) + rules: [tripwire()], // optional; default [tripwire()], [] to opt out + apiUrl: 'https://in.webdecoy.com', // optional (default shown) + threatScoreThreshold: 80, // optional, 0-100 (default 80) + timeout: 5000, // optional, ms (default 5000) + enableTLSFingerprinting: true, // optional (default true) + tlsRejectUnauthorized: true, // optional (default true) + countAIReferrals: true, // optional (default true; aggregate counts, only with an apiKey) + debug: false, // optional (default false) }); ``` diff --git a/packages/webdecoy/src/client.ts b/packages/webdecoy/src/client.ts index 92f01b8..a1e0cef 100644 --- a/packages/webdecoy/src/client.ts +++ b/packages/webdecoy/src/client.ts @@ -8,7 +8,13 @@ */ import type { AIReferralBatch } from './referrals/referral-counter'; -import { SDKDetectionRequest, SDKDetectionResponse } from './types'; +import { + SDKDetectionRequest, + SDKDetectionResponse, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, +} from './types'; import { reportableHeaders } from './report-headers'; import type { ViolationEvent, IPEnrichmentData } from './rules/types'; @@ -78,7 +84,7 @@ export class WebDecoyClient { if (config.tlsRejectUnauthorized === false && config.debug) { console.warn( '[WebDecoy] tlsRejectUnauthorized=false is not supported by the fetch transport and is ignored; ' + - 'for local self-signed certs, trust your CA via NODE_EXTRA_CA_CERTS=/path/to/ca.pem.', + 'for local self-signed certs, trust your CA via NODE_EXTRA_CA_CERTS=/path/to/ca.pem.' ); } } @@ -108,7 +114,11 @@ export class WebDecoyClient { this.pausedUntil = Date.now() + ms; } - private async request(method: 'GET' | 'POST', path: string, body?: unknown): Promise> { + private async request( + method: 'GET' | 'POST', + path: string, + body?: unknown + ): Promise> { if (!this.isAvailable()) { throw new WebDecoyUnavailableError(this.pausedUntil); } @@ -176,10 +186,13 @@ export class WebDecoyClient { response = await this.request( 'POST', '/api/v1/sdk/detect', - toWireDetectionRequest(request), + toWireDetectionRequest(request) ); } catch (error) { - if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) { + if ( + error instanceof Error && + (error.name === 'AbortError' || error.name === 'TimeoutError') + ) { throw new Error('Request timeout. The Web Decoy service did not respond in time.'); } if (error instanceof TypeError) { @@ -207,6 +220,74 @@ export class WebDecoyClient { return response.data as SDKDetectionResponse; } + async createSSRFCanary(options: SSRFCanaryOptions): Promise { + const response = await this.request< + { + marker_id: string; + callback_url: string; + route_template: string; + expires_at: string; + test: boolean; + } & ApiErrorBody + >('POST', '/api/v1/sdk/ssrf/markers', { + property_id: options.propertyId, + route_template: options.routeTemplate, + test: options.test === true, + }); + this.requireSuccess(response); + const data = response.data!; + if (!data.marker_id || !data.callback_url || !data.route_template || !data.expires_at) { + throw new Error('WebDecoy returned an invalid SSRF canary'); + } + return { + markerId: data.marker_id, + callbackUrl: data.callback_url, + routeTemplate: data.route_template, + expiresAt: data.expires_at, + test: data.test === true, + }; + } + + async reportSSRFInitiation( + canary: Pick + ): Promise { + const response = await this.request< + { + detection_id: string; + marker_id: string; + test: boolean; + } & ApiErrorBody + >('POST', '/api/v1/sdk/ssrf/initiate', { + marker_id: canary.markerId, + route_template: canary.routeTemplate, + }); + this.requireSuccess(response); + const data = response.data!; + if (!data.detection_id || !data.marker_id) { + throw new Error('WebDecoy returned an invalid SSRF initiation receipt'); + } + return { detectionId: data.detection_id, markerId: data.marker_id, test: data.test === true }; + } + + private requireSuccess(response: ApiResponse): void { + if (response.status === 401) { + throw new Error('Invalid API key. Please check your Web Decoy configuration.'); + } + if (response.status === 429) { + throw new Error('Rate limit exceeded. Please try again later.'); + } + if (response.status >= 400) { + throw new Error( + response.data?.error || + response.data?.message || + `API request failed: HTTP ${response.status}` + ); + } + if (!response.data) { + throw new Error('WebDecoy returned an empty response'); + } + } + /** * Send violation events to the ingest service */ @@ -247,7 +328,7 @@ export class WebDecoyClient { try { const response = await this.request( 'GET', - `/api/v1/sdk/ip/${encodeURIComponent(ip)}/enrichment`, + `/api/v1/sdk/ip/${encodeURIComponent(ip)}/enrichment` ); if (response.status >= 400) return null; return response.data ?? null; diff --git a/packages/webdecoy/src/index.ts b/packages/webdecoy/src/index.ts index 9eac8cc..714a5aa 100644 --- a/packages/webdecoy/src/index.ts +++ b/packages/webdecoy/src/index.ts @@ -35,6 +35,9 @@ export type { SDKDetectionResponse, ProtectResult, ProtectOptions, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, } from './types'; // The decision `protect()` returns. Exported as a value because the class diff --git a/packages/webdecoy/src/sdk.ts b/packages/webdecoy/src/sdk.ts index 3f032fd..3f30bf7 100644 --- a/packages/webdecoy/src/sdk.ts +++ b/packages/webdecoy/src/sdk.ts @@ -30,6 +30,9 @@ import { ProtectOptions, SDKDetectionRequest, SDKDetectionResponse, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, } from './types'; export class WebDecoy { @@ -42,7 +45,11 @@ export class WebDecoy { }; private ruleEngine: RuleEngine | null; private referralCounter: AIReferralCounter | null = null; - private violationReporter: { report(violations: ViolationEvent[]): void; flush(): Promise; destroy(): Promise } | null = null; + private violationReporter: { + report(violations: ViolationEvent[]): void; + flush(): Promise; + destroy(): Promise; + } | null = null; private ipEnrichmentClient: IPEnrichmentClient | null = null; private _hasFilterRules = false; private _hasAgentRules = false; @@ -324,6 +331,27 @@ export class WebDecoy { return this.getAgentVerifier().verify(request); } + /** Mint a signed, single-use callback marker for an SSRF test or observation. */ + async createSSRFCanary(options: SSRFCanaryOptions): Promise { + if (!this.client) { + throw new Error('An apiKey is required to create an SSRF canary'); + } + return this.client.createSSRFCanary(options); + } + + /** + * Report the initiating server request immediately before the application's + * ordinary fetch. Only the marker ID and route template are sent. + */ + async reportSSRFInitiation( + canary: Pick + ): Promise { + if (!this.client) { + throw new Error('An apiKey is required to report an SSRF initiation'); + } + return this.client.reportSSRFInitiation(canary); + } + /** * Whether this SDK instance has filter rules that need async enrichment */ @@ -347,10 +375,7 @@ export class WebDecoy { * @returns The decision — `conclusion`, every rule's outcome, and the * narrowing helpers. Satisfies `ProtectResult`. */ - async protect( - metadata: RequestMetadata, - options: ProtectOptions = {} - ): Promise { + async protect(metadata: RequestMetadata, options: ProtectOptions = {}): Promise { // The edge verdict is attached here rather than at each return inside // decide(), which has six of them including two fail-open paths. It is // information ABOUT the request, not a product of the decision, so it must be @@ -376,11 +401,7 @@ export class WebDecoy { } // A detection id that is not the decision id means the verdict came back // from ingest rather than being settled locally. - setAttribute( - span, - 'webdecoy.remote', - decision.detection.detection_id !== decision.id, - ); + setAttribute(span, 'webdecoy.remote', decision.detection.detection_id !== decision.id); if (decision.error) { setAttribute(span, 'webdecoy.error', decision.error); } @@ -395,10 +416,7 @@ export class WebDecoy { } } - private async decide( - metadata: RequestMetadata, - options: ProtectOptions = {} - ): Promise { + private async decide(metadata: RequestMetadata, options: ProtectOptions = {}): Promise { // Declared out here so the catch below can stamp the same id and key onto // an ERROR decision. An error is still a decision about a caller. const id = newDecisionId(); @@ -434,9 +452,7 @@ export class WebDecoy { : this.buildContext(metadata); key = context.key ?? key; const agentVerdict: AgentVerdict | undefined = context.agent; - const ruleResult: RuleEngineResult | null = this.ruleEngine - ? this.runRules(context) - : null; + const ruleResult: RuleEngineResult | null = this.ruleEngine ? this.runRules(context) : null; // Rules denied or throttled: decided locally, no API call. Not cached — // a rate limiter has to see every request to advance its window, and a @@ -561,7 +577,9 @@ export class WebDecoy { const decision = new Decision({ conclusion, - reason: allowed ? undefined : `Threat score ${detection.confidence} (threshold ${threshold})`, + reason: allowed + ? undefined + : `Threat score ${detection.confidence} (threshold ${threshold})`, detection, id, results: ruleResult?.results ?? [], @@ -582,7 +600,10 @@ export class WebDecoy { // While the client is paused after an outage, every request lands here. // The failure that started the pause was already logged as an error; // logging each paused request too would flood the operator's logs. - const log = error instanceof WebDecoyUnavailableError ? this.log.debug.bind(this.log) : this.log.error.bind(this.log); + const log = + error instanceof WebDecoyUnavailableError + ? this.log.debug.bind(this.log) + : this.log.error.bind(this.log); log('Protection error', { error: error instanceof Error ? error.message : String(error), }); @@ -694,7 +715,11 @@ export class WebDecoy { * Attach a violation reporter for sending violations to the backend. * Called internally when apiKey is present and rules are configured. */ - setViolationReporter(reporter: { report(violations: ViolationEvent[]): void; flush(): Promise; destroy(): Promise }): void { + setViolationReporter(reporter: { + report(violations: ViolationEvent[]): void; + flush(): Promise; + destroy(): Promise; + }): void { this.violationReporter = reporter; } @@ -737,10 +762,7 @@ export class WebDecoy { function agentInputFromMetadata(metadata: RequestMetadata): AgentRequestInput | null { const headers = metadata.headers || {}; const host = - headers['host'] || - headers[':authority'] || - headers['x-forwarded-host'] || - headers['Host']; + headers['host'] || headers[':authority'] || headers['x-forwarded-host'] || headers['Host']; if (!host) return null; const proto = headers['x-forwarded-proto'] || headers['X-Forwarded-Proto']; diff --git a/packages/webdecoy/src/ssrf-canary.test.ts b/packages/webdecoy/src/ssrf-canary.test.ts new file mode 100644 index 0000000..c5af4ed --- /dev/null +++ b/packages/webdecoy/src/ssrf-canary.test.ts @@ -0,0 +1,64 @@ +import { WebDecoy } from './sdk'; + +describe('SSRF canary correlation', () => { + const realFetch = global.fetch; + + afterEach(() => { + global.fetch = realFetch; + }); + + it('reports only the marker ID and route template on the initiation edge', async () => { + const calls: Array<{ url: string; body: Record }> = []; + global.fetch = jest.fn(async (url: unknown, init: RequestInit) => { + const body = JSON.parse(String(init.body)) as Record; + calls.push({ url: String(url), body }); + if (String(url).endsWith('/ssrf/markers')) { + return new Response( + JSON.stringify({ + marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + callback_url: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', + route_template: '/api/fetch/:id', + expires_at: '2026-11-15T21:00:00Z', + test: true, + token: 'must-not-be-returned-by-the-sdk', + }), + { status: 201 } + ); + } + return new Response( + JSON.stringify({ + detection_id: 'c18348c8-9f6b-43e9-b993-86ca15db257f', + marker_id: body.marker_id, + test: true, + }), + { status: 201 } + ); + }) as jest.Mock; + + const sdk = new WebDecoy({ apiKey: 'sk_test_ssrf', apiUrl: 'https://ingest.example' }); + const canary = await sdk.createSSRFCanary({ routeTemplate: '/api/fetch/:id', test: true }); + const receipt = await sdk.reportSSRFInitiation(canary); + + expect(canary).toEqual({ + markerId: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + callbackUrl: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', + routeTemplate: '/api/fetch/:id', + expiresAt: '2026-11-15T21:00:00Z', + test: true, + }); + expect(receipt.detectionId).toBe('c18348c8-9f6b-43e9-b993-86ca15db257f'); + expect(calls[1]).toEqual({ + url: 'https://ingest.example/api/v1/sdk/ssrf/initiate', + body: { + marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + route_template: '/api/fetch/:id', + }, + }); + expect(JSON.stringify(calls[1].body)).not.toContain('opaque-token'); + }); + + it('requires a hosted API key', async () => { + const sdk = new WebDecoy(); + await expect(sdk.createSSRFCanary({ routeTemplate: '/fetch' })).rejects.toThrow(/apiKey/); + }); +}); diff --git a/packages/webdecoy/src/types.ts b/packages/webdecoy/src/types.ts index 5d68dbb..5f534eb 100644 --- a/packages/webdecoy/src/types.ts +++ b/packages/webdecoy/src/types.ts @@ -139,6 +139,31 @@ export interface WebDecoyConfig { tracer?: Tracer; } +/** Options for one short-lived, property-scoped SSRF canary. */ +export interface SSRFCanaryOptions { + /** The application route that will perform the server-side fetch. */ + routeTemplate: string; + /** Required only when an organization-wide API key is used. */ + propertyId?: string; + /** Keep a controlled validation out of production threat metrics. */ + test?: boolean; +} + +/** A callback marker. Put callbackUrl in the controlled outbound request. */ +export interface SSRFCanary { + markerId: string; + callbackUrl: string; + routeTemplate: string; + expiresAt: string; + test: boolean; +} + +export interface SSRFInitiationReceipt { + detectionId: string; + markerId: string; + test: boolean; +} + /** * TLS connection information from the request */ From 700a9b3d3634bdc317dc4b95641409a8bd9dfc0e Mon Sep 17 00:00:00 2001 From: Chris Portscheller Date: Sun, 15 Nov 2026 20:20:16 -0600 Subject: [PATCH 2/3] Revert "feat(node): add SSRF canary correlation API" This reverts commit 7b1337cb65a3dc136ad853d9e5781adff18ea890. --- README.md | 191 ++++++++++------------ packages/webdecoy/README.md | 153 ++++++++--------- packages/webdecoy/src/client.ts | 93 +---------- packages/webdecoy/src/index.ts | 3 - packages/webdecoy/src/sdk.ts | 70 +++----- packages/webdecoy/src/ssrf-canary.test.ts | 64 -------- packages/webdecoy/src/types.ts | 25 --- 7 files changed, 181 insertions(+), 418 deletions(-) delete mode 100644 packages/webdecoy/src/ssrf-canary.test.ts diff --git a/README.md b/README.md index b78446e..06771f2 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,10 @@ controlled request first, inspect the result, then add detection to your app. WebDecoy complements the edge controls you already use; it only observes requests that reach its middleware. -| Try it | What you will see | What you need | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| [Express browser playground](https://stackblitz.com/github/WebDecoy/node/tree/main/playgrounds/express?file=app.mjs) | Send an ordinary request and a decoy request; compare the HTTP response with the local tripwire decision. | No account or API key. | -| [Next.js 16 on Vercel](https://webdecoy.com/blog/see-bots-ai-crawlers-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=node_demo_to_star&utm_content=nextjs_walkthrough) | Run the downloadable diagnostic app, send a labeled test and match its record in your dashboard. | Your own server-side WebDecoy API key for reporting. | +| Try it | What you will see | What you need | +| --- | --- | --- | +| [Express browser playground](https://stackblitz.com/github/WebDecoy/node/tree/main/playgrounds/express?file=app.mjs) | Send an ordinary request and a decoy request; compare the HTTP response with the local tripwire decision. | No account or API key. | +| [Next.js 16 on Vercel](https://webdecoy.com/blog/see-bots-ai-crawlers-nextjs/?utm_source=github&utm_medium=readme&utm_campaign=node_demo_to_star&utm_content=nextjs_walkthrough) | Run the downloadable diagnostic app, send a labeled test and match its record in your dashboard. | Your own server-side WebDecoy API key for reporting. | The [25-second Vercel proof](https://youtu.be/W_mB8VX0vk0) animates the verified HTTP response and matching **Test → Logged, not blocked** record. This is a @@ -45,27 +45,27 @@ After you have tried an example, **[star WebDecoy/node](https://github.com/WebDe ## What you can do -| Need | Start here | -| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| Detect requests to hidden decoys and scanner-bait paths | [Honeypot tripwires](#why-add-tripwires) | -| Limit repeated requests to your app or API | [Local rules](#more-local-rules) and [shared rate limits](#rate-limits-across-more-than-one-process) | -| Check supported signed AI-agent identities | [Web Bot Auth verification](#verify-ai-agents-web-bot-auth) | -| Publish and enforce an AI crawler policy | [One bot policy](#one-bot-policy-published-and-enforced) | -| Add browser interaction evidence to server decisions | [Client signals](#catching-a-real-browser-that-isnt-a-real-user) | -| See server-side analysis and detections in a dashboard | [Optional WebDecoy platform](#optional-the-webdecoy-platform-api-key) | +| Need | Start here | +| --- | --- | +| Detect requests to hidden decoys and scanner-bait paths | [Honeypot tripwires](#why-add-tripwires) | +| Limit repeated requests to your app or API | [Local rules](#more-local-rules) and [shared rate limits](#rate-limits-across-more-than-one-process) | +| Check supported signed AI-agent identities | [Web Bot Auth verification](#verify-ai-agents-web-bot-auth) | +| Publish and enforce an AI crawler policy | [One bot policy](#one-bot-policy-published-and-enforced) | +| Add browser interaction evidence to server decisions | [Client signals](#catching-a-real-browser-that-isnt-a-real-user) | +| See server-side analysis and detections in a dashboard | [Optional WebDecoy platform](#optional-the-webdecoy-platform-api-key) | WebDecoy works alongside Cloudflare and other CDN protections. Server middleware observes requests that reach your application; requests served or blocked before it runs are outside its view. A crawler name is a claim until supported identity checks establish more. ## Choose your framework -| Your app | Package and setup | -| ------------------------------------------------ | ------------------------------------------------------------------- | -| Express | [Express middleware](packages/express/README.md) | -| Fastify | [Fastify plugin](packages/fastify/README.md) | -| Next.js | [Next.js middleware](packages/nextjs/README.md) | -| Hono, Cloudflare Workers, Bun or Deno | [Hono middleware](packages/hono/README.md) | +| Your app | Package and setup | +| --- | --- | +| Express | [Express middleware](packages/express/README.md) | +| Fastify | [Fastify plugin](packages/fastify/README.md) | +| Next.js | [Next.js middleware](packages/nextjs/README.md) | +| Hono, Cloudflare Workers, Bun or Deno | [Hono middleware](packages/hono/README.md) | | Astro, SvelteKit, Remix or another fetch handler | [`createFetchGuard()`](#any-other-fetch-runtime--no-package-needed) | -| A custom Node.js server | [Core SDK](packages/webdecoy/README.md) | +| A custom Node.js server | [Core SDK](packages/webdecoy/README.md) | The middleware starts in **monitor mode**: it records verdicts without blocking requests. A local rules setup needs no cloud connection; an API key is needed to send detections to the WebDecoy dashboard. @@ -104,8 +104,8 @@ tripwire({ prefixes: ['/.git/'], patterns: [/\/wp-admin\//], includeDefaults: true, // built-in scanner-bait paths (default: true) - action: 'DENY', // or 'THROTTLE' - dryRun: false, // log only, don't block (observe before enforcing) + action: 'DENY', // or 'THROTTLE' + dryRun: false, // log only, don't block (observe before enforcing) }); ``` @@ -144,7 +144,10 @@ const app = express(); app.use( webdecoy({ // No apiKey → purely local rules (tripwires + rate limiting). - rules: [tripwire({ paths: ['/.env', '/wp-config.php'] }), rateLimit({ max: 100, window: 60 })], + rules: [ + tripwire({ paths: ['/.env', '/wp-config.php'] }), + rateLimit({ max: 100, window: 60 }), + ], skipPaths: ['/health', '/public'], }) ); @@ -197,7 +200,7 @@ const guard = createFetchGuard({ mode: 'enforce', rules: [tripwire()] }); export default { async fetch(request: Request): Promise { const { response } = await guard.check(request); - if (response) return response; // denied + if (response) return response; // denied return guard.decorate(await handle(request)); // injects the honeytoken link }, }; @@ -212,8 +215,8 @@ import { WebDecoy, rateLimit, tripwire, filter } from '@webdecoy/node'; const wd = new WebDecoy({ rules: [ - rateLimit({ max: 100, window: 60 }), // 100 req / 60s per IP - tripwire({ paths: ['/.env', '/wp-config.php'] }), // honeypot paths + rateLimit({ max: 100, window: 60 }), // 100 req / 60s per IP + tripwire({ paths: ['/.env', '/wp-config.php'] }), // honeypot paths filter({ expression: 'ip.tor or ip.vpn', action: 'DENY' }), // needs an API key (IP enrichment) ], }); @@ -241,8 +244,7 @@ const wd = new WebDecoy({}); const verdict = await wd.detectBot(request); // a WHATWG Request, or { method, url, headers } // verdict.status: 'verified' | 'impersonation' | 'claimed' | 'none' if (verdict.status === 'impersonation') return new Response('Forbidden', { status: 403 }); -if (verdict.status === 'verified') - console.log('verified agent:', verdict.agentName, verdict.category); +if (verdict.status === 'verified') console.log('verified agent:', verdict.agentName, verdict.category); ``` Or drop it into the rules engine to deny impersonation automatically: @@ -278,7 +280,7 @@ Set `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` and `WEBDECOY_SENSOR_KEY` from ** Tripwire matching is deterministic, but a match does not guarantee malicious intent. Review these edge cases before enforcing: - **The honeytoken link** is rendered hidden and `rel=nofollow`, outside your normal sitemap and navigation. Those properties reduce ordinary discovery; they do not guarantee that legitimate software will never request it, or that a scraper will follow it. -- **Aggressive link-prefetchers and unfurl/preview bots** (e.g. some browsers' speculative prefetch, chat link previews) _can_ fetch a hidden link. If you serve link previews or use prefetching, start with `dryRun: true` to measure before enforcing, or scope the trap to paths those bots won't touch. +- **Aggressive link-prefetchers and unfurl/preview bots** (e.g. some browsers' speculative prefetch, chat link previews) *can* fetch a hidden link. If you serve link previews or use prefetching, start with `dryRun: true` to measure before enforcing, or scope the trap to paths those bots won't touch. - **The default scanner-bait paths** (`/.env`, `/.git/config`, …) can also be requested by your own security scanners, uptime checks or users troubleshooting a site. Exclude known legitimate activity or run `dryRun` first. The honest rule of thumb: enforce tripwires you control the surface of, and use `dryRun` to observe any path you're unsure about. @@ -315,27 +317,6 @@ if (!result.allowed) { } ``` -### Confirm an SSRF callback - -For a route that intentionally performs a server-side fetch, mint a short-lived -canary and report its initiation immediately before the fetch: - -```typescript -const canary = await wd.createSSRFCanary({ - routeTemplate: '/api/fetch/:id', - test: true, // controlled validation; excluded from production threat metrics -}); - -await wd.reportSSRFInitiation(canary); -await applicationFetch(canary.callbackUrl); -``` - -Use the callback URL only as the controlled destination for the fetch you are -testing. WebDecoy never fetches a supplied URL. A confirmed finding requires -both the trusted initiation and the matching single-use callback within 15 -minutes; either edge alone is not confirmed SSRF. Open the callback detection -in WebDecoy to see its **Correlated activity** evidence. - ### Getting an API key 1. Sign up at [app.webdecoy.com](https://app.webdecoy.com) @@ -344,22 +325,22 @@ in WebDecoy to see its **Correlated activity** evidence. ## How it works -| Tier | What | Needs a key? | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------: | -| **0 — Tripwires** | Requests for decoy and scanner-bait paths match before any scoring (recorded in monitor mode, refused in enforce mode). Deterministic matching; see [false positives](#what-counts-as-a-false-positive). | No | -| **1 — Local analysis** | Fast on-server heuristics: suspicious/missing headers, datacenter IPs, known bot user-agents, missing `Sec-CH-UA`. | No | -| **2 — Server verification** | Known-bot database, IP reputation, GeoIP (Tor/VPN/proxy), and JA3 TLS fingerprinting with TLS↔UA mismatch when `tls_info` is supplied. | Yes | +| Tier | What | Needs a key? | +|------|------|:---:| +| **0 — Tripwires** | Requests for decoy and scanner-bait paths match before any scoring (recorded in monitor mode, refused in enforce mode). Deterministic matching; see [false positives](#what-counts-as-a-false-positive). | No | +| **1 — Local analysis** | Fast on-server heuristics: suspicious/missing headers, datacenter IPs, known bot user-agents, missing `Sec-CH-UA`. | No | +| **2 — Server verification** | Known-bot database, IP reputation, GeoIP (Tor/VPN/proxy), and JA3 TLS fingerprinting with TLS↔UA mismatch when `tls_info` is supplied. | Yes | ## Packages -| Package | Version | Description | -| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| [@webdecoy/node](https://www.npmjs.com/package/@webdecoy/node) | [![npm](https://img.shields.io/npm/v/@webdecoy/node.svg)](https://www.npmjs.com/package/@webdecoy/node) | Core SDK + local rules (tripwire, rateLimit, filter) | -| [@webdecoy/express](https://www.npmjs.com/package/@webdecoy/express) | [![npm](https://img.shields.io/npm/v/@webdecoy/express.svg)](https://www.npmjs.com/package/@webdecoy/express) | Express.js middleware | -| [@webdecoy/fastify](https://www.npmjs.com/package/@webdecoy/fastify) | [![npm](https://img.shields.io/npm/v/@webdecoy/fastify.svg)](https://www.npmjs.com/package/@webdecoy/fastify) | Fastify plugin | -| [@webdecoy/nextjs](https://www.npmjs.com/package/@webdecoy/nextjs) | [![npm](https://img.shields.io/npm/v/@webdecoy/nextjs.svg)](https://www.npmjs.com/package/@webdecoy/nextjs) | Next.js middleware | -| [@webdecoy/hono](https://www.npmjs.com/package/@webdecoy/hono) | [![npm](https://img.shields.io/npm/v/@webdecoy/hono.svg)](https://www.npmjs.com/package/@webdecoy/hono) | Hono middleware (Workers, Bun, Deno) | -| [@webdecoy/client](https://www.npmjs.com/package/@webdecoy/client) | [![npm](https://img.shields.io/npm/v/@webdecoy/client.svg)](https://www.npmjs.com/package/@webdecoy/client) | Browser-side signal collector | +| Package | Version | Description | +|---------|---------|-------------| +| [@webdecoy/node](https://www.npmjs.com/package/@webdecoy/node) | [![npm](https://img.shields.io/npm/v/@webdecoy/node.svg)](https://www.npmjs.com/package/@webdecoy/node) | Core SDK + local rules (tripwire, rateLimit, filter) | +| [@webdecoy/express](https://www.npmjs.com/package/@webdecoy/express) | [![npm](https://img.shields.io/npm/v/@webdecoy/express.svg)](https://www.npmjs.com/package/@webdecoy/express) | Express.js middleware | +| [@webdecoy/fastify](https://www.npmjs.com/package/@webdecoy/fastify) | [![npm](https://img.shields.io/npm/v/@webdecoy/fastify.svg)](https://www.npmjs.com/package/@webdecoy/fastify) | Fastify plugin | +| [@webdecoy/nextjs](https://www.npmjs.com/package/@webdecoy/nextjs) | [![npm](https://img.shields.io/npm/v/@webdecoy/nextjs.svg)](https://www.npmjs.com/package/@webdecoy/nextjs) | Next.js middleware | +| [@webdecoy/hono](https://www.npmjs.com/package/@webdecoy/hono) | [![npm](https://img.shields.io/npm/v/@webdecoy/hono.svg)](https://www.npmjs.com/package/@webdecoy/hono) | Hono middleware (Workers, Bun, Deno) | +| [@webdecoy/client](https://www.npmjs.com/package/@webdecoy/client) | [![npm](https://img.shields.io/npm/v/@webdecoy/client.svg)](https://www.npmjs.com/package/@webdecoy/client) | Browser-side signal collector | ## Browser session clearance @@ -380,7 +361,7 @@ enforces it, from one object — so they cannot drift: import { WebDecoy, botPolicy } from '@webdecoy/node'; const policy = botPolicy({ - deny: ['training_crawler'], // or 'ai', a category, or an agent name + deny: ['training_crawler'], // or 'ai', a category, or an agent name allow: ['perplexitybot'], }); @@ -394,7 +375,7 @@ policy you believe is in force and is not. The reverse — enforcing against a crawler the published file invites — is how a site quietly leaves a search index. `robots.txt` is a request, honoured at the crawler's discretion. The registry -records whether each operator _documents_ honouring it, and the generated file +records whether each operator *documents* honouring it, and the generated file names the ones in your deny set that do not: ``` @@ -419,14 +400,12 @@ import { MemoryClientSignalStore, clientSignals, tripwire } from '@webdecoy/node const signalStore = new MemoryClientSignalStore(); app.use(webdecoyCaptcha({ secret: process.env.WEBDECOY_SECRET, signalStore })); -app.use( - webdecoy({ - rules: [ - tripwire(), // intent — deterministic - clientSignals({ store: signalStore, dryRun: true }), // interaction — probabilistic - ], - }) -); +app.use(webdecoy({ + rules: [ + tripwire(), // intent — deterministic + clientSignals({ store: signalStore, dryRun: true }), // interaction — probabilistic + ], +})); ``` `@webdecoy/client` collects behavioural, environmental and form signals in the @@ -447,8 +426,8 @@ what they send: ```typescript attackSignatures({ - inspect: ['path', 'query'], // default; 'body' and 'headers' are opt-in - exclude: ['traversal'], // signature ids + inspect: ['path', 'query'], // default; 'body' and 'headers' are opt-in + exclude: ['traversal'], // signature ids dryRun: false, }); ``` @@ -457,7 +436,7 @@ attackSignatures({ breadth is bought with false positives. This is a small curated set — SQL injection, XSS, traversal, command injection, `${jndi:` — chosen because each has no innocent reading in a path or query string. It composes with the deterministic -signals: a request carrying an injection payload _and_ walking into a tripwire is +signals: a request carrying an injection payload *and* walking into a tripwire is much stronger evidence than either alone. Bodies and headers are off by default, because a CMS saving an article and a URL @@ -505,18 +484,16 @@ The synchronous `evaluateRules()` cannot consume a networked store, and reports Rate limits, IP enrichment and every detection we record are keyed on the caller's address, so it matters that the address is real. `X-Forwarded-For` is written by the client for the first hop — the leftmost value in it is whatever the caller decided to send — so the middleware believes it only as far as you say it should, counted from the **right** of the chain, which is the end your own infrastructure wrote. ```typescript -app.use( - webdecoy({ - trustProxy: 1, // one proxy in front of this app - }) -); +app.use(webdecoy({ + trustProxy: 1, // one proxy in front of this app +})); ``` -| `trustProxy` | Meaning | -| ------------------- | ----------------------------------------------------------------------------------------------------------------- | -| `false` | Read no forwarding headers. The socket address is the client. | -| `1`, `2`, … | The number of proxies between the client and this app. | -| `'cloudflare'` | Use `CF-Connecting-IP`. Only safe if the origin is unreachable except through Cloudflare. | +| `trustProxy` | Meaning | +|---|---| +| `false` | Read no forwarding headers. The socket address is the client. | +| `1`, `2`, … | The number of proxies between the client and this app. | +| `'cloudflare'` | Use `CF-Connecting-IP`. Only safe if the origin is unreachable except through Cloudflare. | | `['10.0.0.0/8', …]` | CIDRs of proxies you run. The chain is walked right to left and the first address that isn't yours is the client. | **Defaults.** Express and Fastify defer to `req.ip` / `request.ip`, which already honour the framework's own trust-proxy setting and otherwise resolve to the socket address — so if you've configured `app.set('trust proxy', …)` there's nothing to do here. Next.js middleware has no socket to fall back on, so it defaults to `1` trusted hop, which is correct on Vercel and on any single-proxy deployment. @@ -529,13 +506,13 @@ The same option is accepted by `webdecoyCaptcha()` / `createCaptchaHandler()`, a ```typescript const wd = new WebDecoy({ - apiKey: process.env.WEBDECOY_API_KEY, // optional — only for platform features - apiUrl: 'https://in.webdecoy.com', // optional (this is the default) - enableTLSFingerprinting: true, // optional (default: true) - threatScoreThreshold: 70, // optional, 0–100 (default: 80) - timeout: 5000, // optional, ms (default: 5000) - debug: false, // optional (default: false) - tlsRejectUnauthorized: true, // optional (default: true) + apiKey: process.env.WEBDECOY_API_KEY, // optional — only for platform features + apiUrl: 'https://in.webdecoy.com', // optional (this is the default) + enableTLSFingerprinting: true, // optional (default: true) + threatScoreThreshold: 70, // optional, 0–100 (default: 80) + timeout: 5000, // optional, ms (default: 5000) + debug: false, // optional (default: false) + tlsRejectUnauthorized: true, // optional (default: true) }); ``` @@ -560,29 +537,29 @@ Full analysis of a request. Returns a typed decision: ```typescript const d = await wd.protect(metadata); -d.conclusion; // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' -d.allowed; // true for ALLOW and ERROR (fail open) -d.id; // 'dec_…', correlates with the dashboard -d.isDenied(); // narrowing helpers -d.deniedBy('tripwire'); // which rule, without string-matching -d.results; // every rule, in order, and what it concluded -d.detection; // the service's response, as before -d.edge; // what the edge validator said +d.conclusion // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' +d.allowed // true for ALLOW and ERROR (fail open) +d.id // 'dec_…', correlates with the dashboard +d.isDenied() // narrowing helpers +d.deniedBy('tripwire') // which rule, without string-matching +d.results // every rule, in order, and what it concluded +d.detection // the service's response, as before +d.edge // what the edge validator said ``` `results` is the part worth knowing about. Every configured rule appears, with a `state`: -| `state` | Meaning | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `RUN` | Evaluated, and its conclusion counts. | -| `DRY_RUN` | Evaluated; conclusion recorded but not enforced. | +| `state` | Meaning | +|---|---| +| `RUN` | Evaluated, and its conclusion counts. | +| `DRY_RUN` | Evaluated; conclusion recorded but not enforced. | | `NOT_RUN` | Could not evaluate — a signal it needs was absent (a `filter()` with no IP enrichment, a `webBotAuth()` on a request with no host). | -| `CACHED` | Not evaluated; a prior decision for this key was reused. | +| `CACHED` | Not evaluated; a prior decision for this key was reused. | `NOT_RUN` is the one that used to be invisible: such a rule reported ALLOW, which reads as "checked and fine" rather than "never checked". A dry-run rule that -matched reports `conclusion: 'DENY'` with `state: 'DRY_RUN'` — what it _would_ +matched reports `conclusion: 'DENY'` with `state: 'DRY_RUN'` — what it *would* have done is the reason you turned it on. `ERROR` is not a synonym for `DENY`. It means no verdict was reached, and the @@ -637,7 +614,7 @@ Pass any object with `debug`/`info`/`warn`/`error`: ```typescript new WebDecoy({ logger: myLogger }); -new WebDecoy({ logger: fromPino(pino()) }); // pino's argument order is reversed +new WebDecoy({ logger: fromPino(pino()) }); // pino's argument order is reversed ``` `fromPino()` exists because passing a pino instance directly type-checks and then diff --git a/packages/webdecoy/README.md b/packages/webdecoy/README.md index 51f4384..27a64ab 100644 --- a/packages/webdecoy/README.md +++ b/packages/webdecoy/README.md @@ -17,13 +17,13 @@ Full documentation: [docs.webdecoy.com/sdk-plugins/node-sdk](https://docs.webdec Most apps should install a framework adapter alongside this package. The adapters handle request mapping, client IP, monitor mode and honeytoken injection for you. Install `@webdecoy/node` too: it is where `tripwire()`, `rateLimit()` and the other rules are imported from. -| Framework | Install | -| --------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| Express | `npm install @webdecoy/express @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/express)) | -| Fastify | `npm install @webdecoy/fastify @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/fastify)) | -| Next.js | `npm install @webdecoy/nextjs @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/nextjs)) | -| Hono (Workers, Bun, Deno, Node) | `npm install @webdecoy/hono @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/hono)) | -| Any other server or fetch runtime | `npm install @webdecoy/node` (this page) | +| Framework | Install | +|---|---| +| Express | `npm install @webdecoy/express @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/express)) | +| Fastify | `npm install @webdecoy/fastify @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/fastify)) | +| Next.js | `npm install @webdecoy/nextjs @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/nextjs)) | +| Hono (Workers, Bun, Deno, Node) | `npm install @webdecoy/hono @webdecoy/node` ([README](https://www.npmjs.com/package/@webdecoy/hono)) | +| Any other server or fetch runtime | `npm install @webdecoy/node` (this page) | ## Installation @@ -39,25 +39,23 @@ import { WebDecoy } from '@webdecoy/node'; const wd = new WebDecoy({ apiKey: process.env.WEBDECOY_API_KEY }); -http - .createServer(async (req, res) => { - const decision = await wd.protect({ - method: req.method, - path: new URL(req.url, 'http://localhost').pathname, - ip: req.socket.remoteAddress ?? '', - user_agent: req.headers['user-agent'], - headers: Object.fromEntries( - Object.entries(req.headers).map(([name, value]) => [name, String(value)]) - ), - timestamp: Date.now(), - }); - - // protect() returns a decision and blocks nothing itself. - // Log decision.conclusion ('ALLOW', 'DENY', 'CHALLENGE' or 'ERROR') first; - // refuse with a 403 when decision.allowed is false only once you are ready. - res.end('ok'); - }) - .listen(3000); +http.createServer(async (req, res) => { + const decision = await wd.protect({ + method: req.method, + path: new URL(req.url, 'http://localhost').pathname, + ip: req.socket.remoteAddress ?? '', + user_agent: req.headers['user-agent'], + headers: Object.fromEntries( + Object.entries(req.headers).map(([name, value]) => [name, String(value)]) + ), + timestamp: Date.now(), + }); + + // protect() returns a decision and blocks nothing itself. + // Log decision.conclusion ('ALLOW', 'DENY', 'CHALLENGE' or 'ERROR') first; + // refuse with a 403 when decision.allowed is false only once you are ready. + res.end('ok'); +}).listen(3000); ``` Behind a proxy, `req.socket.remoteAddress` is the proxy. Use `resolveClientIp()` from this package to read the real client address (see [Client IP behind a proxy](#client-ip-behind-a-proxy)). @@ -70,23 +68,6 @@ Behind a proxy, `req.socket.remoteAddress` is the proxy. Use `resolveClientIp()` To get a key: sign up at [app.webdecoy.com](https://app.webdecoy.com), add your site, then create a key on the **API Keys** page. Keys start with `sk_live_` (production) or `sk_test_` (testing); any other prefix throws when the SDK is constructed. Keep the key on the server and out of committed files. -### Confirm an SSRF callback - -```ts -const canary = await wd.createSSRFCanary({ - routeTemplate: '/api/fetch/:id', - test: true, -}); -await wd.reportSSRFInitiation(canary); -await applicationFetch(canary.callbackUrl); -``` - -The marker is property-scoped, single-use, and expires after 15 minutes. The -SDK reports only its marker ID and route template on the initiation edge. -WebDecoy never fetches a supplied URL; a finding is created only after the -matching callback arrives. Use `test: true` for controlled validation so it is -kept out of production threat metrics. - ### Monitor first `protect()` only returns a decision. It never writes a response, so nothing is blocked until your code acts on `decision.allowed`. The framework adapters and `createFetchGuard()` follow the same rule: they start in **monitor mode** (`mode: 'monitor'`), record the decision and serve every request. Set `mode: 'enforce'` only after you have reviewed what would have been blocked. @@ -98,26 +79,26 @@ kept out of production threat metrics. ```ts const decision = await wd.protect(metadata); -decision.conclusion; // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' -decision.allowed; // true for ALLOW and ERROR (fails open), false for DENY and CHALLENGE -decision.id; // 'dec_...' -decision.isDenied(); // also isAllowed(), isChallenged(), isErrored() -decision.deniedBy('tripwire'); // whether a named rule denied the request -decision.results; // every configured rule, its state and its conclusion -decision.reason; // the deciding reason, when there is one -decision.detection; // { decision, confidence, threat_level, bot_detected, bot_type?, detection_id, rule_enforced } -decision.error; // set when conclusion is 'ERROR' -decision.edge; // what a WebDecoy edge validator said about this request, if one fronted it +decision.conclusion // 'ALLOW' | 'DENY' | 'CHALLENGE' | 'ERROR' +decision.allowed // true for ALLOW and ERROR (fails open), false for DENY and CHALLENGE +decision.id // 'dec_...' +decision.isDenied() // also isAllowed(), isChallenged(), isErrored() +decision.deniedBy('tripwire') // whether a named rule denied the request +decision.results // every configured rule, its state and its conclusion +decision.reason // the deciding reason, when there is one +decision.detection // { decision, confidence, threat_level, bot_detected, bot_type?, detection_id, rule_enforced } +decision.error // set when conclusion is 'ERROR' +decision.edge // what a WebDecoy edge validator said about this request, if one fronted it ``` Each entry in `results` has a `state`: -| `state` | Meaning | -| --------- | -------------------------------------------------------------------------------------------------------------- | -| `RUN` | Evaluated, and its conclusion counts. | -| `DRY_RUN` | Evaluated; the conclusion is recorded but not enforced. | +| `state` | Meaning | +|---|---| +| `RUN` | Evaluated, and its conclusion counts. | +| `DRY_RUN` | Evaluated; the conclusion is recorded but not enforced. | | `NOT_RUN` | Could not evaluate because a signal it needs was absent (for example a `filter()` rule with no IP enrichment). | -| `CACHED` | Not evaluated; a prior decision for this key was reused. | +| `CACHED` | Not evaluated; a prior decision for this key was reused. | `ERROR` is not a denial. It means no verdict was reached (for example WebDecoy could not be reached, or the request had no IP), and `allowed` is `true`. @@ -133,21 +114,21 @@ import { WebDecoy, tripwire, rateLimit, filter } from '@webdecoy/node'; const wd = new WebDecoy({ rules: [ tripwire({ paths: ['/admin-backup.zip'] }), // plus built-in paths such as /.env - rateLimit({ max: 100, window: 60 }), // 100 requests per 60 s per IP + rateLimit({ max: 100, window: 60 }), // 100 requests per 60 s per IP filter({ expression: 'ip.tor or ip.vpn' }), // needs an apiKey (IP enrichment) ], }); ``` -| Rule | What it does | Needs an API key? | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | -| `tripwire({ paths?, prefixes?, patterns?, includeDefaults?, action?, dryRun? })` | Matches requests for decoy and scanner-bait paths. | No | -| `honeytoken()` | Returns `{ path, linkHtml }`: a hidden decoy link and the path to arm with `tripwire({ paths: [path] })`. | No | -| `rateLimit({ max, window, algorithm?, keyBy?, store?, action?, dryRun? })` | Fixed or sliding window, keyed by IP by default. In-memory unless you pass a shared `store` (for example `upstashRateLimitStore()`). | No | -| `attackSignatures({ inspect?, exclude?, action?, dryRun? })` | Denies requests carrying unambiguous injection payloads. | No | -| `webBotAuth()` | Verifies Web Bot Auth (RFC 9421) agent signatures and denies impersonators of known agents. | No | -| `botPolicy({ deny, allow })` | One crawler policy that produces both your `robots.txt` and the rule that enforces it. | No | -| `filter({ expression, action?, dryRun? })` | Expressions over IP reputation and geo, such as `ip.tor` or `ip.country in ["CN", "RU"]`. | Yes | +| Rule | What it does | Needs an API key? | +|---|---|---| +| `tripwire({ paths?, prefixes?, patterns?, includeDefaults?, action?, dryRun? })` | Matches requests for decoy and scanner-bait paths. | No | +| `honeytoken()` | Returns `{ path, linkHtml }`: a hidden decoy link and the path to arm with `tripwire({ paths: [path] })`. | No | +| `rateLimit({ max, window, algorithm?, keyBy?, store?, action?, dryRun? })` | Fixed or sliding window, keyed by IP by default. In-memory unless you pass a shared `store` (for example `upstashRateLimitStore()`). | No | +| `attackSignatures({ inspect?, exclude?, action?, dryRun? })` | Denies requests carrying unambiguous injection payloads. | No | +| `webBotAuth()` | Verifies Web Bot Auth (RFC 9421) agent signatures and denies impersonators of known agents. | No | +| `botPolicy({ deny, allow })` | One crawler policy that produces both your `robots.txt` and the rule that enforces it. | No | +| `filter({ expression, action?, dryRun? })` | Expressions over IP reputation and geo, such as `ip.tor` or `ip.country in ["CN", "RU"]`. | Yes | A tripwire match is evidence, not proof of intent: link prefetchers, preview bots and your own security scanners can request a hidden or scanner-bait path. Use `dryRun: true` on a rule to observe it before enforcing. @@ -185,11 +166,11 @@ export const config = { }; ``` -| Variable | Turns on | Secret? | -| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------- | -| `WEBDECOY_API_KEY` | Detection: bots, tripwire hits and agents the bot registry names are reported to your dashboard. From the **API Keys** page. | Yes | -| `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` | The clearance gate, with the sensor key. From **Enforcement, Setup**. | No | -| `WEBDECOY_SENSOR_KEY` | The clearance gate. From **Enforcement, Setup**. | Yes | +| Variable | Turns on | Secret? | +|---|---|---| +| `WEBDECOY_API_KEY` | Detection: bots, tripwire hits and agents the bot registry names are reported to your dashboard. From the **API Keys** page. | Yes | +| `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID` | The clearance gate, with the sensor key. From **Enforcement, Setup**. | No | +| `WEBDECOY_SENSOR_KEY` | The clearance gate. From **Enforcement, Setup**. | Yes | Either half works without the other; with neither, every request passes. Detection starts in monitor mode (the request is served and the verdict rides on the request as `x-webdecoy-decision`, `x-webdecoy-detection-id` and `x-webdecoy-would-block`), and the gate follows the site's mode in WebDecoy, monitor until you switch it. Every failure, WebDecoy unreachable included, lets the request through. Without `WEBDECOY_API_KEY` the middleware is the clearance gate alone, exactly as before. @@ -205,12 +186,12 @@ curl -A "WebDecoy-Test/1.0" https://your-site.vercel.app/ The SDK reads only these, and only in the features named: -| Variable | Read by | -| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `WEBDECOY_API_KEY` | The Vercel middleware (`@webdecoy/node/vercel`, `createDetectAndGate()`), when `apiKey` is not passed. | +| Variable | Read by | +|---|---| +| `WEBDECOY_API_KEY` | The Vercel middleware (`@webdecoy/node/vercel`, `createDetectAndGate()`), when `apiKey` is not passed. | | `WEBDECOY_SITE_KEY`, `WEBDECOY_SCANNER_ID`, `WEBDECOY_SENSOR_KEY` | The clearance gate (`@webdecoy/node/vercel`, `createClearanceGate()`), when the matching option is not passed. | -| `WEBDECOY_INGEST` | The clearance gate, to override its ingest endpoint. Optional. | -| `NODE_ENV` | The self-hosted captcha: with `production`, a missing or default `secret` throws. | +| `WEBDECOY_INGEST` | The clearance gate, to override its ingest endpoint. Optional. | +| `NODE_ENV` | The self-hosted captcha: with `production`, a missing or default `secret` throws. | Everywhere else `WEBDECOY_API_KEY` is a naming convention used in these docs: pass its value as `apiKey`. @@ -219,14 +200,14 @@ Everywhere else `WEBDECOY_API_KEY` is a naming convention used in these docs: pa ```ts const wd = new WebDecoy({ apiKey: process.env.WEBDECOY_API_KEY, // optional; without it, local rules only - rules: [tripwire()], // optional; default [tripwire()], [] to opt out - apiUrl: 'https://in.webdecoy.com', // optional (default shown) - threatScoreThreshold: 80, // optional, 0-100 (default 80) - timeout: 5000, // optional, ms (default 5000) - enableTLSFingerprinting: true, // optional (default true) - tlsRejectUnauthorized: true, // optional (default true) - countAIReferrals: true, // optional (default true; aggregate counts, only with an apiKey) - debug: false, // optional (default false) + rules: [tripwire()], // optional; default [tripwire()], [] to opt out + apiUrl: 'https://in.webdecoy.com', // optional (default shown) + threatScoreThreshold: 80, // optional, 0-100 (default 80) + timeout: 5000, // optional, ms (default 5000) + enableTLSFingerprinting: true, // optional (default true) + tlsRejectUnauthorized: true, // optional (default true) + countAIReferrals: true, // optional (default true; aggregate counts, only with an apiKey) + debug: false, // optional (default false) }); ``` diff --git a/packages/webdecoy/src/client.ts b/packages/webdecoy/src/client.ts index a1e0cef..92f01b8 100644 --- a/packages/webdecoy/src/client.ts +++ b/packages/webdecoy/src/client.ts @@ -8,13 +8,7 @@ */ import type { AIReferralBatch } from './referrals/referral-counter'; -import { - SDKDetectionRequest, - SDKDetectionResponse, - SSRFCanary, - SSRFCanaryOptions, - SSRFInitiationReceipt, -} from './types'; +import { SDKDetectionRequest, SDKDetectionResponse } from './types'; import { reportableHeaders } from './report-headers'; import type { ViolationEvent, IPEnrichmentData } from './rules/types'; @@ -84,7 +78,7 @@ export class WebDecoyClient { if (config.tlsRejectUnauthorized === false && config.debug) { console.warn( '[WebDecoy] tlsRejectUnauthorized=false is not supported by the fetch transport and is ignored; ' + - 'for local self-signed certs, trust your CA via NODE_EXTRA_CA_CERTS=/path/to/ca.pem.' + 'for local self-signed certs, trust your CA via NODE_EXTRA_CA_CERTS=/path/to/ca.pem.', ); } } @@ -114,11 +108,7 @@ export class WebDecoyClient { this.pausedUntil = Date.now() + ms; } - private async request( - method: 'GET' | 'POST', - path: string, - body?: unknown - ): Promise> { + private async request(method: 'GET' | 'POST', path: string, body?: unknown): Promise> { if (!this.isAvailable()) { throw new WebDecoyUnavailableError(this.pausedUntil); } @@ -186,13 +176,10 @@ export class WebDecoyClient { response = await this.request( 'POST', '/api/v1/sdk/detect', - toWireDetectionRequest(request) + toWireDetectionRequest(request), ); } catch (error) { - if ( - error instanceof Error && - (error.name === 'AbortError' || error.name === 'TimeoutError') - ) { + if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) { throw new Error('Request timeout. The Web Decoy service did not respond in time.'); } if (error instanceof TypeError) { @@ -220,74 +207,6 @@ export class WebDecoyClient { return response.data as SDKDetectionResponse; } - async createSSRFCanary(options: SSRFCanaryOptions): Promise { - const response = await this.request< - { - marker_id: string; - callback_url: string; - route_template: string; - expires_at: string; - test: boolean; - } & ApiErrorBody - >('POST', '/api/v1/sdk/ssrf/markers', { - property_id: options.propertyId, - route_template: options.routeTemplate, - test: options.test === true, - }); - this.requireSuccess(response); - const data = response.data!; - if (!data.marker_id || !data.callback_url || !data.route_template || !data.expires_at) { - throw new Error('WebDecoy returned an invalid SSRF canary'); - } - return { - markerId: data.marker_id, - callbackUrl: data.callback_url, - routeTemplate: data.route_template, - expiresAt: data.expires_at, - test: data.test === true, - }; - } - - async reportSSRFInitiation( - canary: Pick - ): Promise { - const response = await this.request< - { - detection_id: string; - marker_id: string; - test: boolean; - } & ApiErrorBody - >('POST', '/api/v1/sdk/ssrf/initiate', { - marker_id: canary.markerId, - route_template: canary.routeTemplate, - }); - this.requireSuccess(response); - const data = response.data!; - if (!data.detection_id || !data.marker_id) { - throw new Error('WebDecoy returned an invalid SSRF initiation receipt'); - } - return { detectionId: data.detection_id, markerId: data.marker_id, test: data.test === true }; - } - - private requireSuccess(response: ApiResponse): void { - if (response.status === 401) { - throw new Error('Invalid API key. Please check your Web Decoy configuration.'); - } - if (response.status === 429) { - throw new Error('Rate limit exceeded. Please try again later.'); - } - if (response.status >= 400) { - throw new Error( - response.data?.error || - response.data?.message || - `API request failed: HTTP ${response.status}` - ); - } - if (!response.data) { - throw new Error('WebDecoy returned an empty response'); - } - } - /** * Send violation events to the ingest service */ @@ -328,7 +247,7 @@ export class WebDecoyClient { try { const response = await this.request( 'GET', - `/api/v1/sdk/ip/${encodeURIComponent(ip)}/enrichment` + `/api/v1/sdk/ip/${encodeURIComponent(ip)}/enrichment`, ); if (response.status >= 400) return null; return response.data ?? null; diff --git a/packages/webdecoy/src/index.ts b/packages/webdecoy/src/index.ts index 714a5aa..9eac8cc 100644 --- a/packages/webdecoy/src/index.ts +++ b/packages/webdecoy/src/index.ts @@ -35,9 +35,6 @@ export type { SDKDetectionResponse, ProtectResult, ProtectOptions, - SSRFCanary, - SSRFCanaryOptions, - SSRFInitiationReceipt, } from './types'; // The decision `protect()` returns. Exported as a value because the class diff --git a/packages/webdecoy/src/sdk.ts b/packages/webdecoy/src/sdk.ts index 3f30bf7..3f032fd 100644 --- a/packages/webdecoy/src/sdk.ts +++ b/packages/webdecoy/src/sdk.ts @@ -30,9 +30,6 @@ import { ProtectOptions, SDKDetectionRequest, SDKDetectionResponse, - SSRFCanary, - SSRFCanaryOptions, - SSRFInitiationReceipt, } from './types'; export class WebDecoy { @@ -45,11 +42,7 @@ export class WebDecoy { }; private ruleEngine: RuleEngine | null; private referralCounter: AIReferralCounter | null = null; - private violationReporter: { - report(violations: ViolationEvent[]): void; - flush(): Promise; - destroy(): Promise; - } | null = null; + private violationReporter: { report(violations: ViolationEvent[]): void; flush(): Promise; destroy(): Promise } | null = null; private ipEnrichmentClient: IPEnrichmentClient | null = null; private _hasFilterRules = false; private _hasAgentRules = false; @@ -331,27 +324,6 @@ export class WebDecoy { return this.getAgentVerifier().verify(request); } - /** Mint a signed, single-use callback marker for an SSRF test or observation. */ - async createSSRFCanary(options: SSRFCanaryOptions): Promise { - if (!this.client) { - throw new Error('An apiKey is required to create an SSRF canary'); - } - return this.client.createSSRFCanary(options); - } - - /** - * Report the initiating server request immediately before the application's - * ordinary fetch. Only the marker ID and route template are sent. - */ - async reportSSRFInitiation( - canary: Pick - ): Promise { - if (!this.client) { - throw new Error('An apiKey is required to report an SSRF initiation'); - } - return this.client.reportSSRFInitiation(canary); - } - /** * Whether this SDK instance has filter rules that need async enrichment */ @@ -375,7 +347,10 @@ export class WebDecoy { * @returns The decision — `conclusion`, every rule's outcome, and the * narrowing helpers. Satisfies `ProtectResult`. */ - async protect(metadata: RequestMetadata, options: ProtectOptions = {}): Promise { + async protect( + metadata: RequestMetadata, + options: ProtectOptions = {} + ): Promise { // The edge verdict is attached here rather than at each return inside // decide(), which has six of them including two fail-open paths. It is // information ABOUT the request, not a product of the decision, so it must be @@ -401,7 +376,11 @@ export class WebDecoy { } // A detection id that is not the decision id means the verdict came back // from ingest rather than being settled locally. - setAttribute(span, 'webdecoy.remote', decision.detection.detection_id !== decision.id); + setAttribute( + span, + 'webdecoy.remote', + decision.detection.detection_id !== decision.id, + ); if (decision.error) { setAttribute(span, 'webdecoy.error', decision.error); } @@ -416,7 +395,10 @@ export class WebDecoy { } } - private async decide(metadata: RequestMetadata, options: ProtectOptions = {}): Promise { + private async decide( + metadata: RequestMetadata, + options: ProtectOptions = {} + ): Promise { // Declared out here so the catch below can stamp the same id and key onto // an ERROR decision. An error is still a decision about a caller. const id = newDecisionId(); @@ -452,7 +434,9 @@ export class WebDecoy { : this.buildContext(metadata); key = context.key ?? key; const agentVerdict: AgentVerdict | undefined = context.agent; - const ruleResult: RuleEngineResult | null = this.ruleEngine ? this.runRules(context) : null; + const ruleResult: RuleEngineResult | null = this.ruleEngine + ? this.runRules(context) + : null; // Rules denied or throttled: decided locally, no API call. Not cached — // a rate limiter has to see every request to advance its window, and a @@ -577,9 +561,7 @@ export class WebDecoy { const decision = new Decision({ conclusion, - reason: allowed - ? undefined - : `Threat score ${detection.confidence} (threshold ${threshold})`, + reason: allowed ? undefined : `Threat score ${detection.confidence} (threshold ${threshold})`, detection, id, results: ruleResult?.results ?? [], @@ -600,10 +582,7 @@ export class WebDecoy { // While the client is paused after an outage, every request lands here. // The failure that started the pause was already logged as an error; // logging each paused request too would flood the operator's logs. - const log = - error instanceof WebDecoyUnavailableError - ? this.log.debug.bind(this.log) - : this.log.error.bind(this.log); + const log = error instanceof WebDecoyUnavailableError ? this.log.debug.bind(this.log) : this.log.error.bind(this.log); log('Protection error', { error: error instanceof Error ? error.message : String(error), }); @@ -715,11 +694,7 @@ export class WebDecoy { * Attach a violation reporter for sending violations to the backend. * Called internally when apiKey is present and rules are configured. */ - setViolationReporter(reporter: { - report(violations: ViolationEvent[]): void; - flush(): Promise; - destroy(): Promise; - }): void { + setViolationReporter(reporter: { report(violations: ViolationEvent[]): void; flush(): Promise; destroy(): Promise }): void { this.violationReporter = reporter; } @@ -762,7 +737,10 @@ export class WebDecoy { function agentInputFromMetadata(metadata: RequestMetadata): AgentRequestInput | null { const headers = metadata.headers || {}; const host = - headers['host'] || headers[':authority'] || headers['x-forwarded-host'] || headers['Host']; + headers['host'] || + headers[':authority'] || + headers['x-forwarded-host'] || + headers['Host']; if (!host) return null; const proto = headers['x-forwarded-proto'] || headers['X-Forwarded-Proto']; diff --git a/packages/webdecoy/src/ssrf-canary.test.ts b/packages/webdecoy/src/ssrf-canary.test.ts deleted file mode 100644 index c5af4ed..0000000 --- a/packages/webdecoy/src/ssrf-canary.test.ts +++ /dev/null @@ -1,64 +0,0 @@ -import { WebDecoy } from './sdk'; - -describe('SSRF canary correlation', () => { - const realFetch = global.fetch; - - afterEach(() => { - global.fetch = realFetch; - }); - - it('reports only the marker ID and route template on the initiation edge', async () => { - const calls: Array<{ url: string; body: Record }> = []; - global.fetch = jest.fn(async (url: unknown, init: RequestInit) => { - const body = JSON.parse(String(init.body)) as Record; - calls.push({ url: String(url), body }); - if (String(url).endsWith('/ssrf/markers')) { - return new Response( - JSON.stringify({ - marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', - callback_url: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', - route_template: '/api/fetch/:id', - expires_at: '2026-11-15T21:00:00Z', - test: true, - token: 'must-not-be-returned-by-the-sdk', - }), - { status: 201 } - ); - } - return new Response( - JSON.stringify({ - detection_id: 'c18348c8-9f6b-43e9-b993-86ca15db257f', - marker_id: body.marker_id, - test: true, - }), - { status: 201 } - ); - }) as jest.Mock; - - const sdk = new WebDecoy({ apiKey: 'sk_test_ssrf', apiUrl: 'https://ingest.example' }); - const canary = await sdk.createSSRFCanary({ routeTemplate: '/api/fetch/:id', test: true }); - const receipt = await sdk.reportSSRFInitiation(canary); - - expect(canary).toEqual({ - markerId: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', - callbackUrl: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', - routeTemplate: '/api/fetch/:id', - expiresAt: '2026-11-15T21:00:00Z', - test: true, - }); - expect(receipt.detectionId).toBe('c18348c8-9f6b-43e9-b993-86ca15db257f'); - expect(calls[1]).toEqual({ - url: 'https://ingest.example/api/v1/sdk/ssrf/initiate', - body: { - marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', - route_template: '/api/fetch/:id', - }, - }); - expect(JSON.stringify(calls[1].body)).not.toContain('opaque-token'); - }); - - it('requires a hosted API key', async () => { - const sdk = new WebDecoy(); - await expect(sdk.createSSRFCanary({ routeTemplate: '/fetch' })).rejects.toThrow(/apiKey/); - }); -}); diff --git a/packages/webdecoy/src/types.ts b/packages/webdecoy/src/types.ts index 5f534eb..5d68dbb 100644 --- a/packages/webdecoy/src/types.ts +++ b/packages/webdecoy/src/types.ts @@ -139,31 +139,6 @@ export interface WebDecoyConfig { tracer?: Tracer; } -/** Options for one short-lived, property-scoped SSRF canary. */ -export interface SSRFCanaryOptions { - /** The application route that will perform the server-side fetch. */ - routeTemplate: string; - /** Required only when an organization-wide API key is used. */ - propertyId?: string; - /** Keep a controlled validation out of production threat metrics. */ - test?: boolean; -} - -/** A callback marker. Put callbackUrl in the controlled outbound request. */ -export interface SSRFCanary { - markerId: string; - callbackUrl: string; - routeTemplate: string; - expiresAt: string; - test: boolean; -} - -export interface SSRFInitiationReceipt { - detectionId: string; - markerId: string; - test: boolean; -} - /** * TLS connection information from the request */ From 2ed92cb61783e3ec8ef1f476764f22ab4ab94169 Mon Sep 17 00:00:00 2001 From: Chris Portscheller Date: Sun, 15 Nov 2026 20:21:25 -0600 Subject: [PATCH 3/3] feat(node): add SSRF canary correlation API --- README.md | 21 +++++++ packages/webdecoy/README.md | 17 ++++++ packages/webdecoy/src/client.ts | 72 ++++++++++++++++++++++- packages/webdecoy/src/index.ts | 3 + packages/webdecoy/src/sdk.ts | 24 ++++++++ packages/webdecoy/src/ssrf-canary.test.ts | 58 ++++++++++++++++++ packages/webdecoy/src/types.ts | 25 ++++++++ 7 files changed, 219 insertions(+), 1 deletion(-) create mode 100644 packages/webdecoy/src/ssrf-canary.test.ts diff --git a/README.md b/README.md index 06771f2..37fb9a0 100644 --- a/README.md +++ b/README.md @@ -317,6 +317,27 @@ if (!result.allowed) { } ``` +### Confirm an SSRF callback + +For a route that intentionally performs a server-side fetch, mint a short-lived +canary and report its initiation immediately before the fetch: + +```typescript +const canary = await wd.createSSRFCanary({ + routeTemplate: '/api/fetch/:id', + test: true, // controlled validation; excluded from production threat metrics +}); + +await wd.reportSSRFInitiation(canary); +await applicationFetch(canary.callbackUrl); +``` + +Use the callback URL only as the controlled destination for the fetch you are +testing. WebDecoy never fetches a supplied URL. A confirmed finding requires +both the trusted initiation and the matching single-use callback within 15 +minutes; either edge alone is not confirmed SSRF. Open the callback detection +in WebDecoy to see its **Correlated activity** evidence. + ### Getting an API key 1. Sign up at [app.webdecoy.com](https://app.webdecoy.com) diff --git a/packages/webdecoy/README.md b/packages/webdecoy/README.md index 27a64ab..e74fca9 100644 --- a/packages/webdecoy/README.md +++ b/packages/webdecoy/README.md @@ -68,6 +68,23 @@ Behind a proxy, `req.socket.remoteAddress` is the proxy. Use `resolveClientIp()` To get a key: sign up at [app.webdecoy.com](https://app.webdecoy.com), add your site, then create a key on the **API Keys** page. Keys start with `sk_live_` (production) or `sk_test_` (testing); any other prefix throws when the SDK is constructed. Keep the key on the server and out of committed files. +### Confirm an SSRF callback + +```ts +const canary = await wd.createSSRFCanary({ + routeTemplate: '/api/fetch/:id', + test: true, +}); +await wd.reportSSRFInitiation(canary); +await applicationFetch(canary.callbackUrl); +``` + +The marker is property-scoped, single-use, and expires after 15 minutes. The +SDK reports only its marker ID and route template on the initiation edge. +WebDecoy never fetches a supplied URL; a finding is created only after the +matching callback arrives. Use `test: true` for controlled validation so it is +kept out of production threat metrics. + ### Monitor first `protect()` only returns a decision. It never writes a response, so nothing is blocked until your code acts on `decision.allowed`. The framework adapters and `createFetchGuard()` follow the same rule: they start in **monitor mode** (`mode: 'monitor'`), record the decision and serve every request. Set `mode: 'enforce'` only after you have reviewed what would have been blocked. diff --git a/packages/webdecoy/src/client.ts b/packages/webdecoy/src/client.ts index 92f01b8..5df3d58 100644 --- a/packages/webdecoy/src/client.ts +++ b/packages/webdecoy/src/client.ts @@ -8,7 +8,13 @@ */ import type { AIReferralBatch } from './referrals/referral-counter'; -import { SDKDetectionRequest, SDKDetectionResponse } from './types'; +import { + SDKDetectionRequest, + SDKDetectionResponse, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, +} from './types'; import { reportableHeaders } from './report-headers'; import type { ViolationEvent, IPEnrichmentData } from './rules/types'; @@ -207,6 +213,70 @@ export class WebDecoyClient { return response.data as SDKDetectionResponse; } + async createSSRFCanary(options: SSRFCanaryOptions): Promise { + const response = await this.request<{ + marker_id: string; + callback_url: string; + route_template: string; + expires_at: string; + test: boolean; + } & ApiErrorBody>('POST', '/api/v1/sdk/ssrf/markers', { + property_id: options.propertyId, + route_template: options.routeTemplate, + test: options.test === true, + }); + this.requireSuccess(response); + const data = response.data!; + if (!data.marker_id || !data.callback_url || !data.route_template || !data.expires_at) { + throw new Error('WebDecoy returned an invalid SSRF canary'); + } + return { + markerId: data.marker_id, + callbackUrl: data.callback_url, + routeTemplate: data.route_template, + expiresAt: data.expires_at, + test: data.test === true, + }; + } + + async reportSSRFInitiation( + canary: Pick, + ): Promise { + const response = await this.request<{ + detection_id: string; + marker_id: string; + test: boolean; + } & ApiErrorBody>('POST', '/api/v1/sdk/ssrf/initiate', { + marker_id: canary.markerId, + route_template: canary.routeTemplate, + }); + this.requireSuccess(response); + const data = response.data!; + if (!data.detection_id || !data.marker_id) { + throw new Error('WebDecoy returned an invalid SSRF initiation receipt'); + } + return { detectionId: data.detection_id, markerId: data.marker_id, test: data.test === true }; + } + + private requireSuccess(response: ApiResponse): void { + if (response.status === 401) { + throw new Error('Invalid API key. Please check your Web Decoy configuration.'); + } + if (response.status === 429) { + throw new Error('Rate limit exceeded. Please try again later.'); + } + if (response.status >= 400) { + throw new Error( + response.data?.error || + response.data?.message || + `API request failed: HTTP ${response.status}`, + ); + } + if (!response.data) { + throw new Error('WebDecoy returned an empty response'); + } + } + /** * Send violation events to the ingest service */ diff --git a/packages/webdecoy/src/index.ts b/packages/webdecoy/src/index.ts index 9eac8cc..714a5aa 100644 --- a/packages/webdecoy/src/index.ts +++ b/packages/webdecoy/src/index.ts @@ -35,6 +35,9 @@ export type { SDKDetectionResponse, ProtectResult, ProtectOptions, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, } from './types'; // The decision `protect()` returns. Exported as a value because the class diff --git a/packages/webdecoy/src/sdk.ts b/packages/webdecoy/src/sdk.ts index 3f032fd..f996105 100644 --- a/packages/webdecoy/src/sdk.ts +++ b/packages/webdecoy/src/sdk.ts @@ -30,6 +30,9 @@ import { ProtectOptions, SDKDetectionRequest, SDKDetectionResponse, + SSRFCanary, + SSRFCanaryOptions, + SSRFInitiationReceipt, } from './types'; export class WebDecoy { @@ -324,6 +327,27 @@ export class WebDecoy { return this.getAgentVerifier().verify(request); } + /** Mint a signed, single-use callback marker for an SSRF test or observation. */ + async createSSRFCanary(options: SSRFCanaryOptions): Promise { + if (!this.client) { + throw new Error('An apiKey is required to create an SSRF canary'); + } + return this.client.createSSRFCanary(options); + } + + /** + * Report the initiating server request immediately before the application's + * ordinary fetch. Only the marker ID and route template are sent. + */ + async reportSSRFInitiation( + canary: Pick, + ): Promise { + if (!this.client) { + throw new Error('An apiKey is required to report an SSRF initiation'); + } + return this.client.reportSSRFInitiation(canary); + } + /** * Whether this SDK instance has filter rules that need async enrichment */ diff --git a/packages/webdecoy/src/ssrf-canary.test.ts b/packages/webdecoy/src/ssrf-canary.test.ts new file mode 100644 index 0000000..ec571d7 --- /dev/null +++ b/packages/webdecoy/src/ssrf-canary.test.ts @@ -0,0 +1,58 @@ +import { WebDecoy } from './sdk'; + +describe('SSRF canary correlation', () => { + const realFetch = global.fetch; + + afterEach(() => { + global.fetch = realFetch; + }); + + it('reports only the marker ID and route template on the initiation edge', async () => { + const calls: Array<{ url: string; body: Record }> = []; + global.fetch = jest.fn(async (url: unknown, init: RequestInit) => { + const body = JSON.parse(String(init.body)) as Record; + calls.push({ url: String(url), body }); + if (String(url).endsWith('/ssrf/markers')) { + return new Response(JSON.stringify({ + marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + callback_url: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', + route_template: '/api/fetch/:id', + expires_at: '2026-11-15T21:00:00Z', + test: true, + token: 'must-not-be-returned-by-the-sdk', + }), { status: 201 }); + } + return new Response(JSON.stringify({ + detection_id: 'c18348c8-9f6b-43e9-b993-86ca15db257f', + marker_id: body.marker_id, + test: true, + }), { status: 201 }); + }) as jest.Mock; + + const sdk = new WebDecoy({ apiKey: 'sk_test_ssrf', apiUrl: 'https://ingest.example' }); + const canary = await sdk.createSSRFCanary({ routeTemplate: '/api/fetch/:id', test: true }); + const receipt = await sdk.reportSSRFInitiation(canary); + + expect(canary).toEqual({ + markerId: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + callbackUrl: 'https://ingest.example/api/v1/ssrf/callback/opaque-token', + routeTemplate: '/api/fetch/:id', + expiresAt: '2026-11-15T21:00:00Z', + test: true, + }); + expect(receipt.detectionId).toBe('c18348c8-9f6b-43e9-b993-86ca15db257f'); + expect(calls[1]).toEqual({ + url: 'https://ingest.example/api/v1/sdk/ssrf/initiate', + body: { + marker_id: 'd65fd38c-4f45-4f32-91cf-1cdcd9c03fe6', + route_template: '/api/fetch/:id', + }, + }); + expect(JSON.stringify(calls[1].body)).not.toContain('opaque-token'); + }); + + it('requires a hosted API key', async () => { + const sdk = new WebDecoy(); + await expect(sdk.createSSRFCanary({ routeTemplate: '/fetch' })).rejects.toThrow(/apiKey/); + }); +}); diff --git a/packages/webdecoy/src/types.ts b/packages/webdecoy/src/types.ts index 5d68dbb..5f534eb 100644 --- a/packages/webdecoy/src/types.ts +++ b/packages/webdecoy/src/types.ts @@ -139,6 +139,31 @@ export interface WebDecoyConfig { tracer?: Tracer; } +/** Options for one short-lived, property-scoped SSRF canary. */ +export interface SSRFCanaryOptions { + /** The application route that will perform the server-side fetch. */ + routeTemplate: string; + /** Required only when an organization-wide API key is used. */ + propertyId?: string; + /** Keep a controlled validation out of production threat metrics. */ + test?: boolean; +} + +/** A callback marker. Put callbackUrl in the controlled outbound request. */ +export interface SSRFCanary { + markerId: string; + callbackUrl: string; + routeTemplate: string; + expiresAt: string; + test: boolean; +} + +export interface SSRFInitiationReceipt { + detectionId: string; + markerId: string; + test: boolean; +} + /** * TLS connection information from the request */