Registry / auth-security / request-filtering-agent

request-filtering-agent

library3.2.0jsnpmunverified

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.

auth-security http-networking

npm install request-filtering-agent

github ↗package ↗

INSTALL

IMPORT

SIG · REQUEST-FILTERING-

request-filtering-agent

auth-securityjavascriptv3.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useAgent

✓ import { useAgent } from 'request-filtering-agent';

✗ const { useAgent } = require('request-filtering-agent');

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.

HttpFilteringAgent

✓ import { HttpFilteringAgent } from 'request-filtering-agent';

✗ const { HttpFilteringAgent } = require('request-filtering-agent');

The class implementation for filtering HTTP requests. The `useAgent` factory function internally returns an instance of this class for HTTP URLs.

HttpsFilteringAgent

✓ import { HttpsFilteringAgent } from 'request-filtering-agent';

✗ const { HttpsFilteringAgent } = require('request-filtering-agent');

The class implementation for filtering HTTPS requests. The `useAgent` factory function internally returns an instance of this class for HTTPS URLs.

FilteringAgentOptions

✓ import type { FilteringAgentOptions } from 'request-filtering-agent';

Type definition for configuring the `useAgent` function or agent constructors, allowing specification of IP address filtering lists (e.g., `allowIPAddressList`, `denyIPAddressList`).

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.

import { request } from 'node:http'; import { useAgent, FilteringAgentOptions } from 'request-filtering-agent'; // This URL resolves to a private loopback IP (127.0.0.1) and will be blocked by default. const url = new URL('http://127.0.0.1:8080/'); const agentOptions: FilteringAgentOptions = { // Optionally, specify allowed or denied IP lists using CIDR notation. // allowIPAddressList: ['192.168.1.0/24'], // denyIPAddressList: ['10.0.0.0/8'] }; // Create a filtering agent instance for the target URL const agent = useAgent(url, agentOptions); // Use the agent with Node.js's built-in http.request const req = request(url, { agent }, (res) => { console.log(`STATUS: ${res.statusCode}`); res.setEncoding('utf8'); res.on('data', (chunk) => { console.log(`BODY: ${chunk}`); }); res.on('end', () => { console.log('No more data in response.'); }); }); req.on('error', (e) => { // Expected error for 127.0.0.1: "DNS lookup 127.0.0.1(...) is not allowed. Because, It is private IP address." console.error(`Problem with request: ${e.message}`); }); req.end();

Debug

Known issues

breakingPackage switched from CommonJS to ESM and requires Node.js 20+.

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`.

affects: >=3.0.0

breakingDropped support for older Node.js versions (12, 14, 16), requiring Node.js 18+.

fix

Upgrade your Node.js runtime to 18 or higher. For Node.js 20+ and ESM, refer to the v3 breaking changes.

affects: >=2.0.0 <3.0.0

gotchaNode.js's built-in `fetch` API does not support custom `http.Agent` implementations, making it incompatible with `request-filtering-agent`.

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`.

affects: all

gotchaCIDR notation support for `allowIPAddressList` and `denyIPAddressList` was introduced in minor updates.

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.

affects: <3.2.0

Errors

Common errors & fixes

DNS lookup [IP_ADDRESS](family:[NUMBER], host:[HOSTNAME]) is not allowed. Because, It is private IP address.

Attempting to connect to a private or reserved IP address which is blocked by `request-filtering-agent` by default.

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.

ERR_REQUIRE_ESM: require() of ES Module .../request-filtering-agent/index.js from ... not supported.

Attempting to use `require()` with `request-filtering-agent` v3.x, which is an ESM-only package.

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`.

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

ipaddr.jsrequiredUsed for defining and checking IP address ranges and types (private, reserved, link-local).

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/azu/request-filtering-agent ↗

packagehttps://www.npmjs.com/package/request-filtering-agent ↗