{"id":24166584,"url":"https://github.com/fabriziosalmi/caddy-waf","last_synced_at":"2026-02-22T21:13:23.483Z","repository":{"id":270693455,"uuid":"911176304","full_name":"fabriziosalmi/caddy-waf","owner":"fabriziosalmi","description":"Caddy WAF (Regex Rules, IP and DNS filtering, Rate Limiting, GeoIP, Tor, Anomaly Detection)","archived":false,"fork":false,"pushed_at":"2026-01-17T23:15:54.000Z","size":8650,"stargazers_count":711,"open_issues_count":0,"forks_count":27,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-01-18T01:22:42.698Z","etag":null,"topics":["caddy","caddy-module","caddy-plugin","caddy-security","caddyserver","dns-blacklist","dns-filtering","geo-blocking","geoip2","ip-blacklist","ip-filtering","owasp","rate-limiter","rate-limiting","security-tools","waf","web-application-firewall","web-security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabriziosalmi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"fabriziosalmi"}},"created_at":"2025-01-02T12:13:56.000Z","updated_at":"2026-01-17T23:15:41.000Z","dependencies_parsed_at":"2025-01-16T13:54:04.305Z","dependency_job_id":"94d22afb-2d22-4bcf-8cc1-4d05bfc72bb4","html_url":"https://github.com/fabriziosalmi/caddy-waf","commit_stats":null,"previous_names":["fabriziosalmi/caddy-waf"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/fabriziosalmi/caddy-waf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Fcaddy-waf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Fcaddy-waf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Fcaddy-waf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Fcaddy-waf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabriziosalmi","download_url":"https://codeload.github.com/fabriziosalmi/caddy-waf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziosalmi%2Fcaddy-waf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28531993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["caddy","caddy-module","caddy-plugin","caddy-security","caddyserver","dns-blacklist","dns-filtering","geo-blocking","geoip2","ip-blacklist","ip-filtering","owasp","rate-limiter","rate-limiting","security-tools","waf","web-application-firewall","web-security"],"created_at":"2025-01-12T21:00:55.792Z","updated_at":"2026-01-18T06:16:22.628Z","avatar_url":"https://github.com/fabriziosalmi.png","language":"Go","funding_links":["https://github.com/sponsors/fabriziosalmi"],"categories":["Go"],"sub_categories":[],"readme":"# 🛡️ Caddy WAF Middleware\n\nA robust, highly customizable, and feature-rich **Web Application Firewall (WAF)** middleware for the Caddy web server. This middleware provides **advanced protection** against a comprehensive range of web-based threats, seamlessly integrating with Caddy and offering flexible configuration options to secure your applications effectively.\n\n[![Tests](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/test.yml/badge.svg)](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/test.yml) [![CodeQL](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/github-code-scanning/codeql)  [![Build, Run and Validate](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/build-run-validate.yml/badge.svg)](https://github.com/fabriziosalmi/caddy-waf/actions/workflows/build-run-validate.yml)\n\n## 🛡️ Core Protections\n\n*   **Regex-Based Filtering:** Deep URL, data \u0026 header inspection using powerful regex rules.\n*   **Blacklisting:** Blocks malicious IPs, domains, ASNs \u0026 optionally TOR exit nodes.\n*   **Geo-Blocking:** Restricts access by country using GeoIP.\n*   **Rate Limiting:** Prevents abuse via customizable IP request limits.\n*   **Anomaly Scoring:** Dynamically blocks requests based on cumulative rule matches.\n*   **Multi-Phase Inspection:** Analyzes traffic throughout the request lifecycle.\n*   **Sensitive Data Redaction:** Removes private info from logs.\n*   **Custom Response Handling:** Tailored responses for blocked requests.\n*   **Detailed Monitoring:** JSON endpoint for performance tracking \u0026 analysis.\n*   **Dynamic Config Reloads:** Seamless updates without restarts.\n*   **File Watchers:** Automatic reloads on rule/blacklist changes.\n*   **Observability:** Seamless integration with ELK stack and Prometheus.\n*   **Rules generator**: [available here](https://chatgpt.com/g/g-677d07dd07e48191b799b9e5d6da7828-caddy-waf-ruler)\n\n_Simple at a glance UI :)_\n![demo](https://github.com/fabriziosalmi/caddy-waf/blob/main/docs/caddy-waf-ui.png?raw=true)  \n\n## Security \u0026 Performance\n*   **Zero-Copy Networking**: Uses `unsafe.String` to eliminate memory allocations during request body inspection.\n*   **Wait-Free Concurrency**: Atomic counters ensure accurate metrics and rule hit counting without lock contention.\n*   **Circuit Breaker**: `geoip_fail_open` prevents database failures from causing service outages.\n*   **DoS Protection**: `io.LimitReader` enforces strict request body limits to prevent memory exhaustion.\n*   **ReDoS Safety**: Built on top of Go's `regexp` (RE2), guaranteeing linear time execution for all regex rules.\n\n## 🚀 Quick Start\n\n```bash\ncurl -fsSL -H \"Pragma: no-cache\" https://raw.githubusercontent.com/fabriziosalmi/caddy-waf/refs/heads/main/install.sh | bash\n```\n\n**Example Output:**\n\n```\n2025/01/29 13:50:49.791 INFO    Provisioning WAF middleware     {\"log_level\": \"info\", \"log_path\": \"debug.json\", \"log_json\": true, \"anomaly_threshold\": 10}\n2025/01/29 12:50:49.918 INFO    http.handlers.waf       Tor exit nodes updated  {\"count\": 1093}\n2025/01/29 13:50:49.918 INFO    WAF middleware version  {\"version\": \"v0.0.0-20250128221917-c99e875aaf7c\"}\n2025/01/29 13:50:49.918 INFO    Rate limit configuration        {\"requests\": 100, \"window\": 10, \"cleanup_interval\": 300, \"paths\": [\"/api/v1/.*\", \"/admin/.*\"], \"match_all_paths\": false}\n2025/01/29 13:50:49.918 WARN    GeoIP database not found. Country blocking/whitelisting will be disabled        {\"path\": \"GeoLite2-Country.mmdb\"}\n2025/01/29 13:50:50.359 INFO    IP blacklist loaded     {\"path\": \"ip_blacklist.txt\", \"valid_entries\": 223770, \"invalid_entries\": 0, \"total_lines\": 223770}\n2025/01/29 13:50:50.489 INFO    DNS blacklist loaded    {\"path\": \"dns_blacklist.txt\", \"valid_entries\": 854479, \"total_lines\": 854479}\n2025/01/29 13:50:50.490 INFO    WAF rules loaded successfully   {\"total_rules\": 33, \"rule_counts\": \"Phase 1: 17 rules, Phase 2: 16 rules, Phase 3: 0 rules, Phase 4: 0 rules, \"}\n2025/01/29 13:50:50.490 INFO    WAF middleware provisioned successfully\n```\n\n## 📑 Table of Contents\n\n1.  [🚀 Installation](#-installation)\n2.  [🛠️ Basic Configuration](#️-basic-configuration)\n3.  [📚 Full Documentation](#-full-documentation)\n4.  [📜 License](#-license)\n5.  [🙏 Contributing](#-contributing)\n\n---\n\n## 🚀 Installation\n\n### Option 1: Quick Script (Recommended)\n\nThe fastest way to get started:\n\n```bash\ncurl -fsSL -H \"Pragma: no-cache\" https://raw.githubusercontent.com/fabriziosalmi/caddy-waf/refs/heads/main/install.sh | bash\n```\n\n### Option 2: Build with xcaddy\n\n```bash\n# Install xcaddy if you don't have it\ngo install github.com/caddyserver/xcaddy/cmd/xcaddy@latest\n\n# Build Caddy with the WAF module\nxcaddy build --with github.com/fabriziosalmi/caddy-waf\n```\n\n### Option 3: Build from Source\n\n#### Prerequisites\n\n- [Go](https://golang.org/dl/) **1.25** or higher\n- [Caddy](https://caddyserver.com/docs/install) **v2.10.x** or higher (for building with this plugin)\n- [xcaddy](https://github.com/caddyserver/xcaddy) (for building Caddy with plugins)\n\n```bash\n# Step 1: Clone the caddy-waf repository from GitHub\ngit clone https://github.com/fabriziosalmi/caddy-waf.git\n\n# Step 2: Navigate into the caddy-waf directory\ncd caddy-waf\n\n# Step 3: Clean up and update the go.mod file\ngo mod tidy\n\n# Step 4: Fetch and install the required Go modules\ngo get github.com/caddyserver/caddy/v2\ngo get github.com/caddyserver/caddy/v2/caddyconfig/caddyfile\ngo get github.com/caddyserver/caddy/v2/caddyconfig/httpcaddyfile\ngo get github.com/caddyserver/caddy/v2/modules/caddyhttp\ngo get github.com/oschwald/maxminddb-golang\ngo get github.com/fsnotify/fsnotify\ngo get -v github.com/fabriziosalmi/caddy-waf\ngo mod tidy\n\n# Step 5: Download the GeoLite2 Country database (required for country blocking/whitelisting)\nwget https://git.io/GeoLite2-Country.mmdb\n\n# Step 6: Build Caddy with the caddy-waf module\nxcaddy build --with github.com/fabriziosalmi/caddy-waf=./\n\n# Step 7: Fix Caddyfile format\ncaddy fmt --overwrite\n\n# Step 8: Run the compiled Caddy server\n./caddy run\n```\n\n---\n\n## 🛠️ Basic Configuration\n\nHere's a minimal Caddyfile example to get started:\n\n```caddyfile\n{\n    auto_https off\n    admin localhost:2019\n}\n\n:8080 {\n    log {\n        output stdout\n        format console\n        level INFO\n    }\n\n    handle {\n        header -Server\n    }\n\n    route {\n        # WAF Plugin runs on all requests first\n        waf {\n            metrics_endpoint /waf_metrics\n            rule_file rules.json\n            ip_blacklist_file ip_blacklist.txt\n            dns_blacklist_file dns_blacklist.txt\n        }\n\n        # Match the waf metrics endpoint specifically and stop processing\n        @wafmetrics path /waf_metrics\n        handle @wafmetrics {\n            # Do not respond here so it goes to the WAF plugin\n        }\n\n        # All other requests, respond with \"Hello World\"\n        handle {\n            respond \"Hello world!\" 200\n        }\n    }\n}\n```\n\n**For more detailed configuration options, rules format, and usage instructions, please refer to the [Full Documentation](#-full-documentation).**\n\n---\n\n## 📚 Full Documentation\n\nFor complete documentation, including configuration options, rule format details, protected attack types, testing strategies, and more, please refer to the `/docs` directory in this repository.\n\n### 📑 Table of Contents\n\n1.  [**Installation**](docs/installation.md) - *Instructions for installing the Caddy WAF middleware.*\n2.  [**Using `caddy add-package`**](docs/add-package-guide.md) - *Quick guide for installing with the `caddy add-package` command.*\n3.  [**Configuration Options**](docs/configuration.md) - *Detailed explanation of all available configuration settings.*\n4.  [**Rules Format (`rules.json`)**](docs/rules.md) - *A comprehensive guide to defining custom rules using the JSON format.*\n5.  [**Blacklist Formats**](docs/blacklists.md) - *Documentation of the formats used for defining IP and DNS blacklists.*\n6.   [**Rate Limiting**](docs/ratelimit.md) - *How to configure rate limiting, including parameters and usage.*\n7.  [**Country Blocking and Whitelisting**](docs/geoblocking.md) - *Details on how to configure country-based blocking and whitelisting.*\n8.  [**Protected Attack Types**](docs/attacks.md) - *An overview of the wide range of web-based threats that the Caddy WAF is designed to protect against.*\n9.  [**Dynamic Updates**](docs/dynamicupdates.md) - *How to dynamically update the WAF rules and other settings without downtime.*\n10.  [**Metrics**](docs/metrics.md) - *Details about the WAF's metrics endpoint and the different metrics collected.*\n11. [**Prometheus Metrics**](docs/prometheus.md) - *Instructions on how to expose WAF metrics using the Prometheus format.*\n12. [**ELK Observability**](https://github.com/fabriziosalmi/caddy-waf/blob/main/docs/caddy-waf-elk.md) - *Instructions on how to configure caddy-waf ELK stack observability.*\n13. [**Rule/Blacklist Population Scripts**](docs/scripts.md) - *Documentation on the provided scripts to automatically fetch, update and generate rules and blacklists.*\n14. [**Testing**](docs/testing.md) - *Guidance on how to test the WAF's effectiveness using the provided testing tools.*\n15.  [**Docker Support**](docs/docker.md) - *Instructions on how to build and run the WAF using Docker.*\n\n---\n\n## 📜 License\n\nThis project is licensed under the **AGPLv3 License**.\n\n---\n\n## Others projects\n\nIf You like my projects, you may also like these ones:\n\n- [patterns](https://github.com/fabriziosalmi/patterns) Automated OWASP CRS and Bad Bot Detection for Nginx, Apache, Traefik and HaProxy\n- [blacklists](https://github.com/fabriziosalmi/blacklists) Hourly updated domains blacklist 🚫 \n- [proxmox-vm-autoscale](https://github.com/fabriziosalmi/proxmox-vm-autoscale) Automatically scale virtual machines resources on Proxmox hosts \n- [UglyFeed](https://github.com/fabriziosalmi/UglyFeed) Retrieve, aggregate, filter, evaluate, rewrite and serve RSS feeds using Large Language Models for fun, research and learning purposes \n- [proxmox-lxc-autoscale](https://github.com/fabriziosalmi/proxmox-lxc-autoscale) Automatically scale LXC containers resources on Proxmox hosts \n- [DevAssistant](https://github.com/fabriziosalmi/DevGPT) Code together, right now! AI powered code assistant to build project in minutes\n- [websites-monitor](https://github.com/fabriziosalmi/websites-monitor) Websites monitoring via GitHub Actions (expiration, security, performances, privacy, SEO)\n- [caddy-mib](https://github.com/fabriziosalmi/caddy-mib) Track and ban client IPs generating repetitive errors on Caddy \n- [zonecontrol](https://github.com/fabriziosalmi/zonecontrol) Cloudflare Zones Settings Automation using GitHub Actions \n- [lws](https://github.com/fabriziosalmi/lws) linux (containers) web services\n- [cf-box](https://github.com/fabriziosalmi/cf-box) cf-box is a set of Python tools to play with API and multiple Cloudflare accounts.\n- [limits](https://github.com/fabriziosalmi/limits) Automated rate limits implementation for web servers \n- [dnscontrol-actions](https://github.com/fabriziosalmi/dnscontrol-actions) Automate DNS updates and rollbacks across multiple providers using DNSControl and GitHub Actions \n- [proxmox-lxc-autoscale-ml](https://github.com/fabriziosalmi/proxmox-lxc-autoscale-ml) Automatically scale the LXC containers resources on Proxmox hosts with AI\n- [csv-anonymizer](https://github.com/fabriziosalmi/csv-anonymizer) CSV fuzzer/anonymizer\n- [iamnotacoder](https://github.com/fabriziosalmi/iamnotacoder) AI code generation and improvement\n\n\n## 🙏 Contributing\n\nContributions are highly welcome! Feel free to open an issue or submit a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziosalmi%2Fcaddy-waf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabriziosalmi%2Fcaddy-waf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziosalmi%2Fcaddy-waf/lists"}