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 */