Skip to content

Runtime ban list ​

Sources live under examples/waf-ban/.

Bans are operational state, not configuration. They are created from the Admin Console or the /api/v1/waf/bans API and stored in the admin database — nothing is written into ingress.yaml.

Config (enables the console and trusted proxies) ​

yaml
# Runtime ban list example.
#
# Bans are NOT configured here. They are created from the Admin Console
# (WAF -> 封禁名单) or via POST /api/v1/waf/bans, stored in the admin database,
# and injected into the running ingress as an immutable snapshot. Publishing a
# ban never reloads this file, so caches and rate-limit counters are untouched.
#
# This file only enables the pieces the ban list depends on:
#   - admin console (where bans are managed)
#   - waf.trusted_proxies (so the client IP behind a load balancer is real;
#     banning a proxy address is rejected by the API on purpose)
version: v1
port: 8080

admin:
  enabled: true
  port: 9080
  database:
    driver: sqlite
    dsn: file:./admin.db?cache=shared&_fk=1
  web:
    dev_proxy: true

waf:
  # The ban list works even with waf.enabled: false — it is deliberately
  # independent from the WAF switch so an emergency "turn WAF off" cannot
  # silently drop active bans. Enabling WAF here just adds signature rules.
  enabled: true
  # Only trust X-Forwarded-For from the proxy tier. Without this, the client IP
  # is the raw TCP peer and banning it would hit the load balancer instead.
  trusted_proxies:
    - 10.0.0.0/8
    - 172.16.0.0/12

rules:
  - host: api.example.com
    backend:
      service:
        name: api
        port: 8080
        protocol: http

Create, preview, and remove bans ​

bash
# Preview impact before banning
curl -s -X POST http://127.0.0.1:9080/api/v1/waf/bans/preview \
  -H 'Content-Type: application/json' \
  -d '{"kind":"ip","value":"203.0.113.42"}'

# 24-hour IP ban
curl -s -X POST http://127.0.0.1:9080/api/v1/waf/bans \
  -H 'Content-Type: application/json' \
  -d '{"kind":"ip","value":"203.0.113.42","ttl_seconds":86400,"reason":"port scan"}'

# User-Agent ban (Go regexp syntax)
curl -s -X POST http://127.0.0.1:9080/api/v1/waf/bans \
  -H 'Content-Type: application/json' \
  -d '{"kind":"ua_regex","value":"(?i)(nikto|sqlmap)","ttl_seconds":604800}'

# Unban — access is restored immediately
curl -s -X DELETE http://127.0.0.1:9080/api/v1/waf/bans/1

Validate ​

bash
ingress validate -c examples/waf-ban/ingress.yaml

See WAF guide for semantics, guardrails, and limitations.

Released under the MIT License.