{"id":15659655,"url":"https://github.com/azu/request-filtering-agent","last_synced_at":"2025-08-09T02:19:42.086Z","repository":{"id":35088263,"uuid":"204935733","full_name":"azu/request-filtering-agent","owner":"azu","description":"An http(s).Agent implementation that block request Private/Reserved IP addresses. Prevent SSRF.","archived":false,"fork":false,"pushed_at":"2024-02-10T00:20:38.000Z","size":156,"stargazers_count":22,"open_issues_count":3,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-13T09:38:42.425Z","etag":null,"topics":["agent","block","http","node","nodejs","security","ssrf"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azu.png","metadata":{"funding":{"github":"azu"},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-08-28T13:15:16.000Z","updated_at":"2024-12-02T13:53:19.000Z","dependencies_parsed_at":"2024-02-10T01:26:47.705Z","dependency_job_id":null,"html_url":"https://github.com/azu/request-filtering-agent","commit_stats":{"total_commits":74,"total_committers":4,"mean_commits":18.5,"dds":0.09459459459459463,"last_synced_commit":"81b1764f454d1b805e6acad10a1727d2ff255597"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Frequest-filtering-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Frequest-filtering-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Frequest-filtering-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azu%2Frequest-filtering-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azu","download_url":"https://codeload.github.com/azu/request-filtering-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230423563,"owners_count":18223435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","block","http","node","nodejs","security","ssrf"],"created_at":"2024-10-03T13:18:01.928Z","updated_at":"2024-12-19T11:12:46.053Z","avatar_url":"https://github.com/azu.png","language":"TypeScript","funding_links":["https://github.com/sponsors/azu"],"categories":[],"sub_categories":[],"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)\n\nAn [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).\n\nIt helps to prevent [server-side request forgery (SSRF)](https://en.wikipedia.org/wiki/Server-side_request_forgery) attack.\n\n- [What is SSRF (Server-side request forgery)? Tutorial \u0026 Examples](https://portswigger.net/web-security/ssrf)\n\nThis library depends on [ipaddr.js](https://github.com/whitequark/ipaddr.js) definitions.\nThis library blocks the request to these IP addresses by default.\n\n- [Private IPv4 addresses](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses)\n- [Private IPv6 addresses](https://en.wikipedia.org/wiki/Private_network#Private_IPv6_addresses)\n- [Link-local addresses](https://en.wikipedia.org/wiki/Private_network#Link-local_addresses)\n- [Reserved IP addresses](https://en.wikipedia.org/wiki/Reserved_IP_addresses)\n\nSo, This library block the request to non-`unicast` IP addresses.\n\n:warning: Node.js's built-in `fetch` does not support `http.Agent`.\n\n- [Support nodejs/undici · Issue #23 · azu/request-filtering-agent](https://github.com/azu/request-filtering-agent/issues/23)\n\n## Support `http.Agent` libraries\n\nThis library provides Node.js's [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) implementation.\n[http.Agent](https://nodejs.org/api/http.html#http_class_http_agent) is supported by popular library.\n\n- Node.js's built-in `http` and `https`\n- [node-fetch](https://github.com/bitinn/node-fetch)\n- [node-http-proxy](https://github.com/http-party/node-http-proxy)\n- [axios](https://github.com/axios/axios)\n- [got](https://github.com/sindresorhus/got)\n- [@cypress/request](https://github.com/cypress-io/request)\n  - :memo: [Request](https://github.com/request/request) is deprecated and it has SSRF issue\n  - [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)\n  - [Server-Side Request Forgery in Request · CVE-2023-28155 · GitHub Advisory Database](https://github.com/advisories/GHSA-p8p7-x288-28g6)\n\n\n`request-filtering-agent` works with these libraries!\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/):\n\n    npm install request-filtering-agent\n\n### Support Node.js version\n\n| Version | Node.js 12 | Node.js 14 | Node.js 16 | Node.js 18 | Node.js 20  |\n| :------ | :--------- | :--------- | :--------- | :--------- | :---------- |\n| v1.x.x  | Support    | Support    | Support    | Support    | Not Support |\n| v2.0.0  | No Support | No Support | No Support | Support    | Support     |\n\n## Usage\n\n`useAgent(url, options)` return an agent for the url.\n\nThe 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.\n\n```js\nconst fetch = require(\"node-fetch\");\nconst { useAgent } = require(\"request-filtering-agent\");\nconst url = 'http://127.0.0.1:8080/';\nfetch(url, {\n    // use http or https agent for url\n    agent: useAgent(url)\n}).catch(err =\u003e {\n    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.\n});\n```\n\n`request-filtering-agent` support loopback domain like [nip.io](http://nip.io).\nThis library detects the IP address that is dns lookup-ed.\n\n```\n$ dig 127.0.0.1.nip.io\n\n;127.0.0.1.nip.io.\t\tIN\tA\n\n;; ANSWER SECTION:\n127.0.0.1.nip.io.\t300\tIN\tA\t127.0.0.1\n```\n\nExample code:\n\n```js\nconst fetch = require(\"node-fetch\");\nconst { useAgent } = require(\"request-filtering-agent\");\nconst url = 'http://127.0.0.1.nip.io:8080/';\nfetch(url, {\n    agent: useAgent(url) // use http or https agent for url\n}).catch(err =\u003e {\n    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.\n});\n```\n\nIt will prevent [DNS rebinding](https://en.wikipedia.org/wiki/DNS_rebinding)\n\n## API\n\n```ts\nexport interface RequestFilteringAgentOptions {\n    // Allow to connect private IP address\n    // This includes Private IP addresses and Reserved IP addresses.\n    // https://en.wikipedia.org/wiki/Private_network\n    // https://en.wikipedia.org/wiki/Reserved_IP_addresses\n    // Example, http://127.0.0.1/, http://localhost/, https://169.254.169.254/\n    // Default: false\n    allowPrivateIPAddress?: boolean;\n    // Allow to connect meta address 0.0.0.0\n    // 0.0.0.0 (IPv4) and :: (IPv6) a meta address that routing another address\n    // https://en.wikipedia.org/wiki/Reserved_IP_addresses\n    // https://tools.ietf.org/html/rfc6890\n    // Default: false\n    allowMetaIPAddress?: boolean;\n    // Allow address list\n    // This values are preferred than denyAddressList\n    // Default: []\n    allowIPAddressList?: string[];\n    // Deny address list\n    // Default: []\n    denyIPAddressList?: string[];\n}\n/**\n * A subclass of http.Agent with request filtering\n */\nexport declare class RequestFilteringHttpAgent extends http.Agent {\n    constructor(options?: http.AgentOptions \u0026 RequestFilteringAgentOptions);\n}\n/**\n * A subclass of https.Agent with request filtering\n */\nexport declare class RequestFilteringHttpsAgent extends https.Agent {\n    constructor(options?: https.AgentOptions \u0026 RequestFilteringAgentOptions);\n}\nexport declare const globalHttpAgent: RequestFilteringHttpAgent;\nexport declare const globalHttpsAgent: RequestFilteringHttpsAgent;\n/**\n * Get an agent for the url\n * return http or https agent\n * @param url\n */\nexport declare const useAgent: (url: string, options?: https.AgentOptions \u0026 RequestFilteringAgentOptions) =\u003e RequestFilteringHttpAgent | RequestFilteringHttpsAgent;\n```\n\n### Example: Create an Agent with options\n\nAn agent that allow requesting `127.0.0.1`, but it disallows other Private IP.\n\n```js\nconst fetch = require(\"node-fetch\");\nconst { RequestFilteringHttpAgent } = require(\"request-filtering-agent\");\n\n// Create http agent that allow 127.0.0.1, but it disallow other private ip\nconst agent = new RequestFilteringHttpAgent({\n    allowIPAddressList: [\"127.0.0.1\"], // it is preferred than allowPrivateIPAddress option\n    allowPrivateIPAddress: false, // Default: false\n});\n// 127.0.0.1 is private ip address, but it is allowed\nconst url = 'http://127.0.0.1:8080/';\nfetch(url, {\n    agent: agent\n}).then(res =\u003e {\n    console.log(res); // OK\n});\n```\n\n## Related\n\n- [welefen/ssrf-agent: make http(s) request to prevent SSRF](https://github.com/welefen/ssrf-agent)\n    - It provides only high level wrapper\n    - 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)\n        - Missing Meta IP Address like `0.0.0.0`\n\n## Changelog\n\nSee [Releases page](https://github.com/azu/request-filtering-agent/releases).\n\n## Running tests\n\nInstall devDependencies and Run `yarn test`:\n\n    yarn test\n\n:memo: This testing require IPv6 supports:\n\n- Travis CI: NG \n- GitHub Actions: OK\n\n## Contributing\n\nPull requests and stars are always welcome.\n\nFor bugs and feature requests, [please create an issue](https://github.com/azu/request-filtering-agent/issues).\n\nFor security issue, please see [SECURITY.md](./SECURITY.md)\n\n1. Fork it!\n2. Create your feature branch: `git checkout -b my-new-feature`\n3. Commit your changes: `git commit -am 'Add some feature'`\n4. Push to the branch: `git push origin my-new-feature`\n5. Submit a pull request :D\n\n## Author\n\n- [github/azu](https://github.com/azu)\n- [twitter/azu_re](https://twitter.com/azu_re)\n\n## License\n\nMIT © azu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Frequest-filtering-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazu%2Frequest-filtering-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazu%2Frequest-filtering-agent/lists"}