SSRF protection for webhooks: call user URLs safely

mkdir ticketshop-webhooks && cd ticketshop-webhooks
npm init -y
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
npm install -D typescript tsx esbuild @types/node @types/aws-lambda aws-cdk aws-cdk-lib constructs
mkdir -p bin lib src/ssrf src/handlers test

// src/ssrf/blocked-ranges.ts
import { BlockList, isIP } from 'node:net';

// Address ranges a webhook must never reach.
// Everything that is not public internet is blocked.
const IPV4_RANGES: Array<[string, number]> = [
  ['0.0.0.0', 8], // "this network"
  ['10.0.0.0', 8], // private network (RFC 1918)
  ['100.64.0.0', 10], // carrier-grade NAT
  ['127.0.0.0', 8], // loopback, including the Lambda Runtime API
  ['169.254.0.0', 16], // link-local, including instance and task metadata
  ['172.16.0.0', 12], // private network (RFC 1918)
  ['192.0.0.0', 24], // IETF protocol assignments
  ['192.0.2.0', 24], // documentation
  ['192.168.0.0', 16], // private network (RFC 1918)
  ['198.18.0.0', 15], // benchmarking
  ['198.51.100.0', 24], // documentation
  ['203.0.113.0', 24], // documentation
  ['224.0.0.0', 4], // multicast
  ['240.0.0.0', 4], // reserved, including broadcast
];

const IPV6_RANGES: Array<[string, number]> = [
  ['::', 128], // unspecified
  ['::1', 128], // loopback
  ['64:ff9b::', 96], // NAT64, can point to internal IPv4 addresses
  ['64:ff9b:1::', 48], // local NAT64
  ['100::', 64], // discard
  ['2001::', 32], // Teredo
  ['2001:db8::', 32], // documentation
  ['2002::', 16], // 6to4
  ['fc00::', 7], // unique local addresses, including fd00:ec2::254
  ['fe80::', 10], // link-local
  ['ff00::', 8], // multicast
];

const blockList = new BlockList();
for (const [net, prefix] of IPV4_RANGES) blockList.addSubnet(net, prefix, 'ipv4');
for (const [net, prefix] of IPV6_RANGES) blockList.addSubnet(net, prefix, 'ipv6');

/** true if the address must not be contacted. Unknown formats are blocked too. */
export function isBlockedAddress(address: string): boolean {
  const version = isIP(address);
  if (version === 0) return true;
  // IPv4-mapped IPv6 addresses (::ffff:127.0.0.1) are checked against the IPv4 rules.
  return blockList.check(address, version === 4 ? 'ipv4' : 'ipv6');
}

// src/ssrf/validate-url.ts
import { isIP } from 'node:net';
import { lookup, type LookupAddress } from 'node:dns';
import { isBlockedAddress } from './blocked-ranges';

export class UnsafeUrlError extends Error {
  constructor(public readonly reason: string) {
    super(`Webhook URL rejected: ${reason}`);
    this.name = 'UnsafeUrlError';
  }
}

export type Resolver = (hostname: string) => Promise<LookupAddress[]>;

const MAX_URL_LENGTH = 2048;
const INTERNAL_SUFFIXES = ['.internal', '.local', '.localhost', '.lan', '.home.arpa', '.corp'];

const resolveAll: Resolver = (hostname) =>
  new Promise((resolve, reject) => {
    lookup(hostname, { all: true }, (err, addresses) => (err ? reject(err) : resolve(addresses)));
  });

/** Checks the form of the URL. Does not do any network access. */
export function parseWebhookUrl(raw: string): URL {
  if (typeof raw !== 'string' || raw.length > MAX_URL_LENGTH) {
    throw new UnsafeUrlError('URL is missing or too long');
  }
  let url: URL;
  try {
    url = new URL(raw.trim());
  } catch {
    throw new UnsafeUrlError('not a valid URL');
  }
  if (url.protocol !== 'https:') throw new UnsafeUrlError('only https is allowed');
  if (url.username || url.password) throw new UnsafeUrlError('credentials in the URL are not allowed');
  if (url.port !== '') throw new UnsafeUrlError('only the default port 443 is allowed');

  // The URL parser normalizes 0x7f.1 or 2130706433 to 127.0.0.1 - so this check catches them too.
  const host = url.hostname.toLowerCase().replace(/\.$/, '');
  if (host.startsWith('[') || isIP(host) !== 0) {
    throw new UnsafeUrlError('IP addresses are not allowed, please use a hostname');
  }
  if (!host.includes('.') || host === 'localhost' || INTERNAL_SUFFIXES.some((s) => host.endsWith(s))) {
    throw new UnsafeUrlError('internal hostnames are not allowed');
  }
  url.hash = '';
  return url;
}

/** Resolves all A and AAAA records. A single internal address is enough to reject. */
export async function assertPublicHost(hostname: string, resolve: Resolver = resolveAll): Promise<string[]> {
  let addresses: LookupAddress[];
  try {
    addresses = await resolve(hostname);
  } catch {
    throw new UnsafeUrlError('hostname cannot be resolved');
  }
  if (addresses.length === 0) throw new UnsafeUrlError('hostname cannot be resolved');
  if (addresses.some((a) => isBlockedAddress(a.address))) {
    throw new UnsafeUrlError('hostname points to an internal address');
  }
  return addresses.map((a) => a.address);
}

/** Full check at registration: form plus DNS. */
export async function validateWebhookUrl(raw: string, resolve?: Resolver): Promise<URL> {
  const url = parseWebhookUrl(raw);
  await assertPublicHost(url.hostname, resolve);
  return url;
}

// src/ssrf/safe-post.ts
import { request as httpsRequest, type RequestOptions } from 'node:https';
import type { ClientRequest, IncomingMessage } from 'node:http';
import { lookup as dnsLookup, type LookupAddress } from 'node:dns';
import { isIP, type LookupFunction } from 'node:net';
import { isBlockedAddress } from './blocked-ranges';
import { UnsafeUrlError } from './validate-url';

type RequestFn = (options: RequestOptions, callback: (res: IncomingMessage) => void) => ClientRequest;

export interface SafePostOptions {
  timeoutMs?: number;
  maxResponseBytes?: number;
  headers?: Record<string, string>;
  /** Only for tests: replace the blocking rule or the transport. */
  isBlocked?: (address: string) => boolean;
  requestFn?: RequestFn;
}

export interface SafePostResult {
  statusCode: number;
  delivered: boolean;
  redirected: boolean;
}

/**
 * DNS lookup that checks every address right before the connection is opened.
 * The socket connects only to addresses that passed the check.
 * That closes the gap DNS rebinding relies on.
 */
export function guardedLookup(isBlocked: (address: string) => boolean): LookupFunction {
  return (hostname, options, callback) => {
    dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
      if (err) return callback(err, '', 0);
      const list = addresses as unknown as LookupAddress[];
      if (list.length === 0 || list.some((a) => isBlocked(a.address))) {
        const error = new UnsafeUrlError('hostname points to an internal address') as NodeJS.ErrnoException;
        error.code = 'EBLOCKEDADDRESS';
        return callback(error, '', 0);
      }
      if (options.all) {
        // Node with autoSelectFamily asks for all addresses.
        return (callback as unknown as (e: null, a: LookupAddress[]) => void)(null, list);
      }
      return callback(null, list[0].address, list[0].family);
    });
  };
}

/** Sends JSON without following redirects, with a hard time and size limit. */
export function safePostJson(url: URL, body: unknown, options: SafePostOptions = {}): Promise<SafePostResult> {
  const {
    timeoutMs = 5000,
    maxResponseBytes = 64 * 1024,
    headers = {},
    isBlocked = isBlockedAddress,
    requestFn = httpsRequest,
  } = options;

  const hostname = url.hostname.replace(/^\[|\]$/g, '');
  // With an IP literal Node skips the lookup - so we check it here.
  if (isIP(hostname) !== 0 && isBlocked(hostname)) {
    return Promise.reject(new UnsafeUrlError('IP address is internal'));
  }

  const payload = JSON.stringify(body);
  return new Promise((resolve, reject) => {
    const req = requestFn(
      {
        method: 'POST',
        hostname,
        port: url.port || undefined,
        path: `${url.pathname}${url.search}`,
        headers: {
          'content-type': 'application/json',
          'content-length': Buffer.byteLength(payload).toString(),
          'user-agent': 'ticketshop-webhooks/1.0',
          ...headers,
        },
        lookup: guardedLookup(isBlocked),
        signal: AbortSignal.timeout(timeoutMs),
        agent: false,
      },
      (res) => {
        const statusCode = res.statusCode ?? 0;
        let received = 0;
        res.on('data', (chunk: Buffer) => {
          received += chunk.length;
          // The response is discarded anyway - we only read as much as necessary.
          if (received > maxResponseBytes) res.destroy();
        });
        const done = () =>
          resolve({
            statusCode,
            delivered: statusCode >= 200 && statusCode < 300,
            redirected: statusCode >= 300 && statusCode < 400,
          });
        res.on('end', done);
        res.on('close', done);
        res.on('error', done);
      },
    );
    req.on('error', reject);
    req.end(payload);
  });
}

// src/handlers/register-webhook.ts
import { randomUUID } from 'node:crypto';
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
import { UnsafeUrlError, validateWebhookUrl } from '../ssrf/validate-url';

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));
const TABLE = process.env.WEBHOOK_TABLE!;

const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
  statusCode,
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(body),
});

export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
  let input: { organizerId?: string; url?: string };
  try {
    input = JSON.parse(event.body ?? '{}');
  } catch {
    return json(400, { message: 'Body must be JSON' });
  }
  if (!input.organizerId || !input.url) {
    return json(400, { message: 'organizerId and url are required' });
  }

  try {
    const url = await validateWebhookUrl(input.url);
    const id = randomUUID();
    await db.send(
      new PutCommand({
        TableName: TABLE,
        Item: { pk: input.organizerId, sk: `WEBHOOK#${id}`, url: url.toString(), createdAt: new Date().toISOString() },
      }),
    );
    return json(201, { id, url: url.toString() });
  } catch (err) {
    if (err instanceof UnsafeUrlError) {
      // Name the reason, but never reveal resolved IP addresses.
      return json(400, { message: err.message });
    }
    throw err;
  }
};

// src/handlers/deliver-webhook.ts
import type { SQSBatchResponse, SQSEvent } from 'aws-lambda';
import { parseWebhookUrl, UnsafeUrlError } from '../ssrf/validate-url';
import { safePostJson } from '../ssrf/safe-post';

interface DeliveryJob {
  webhookId: string;
  url: string;
  event: { type: string; data: unknown };
}

export const handler = async (event: SQSEvent): Promise<SQSBatchResponse> => {
  const batchItemFailures: SQSBatchResponse['batchItemFailures'] = [];

  for (const record of event.Records) {
    const job = JSON.parse(record.body) as DeliveryJob;
    try {
      // Check the form again: the database could contain old entries.
      const url = parseWebhookUrl(job.url);
      const result = await safePostJson(url, job.event, { timeoutMs: 5000 });

      if (result.delivered) continue;
      if (result.redirected) {
        // Redirects are not followed - retrying makes no sense.
        console.warn(JSON.stringify({ msg: 'webhook redirect ignored', webhookId: job.webhookId, status: result.statusCode }));
        continue;
      }
      console.warn(JSON.stringify({ msg: 'webhook failed', webhookId: job.webhookId, status: result.statusCode }));
      batchItemFailures.push({ itemIdentifier: record.messageId });
    } catch (err) {
      if (err instanceof UnsafeUrlError) {
        // Security event: log it, do not retry.
        console.error(JSON.stringify({ msg: 'webhook blocked', webhookId: job.webhookId, reason: err.reason }));
        continue;
      }
      console.warn(JSON.stringify({ msg: 'webhook error', webhookId: job.webhookId, error: (err as Error).name }));
      batchItemFailures.push({ itemIdentifier: record.messageId });
    }
  }
  return { batchItemFailures };
};

// lib/webhook-guard-stack.ts
import { Duration, RemovalPolicy, Stack, type StackProps } from 'aws-cdk-lib';
import type { Construct } from 'constructs';
import { AttributeType, Billing, TableV2 } from 'aws-cdk-lib/aws-dynamodb';
import { Queue } from 'aws-cdk-lib/aws-sqs';
import { Runtime } from 'aws-cdk-lib/aws-lambda';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import { SqsEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';
import { HttpApi, HttpMethod } from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';

export class WebhookGuardStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const table = new TableV2(this, 'Webhooks', {
      partitionKey: { name: 'pk', type: AttributeType.STRING },
      sortKey: { name: 'sk', type: AttributeType.STRING },
      billing: Billing.onDemand(),
      removalPolicy: RemovalPolicy.DESTROY, // demo only
    });

    const dlq = new Queue(this, 'DeliveryDlq', { retentionPeriod: Duration.days(14) });
    const deliveryQueue = new Queue(this, 'DeliveryQueue', {
      visibilityTimeout: Duration.seconds(60),
      deadLetterQueue: { queue: dlq, maxReceiveCount: 5 },
    });

    const common = {
      runtime: Runtime.NODEJS_22_X,
      memorySize: 256,
      bundling: { minify: true, sourceMap: true },
    };

    const register = new NodejsFunction(this, 'RegisterWebhook', {
      ...common,
      entry: 'src/handlers/register-webhook.ts',
      timeout: Duration.seconds(10),
      environment: { WEBHOOK_TABLE: table.tableName },
    });
    table.grantWriteData(register);

    // Deliberately no VPC: the delivery function cannot see any private resources.
    // It only needs to read from the queue - no database, no other permissions.
    const deliver = new NodejsFunction(this, 'DeliverWebhook', {
      ...common,
      entry: 'src/handlers/deliver-webhook.ts',
      timeout: Duration.seconds(30),
      reservedConcurrentExecutions: 10,
    });
    deliver.addEventSource(new SqsEventSource(deliveryQueue, { batchSize: 5, reportBatchItemFailures: true }));

    const api = new HttpApi(this, 'WebhookApi');
    api.addRoutes({
      path: '/webhooks',
      methods: [HttpMethod.POST],
      integration: new HttpLambdaIntegration('RegisterIntegration', register),
    });
  }
}

// bin/app.ts
import { App } from 'aws-cdk-lib';
import { WebhookGuardStack } from '../lib/webhook-guard-stack';

const app = new App();
new WebhookGuardStack(app, 'WebhookGuardStack');

// test/ssrf.test.ts
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { createServer, request as httpRequest, type Server } from 'node:http';
import type { AddressInfo } from 'node:net';
import { isBlockedAddress } from '../src/ssrf/blocked-ranges';
import { assertPublicHost, parseWebhookUrl, UnsafeUrlError } from '../src/ssrf/validate-url';
import { safePostJson } from '../src/ssrf/safe-post';

test('blocks internal addresses', () => {
  for (const ip of ['127.0.0.1', '10.1.2.3', '172.20.0.1', '192.168.1.1', '169.254.169.254', '100.64.0.1', '0.0.0.0', '::1', 'fd00:ec2::254', 'fe80::1', '::ffff:127.0.0.1', '::ffff:a9fe:a9fe', '64:ff9b::a9fe:a9fe']) {
    assert.equal(isBlockedAddress(ip), true, ip);
  }
});

test('allows public addresses', () => {
  for (const ip of ['1.1.1.1', '8.8.8.8', '2606:4700:4700::1111']) {
    assert.equal(isBlockedAddress(ip), false, ip);
  }
});

test('rejects dangerous URL forms', () => {
  const bad = [
    'http://tickets.example.com/hook',
    'https://user:[email protected]/hook',
    'https://tickets.example.com:8443/hook',
    'https://127.0.0.1/hook',
    'https://2130706433/hook',
    'https://0x7f.1/hook',
    'https://[::1]/hook',
    'https://localhost/hook',
    'https://localhost./hook',
    'https://metadata.google.internal/hook',
    'https://intranet/hook',
    'file:///etc/passwd',
  ];
  for (const url of bad) {
    assert.throws(() => parseWebhookUrl(url), UnsafeUrlError, url);
  }
});

test('accepts a normal https URL', () => {
  assert.equal(parseWebhookUrl('https://hooks.example.com/tickets?x=1#a').toString(), 'https://hooks.example.com/tickets?x=1');
});

test('rejects a hostname with a single internal address', async () => {
  const fakeDns = async () => [
    { address: '93.184.215.14', family: 4 },
    { address: '10.0.0.5', family: 4 },
  ];
  await assert.rejects(assertPublicHost('mixed.example.com', fakeDns), /internal address/);
});

async function startServer(handler: Parameters<typeof createServer>[1]): Promise<Server> {
  const server = createServer(handler);
  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
  return server;
}
const urlFor = (s: Server, path = '/hook') => new URL(`http://localhost:${(s.address() as AddressInfo).port}${path}`);

test('blocks the connection when the DNS answer is internal', async () => {
  let hits = 0;
  const server = await startServer((_req, res) => {
    hits++;
    res.end('ok');
  });
  try {
    await assert.rejects(safePostJson(urlFor(server), { hello: 'world' }, { requestFn: httpRequest }), UnsafeUrlError);
    assert.equal(hits, 0);
  } finally {
    server.close();
  }
});

test('does not follow redirects', async () => {
  const server = await startServer((req, res) => {
    if (req.url === '/hook') {
      res.writeHead(302, { location: 'http://169.254.169.254/latest/meta-data/' }).end();
    } else {
      res.end('should never be reached');
    }
  });
  try {
    const result = await safePostJson(urlFor(server), {}, { requestFn: httpRequest, isBlocked: () => false });
    assert.deepEqual(result, { statusCode: 302, delivered: false, redirected: true });
  } finally {
    server.close();
  }
});

test('aborts slow servers', async () => {
  const server = await startServer(() => {
    /* never respond */
  });
  try {
    await assert.rejects(
      safePostJson(urlFor(server), {}, { requestFn: httpRequest, isBlocked: () => false, timeoutMs: 300 }),
      /aborted|timeout/i,
    );
  } finally {
    server.closeAllConnections();
    server.close();
  }
});

npx tsc --noEmit
node --import tsx --test test/ssrf.test.ts

npx cdk synth
npx cdk deploy

API=https://abc123.execute-api.eu-central-1.amazonaws.com
curl -s -X POST "$API/webhooks" -d '{"organizerId":"riverside-hall","url":"https://example.com/tickets"}'
curl -s -X POST "$API/webhooks" -d '{"organizerId":"riverside-hall","url":"https://169.254.169.254/latest/meta-data/"}'