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)
			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!"
}

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

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

TODO

• Detection and Interception
• Pass the remote_addr to the Engine
• Multi backend engine instances support, include Load Balance and High Availability

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
• type Engine
  • func (e *Engine) Available() bool
  • 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"`

	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

Cleans up the WAF plugin instance by closing the WAF engine and logging the cleanup process.

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.

type Engine

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

Engine wraps a t1k.ChannelPool with per-engine health state.

func (*Engine) Available

func (e *Engine) Available() bool

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"`

	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.