{"id":17345,"library":"request-filtering-agent","title":"Request Filtering Agent","description":"request-filtering-agent is an http(s).Agent implementation for Node.js designed to mitigate Server-Side Request Forgery (SSRF) attacks by blocking requests to private and reserved IP addresses by default. Currently stable at v3.2.0, the library has an active release cadence, introducing features like CIDR notation support for allow/deny lists in recent minor versions. Its key differentiator lies in providing a security-focused http.Agent that integrates seamlessly with popular HTTP clients such as node-fetch, axios, and got, while explicitly not supporting Node.js's built-in fetch due to its lack of http.Agent compatibility. The agent dynamically detects DNS-resolved IP addresses, including those from loopback domains like nip.io, ensuring comprehensive protection against internal network access.","status":"active","version":"3.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/azu/request-filtering-agent","tags":["javascript","http","https","proxy","agent","ssrf","security","typescript"],"install":[{"cmd":"npm install request-filtering-agent","lang":"bash","label":"npm"},{"cmd":"yarn add request-filtering-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add request-filtering-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for defining and checking IP address ranges and types (private, reserved, link-local).","package":"ipaddr.js"}],"imports":[{"note":"Since v3.0.0, the package is ESM-only. Attempting to `require()` it will result in `ERR_REQUIRE_ESM`. For CommonJS support, use v2.x.x or earlier.","wrong":"const { useAgent } = require('request-filtering-agent');","symbol":"useAgent","correct":"import { useAgent } from 'request-filtering-agent';"},{"note":"The class implementation for filtering HTTP requests. The `useAgent` factory function internally returns an instance of this class for HTTP URLs.","wrong":"const { HttpFilteringAgent } = require('request-filtering-agent');","symbol":"HttpFilteringAgent","correct":"import { HttpFilteringAgent } from 'request-filtering-agent';"},{"note":"The class implementation for filtering HTTPS requests. The `useAgent` factory function internally returns an instance of this class for HTTPS URLs.","wrong":"const { HttpsFilteringAgent } = require('request-filtering-agent');","symbol":"HttpsFilteringAgent","correct":"import { HttpsFilteringAgent } from 'request-filtering-agent';"},{"note":"Type definition for configuring the `useAgent` function or agent constructors, allowing specification of IP address filtering lists (e.g., `allowIPAddressList`, `denyIPAddressList`).","symbol":"FilteringAgentOptions","correct":"import type { FilteringAgentOptions } from 'request-filtering-agent';"}],"quickstart":{"code":"import { request } from 'node:http';\nimport { useAgent, FilteringAgentOptions } from 'request-filtering-agent';\n\n// This URL resolves to a private loopback IP (127.0.0.1) and will be blocked by default.\nconst url = new URL('http://127.0.0.1:8080/');\n\nconst agentOptions: FilteringAgentOptions = {\n    // Optionally, specify allowed or denied IP lists using CIDR notation.\n    // allowIPAddressList: ['192.168.1.0/24'],\n    // denyIPAddressList: ['10.0.0.0/8']\n};\n\n// Create a filtering agent instance for the target URL\nconst agent = useAgent(url, agentOptions);\n\n// Use the agent with Node.js's built-in http.request\nconst req = request(url, { agent }, (res) => {\n    console.log(`STATUS: ${res.statusCode}`);\n    res.setEncoding('utf8');\n    res.on('data', (chunk) => {\n        console.log(`BODY: ${chunk}`);\n    });\n    res.on('end', () => {\n        console.log('No more data in response.');\n    });\n});\n\nreq.on('error', (e) => {\n    // Expected error for 127.0.0.1: \"DNS lookup 127.0.0.1(...) is not allowed. Because, It is private IP address.\"\n    console.error(`Problem with request: ${e.message}`);\n});\n\nreq.end();","lang":"typescript","description":"Demonstrates how to initialize and use `request-filtering-agent` with Node.js's built-in `http.request` to prevent requests to private IP addresses, showing expected error handling."},"warnings":[{"fix":"Update your Node.js version to 20 or higher and refactor `require()` statements to `import` statements. For older Node.js versions or continued CommonJS support, use `request-filtering-agent@^2.0.0`.","message":"Package switched from CommonJS to ESM and requires Node.js 20+.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js runtime to 18 or higher. For Node.js 20+ and ESM, refer to the v3 breaking changes.","message":"Dropped support for older Node.js versions (12, 14, 16), requiring Node.js 18+.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Use alternative HTTP client libraries like `node-fetch`, `axios`, or `got` which provide `http.Agent` support. Avoid using `request-filtering-agent` with the native `fetch`.","message":"Node.js's built-in `fetch` API does not support custom `http.Agent` implementations, making it incompatible with `request-filtering-agent`.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure you are using `request-filtering-agent@^3.2.0` (or `^3.1.0` for `allowIPAddressList` CIDR) to utilize CIDR notation in your filtering rules.","message":"CIDR notation support for `allowIPAddressList` and `denyIPAddressList` was introduced in minor updates.","severity":"gotcha","affected_versions":"<3.2.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify the target IP address. If it's legitimately intended to be accessed and is a private IP, configure the `allowIPAddressList` option in `FilteringAgentOptions` to explicitly permit that IP or range.","cause":"Attempting to connect to a private or reserved IP address which is blocked by `request-filtering-agent` by default.","error":"DNS lookup [IP_ADDRESS](family:[NUMBER], host:[HOSTNAME]) is not allowed. Because, It is private IP address."},{"fix":"Refactor your codebase to use ES module `import` syntax. Ensure your environment supports ESM (e.g., Node.js 20+ and `\"type\": \"module\"` in `package.json` for top-level files). If you need CommonJS, downgrade to `request-filtering-agent@^2.0.0`.","cause":"Attempting to use `require()` with `request-filtering-agent` v3.x, which is an ESM-only package.","error":"ERR_REQUIRE_ESM: require() of ES Module .../request-filtering-agent/index.js from ... not supported."}],"ecosystem":"npm","meta_description":null}