{"id":15522688,"url":"https://github.com/serceman/firewalker","last_synced_at":"2025-04-05T03:04:31.752Z","repository":{"id":39442614,"uuid":"266126255","full_name":"SerCeMan/firewalker","owner":"SerCeMan","description":"Testing framework for Cloudflare Firewall rules","archived":false,"fork":false,"pushed_at":"2025-01-29T22:53:29.000Z","size":19873,"stargazers_count":59,"open_issues_count":5,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T02:02:59.047Z","etag":null,"topics":["cloudflare","security","waf"],"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/SerCeMan.png","metadata":{"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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-22T14:08:53.000Z","updated_at":"2025-03-27T18:01:42.000Z","dependencies_parsed_at":"2024-06-19T07:28:59.290Z","dependency_job_id":null,"html_url":"https://github.com/SerCeMan/firewalker","commit_stats":{"total_commits":68,"total_committers":5,"mean_commits":13.6,"dds":0.3382352941176471,"last_synced_commit":"eec34595fd5bcbaa895eb59ceac83b381da8283f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SerCeMan%2Ffirewalker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SerCeMan%2Ffirewalker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SerCeMan%2Ffirewalker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SerCeMan%2Ffirewalker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SerCeMan","download_url":"https://codeload.github.com/SerCeMan/firewalker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280262,"owners_count":20912967,"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":["cloudflare","security","waf"],"created_at":"2024-10-02T10:41:56.452Z","updated_at":"2025-04-05T03:04:31.733Z","avatar_url":"https://github.com/SerCeMan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](https://github.com/SerCeMan/firewalker/raw/master/logo/logo.png)\n\n[![Build Status](https://circleci.com/gh/SerCeMan/firewalker.svg?style=svg)](https://circleci.com/gh/SerCeMan/firewalker)\n[![Codecov](https://codecov.io/gh/SerCeMan/firewalker/branch/master/graph/badge.svg)](https://codecov.io/gh/SerCeMan/firewalker)\n[![npm version](https://badge.fury.io/js/firewalker.svg)](https://www.npmjs.com/package/firewalker)\n\nA framework for executing and testing Cloudflare Firewall rules locally.\n\n```typescript\nconst firewall = new Firewall();\nconst rule = firewall.createRule(`\n    http.host eq \"www.example.org\"\n`);\n\nrule.match(new Request('http://www.example.org')); // -\u003e true\nrule.match(new Request('http://www.example.com')); // -\u003e false\n```\n\nSee more [examples](https://github.com/SerCeMan/firewalker/blob/master/test/firewall.tests.ts).\n\nAnd for integration testing see some of the [ruleset examples](https://github.com/SerCeMan/firewalker/blob/master/test/ruleset.tests.ts)\n\n## Motivation\n\nIt's easy to treat firewall rules as plain configuration. It's incredibly easy to manage a couple of rules that look like.\n\n```\nhttp.host eq \"www.example.org\"\n```\n\nAnd end up with a rule that looks more like.\n\n```wireshark\nhttp.host matches \"(www|api)\\.example\\.org\"\nand not lower(http.request.uri.path) matches \"/(auth|login|logut).*\"\nand (\n  any(http.request.uri.args.names[*] == \"token\") or\n  ip.src in { 93.184.216.34 62.122.170.171 }\n)\nor cf.threat_score lt 10\n```\n\nOver time, the number of rules and their complexity grows. Manually testing rules like the above is error-prone as humans are known to make mistakes. After a few steps up in complexity, it becomes apparent that firewall rules are code, and need to be treated as code. They need to be stored in a source code repository, managed with a tool like Terraform, and the changes need to be tested on CI.\n\nHere is where Firewalker comes into play allowing you to write unit tests to ensure that a change to the path regex isn't going to block all of the traffic to your site or cancel out the effect of the rule completely. For instance, for the rule above, you can define multiple assertions with jest.\n\n```typescript\nconst rule = firewall.createRule(/* */);\n\nexpect(rule.match(new Request('http://www.example.org'))).toBeFalsy();\nexpect(rule.match(new Request('http://www.example.org?token=abc'))).toBeTruthy();\nexpect(rule.match(new Request('http://www.example.org/login/user?token=abc'))).toBeFalsy();\nexpect(\n  rule.match(\n    new Request('http://www.example.org/login/user?token=abc', {\n      cf: { 'cf.threat_score': 5 },\n    }),\n  ),\n).toBeTruthy();\n// etc\n```\n\nFirewalker builds on top of Cloudflare's [wirefilter](https://github.com/cloudflare/wirefilter) rule engine and provides API to construct the requests in JS. After all, if the tests for your workers are in JS, why not to use the same syntax for the WAF rules?\n\n## Supported platforms\n\nFirewalker relies on a binary build [wirefilter](https://github.com/cloudflare/wirefilter) to run and execute the firewall rules. Therefore, only the platforms which binaries were pre-built will be able to run Firewalker. Currently supported platforms are:\n\n- MacOS\n- Linux\n\n## Disclaimer\n\nThe Firewalker project is not officially supported by Cloudflare or affiliated with Cloudflare in any way. While Firewalker tries to preserve the semantics of the Cloudflare WAF rule engine, there will always be some differences, so use it at your own risk as general guidance for local testing rather than the ultimate truth.\n\n## Contribute\n\nContributions are always welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserceman%2Ffirewalker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserceman%2Ffirewalker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserceman%2Ffirewalker/lists"}