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.

• What is SSRF (Server-side request forgery)? Tutorial & Examples

This library depends on ipaddr.js definitions. This library blocks the request to these IP addresses by default.

• Private IPv4 addresses
• Private IPv6 addresses
• Link-local addresses
• Reserved IP addresses

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

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

• Passing a custom agent to fetch() · Issue #1489 · nodejs/undici

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 http and https
• node-fetch
• Request
  • :memo: request's agent may be insecure
  • 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
  • Server-Side Request Forgery in Request · CVE-2023-28155 · GitHub Advisory Database
• node-http-proxy
• axios
• got

request-filtering-agent works with these libraries!

Install

Install with npm:

npm install request-filtering-agent

Support Node.js version

Version	Node.js 12	Node.js 14	Node.js 16	Node.js 18	Node.js 20
v1.x.x	Support	Support	Support	Support	Not Support
v2.0.0	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.

1const fetch = require("node-fetch");
2const { useAgent } = require("request-filtering-agent");
3const url = 'http://127.0.0.1:8080/';
4fetch(url, {
5    // use http or https agent for url
6    agent: useAgent(url)
7}).catch(err => {
8    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.
9});

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:

1const fetch = require("node-fetch");
2const { useAgent } = require("request-filtering-agent");
3const url = 'http://127.0.0.1.nip.io:8080/';
4fetch(url, {
5    agent: useAgent(url) // use http or https agent for url
6}).catch(err => {
7    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.
8});

It will prevent DNS rebinding

API

1export interface RequestFilteringAgentOptions {
2    // Allow to connect private IP address
3    // This includes Private IP addresses and Reserved IP addresses.
4    // https://en.wikipedia.org/wiki/Private_network
5    // https://en.wikipedia.org/wiki/Reserved_IP_addresses
6    // Example, http://127.0.0.1/, http://localhost/, https://169.254.169.254/
7    // Default: false
8    allowPrivateIPAddress?: boolean;
9    // Allow to connect meta address 0.0.0.0
10    // 0.0.0.0 (IPv4) and :: (IPv6) a meta address that routing another address
11    // https://en.wikipedia.org/wiki/Reserved_IP_addresses
12    // https://tools.ietf.org/html/rfc6890
13    // Default: false
14    allowMetaIPAddress?: boolean;
15    // Allow address list
16    // This values are preferred than denyAddressList
17    // Default: []
18    allowIPAddressList?: string[];
19    // Deny address list
20    // Default: []
21    denyIPAddressList?: string[];
22}
23/**
24 * A subclass of http.Agent with request filtering
25 */
26export declare class RequestFilteringHttpAgent extends http.Agent {
27    constructor(options?: http.AgentOptions & RequestFilteringAgentOptions);
28}
29/**
30 * A subclass of https.Agent with request filtering
31 */
32export declare class RequestFilteringHttpsAgent extends https.Agent {
33    constructor(options?: https.AgentOptions & RequestFilteringAgentOptions);
34}
35export declare const globalHttpAgent: RequestFilteringHttpAgent;
36export declare const globalHttpsAgent: RequestFilteringHttpsAgent;
37/**
38 * Get an agent for the url
39 * return http or https agent
40 * @param url
41 */
42export declare const useAgent: (url: string, options?: https.AgentOptions & RequestFilteringAgentOptions) => RequestFilteringHttpAgent | RequestFilteringHttpsAgent;

Example: Create an Agent with options

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

1const fetch = require("node-fetch");
2const { RequestFilteringHttpAgent } = require("request-filtering-agent");
3
4// Create http agent that allow 127.0.0.1, but it disallow other private ip
5const agent = new RequestFilteringHttpAgent({
6    allowIPAddressList: ["127.0.0.1"], // it is preferred than allowPrivateIPAddress option
7    allowPrivateIPAddress: false, // Default: false
8});
9// 127.0.0.1 is private ip address, but it is allowed
10const url = 'http://127.0.0.1:8080/';
11fetch(url, {
12    agent: agent
13}).then(res => {
14    console.log(res); // OK
15});

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

Changelog

See Releases page.

Running tests

Install devDependencies and Run yarn test:

yarn test

:memo: This testing require IPv6 supports:

• Travis CI: NG
• GitHub Actions: OK

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

• github/azu
• twitter/azu_re

License

MIT © azu