# request-filtering-agent

> An http(s).Agent implementation that block request Private IP address.

Latest version **3.3.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install request-filtering-agent
pnpm add request-filtering-agent
yarn add request-filtering-agent
bun add request-filtering-agent
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 3.3.0 |
| Published | 2026-11-19 |
| First published | 2019-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.0.0 |
| Dependencies | 1 |
| Unpacked size | 61.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 28 |
| Author | azu |
| Maintainers | azu |
| Keywords | http, https, proxy, agent, ssrf, security |

## Links

- npm: https://www.npmjs.com/package/request-filtering-agent
- Repository: https://github.com/azu/request-filtering-agent
- Issues: https://github.com/azu/request-filtering-agent/issues
- npm.io page: https://npm.io/package/request-filtering-agent

## Dependencies (1)

- [ipaddr.js](https://npm.io/package/ipaddr.js.md) ^2.5.0

## Recent versions

- 3.3.0 (latest) — 2026-11-19
- 3.2.2 — 2026-11-19
- 3.2.1 — 2026-06-29
- 3.2.0 — 2025-12-15
- 3.1.0 — 2025-12-15
- 3.0.2 — 2025-09-05
- 3.0.0 — 2025-08-24
- 2.0.1 — 2023-10-31
- 2.0.0 — 2023-10-21
- 1.1.2 — 2022-07-04
- 1.1.0 — 2022-04-24
- 1.0.7 — 2021-07-20
- 1.0.6 — 2021-06-04
- 1.0.5 — 2020-07-04
- 1.0.4 — 2019-09-05
- … 3 more at https://npm.io/package/request-filtering-agent/versions

## README

# request-filtering-agent [![Actions Status](https://github.com/azu/request-filtering-agent/workflows/ci/badge.svg)](https://github.com/azu/request-filtering-agent/actions)

An [http(s).Agent](https://nodejs.org/api/http.html#http_class_http_agent) class block the request to [Private IP addresses](https://en.wikipedia.org/wiki/Private_network) and [Reserved IP addresses](https://en.wikipedia.org/wiki/Reserved_IP_addresses).

It helps to prevent [server-side request forgery (SSRF)](https://en.wikipedia.org/wiki/Server-side_request_forgery) attack.

- [What is SSRF (Server-side request forgery)? Tutorial & Examples](https://portswigger.net/web-security/ssrf)

This library depends on [ipaddr.js](https://github.com/whitequark/ipaddr.js) definitions.
This library blocks the request to these IP addresses by default.

- [Private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses)
- [Private IPv6 addresses](https://en.wikipedia.org/wiki/Private_network#Private_IPv6_addresses)
- [Link-local addresses](https://en.wikipedia.org/wiki/Private_network#Link-local_addresses)
- [Reserved IP addresses](https://en.wikipedia.org/wiki/Reserved_IP_addresses)

So, This library block the request to non-`unicast` IP addresses.

### Which IP addresses are allowed?

This library allows the request only if the destination IP address is a public address.
It checks the IP address that the request actually connects to, after DNS lookup.

- IPv4: the address is allowed if [ipaddr.js](https://github.com/whitequark/ipaddr.js) classifies it as `unicast`
- IPv6: the address is allowed if ipaddr.js classifies it as `unicast` **and** it is in `2000::/3`

`2000::/3` is the only range that IANA allocates as Global Unicast ([IANA IPv6 Address Space](https://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.xhtml)).
Public IPv6 addresses on the Internet start with `2` or `3`, like `2001:4860:4860::8888`.
Other IPv6 addresses are reserved, deprecated, or for special purposes, so this library blocks them even if ipaddr.js does not know the range.

| Destination                               | Example                                             | Result  |
| ----------------------------------------- | --------------------------------------------------- | ------- |
| Public IPv4 address                       | `8.8.8.8`                                           | Allowed |
| Public IPv6 address in `2000::/3`         | `2001:4860:4860::8888`                              | Allowed |
| Loopback                                  | `127.0.0.1`, `::1`                                  | Blocked |
| Private and link-local address            | `10.0.0.1`, `169.254.169.254`, `fc00::1`, `fe80::1` | Blocked |
| Meta address                              | `0.0.0.0`, `::`                                     | Blocked |
| IPv4-mapped IPv6 address                  | `::ffff:127.0.0.1`, `::ffff:8.8.8.8`                | Blocked |
| IPv4-compatible IPv6 address (deprecated) | `::127.0.0.1` (= `::7f00:1`)                        | Blocked |
| Special range in `2000::/3`               | `2001:db8::1`, `2002::1` (6to4)                     | Blocked |
| Other IPv6 address out of `2000::/3`      | `fec0::1`, `64:ff9b::808:808` (NAT64)               | Blocked |

:memo: An IPv6 address that embeds an IPv4 address (IPv4-mapped, NAT64, 6to4, etc.) is blocked even if the embedded IPv4 address is public.

If you need to connect to a blocked address, use `allowPrivateIPAddress` with `filter`. `allowIPAddressList` also works, but it is deprecated.

:warning: Node.js's built-in `fetch` does not support `http.Agent`.

- [Support nodejs/undici · Issue #23 · azu/request-filtering-agent](https://github.com/azu/request-filtering-agent/issues/23)

## Support `http.Agent` libraries

This library provides Node.js's [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) implementation.
[http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) is supported by popular library.

- Node.js's built-in `http` and `https`
- [node-fetch](https://github.com/bitinn/node-fetch)
- [node-http-proxy](https://github.com/http-party/node-http-proxy)
- [axios](https://github.com/axios/axios)
- [got](https://github.com/sindresorhus/got)
- [@cypress/request](https://github.com/cypress-io/request)
    - :memo: [Request](https://github.com/request/request) is deprecated and it has SSRF issue
    - [CVE-2023-28155 Request allows a bypass of SSRF mitigations via an attacker-controller server that does a cross-protocol redirect · Issue #3442 · request/request](https://github.com/request/request/issues/3442)
    - [Server-Side Request Forgery in Request · CVE-2023-28155 · GitHub Advisory Database](https://github.com/advisories/GHSA-p8p7-x288-28g6)

`request-filtering-agent` works with these libraries!

## Install

Install with [npm](https://www.npmjs.com/):

    npm install request-filtering-agent

### Support Node.js version

| Version | Node.js 14 | Node.js 16 | Node.js 18 | Node.js 20 | Node.js 22 |
| :------ | :--------- | :--------- | :--------- | :--------- | :--------- |
| v1.x.x  | Support    | Support    | Support    | No Support | No Support |
| v2.x.x  | No Support | No Support | Support    | Support    | Support    |
| v3.x.x  | No Support | No Support | No Support | Support    | Support    |

## Usage

`useAgent(url, options)` return an agent for the url.

The agent blocks the request to [Private network](https://en.wikipedia.org/wiki/Private_network) and [Reserved IP addresses](https://en.wikipedia.org/wiki/Reserved_IP_addresses) by default.

```js
const fetch = require("node-fetch");
const { useAgent } = require("request-filtering-agent");
const url = "http://127.0.0.1:8080/";
fetch(url, {
    // use http or https agent for url
    agent: useAgent(url)
}).catch((err) => {
    console.err(err); // DNS lookup 127.0.0.1(family:4, host:127.0.0.1.nip.io) is not allowed. Because, It is private IP address.
});
```

`request-filtering-agent` support loopback domain like [nip.io](http://nip.io).
This library detects the IP address that is dns lookup-ed.

```
$ dig 127.0.0.1.nip.io

;127.0.0.1.nip.io.		IN	A

;; ANSWER SECTION:
127.0.0.1.nip.io.	300	IN	A	127.0.0.1
```

Example code:

```js
const fetch = require("node-fetch");
const { useAgent } = require("request-filtering-agent");
const url = "http://127.0.0.1.nip.io:8080/";
fetch(url, {
    agent: useAgent(url) // use http or https agent for url
}).catch((err) => {
    console.err(err); // DNS lookup 127.0.0.1(family:4, host:127.0.0.1.nip.io) is not allowed. Because, It is private IP address.
});
```

It will prevent [DNS rebinding](https://en.wikipedia.org/wiki/DNS_rebinding)

### Error handling

This library blocks a request by an error. It does not throw the error synchronously, and it does not crash the process by itself.
The error is passed to the request in the same way as other connection errors such as `ECONNREFUSED`.

- Promise-based libraries such as `node-fetch`: the returned `Promise` is rejected. Use `try`/`catch` or `.catch()`.
- Node.js's built-in `http.request` and `https.request`: the request emits an `error` event. Add an `error` listener to the request.

```js
const http = require("node:http");
const { globalHttpAgent } = require("request-filtering-agent");

const req = http.get("http://127.0.0.1:8080/", { agent: globalHttpAgent });
// Without this listener, Node.js throws the error as an uncaught exception and the process exits
req.on("error", (error) => {
    console.error(error); // DNS lookup 127.0.0.1(...) is not allowed. Because, It is private IP address.
});
```

:warning: Node.js exits the process when an `EventEmitter` emits an `error` event without a listener.
It is [the behavior of Node.js](https://nodejs.org/api/events.html#error-events), and it is the same for any request error.
A crash caused by a missing error handling in an application is not a vulnerability of this library.

The same applies to the following cases:

- An error thrown by the `filter` function blocks the request, and it is passed to the request as an error.
- A custom `lookup` function that returns an invalid result (e.g. `undefined` instead of an array) behaves in the same way as Node.js's `http.Agent`. This library does not validate the result format of a custom `lookup` function.

## API

```ts
export interface RequestFilteringAgentOptions {
    // Allow to connect private IP address
    // This includes Private IP addresses and Reserved IP addresses.
    // https://en.wikipedia.org/wiki/Private_network
    // https://en.wikipedia.org/wiki/Reserved_IP_addresses
    // Example, http://127.0.0.1/, http://localhost/, https://169.254.169.254/
    // Default: false
    allowPrivateIPAddress?: boolean;
    // Allow to connect meta address 0.0.0.0
    // 0.0.0.0 (IPv4) and :: (IPv6) a meta address that routing another address
    // https://en.wikipedia.org/wiki/Reserved_IP_addresses
    // https://tools.ietf.org/html/rfc6890
    // Default: false
    allowMetaIPAddress?: boolean;
    // [Deprecated] Use `filter` instead.
    // Allow address list
    // It supports CIDR notation.
    // This values are preferred than denyAddressList
    // Default: []
    allowIPAddressList?: string[];
    // [Deprecated] Use `filter` instead.
    // Deny address list
    // It supports CIDR notation.
    // The address is compared as it is. It is not a security boundary.
    // See "Security considerations for denyIPAddressList" section.
    // Default: []
    denyIPAddressList?: string[];
    // Custom filter function that is called with the resolved and normalized IP address.
    // It is called after the built-in checks (allowPrivateIPAddress, allowMetaIPAddress, denyIPAddressList) pass.
    // It is also called for the address that is allowed by allowIPAddressList.
    // Only a strict `true` return value allows the connection.
    // Default: undefined
    filter?: RequestFilteringAgentFilter;
}
export interface RequestFilteringAgentFilterContext {
    // The original IP address before normalization. Example: "::ffff:7f00:1"
    raw: string;
    // IP family of the normalized address
    family: 4 | 6;
    // The requested hostname. It is undefined when the request uses a literal IP address.
    host?: string;
    // The range name of the normalized address defined by ipaddr.js
    // It is the same range that the built-in checks use:
    // "unicast" is a public address, and an IPv6 address outside of 2000::/3 is "reserved" instead of "unicast".
    // Example: "unicast", "private", "loopback", "linkLocal", "unspecified", "reserved"
    range: string;
}
// `address` is the normalized IP address after DNS resolution.
// IPv4-mapped IPv6 address is converted to IPv4 address (e.g. "::ffff:7f00:1" → "127.0.0.1")
export type RequestFilteringAgentFilter = (address: string, context: RequestFilteringAgentFilterContext) => boolean;
/**
 * A subclass of http.Agent with request filtering
 */
export declare class RequestFilteringHttpAgent extends http.Agent {
    constructor(options?: http.AgentOptions & RequestFilteringAgentOptions);
}
/**
 * A subclass of https.Agent with request filtering
 */
export declare class RequestFilteringHttpsAgent extends https.Agent {
    constructor(options?: https.AgentOptions & RequestFilteringAgentOptions);
}
export declare const globalHttpAgent: RequestFilteringHttpAgent;
export declare const globalHttpsAgent: RequestFilteringHttpsAgent;
/**
 * Get an agent for the url
 * return http or https agent
 * @param url
 */
export declare const useAgent: (
    url: string,
    options?: https.AgentOptions & RequestFilteringAgentOptions
) => RequestFilteringHttpAgent | RequestFilteringHttpsAgent;
```

### Example: Filter the request with `filter` function

`filter` function receives the IP address after DNS resolution and normalization.
The `context.raw` is the original IP address before normalization.
The request is allowed only when `filter` returns `true`.

`filter` is called after the built-in checks pass, and it is also called for the address that is allowed by `allowIPAddressList`.
If `filter` returns a `Promise`, the request is blocked, because `filter` must return `true` synchronously.
If you want to allow some private IP addresses, set `allowPrivateIPAddress: true` and check `context.range` in `filter`.

Notes:

- `filter` is called when the agent creates a new connection. It is not called for a request that reuses a keep-alive connection, because the address of the connection is already checked.
- If DNS lookup returns multiple IP addresses, `filter` is called for each address. The request is blocked if `filter` rejects any of them.

```js
const fetch = require("node-fetch");
const { RequestFilteringHttpAgent } = require("request-filtering-agent");

// Allow public IP addresses and 127.0.0.1, but disallow other private IP addresses
const agent = new RequestFilteringHttpAgent({
    allowPrivateIPAddress: true,
    filter: (address, { range }) => {
        return range === "unicast" || address === "127.0.0.1";
    }
});
const url = 'http://127.0.0.1:8080/';
fetch(url, {
    agent: agent
}).then(res => {
    console.log(res); // OK
});
```

### Example: Use CIDR in `filter` function

`filter` does not provide CIDR matching.
You can use Node.js built-in [`net.BlockList`](https://nodejs.org/api/net.html#class-netblocklist) to match CIDR ranges.

```js
const net = require("node:net");
const fetch = require("node-fetch");
const { RequestFilteringHttpAgent } = require("request-filtering-agent");

// Migration from `allowIPAddressList: ["192.168.1.0/24"]`
const allowList = new net.BlockList();
allowList.addSubnet("192.168.1.0", 24, "ipv4");
const allowAgent = new RequestFilteringHttpAgent({
    allowPrivateIPAddress: true,
    filter: (address, { family, range }) => {
        return range === "unicast" || allowList.check(address, family === 4 ? "ipv4" : "ipv6");
    }
});

// Migration from `allowPrivateIPAddress: true, denyIPAddressList: ["192.168.1.0/24"]`
const denyList = new net.BlockList();
denyList.addSubnet("192.168.1.0", 24, "ipv4");
const denyAgent = new RequestFilteringHttpAgent({
    allowPrivateIPAddress: true,
    filter: (address, { family }) => {
        return !denyList.check(address, family === 4 ? "ipv4" : "ipv6");
    }
});
```

### Example: Create an Agent with options

:warning: `allowIPAddressList` and `denyIPAddressList` are deprecated. Use `filter` instead.

An agent that allow requesting `127.0.0.1`, but it disallows other Private IP.

```js
const fetch = require("node-fetch");
const { RequestFilteringHttpAgent } = require("request-filtering-agent");

// Create http agent that allow 127.0.0.1, but it disallow other private ip
const agent = new RequestFilteringHttpAgent({
    allowIPAddressList: ["127.0.0.1"], // it is preferred than allowPrivateIPAddress option
    allowPrivateIPAddress: false // Default: false
});
// 127.0.0.1 is private ip address, but it is allowed
const url = "http://127.0.0.1:8080/";
fetch(url, {
    agent: agent
}).then((res) => {
    console.log(res); // OK
});

// Allow requests to a specific CIDR range
const agentWithCIDR = new RequestFilteringHttpAgent({
    allowIPAddressList: ["192.168.1.0/24"]
});
const urlInCIDR = "http://192.168.1.1:8080/";
fetch(urlInCIDR, {
    agent: agentWithCIDR
}).then((res) => {
    console.log(res); // OK
});
```

### Security considerations for `denyIPAddressList`

:warning: `denyIPAddressList` is deprecated. Use `filter` instead. `filter` receives the normalized IP address, so `::ffff:169.254.169.254` is passed as `169.254.169.254`.

`denyIPAddressList` is not a security boundary when `allowPrivateIPAddress` is `true`.
The same IP address can be written in many forms, so it is hard to deny a destination as you intended.

For example, `denyIPAddressList: ["169.254.169.254"]` does not block the following addresses, because they are written in another form.
A single IP address in the list is compared as a string, and this library does not normalize the address.

```js
// All of them connect to 169.254.169.254, but they do not match "169.254.169.254" or "169.254.0.0/16"
"::ffff:169.254.169.254";
"::ffff:a9fe:a9fe";
"0:0:0:0:0:ffff:a9fe:a9fe";
```

To deny the destination with `denyIPAddressList`, you need to list every form of the address, and it is easy to miss one.
With `allowPrivateIPAddress: false` (default), these addresses are blocked, because they are not `unicast` addresses.

If you need to block specific private IP addresses like cloud metadata endpoint (`169.254.169.254`), we recommend the following:

- Keep `allowPrivateIPAddress: false`, or use `filter` to allow only the required addresses. `filter` receives the normalized IP address and its range
- Validate and normalize the host in your application before passing the request to this agent
- Block the destination at the network layer (e.g. firewall, egress proxy, [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html))

## Related

- [welefen/ssrf-agent: make http(s) request to prevent SSRF](https://github.com/welefen/ssrf-agent)
    - It provides only high level wrapper
    - It only handles Private IP address that is definition in [node-ip](https://github.com/indutny/node-ip/blob/43e442366bf5a93493c8c4c36736f87d675b0c3d/lib/ip.js#L302-L314)
        - Missing Meta IP Address like `0.0.0.0`

## Changelog

See [Releases page](https://github.com/azu/request-filtering-agent/releases).

## Running tests

Install devDependencies and Run `pnpm test`:

    pnpm test

The tests start a DNS server on `127.0.0.1` and send real DNS queries to it, so most tests do not depend on external DNS.

- Tests named `E2E:` use real DNS (`nip.io`) and connect to the Internet. Set `SKIP_NETWORK_TEST=1` to skip them
- Tests that connect to an IPv6 address are skipped if the environment does not support IPv6

## Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, [please create an issue](https://github.com/azu/request-filtering-agent/issues).

For security issue, please see [SECURITY.md](./SECURITY.md)

1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D

## Author

- [github/azu](https://github.com/azu)
- [twitter/azu_re](https://twitter.com/azu_re)

## License

MIT © azu

---
_Source: https://npm.io/package/request-filtering-agent · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
