request-filtering-agent 
An http(s).Agent class block the request to Private IP addresses and Reserved IP addresses.
It helps to prevent server-side request forgery (SSRF) attack.
This library depends on ipaddr.js definitions. This library blocks the request to these IP addresses by default.
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 classifies it as
unicast - IPv6: the address is allowed if ipaddr.js classifies it as
unicastand it is in2000::/3
2000::/3 is the only range that IANA allocates as Global Unicast (IANA IPv6 Address Space).
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 |
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.
Node.js's built-in fetch does not support http.Agent.
Support http.Agent libraries
This library provides Node.js's http.Agent implementation. http.Agent is supported by popular library.
- Node.js's built-in
httpandhttps - node-fetch
- node-http-proxy
- axios
- got
- @cypress/request
request-filtering-agent works with these libraries!
Install
Install with npm:
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 and Reserved IP addresses by default.
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.
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:
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
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 returnedPromiseis rejected. Usetry/catchor.catch(). - Node.js's built-in
http.requestandhttps.request: the request emits anerrorevent. Add anerrorlistener to the request.
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.
});
Node.js exits the process when an EventEmitter emits an error event without a listener.
It is the behavior of Node.js, 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
filterfunction blocks the request, and it is passed to the request as an error. - A custom
lookupfunction that returns an invalid result (e.g.undefinedinstead of an array) behaves in the same way as Node.js'shttp.Agent. This library does not validate the result format of a customlookupfunction.
API
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:
filteris 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,
filteris called for each address. The request is blocked iffilterrejects any of them.
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 to match CIDR ranges.
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
allowIPAddressList and denyIPAddressList are deprecated. Use filter instead.
An agent that allow requesting 127.0.0.1, but it disallows other Private IP.
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
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.
// 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 usefilterto allow only the required addresses.filterreceives 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)
Related
- welefen/ssrf-agent: make http(s) request to prevent SSRF
- It provides only high level wrapper
- It only handles Private IP address that is definition in node-ip
- Missing Meta IP Address like
0.0.0.0
- Missing Meta IP Address like
Changelog
See Releases page.
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. SetSKIP_NETWORK_TEST=1to 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.
For security issue, please see SECURITY.md
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request :D
Author
License
MIT azu