# fabriziosalmi/caddy-waf architecture

> Architecture diagram of the GitHub repository fabriziosalmi/caddy-waf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabriziosalmi/caddy-waf
- Repository: https://github.com/fabriziosalmi/caddy-waf

## Overview

##### Project type and purpose
- This is a Go-based middleware plugin for the Caddy web server, implementing a full-featured Web Application Firewall (WAF).
- It inspects HTTP traffic in multiple phases, applies regex rules, IP/DNS/TOR blacklists, GeoIP checks, rate limiting, anomaly scoring, dynamic config reloads, logging, metrics and a simple UI.

##### File structure
- Top-level Go code:
– handler.go, request.go, response.go: core HTTP handling
– config.go: parsing Caddyfile and JSON rule configuration
– blacklist.go, geoip.go, tor.go: IP, DNS, TOR blacklist services
– ratelimiter.go: per-IP rate limiting
– rules.go, helpers.go, types.go, logging.go, debug_waf.go: rule engine, utilities, logging, debugging
- Rules and data files:
– rules/*.json and sample_rules.json: built-in rule sets by attack type
– ip_blacklist.txt, dns_blacklist.txt, tor_blacklist.txt: raw blacklist sources
– GeoLite2-Country.mmdb external database (optional)
- Python scripts and utilities:
– get_* scripts to fetch or regenerate blacklists and rules from external sources
– caddytest.py, e2e.py, benchmark.py, debug_test_results.py, check_waf_config.py: testing, benchmarking, validation
- Configuration and deployment:
– Caddyfile, Dockerfile, install.sh, install_with_modules.sh, Caddy workflows in .github
– docs/ folder with Markdown files describing all features, metrics, prometheus, ELK integration
- Static UI:
– ui/index.html: minimal in-browser interface for simple rule overview

##### README for additional insights
- Confirms middleware integration into Caddy request pipeline
- Lists all protection features: regex filtering, blacklists, geo-blocking, rate limiting, anomaly scoring, dynamic updates, observability (Prometheus/ELK), custom responses, metrics endpoint, simple UI
- Shows example Caddyfile integration and quick installation steps
- Points to docs directory for deeper technical references

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Request Flow
    Request["HTTP Request"]:::external
    subgraph "Caddy Web Server Core"
        direction TB
        PluginEntrypoint["Caddy Plugin Entrypoint"]:::core
        HandlerChain["Next Handler (Backend/App)"]:::core
    end
    Request -->|"passes through"| PluginEntrypoint
    PluginEntrypoint -->|"invokes"| WAFModule

    subgraph "WAF Middleware Module"
        direction TB
        ConfigManager["Config Manager & File Watcher"]:::core
        RuleEngine["Rule Engine & Phases"]:::core
        BlacklistSvc["Blacklist Service"]:::core
        GeoIP["GeoIP Service"]:::core
        RateLimiter["Rate Limiter"]:::core
        AnomalyScorer["Anomaly Scorer"]:::core
        LoggerAuditor["Logger / Auditor"]:::core
        MetricsExporter["Metrics Exporter (/waf_metrics)"]:::core
        StaticUI["Static UI Server"]:::core
        DebugIntrospect["Debugging & WAF Introspection"]:::core
    end

    WAFModule --> ConfigManager
    ConfigManager --> RuleEngine
    RuleEngine --> BlacklistSvc
    RuleEngine --> GeoIP
    RuleEngine --> RateLimiter
    RuleEngine --> AnomalyScorer
    RuleEngine --> LoggerAuditor
    RuleEngine --> DebugIntrospect
    RuleEngine --> HandlerChain
    MetricsExporter -->|"serves metrics"| Request

    BlacklistSvc --> IPBlacklist
    BlacklistSvc --> DNSBlacklist
    BlacklistSvc --> TORBlacklist

    %% External Data Stores
    subgraph "External Data Stores"
        direction TB
        IPBlacklist[(ip_blacklist.txt)]:::datastore
        DNSBlacklist[(dns_blacklist.txt)]:::datastore
        TORBlacklist[(tor_blacklist.txt)]:::datastore
        RulesFiles[(rules/*.json<br/>sample_rules.json)]:::datastore
        GeoIPDB[(GeoLite2-Country.mmdb)]:::datastore
    end

    %% Python Scripts & Feeds
    subgraph "Data Fetch & Utility Scripts"
        direction TB
        PythonScripts["Python Data Fetch & Utility Scripts"]:::external
    end

    PythonScripts --> RulesFiles
    PythonScripts --> IPBlacklist
    PythonScripts --> DNSBlacklist
    PythonScripts --> TORBlacklist
    ConfigManager --> RulesFiles

    %% Observability
    subgraph "External Systems"
        direction TB
        Prometheus[(Prometheus)]:::external
        ELK[(ELK Stack)]:::external
    end

    MetricsExporter -->|scraped by| Prometheus
    LoggerAuditor -->|logs to| ELK

    %% Final Flow
    WAFModule --> HandlerChain

    %% Click Events
    click PluginEntrypoint "https://github.com/fabriziosalmi/caddy-waf/blob/main/caddywaf.go"
    click ConfigManager "https://github.com/fabriziosalmi/caddy-waf/blob/main/config.go"
    click RuleEngine "https://github.com/fabriziosalmi/caddy-waf/blob/main/rules.go"
    click RuleEngine "https://github.com/fabriziosalmi/caddy-waf/blob/main/types.go"
    click RuleEngine "https://github.com/fabriziosalmi/caddy-waf/blob/main/helpers.go"
    click IPBlacklist "https://github.com/fabriziosalmi/caddy-waf/blob/main/blacklist.go"
    click IPBlacklist "https://github.com/fabriziosalmi/caddy-waf/blob/main/ip_blacklist.txt"
    click DNSBlacklist "https://github.com/fabriziosalmi/caddy-waf/blob/main/dns_blacklist.txt"
    click TORBlacklist "https://github.com/fabriziosalmi/caddy-waf/blob/main/tor.go"
    click TORBlacklist "https://github.com/fabriziosalmi/caddy-waf/blob/main/tor_blacklist.txt"
    click GeoIP "https://github.com/fabriziosalmi/caddy-waf/blob/main/geoip.go"
    click RateLimiter "https://github.com/fabriziosalmi/caddy-waf/blob/main/ratelimiter.go"
    click LoggerAuditor "https://github.com/fabriziosalmi/caddy-waf/blob/main/logging.go"
    click DebugIntrospect "https://github.com/fabriziosalmi/caddy-waf/blob/main/debug_waf.go"
    click MetricsExporter "https://github.com/fabriziosalmi/caddy-waf/blob/main/handler.go"
    click StaticUI "https://github.com/fabriziosalmi/caddy-waf/blob/main/ui/index.html"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#000
    classDef datastore fill:#c8e6c9,stroke:#388e3c,color:#000
    classDef external fill:#ffe0b2,stroke:#f57c00,color:#000
```
