npm.io
3.3.0 • Published 7h ago

request-filtering-agent

Licence
MIT
Version
3.3.0
Deps
1
Size
62 kB
Vulns
0
Weekly
0
Stars
28

request-filtering-agent Actions Status

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 unicast and it is in 2000::/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.

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

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

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

For security issue, please see 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

License

MIT azu

Keywords