ssrf-agent-guard 0.1.6 → 0.1.8

package/README.md

@@ -6,10 +6,17 @@
 ## Features
 
 * Block requests to internal/private IPs
-* Detect and block cloud provider metadata endpoints (AWS, GCP, Azure)
+* Detect and block cloud provider metadata endpoints (AWS, GCP, Azure, Oracle, DigitalOcean, Kubernetes)
 * DNS rebinding detection
+* Policy-based domain filtering (allowlists, denylists, TLD blocking)
+* Multiple operation modes (block, report, allow)
+* Custom logging support
 * Fully written in TypeScript with type definitions
 
+## Documentation
+
+For complete API documentation, see [API.md](./API.md).
+
 ---
 
 ## Installation
@@ -24,20 +31,15 @@ yarn add ssrf-agent-guard
 
 ## Usage
 
-`isValidDomainOptions` reference [is-valid-domain](https://github.com/miguelmota/is-valid-domain)
-
 ### axios
 
 ```ts
 const ssrfAgentGuard = require('ssrf-agent-guard');
 const url = 'https://127.0.0.1'
-const isValidDomainOptions = {
-  subdomain: true,
-  wildcard: true
-};
 axios.get(
   url, {
-    httpAgent: ssrfAgentGuard(url, isValidDomainOptions), httpsAgent: ssrfAgentGuard(url, isValidDomainOptions)
+    httpAgent: ssrfAgentGuard(url), 
+    httpsAgent: ssrfAgentGuard(url)
     })
       .then((response) => {
         console.log(`Success`);
@@ -55,12 +57,8 @@ axios.get(
 ```ts
 const ssrfAgentGuard = require('ssrf-agent-guard');
 const url = 'https://127.0.0.1'
-const isValidDomainOptions = {
-  subdomain: true,
-  wildcard: true
-};
 fetch(url, {
-    agent: ssrfAgentGuard(url, isValidDomainOptions)
+    agent: ssrfAgentGuard(url)
   })
   .then((response) => {
     console.log(`Success`);
@@ -70,6 +68,26 @@ fetch(url, {
   });
 ```
 
+### Advanced Configuration
+
+```ts
+const ssrfAgentGuard = require('ssrf-agent-guard');
+
+const agent = ssrfAgentGuard('https://api.example.com', {
+  mode: 'block',                    // 'block' | 'report' | 'allow'
+  blockCloudMetadata: true,         // Block AWS/GCP/Azure metadata endpoints
+  detectDnsRebinding: true,         // Detect DNS rebinding attacks
+  policy: {
+    allowDomains: ['*.trusted.com'], // Only allow these domains
+    denyDomains: ['evil.com'],       // Block these domains
+    denyTLD: ['local', 'internal']   // Block these TLDs
+  },
+  logger: (level, msg, meta) => {
+    console.log(`[${level}] ${msg}`, meta);
+  }
+});
+```
+
 ---
 
 ## Development

package/dist/index.cjs.js

@@ -7,12 +7,36 @@ var https = require('https');
 var isValidDomain = require('is-valid-domain');
 var ipaddr = require('ipaddr.js');
 
-const CLOUD_METADATA_HOSTS = [
+// lib/types.ts
+/**
+ * Default cloud metadata hosts to block.
+ * Includes AWS, GCP, Azure, Oracle Cloud, DigitalOcean, and Kubernetes.
+ */
+const CLOUD_METADATA_HOSTS = new Set([
+    // AWS EC2 metadata service
     '169.254.169.254',
     '169.254.169.253',
+    // GCP metadata service
     'metadata.google.internal',
+    'metadata.goog',
+    // Azure IMDS
+    '169.254.169.254',
+    '168.63.129.16',
+    // ECS task metadata (AWS Fargate)
     '169.254.170.2',
-];
+    // Kubernetes metadata
+    'kubernetes.default',
+    'kubernetes.default.svc',
+    'kubernetes.default.svc.cluster.local',
+    // Oracle Cloud
+    '169.254.169.254',
+    // DigitalOcean
+    '169.254.169.254',
+    // Alibaba Cloud
+    '100.100.100.200',
+    // Link-local for metadata
+    '169.254.0.0',
+]);
 
 // lib/utils.ts
 /**
@@ -27,87 +51,266 @@ function isIp(input) {
 function isPublicIp(ip) {
     return ipaddr.parse(ip).range() === 'unicast';
 }
+/**
+ * Extracts the TLD from a hostname.
+ * @param hostname The hostname to extract TLD from
+ * @returns The TLD or empty string if not found
+ */
+function getTLD(hostname) {
+    const parts = hostname.toLowerCase().split('.');
+    return parts.length > 0 ? parts[parts.length - 1] : '';
+}
+/**
+ * Checks if a hostname matches a domain pattern.
+ * Supports exact match and wildcard subdomain matching.
+ * @param hostname The hostname to check
+ * @param pattern The domain pattern (e.g., 'example.com' or '*.example.com')
+ */
+function matchesDomain(hostname, pattern) {
+    const normalizedHost = hostname.toLowerCase();
+    const normalizedPattern = pattern.toLowerCase();
+    // Exact match
+    if (normalizedHost === normalizedPattern) {
+        return true;
+    }
+    // Wildcard match (*.example.com matches sub.example.com)
+    if (normalizedPattern.startsWith('*.')) {
+        const baseDomain = normalizedPattern.slice(2);
+        return normalizedHost.endsWith('.' + baseDomain) || normalizedHost === baseDomain;
+    }
+    // Subdomain match (example.com matches sub.example.com)
+    return normalizedHost.endsWith('.' + normalizedPattern);
+}
+/**
+ * Checks if a hostname matches any domain in a list.
+ */
+function matchesAnyDomain(hostname, domains) {
+    return domains.some(domain => matchesDomain(hostname, domain));
+}
+/**
+ * Validates a host against policy options.
+ * @param hostname The hostname to validate
+ * @param policy The policy options
+ * @returns ValidationResult with safe status and reason if blocked
+ */
+function validatePolicy(hostname, policy) {
+    if (!policy) {
+        return { safe: true };
+    }
+    // Check allowDomains first (explicit allowlist takes precedence)
+    if (policy.allowDomains && policy.allowDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.allowDomains)) {
+            return { safe: true };
+        }
+        // If allowDomains is specified but host doesn't match, it's not allowed
+        return { safe: false, reason: 'not_allowed_domain' };
+    }
+    // Check denyDomains
+    if (policy.denyDomains && policy.denyDomains.length > 0) {
+        if (matchesAnyDomain(hostname, policy.denyDomains)) {
+            return { safe: false, reason: 'denied_domain' };
+        }
+    }
+    // Check denyTLD
+    if (policy.denyTLD && policy.denyTLD.length > 0) {
+        const tld = getTLD(hostname);
+        if (policy.denyTLD.map(t => t.toLowerCase()).includes(tld)) {
+            return { safe: false, reason: 'denied_tld' };
+        }
+    }
+    return { safe: true };
+}
+/**
+ * Checks if a hostname is a cloud metadata endpoint.
+ * @param hostname The hostname to check
+ * @param customHosts Additional custom metadata hosts to check
+ */
+function isCloudMetadata(hostname, customHosts) {
+    if (CLOUD_METADATA_HOSTS.has(hostname)) {
+        return true;
+    }
+    if (customHosts && customHosts.includes(hostname)) {
+        return true;
+    }
+    return false;
+}
 /**
  * High-level validation for hostnames (domains + public IPs).
+ * Returns detailed validation result with reason for blocking.
+ *
+ * @param hostname The hostname or IP to validate
+ * @param options Configuration options including policy and metadata settings
+ * @returns ValidationResult with safe status and optional reason
  */
-function isSafeHost(hostname, isValidDomainOptions) {
+function validateHost(hostname, options) {
+    const blockCloudMetadata = options?.blockCloudMetadata !== false; // default true
     // Block cloud metadata IP/domains
-    if (CLOUD_METADATA_HOSTS.indexOf(hostname) !== -1)
-        return false;
+    if (blockCloudMetadata && isCloudMetadata(hostname, options?.metadataHosts)) {
+        return { safe: false, reason: 'cloud_metadata' };
+    }
+    // Check policy-based rules (only for non-IP hostnames)
+    if (!isIp(hostname)) {
+        const policyResult = validatePolicy(hostname, options?.policy);
+        if (!policyResult.safe) {
+            return policyResult;
+        }
+    }
     // Case 1: IP address
-    if (isIp(hostname))
-        return isPublicIp(hostname);
-    // Case 2: Domain name
-    return isValidDomain(hostname, {
-        allowUnicode: false,
-        subdomain: true,
-        ...isValidDomainOptions,
-    });
+    if (isIp(hostname)) {
+        if (!isPublicIp(hostname)) {
+            return { safe: false, reason: 'private_ip' };
+        }
+        return { safe: true };
+    }
+    // Case 2: Domain name validation
+    if (!isValidDomain(hostname, { allowUnicode: false, subdomain: true })) {
+        return { safe: false, reason: 'invalid_domain' };
+    }
+    return { safe: true };
 }
 
-// Instantiate the default agents
-const httpAgent = new http.Agent();
-const httpsAgent = new https.Agent();
+// WeakMap to track patched agents without modifying the agent object
+const patchedAgents = new WeakMap();
 /**
- * Determines the correct Agent instance based on the input.
- * @param url The URL or another input to determine the agent type.
- * @returns The appropriate HttpAgent or HttpsAgent instance.
+ * Determines the correct Agent instance based on the protocol.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Optional options that may contain protocol hint.
+ * @returns A new HttpAgent or HttpsAgent instance.
  */
-const getAgent = (url) => {
-    // If it's a string, check if it implies HTTPS
-    if (typeof url === 'string' && url.startsWith('https')) {
-        return httpsAgent;
+const createAgent = (url, options) => {
+    const protocol = options?.protocol || url;
+    if (typeof protocol === 'string' && protocol.startsWith('https')) {
+        return new https.Agent();
     }
-    // Default to HTTP agent
-    return httpAgent;
+    return new http.Agent();
 };
-// Define a Symbol for a unique property to prevent double-patching the agent.
-const CREATE_CONNECTION = Symbol('createConnection');
 /**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
+ * Creates a BlockEvent for logging.
+ */
+function createBlockEvent(url, reason, ip, hostname) {
+    return {
+        url,
+        reason,
+        ip,
+        hostname,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Handles a block action based on mode.
+ * @returns true if the request should be blocked, false if allowed
+ */
+function handleBlock(options, url, reason, ip, hostname) {
+    const mode = options?.mode || 'block';
+    const logger = options?.logger;
+    // Create event for logging
+    const event = createBlockEvent(url, reason, ip, hostname);
+    // Log based on mode
+    if (logger) {
+        if (mode === 'block') {
+            logger('error', `SSRF blocked: ${reason}`, event);
+        }
+        else if (mode === 'report') {
+            logger('warn', `SSRF detected (report mode): ${reason}`, event);
+        }
+    }
+    // Return whether to actually block
+    return mode === 'block';
+}
+/**
+ * Gets a human-readable error message for a block reason.
+ */
+function getErrorMessage(reason, target) {
+    switch (reason) {
+        case 'private_ip':
+            return `Private IP address ${target} is not allowed`;
+        case 'cloud_metadata':
+            return `Cloud metadata endpoint ${target} is not allowed`;
+        case 'invalid_domain':
+            return `Invalid domain ${target}`;
+        case 'dns_rebinding':
+            return `DNS rebinding attack detected for ${target}`;
+        case 'denied_domain':
+            return `Domain ${target} is denied by policy`;
+        case 'denied_tld':
+            return `TLD of ${target} is denied by policy`;
+        case 'not_allowed_domain':
+            return `Domain ${target} is not in the allowed list`;
+        default:
+            return `Request to ${target} is not allowed`;
+    }
+}
+/**
+ * Patches an http.Agent or https.Agent to enforce HOST/IP checks
+ * before and after DNS lookup, with full policy support.
  *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Configuration options for SSRF protection.
  * @returns The patched CustomAgent instance.
  */
-const ssrfAgentGuard = function (url, isValidDomainOptions) {
-    const finalAgent = getAgent(url);
-    // Prevent patching the agent multiple times
-    if (finalAgent[CREATE_CONNECTION]) {
+function ssrfAgentGuard(url, options) {
+    // Create a new agent for each call to avoid shared state issues
+    const finalAgent = createAgent(url, options);
+    // If mode is 'allow', return unpatched agent
+    if (options?.mode === 'allow') {
         return finalAgent;
     }
-    finalAgent[CREATE_CONNECTION] = true;
-    // The original createConnection function from the Agent
-    const createConnection = finalAgent.createConnection;
-    // Patch the createConnection method on the agent
-    finalAgent.createConnection = function (options, fn) {
-        const { host: address } = options;
+    // Check if already patched (shouldn't happen with new agents, but safety check)
+    if (patchedAgents.get(finalAgent)) {
+        return finalAgent;
+    }
+    patchedAgents.set(finalAgent, true);
+    // Store original createConnection
+    const originalCreateConnection = finalAgent.createConnection;
+    // Whether to detect DNS rebinding (default: true)
+    const detectDnsRebinding = options?.detectDnsRebinding !== false;
+    // Patch createConnection
+    finalAgent.createConnection = function (connectionOptions, callback) {
+        const hostname = connectionOptions.host || '';
         // --- 1. Pre-DNS Check (Host/Address Check) ---
-        // If the 'host' option is an IP address, check it immediately.
-        // If it's a hostname, this check will usually pass (via defaultIpChecker).
-        if (address && !isSafeHost(address, isValidDomainOptions)) {
-            throw new Error(`DNS lookup ${address} is not allowed.`);
+        const preCheckResult = validateHost(hostname, options);
+        if (!preCheckResult.safe && preCheckResult.reason) {
+            const shouldBlock = handleBlock(options, hostname, preCheckResult.reason, undefined, hostname);
+            if (shouldBlock) {
+                throw new Error(getErrorMessage(preCheckResult.reason, hostname));
+            }
         }
         // Call the original createConnection
-        const client = createConnection.call(this, options, fn);
+        const client = originalCreateConnection.call(this, connectionOptions, callback);
         // --- 2. Post-DNS Check (Lookup Event Check) ---
-        // The 'lookup' event fires after the DNS lookup is complete
-        // and provides the resolved IP address.
-        client?.on('lookup', (err, resolvedAddress) => {
-            // Ensure resolvedAddress is a string for the check (it's typically a string for simple lookups)
-            const ipToCheck = Array.isArray(resolvedAddress) ? resolvedAddress[0] : resolvedAddress;
-            // If there was an error in lookup, or if the resolved IP is allowed, do nothing.
-            if (err || isSafeHost(ipToCheck, isValidDomainOptions)) {
-                return false;
-            }
-            // If the resolved IP is NOT allowed (e.g., a private IP), destroy the connection.
-            return client?.destroy(new Error(`DNS lookup ${ipToCheck} is not allowed.`));
-        });
+        // Only add listener if DNS rebinding detection is enabled
+        if (detectDnsRebinding && client) {
+            client.on('lookup', (err, resolvedAddress) => {
+                if (err) {
+                    return; // DNS lookup failed, let it propagate naturally
+                }
+                // Check all resolved IPs (handle both single IP and array)
+                const ipsToCheck = Array.isArray(resolvedAddress) ? resolvedAddress : [resolvedAddress];
+                for (const ip of ipsToCheck) {
+                    if (!ip)
+                        continue;
+                    const postCheckResult = validateHost(ip, options);
+                    if (!postCheckResult.safe && postCheckResult.reason) {
+                        // For post-DNS check, the reason is DNS rebinding
+                        const reason = 'dns_rebinding';
+                        const shouldBlock = handleBlock(options, hostname, reason, ip, hostname);
+                        if (shouldBlock) {
+                            client.destroy(new Error(getErrorMessage(reason, `${hostname} -> ${ip}`)));
+                            return;
+                        }
+                    }
+                }
+            });
+        }
         return client;
     };
     return finalAgent;
-};
+}
 module.exports = ssrfAgentGuard;
 
 exports.default = ssrfAgentGuard;
+exports.getTLD = getTLD;
+exports.isCloudMetadata = isCloudMetadata;
+exports.matchesDomain = matchesDomain;
+exports.validateHost = validateHost;
+exports.validatePolicy = validatePolicy;

package/dist/index.d.ts

@@ -1,14 +1,16 @@
 import { Agent as HttpAgent } from 'http';
 import { Agent as HttpsAgent } from 'https';
-import { IsValidDomainOptions } from './lib/types';
+import { Options } from './lib/types';
+export { Options, PolicyOptions, BlockEvent, BlockReason, ValidationResult } from './lib/types';
+export { validateHost, isCloudMetadata, validatePolicy, matchesDomain, getTLD } from './lib/utils';
 type CustomAgent = HttpAgent | HttpsAgent;
 /**
- * Patches an http.Agent or https.Agent to enforce an HOST/IP check
- * before and after a DNS lookup.
+ * Patches an http.Agent or https.Agent to enforce HOST/IP checks
+ * before and after DNS lookup, with full policy support.
  *
- * @param url The URL or another input to determine the agent type.
- * @param isValidDomainOptions Options for validating domain names.
+ * @param url The URL or protocol hint to determine the agent type.
+ * @param options Configuration options for SSRF protection.
  * @returns The patched CustomAgent instance.
  */
-declare const ssrfAgentGuard: (url: string, isValidDomainOptions?: IsValidDomainOptions) => CustomAgent;
+declare function ssrfAgentGuard(url: string, options?: Options): CustomAgent;
 export default ssrfAgentGuard;