{"id":21073929,"url":"https://github.com/timokoessler/easy-waf","last_synced_at":"2025-04-07T12:05:14.364Z","repository":{"id":60701208,"uuid":"514525506","full_name":"timokoessler/easy-waf","owner":"timokoessler","description":"An easy-to-use Web Application Firewall (WAF) for Node.js. Can be used with Express, Fastify, NextJS, NuxtJS ... or plain Node.js http.","archived":false,"fork":false,"pushed_at":"2025-01-08T09:38:40.000Z","size":767,"stargazers_count":44,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T11:03:57.307Z","etag":null,"topics":["javascript","mit-license","nodejs","security","typescript","waf","web-application-firewall","web-application-security"],"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/timokoessler.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-16T08:47:14.000Z","updated_at":"2025-03-20T15:19:49.000Z","dependencies_parsed_at":"2024-05-17T11:27:23.611Z","dependency_job_id":"3ef37a9e-23f8-452b-a723-f317a995e1b7","html_url":"https://github.com/timokoessler/easy-waf","commit_stats":{"total_commits":86,"total_committers":1,"mean_commits":86.0,"dds":0.0,"last_synced_commit":"7e2c236b970dcad7ec5e021a4ed4f5c473359636"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timokoessler%2Feasy-waf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timokoessler%2Feasy-waf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timokoessler%2Feasy-waf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timokoessler%2Feasy-waf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timokoessler","download_url":"https://codeload.github.com/timokoessler/easy-waf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648976,"owners_count":20972945,"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":["javascript","mit-license","nodejs","security","typescript","waf","web-application-firewall","web-application-security"],"created_at":"2024-11-19T19:13:45.909Z","updated_at":"2025-04-07T12:05:14.343Z","avatar_url":"https://github.com/timokoessler.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Easy WAF (Beta) 🧱\n\n\u003e [!TIP]\n\u003e Have a look at [Zen by Aikido](https://www.aikido.dev/zen) if you are looking for a professional embedded firewall with fewer false positives, better performance and a web dashboard to monitor your app.\n\u003e Available for [Node.js](https://github.com/AikidoSec/firewall-node), [Python](https://github.com/AikidoSec/firewall-python) and [PHP](https://github.com/AikidoSec/firewall-php).\n\nAn easy-to-use Web Application Firewall (WAF) for Node.js. Can be used with Express, Fastify, NextJS, NuxtJS ... or Node.js http.\n\n[![npm version](https://badgen.net/npm/v/easy-waf)](https://www.npmjs.com/package/easy-waf)\n[![npm downloads](https://badgen.net/npm/dt/easy-waf)](https://www.npmjs.com/package/easy-waf)\n[![license](https://badgen.net/npm/license/easy-waf)](LICENSE)\n[![CodeFactor](https://www.codefactor.io/repository/github/timokoessler/easy-waf/badge)](https://www.codefactor.io/repository/github/timokoessler/easy-waf)\n[![codecov](https://codecov.io/gh/timokoessler/easy-waf/branch/main/graph/badge.svg?token=62LUMSMRL0)](https://codecov.io/gh/timokoessler/easy-waf)\n[![install size](https://packagephobia.com/badge?p=easy-waf)](https://packagephobia.com/result?p=easy-waf)\n\n```javascript\nimport express from 'express';\nimport easyWaf from 'easy-waf'; // CommonJS: require('easy-waf').default;\nconst app = express();\n\napp.use(easyWaf());\n\napp.listen(3000);\n```\n\n\u003e [!WARNING]\n\u003e This software tries to defend many common attacks while keeping the rate of false positives low. There will always be methods to bypass this WAF. Therefore, using this package is not a reason to neglect security when developing an application. Always validate user input! This software should be used with caution and is more an educational tool than a professional security solution.\n\n## Features\n\n-   Restrict allowed HTTP methods and add your own ip black- and whitelist\n-   Blocks requests from bad bots and fake crawlers\n-   Blocks malicious requests:\n    -   CRLF Injection\n    -   Cross-Site-Scripting (XSS)\n    -   Directory / Path Traversal\n    -   HTTP Parameter Pollution\n    -   Open Redirect / Server Side Request Forgery (SSRF) (queryUrlWhitelist option must be set)\n    -   Prototype Pollution\n    -   SQL Injections and NoSQL Injections\n-   Can block requests from the Tor network (disabled by default)\n-   Compatible with many popular web frameworks and with the integrated Node.js HTTP server\n-   Supports ES modules and CommonJS\n\n## Installation\n\n\u003e [!TIP]\n\u003e I strongly recommend to activate the \"dryMode\" at the beginning to be able to identify possible false positives from the logs.\n\u003e If EasyWAF should parse bodies, bind a body-parser middleware to your app before adding EasyWAF.\n\n```bash\nnpm i easy-waf\n```\n\nIn the [examples](examples/) folder you can find samples of how to integrate EasyAF into your application.\n\nIf you run your Node.js app behind a reverse proxy, don't forget to set the `trustProxy` option.\nTo enable Open Redirect protection, configure the `queryUrlWhitelist` option.\n\n## Configuration\n\nEasyWAF is easy to use without the need for much configuration, but there are still many customization options.\n\n```javascript\napp.use(\n    easyWaf({\n        allowedHTTPMethods: ['GET', 'POST'],\n        queryUrlWhitelist: ['github.com'],\n        modules: {\n            directoryTraversal: {\n                enabled: true,\n                excludePaths: /^\\/exclude$/i,\n            },\n        },\n    }),\n);\n```\n\n| Option                     | Type           | Default                             | Description                                                                                                                                            |\n| -------------------------- | -------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| allowedHTTPMethods         | array          | undefined                           | List of all HTTP request methods that are allowed. All other request methods will be blocked. By default, all HTTP methods are allowed.                |\n| customBlockedPage          | string         | undefined                           | Add HTML code to override the default \"Request blocked\" page. [View example with placeholders](examples/custom-blocked-page.js)                        |\n| queryUrlWhitelist          | array          | undefined                           | List of urls that are allowed to be included in the path or query of the request url. By default, all urls are allowed. (Open Redirect / SSRF)         |\n| disableLogging             | boolean        | false                               | If true, nothing is logged. _This is not recommended!_                                                                                                 |\n| dryMode                    | boolean        | false                               | If true, suspicious requests are only logged and not blocked. In addition, the log format is changed to prevent an IPS from blocking the IP.           |\n| ipBlacklist                | array          | []                                  | All requests by ips on the blacklist are blocked. CIDR notation is supported (IPv4 and IPv6). On single addresses, a prefix of /32 or /128 is assumed. |\n| ipWhitelist                | array          | []                                  | All requests by ips on the whitelist are never blocked. CIDR notation is supported.                                                                    |\n| modules[name].enabled      | boolean        | true, except \"Block Tor Exit Nodes\" | This option allows you to completely disable a specific module.                                                                                        |\n| modules[name].excludePaths | boolean        | undefined                           | Exclude paths from being checked by this module with a regex.                                                                                          |\n| postBlockHook              | callback       | undefined                           | Run your own code after a request is blocked. For example, you can send a notification.                                                                |\n| preBlockHook               | callback       | undefined                           | Run your own code before a request is blocked. Return false if the request should not be blocked.                                                      |\n| trustProxy                 | string / array | []                                  | If a reverse proxy is used, this setting must be configured. See [npm/proxy-addr](https://www.npmjs.com/package/proxy-addr) for possible values.       |\n\n## What is checked?\n\nThe following table shows which user input is checked by which module:\n\n| Name                       | URL      | Body\\* | Headers\\*\\* | IP  |\n| -------------------------- | -------- | ------ | ----------- | --- |\n| Bad Bots                   | ❌       | ❌     | ✅          | ❌  |\n| Block Tor Exit Nodes       | ❌       | ❌     | ❌          | ✅  |\n| CRLF Injection             | ✅       | ✅     | ❌          | ❌  |\n| Cross-Site-Scripting (XSS) | ✅       | ✅     | ✅          | ❌  |\n| Directory Traversal        | ✅       | ✅     | ❌          | ❌  |\n| Fake Crawlers              | ❌       | ❌     | ✅          | ✅  |\n| HTTP Parameter Pollution   | ✅\\*\\*\\* | ❌     | ❌          | ❌  |\n| NoSQL Injections           | ✅       | ✅     | ✅          | ❌  |\n| Open Redirect / SSRF       | ✅       | ❌     | ❌          | ❌  |\n| Prototype Pollution        | ✅       | ✅     | ✅          | ❌  |\n| SQL Injections             | ✅       | ✅     | ✅          | ❌  |\n| XML Injections (Basic)     | ❌       | ✅     | ❌          | ❌  |\n\n\\* Bodies are only checked if req.body is set by a middleware or the web framework itself before EasyWAF.  \n\\*\\* Includes user agent and cookies  \n\\*\\*\\* Only if req.query is set by a framework.\n\nA short description of all modules can be found in [src/modules](src/modules).\n\n## Contact\n\nIf a public GitHub issue or discussion is not the right choice for your concern, you can contact me directly:\n\n-   E-Mail: [info@timokoessler.de](mailto:info@timokoessler.de)\n-   Twitter: [@timokoessler](https://twitter.com/timokoessler)\n\n## Sources\n\n-   [Payloads All The Thing: A list of useful payloads and bypass for Web Application Security](https://github.com/swisskyrepo/PayloadsAllTheThings)\n-   [HackTricks: A free hacking book](https://book.hacktricks.xyz/pentesting-web/)\n-   [Nginx Ultimate Bad Bot Blocker: The source of the bad bots list for EasyWAF](https://github.com/mitchellkrogza/nginx-ultimate-bad-bot-blocker)\n\n## License\n\n© Timo Kössler 2024  \nReleased under the [MIT license](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimokoessler%2Feasy-waf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimokoessler%2Feasy-waf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimokoessler%2Feasy-waf/lists"}