caddy_waf_t1k

README

About this repo

This is a WAF plugin for Caddy Server using Chaitin SafeLine as backend engine.

How to use

(waf) {
	route {
		waf_chaitin {
			waf_engine_addr 169.254.0.5:8000 169.254.0.6:8000 169.254.0.7:8000
			initial_cap 1 # initial connection of the engine
			max_idle 16 # max idle connections
			max_cap 32 # max connections
			idle_timeout 30s # connections idle timeout
			lb_policy round_robin # load balancing policy (random or round_robin, default: random)
			lb_retries 1 # additional engines to try after Detect engine error (default: 0)
			max_body_size 1MiB # inspect at most 1 MiB of each request body; 0 = unlimited (default)
			health_fail_duration 30s # passive health check window (default: 0 = disabled)
			health_max_fails 3 # failure threshold to mark engine unhealthy (default: 1)
		}
	}
}

:8000 {
	import waf
	respond / "Hello, world!"
}

Request body inspection cap

By default, the WAF buffers the entire request body for detection. Use max_body_size to limit how many bytes of the request body are sent to the WAF engine:

max_body_size 1MiB

Only the first N bytes are sent to detection; the full request body is still streamed to the downstream handler, so this setting does not limit or truncate uploads. To limit the upload itself, use Caddy's native request_body { max_size ... } directive.

Default is 0, preserving the original unlimited behavior. Sizes can be given as raw bytes or using go-humanize SI/IEC suffixes, e.g. 1MB, 1MiB, 512KB.

Load balancing retries

By default (lb_retries 0), a Detect engine error fail-opens immediately (same as before). Set lb_retries to try other engines on the same request (engine errors only; client errors are never retried). To approximate nginx t1k_next_upstream with N engines, use lb_retries N-1.

Shared engines and connection pools

WAF instances that reference the same engine address (waf_engine_addr) with identical pool and health parameters share one Connection pool process-wide — one Engine per address, reference-counted across instances. This keeps the total number of TCP connections to the engine cluster bounded (N_addresses × max_cap) instead of scaling with the number of instances, and makes passive health state agreed globally (an Engine marked unhealthy by one site is avoided by all sites).

Instances with different parameter sets (e.g. a different max_cap or health_fail_duration) get separate pools to the same address. This also preserves per-site capacity tuning: a site that needs a larger pool can set its own parameters and gets its own pool.

Because pools are per engine address, pool and health metrics are labeled by engine address only (no waf_instance label); a shared Engine exposes exactly one series.

How to build

xcaddy build --with github.com/W0n9/caddy_waf_t1k --replace github.com/chaitin/t1k-go=github.com/w0n9/t1k-go@latest

Local development (uses src/t1k-go checkout):

xcaddy build \
  --with github.com/W0n9/caddy_waf_t1k=. \
  --replace github.com/chaitin/t1k-go=./src/t1k-go \
  --output ./build/caddy

Prometheus metrics

The plugin registers metrics on Caddy's metrics registry. Expose them for scraping:

:9090 {
    metrics /metrics
}

Or scrape the Admin API: GET http://localhost:2019/metrics

Request metrics

Metric	Labels	Description
caddy_waf_requests_total	action	blocked / passed / error / failopen
caddy_waf_detect_duration_seconds	engine	WAF detection latency
caddy_waf_oversize_requests_total	—	Requests whose body was truncated for detection

Engine health & connection pool (updated every 10s)

Metric	Labels	Description
caddy_waf_engines_healthy	engine	1=healthy, 0=unhealthy
caddy_waf_pool_idle_conns	engine	Idle TCP connections
caddy_waf_pool_active_conns	engine	Active TCP connections
caddy_waf_pool_max_conns	engine	Configured max connections
caddy_waf_pool_waiting_requests	engine	Requests waiting for a connection

Connection errors & pool events

Metric	Labels	Description
caddy_waf_connection_errors_total	engine, reason	Detect errors (connection_refused, dial_timeout, broken_pipe, max_active_reached, pool_closed, client_error, other)
caddy_waf_pool_events_total	engine, reason	Pool lifecycle (dial_failed, idle_expired, ping_failed, pool_full_close, max_active_hit)

Example PromQL

# Connection pool utilization
caddy_waf_pool_active_conns / caddy_waf_pool_max_conns

# Engine unhealthy
caddy_waf_engines_healthy == 0

# Connection error rate
rate(caddy_waf_connection_errors_total[5m])

Example alert rules

- alert: WAFEngineUnhealthy
  expr: caddy_waf_engines_healthy == 0
  for: 1m

- alert: WAFPoolSaturated
  expr: caddy_waf_pool_active_conns / caddy_waf_pool_max_conns > 0.9
  for: 5m

- alert: WAFPoolWaiting
  expr: caddy_waf_pool_waiting_requests > 0
  for: 2m

- alert: WAFConnectionErrors
  expr: rate(caddy_waf_connection_errors_total[5m]) > 0.1
  for: 3m

Documentation

Index

• type CaddyWAF
  • func (CaddyWAF) CaddyModule() caddy.ModuleInfo
  • func (m *CaddyWAF) Cleanup() error
  • func (m *CaddyWAF) Provision(ctx caddy.Context) error
  • func (m *CaddyWAF) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (m *CaddyWAF) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (m *CaddyWAF) Validate() error
• type Engine
  • func (e *Engine) Available() bool
  • func (e *Engine) Destruct() error
  • func (e *Engine) DetectHttpRequest(r *http.Request) (*detection.Result, error)
  • func (e *Engine) Fails() int
• type EnginePool
• type LoadBalancing
• type RandomSelection
  • func (RandomSelection) CaddyModule() caddy.ModuleInfo
  • func (r RandomSelection) Select(pool EnginePool, request *http.Request, _ http.ResponseWriter) *Engine
  • func (r *RandomSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
• type RoundRobinSelection
  • func (RoundRobinSelection) CaddyModule() caddy.ModuleInfo
  • func (r *RoundRobinSelection) Select(pool EnginePool, _ *http.Request, _ http.ResponseWriter) *Engine
  • func (r *RoundRobinSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
• type Selector

Types

type CaddyWAF

type CaddyWAF struct {
	WafEngineAddrs []string `json:"waf_engine_addrs,omitempty"` // WAF Engine address, expects a URL or IP address

	// Multiple WAF engine pools
	Engines EnginePool

	// Load balancing distributes load/requests between backends.
	LoadBalancing *LoadBalancing `json:"load_balancing,omitempty"`

	InitialCap  int           `json:"initial_cap,omitempty"`
	MaxIdle     int           `json:"max_idle,omitempty"`
	MaxCap      int           `json:"max_cap,omitempty"`
	IdleTimeout time.Duration `json:"idle_timeout,omitempty"`

	// MaxBodySize limits the number of request-body bytes sent to the detection engine;
	// the full body is still forwarded downstream. A value of 0 preserves unlimited detection.
	MaxBodySize int64 `json:"max_body_size,omitempty"`

	HealthFailDuration caddy.Duration `json:"health_fail_duration,omitempty"`
	HealthMaxFails     int            `json:"health_max_fails,omitempty"`
	// contains filtered or unexported fields
}

CaddyWAF implements an HTTP handler for WAF.

func (CaddyWAF) CaddyModule

func (CaddyWAF) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*CaddyWAF) Cleanup

func (m *CaddyWAF) Cleanup() error

Cleanup releases the shared Engines this instance acquired at provisioning time. Metric series are per-Engine and are removed by the Engine's Destruct when the last referencing instance cleans up (registry reference count hits zero); the global metrics updater keeps running for the remaining Engines.

func (*CaddyWAF) Provision

func (m *CaddyWAF) Provision(ctx caddy.Context) error

Provision sets up the WAF module.

func (*CaddyWAF) ServeHTTP

func (m *CaddyWAF) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP processes incoming HTTP requests by utilizing the Caddy WAF engine to detect potential threats. If a request is identified as malicious, it redirects the request to an intercept handler. Otherwise, it passes the request to the next handler in the chain. The method handles detection errors and enforces a timeout for the detection process, logging relevant information in each case.

func (*CaddyWAF) UnmarshalCaddyfile

func (m *CaddyWAF) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile implements caddyfile.Unmarshaler.

func (*CaddyWAF) Validate

func (m *CaddyWAF) Validate() error

Validate ensures module configuration is valid.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine wraps a t1k.ChannelPool with per-engine health state. An Engine is self-contained: it owns its Passive health check parameters (health_max_fails / health_fail_duration) and its own teardown, so availability decisions on a shared Engine are unambiguous.

func (*Engine) Available

func (e *Engine) Available() bool

func (*Engine) Destruct

func (e *Engine) Destruct() error

Destruct tears the Engine down: it releases the Connection pool and removes this Engine's metric label series. The registry calls it when the last reference to the Engine is released. It is idempotent, and it marks the Engine destroyed so the metrics updater does not recreate its series after teardown.

func (*Engine) DetectHttpRequest

func (e *Engine) DetectHttpRequest(r *http.Request) (*detection.Result, error)

func (*Engine) Fails

func (e *Engine) Fails() int

type EnginePool

type EnginePool []*Engine

type LoadBalancing

type LoadBalancing struct {
	// A selection policy is how to choose an available backend.
	// The default policy is random selection.
	SelectionPolicyRaw json.RawMessage `json:"selection_policy,omitempty" caddy:"namespace=http.waf_chaitin.selection_policies inline_key=policy"`

	// Retries is how many additional engines to try after the first
	// Detect failure (engine errors only). Default 0 disables retry.
	Retries int `json:"retries,omitempty"`

	SelectionPolicy Selector `json:"-"`
}

LoadBalancing has parameters related to load balancing.

type RandomSelection

type RandomSelection struct{}

RandomSelection is a policy that selects an available host at random.

func (RandomSelection) CaddyModule

func (RandomSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (RandomSelection) Select

func (r RandomSelection) Select(pool EnginePool, request *http.Request, _ http.ResponseWriter) *Engine

Select returns an available host, if any.

func (*RandomSelection) UnmarshalCaddyfile

func (r *RandomSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type RoundRobinSelection

type RoundRobinSelection struct {
	// contains filtered or unexported fields
}

RoundRobinSelection is a policy that selects a host based on round-robin ordering.

func (RoundRobinSelection) CaddyModule

func (RoundRobinSelection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*RoundRobinSelection) Select

func (r *RoundRobinSelection) Select(pool EnginePool, _ *http.Request, _ http.ResponseWriter) *Engine

Select returns an available host, if any.

func (*RoundRobinSelection) UnmarshalCaddyfile

func (r *RoundRobinSelection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile sets up the module from Caddyfile tokens.

type Selector

type Selector interface {
	Select(EnginePool, *http.Request, http.ResponseWriter) *Engine
}

Selector selects an available upstream from the pool.