# fabriziosalmi/caddy-adf architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Caddy v2 middleware module written in Go, called “caddy-adf.”
- Its purpose is to act as a real-time, ML-enhanced Web Application Firewall (WAF) that plugs into the Caddy HTTP server.

##### File structure
- Top-level Go source files (admin.go, anomaly.go, caddyadf.go, caddyfile.go, history.go, ml.go, normalizer.go, sanitize.go) implement discrete subsystems:
- caddyadf.go: module registration and hooks into the Caddy middleware chain
- caddyfile.go: parsing of ml_waf directives in the Caddyfile
- anomaly.go: core scoring orchestration
- ml.go: ML score extraction using pre-trained.model and new_pre-trained.model
- history.go: time-windowed, sharded request history store per client IP
- normalizer.go: attribute normalization (linear/log)
- sanitize.go: redaction of sensitive headers and query parameters
- admin.go: HTTP admin endpoints (/ml_waf/update_model, /ml_waf/get_config)
- Configuration and scripts:
- Caddyfile: example integration with global and per-path settings
- go.mod / go.sum: module dependencies
- test.py, test.sh: functional and CI smoke tests
- CI metadata under .github/workflows (Go build/tests and Caddy integration).

##### README for architectural insights
- Describes a pipeline: Attribute Extraction → Normalization → Weighting → (Optionally) ML Scoring → History Correlation → Threshold Evaluation → Action (mark/block)
- Highlights dynamic thresholds, per-path configs, redaction, and admin API.

##### Main components and interactions
a. Components:
1. HTTP Client
2. Caddy Core HTTP Server
3. caddy-adf Middleware
– Attribute Extractor
– Normalizer
– Traditional Scoring Engine (weights + range checks)
– ML Scoring Engine (lookup in pre-trained.model)
– Request History Store (sharded in-memory cache)
– Redaction Engine
– Configuration Manager (global, per-path, dynamic thresholds)
4. File System (model files, config)
5. Admin HTTP API (/ml_waf)
6. Upstream Handler or Origin (the final “respond” or proxy)
b. Interactions / Data flow:
1. Client → Caddy Core → caddy-adf
2. caddy-adf: extract attributes → normalize → apply weights → (if enabled) ML lookup → combine scores
3. caddy-adf: query/update in-memory history store → calculate correlation score
4. caddy-adf: evaluate against anomaly_threshold and blocking_threshold (global or per-path)
5. caddy-adf: redact sensitive data → if blocked, return 403 + blocking headers → else pass to upstream
6. Admin tool or script → HTTP POST/GET to /ml_waf → update model file path or fetch current config
c. Architectural patterns and principles:
- Middleware pipeline (thin, composable stages)
- Sharded in-memory cache for concurrency and low latency
- Configuration-as-code via Caddyfile (declarative)
- Separation of concerns: scoring vs normalization vs persistence vs admin
d. Key technologies and libraries:
- Go modules and standard library (net/http, time, sync)
- Caddy v2 plugin SDK (module registration, Caddyfile parsing)
- xcaddy for custom build with the module
- Regular expressions for per-path matching and redaction
- Simple file-based ML model lookup

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Client["HTTP Client"]:::external
    CaddyCore["Caddy Core HTTP Server"]:::external

    %% Middleware Subgraph
    subgraph "caddy-adf Middleware"
        direction TB
        Reg["Module Registration & Middleware Hook"]:::processing
        AttrExt["Attribute Extractor"]:::processing
        Norm["Normalizer"]:::processing
        TradScore["Traditional Scoring Engine"]:::processing
        MLScore["ML Scoring Engine"]:::processing
        HistStore["History Store (N shards)"]:::datastore
        Redact["Redaction Engine"]:::processing
        ConfigMgr["Configuration Manager"]:::config
    end

    %% Upstream
    Origin["Upstream Handler / Origin"]:::external

    %% File System and Data Stores
    subgraph "File System"
        direction TB
        Model1["pre-trained.model"]:::datastore
        Model2["new_pre-trained.model"]:::datastore
    end

    %% Admin API
    subgraph "Admin API" 
        direction TB
        AdminAPI["/ml_waf Endpoints"]:::config
    end

    %% CI & Documentation
    subgraph "Repository Artifacts"
        direction TB
        CaddyfileNode["Caddyfile"]:::config
        GoMods["go.mod / go.sum"]:::config
        Tests["test.py / test.sh"]:::external
        CIWorkflows[".github/workflows"]:::config
        README["README.md"]:::external
    end

    %% Main Flow
    Client -->|"HTTP request"| CaddyCore
    CaddyCore -->|"invokes middleware"| Reg
    Reg --> AttrExt -->|"attributes"| Norm -->|"normalized data"| TradScore
    TradScore -->|"score"| MLScore
    MLScore -->|"mlScore"| HistStore
    HistStore -->|"historyCorrelation"| ConfigMgr
    ConfigMgr -->|"thresholds"| Redact
    Redact -->|"cleaned request"| Origin
    Redact -->|"blocked → 403"| CaddyCore

    %% Admin interactions
    AdminAPI -.->|"update_model/config reload"| Model1
    AdminAPI -.->|"fetch config"| ConfigMgr

    %% Models loaded by ML Engine
    MLScore -->|"model lookup"| Model1
    MLScore -->|"model lookup"| Model2

    %% Repository artifacts links
    CaddyCore --> CaddyfileNode
    CaddyCore --> GoMods
    CaddyCore --> Tests
    CaddyCore --> CIWorkflows
    CaddyCore --> README

    %% Click Events
    click Reg "https://github.com/fabriziosalmi/caddy-adf/blob/main/caddyadf.go"
    click CaddyfileNode "https://github.com/fabriziosalmi/caddy-adf/blob/main/caddyfile.go"
    click TradScore "https://github.com/fabriziosalmi/caddy-adf/blob/main/anomaly.go"
    click Norm "https://github.com/fabriziosalmi/caddy-adf/blob/main/normalizer.go"
    click MLScore "https://github.com/fabriziosalmi/caddy-adf/blob/main/ml.go"
    click HistStore "https://github.com/fabriziosalmi/caddy-adf/blob/main/history.go"
    click Redact "https://github.com/fabriziosalmi/caddy-adf/blob/main/sanitize.go"
    click AdminAPI "https://github.com/fabriziosalmi/caddy-adf/blob/main/admin.go"
    click Model1 "https://github.com/fabriziosalmi/caddy-adf/blob/main/pre-trained.model"
    click Model2 "https://github.com/fabriziosalmi/caddy-adf/blob/main/new_pre-trained.model"
    click CaddyfileNode "https://github.com/fabriziosalmi/caddy-adf/tree/main/Caddyfile"
    click GoMods "https://github.com/fabriziosalmi/caddy-adf/blob/main/go.mod"
    click Tests "https://github.com/fabriziosalmi/caddy-adf/blob/main/test.py"
    click Tests "https://github.com/fabriziosalmi/caddy-adf/blob/main/test.sh"
    click CIWorkflows "https://github.com/fabriziosalmi/caddy-adf/blob/main/.github/workflows/go.yml"
    click CIWorkflows "https://github.com/fabriziosalmi/caddy-adf/blob/main/.github/workflows/main.yml"
    click README "https://github.com/fabriziosalmi/caddy-adf/blob/main/README.md"

    %% Styles
    classDef processing fill:#add8e6,stroke:#333,stroke-width:1px
    classDef datastore fill:#90ee90,stroke:#333,stroke-width:1px
    classDef config fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#333,stroke-width:1px
```
