An http(s).Agent implementation that block request Private IP address.
npm install request-filtering-agentAn 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.
- Support nodejs/undici · Issue #23 · azu/request-filtering-agent
http.Agent librariesThis 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
- node-http-proxy
- axios
- got
- @cypress/request
- :memo: 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
- Server-Side Request Forgery in Request · CVE-2023-28155 · GitHub Advisory Database
request-filtering-agent works with these libraries!
Install with npm:
npm install request-filtering-agent
| 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 |
useAgent(url, options) return an agent for the url.
The agent blocks the request to Private network and 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.
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
`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;
// Allow address list
// It supports CIDR notation.
// This values are preferred than denyAddressList
// Default: []
allowIPAddressList?: string[];
// Deny address list
// It supports CIDR notation.
// Default: []
denyIPAddressList?: string[];
}
/**
* 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;
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
});
// Deny requests to a specific CIDR range
const agentWithDenyCIDR = new RequestFilteringHttpAgent({
allowPrivateIPAddress: true,
denyIPAddressList: ["192.168.1.0/24"],
});
const urlInDenyCIDR = 'http://192.168.1.1:8080/';
fetch(urlInDenyCIDR, {
agent: agentWithDenyCIDR
}).catch(err => {
console.err(err); // DNS lookup 192.168.1.1(family:4, host:192.168.1.1) is not allowed. Because It is defined in denyIPAddressList.
});
`
- 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
See Releases page.
Install devDependencies and Run yarn test:
yarn test
:memo: This testing require IPv6 supports:
- Travis CI: NG
- GitHub Actions: OK
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:
4. Push to the branch:
5. Submit a pull request :D
MIT © azu