GuardianWAF

Zero-dependency WAF. One binary. Total protection.

GuardianWAF is a production-grade Web Application Firewall written in pure Go with zero external dependencies. It protects any HTTP backend — Node.js, Python, Java, PHP, Ruby, .NET, or any other language — as a standalone reverse proxy, sidecar, or embeddable Go library. Docker auto-discovery, AI-powered threat analysis, and real-time dashboard included. Single binary, zero config required.

Features

Detection & Protection

• Six attack detectors: SQL injection, XSS, path traversal, command injection, XXE, SSRF
• Tokenizer-based detection engine with configurable scoring thresholds
• JS Challenge (SHA-256 proof-of-work) for suspicious requests -- stops bots, passes real browsers
• Rate limiting with token bucket algorithm, per-IP and per-path scoping, and auto-ban
• IP whitelist/blacklist with radix tree for O(k) CIDR lookups (runtime add/remove via dashboard)
• Bot detection via JA3/JA4 TLS fingerprinting, User-Agent analysis, and behavioral tracking
• Response protection: security headers (HSTS, X-Frame-Options, CSP), credit card/SSN/API key masking, stack trace stripping
• Branded HTML block page with request ID and threat score
• Threat Intelligence: IP and domain reputation checking with JSONL/CSV/JSON feeds, LRU cache, CIDR matching
• CORS Security: Origin validation with wildcard patterns, preflight handling, strict mode blocking
• API Security: JWT validation (RS256/ES256/HS256/etc), JWKS support, API key authentication with path authorization
• Account Takeover Protection: Brute force detection, credential stuffing detection, password spray detection, impossible travel detection

Reverse Proxy & Routing

• Multi-domain routing via virtual hosts (Host header + SNI)
• Wildcard domain support (*.example.com)
• Load balancing: round-robin, weighted, least-connections, IP hash
• Active health checks with configurable interval, timeout, and path
• Circuit breaker per target (closed -> open -> half-open -> probe)
• TLS termination with SNI-based certificate selection
• Certificate hot-reload (automatic file change detection)
• ACME / Let's Encrypt client for automatic certificate provisioning
• HTTP to HTTPS redirect (automatic when TLS enabled)
• Path-based routing with optional prefix stripping

Docker Auto-Discovery

• Automatic backend discovery from Docker container labels (gwaf.*)
• Zero-config service mesh: label your containers, GuardianWAF does the rest
• Event-driven: instant detection of container start/stop/scale
• Upstream pooling: multiple containers with same label = load-balanced pool
• Supports all LB strategies, health checks, weights via labels
• Platform-agnostic: Linux (Unix socket), Windows (named pipe), remote (Docker CLI)
• See Docker Discovery Guide for full label reference

AI-Powered Threat Analysis

• Background batch AI analysis of suspicious events using LLMs
• 400+ AI providers synced from models.dev (OpenAI, Groq, DeepSeek, Anthropic, etc.)
• Dashboard UI for provider/model selection, API key management, analysis history
• Auto-block malicious IPs based on AI verdict (configurable confidence threshold)
• Hard cost limits: tokens/hour, tokens/day, requests/hour to prevent runaway API costs
• See AI Analysis Guide for setup and configuration

Alerting & Notifications

• Real-time webhook alerts for Slack, Discord, PagerDuty, and generic HTTP endpoints
• SMTP email alerts with TLS encryption support
• Per-target event filtering (block, challenge, log, or all events)
• Minimum score thresholds and cooldown periods per IP
• Custom email templates with variable substitution
• Dashboard integration with alerting statistics

Deployment

• Three deployment modes: standalone reverse proxy, Go library middleware, sidecar proxy
• Single static binary with zero external Go dependencies -- no CGO, no shared libraries
• Docker image based on Alpine (< 20 MB)
• Graceful shutdown with connection draining and event flushing

Dashboard & Operations

• Built-in web dashboard with real-time monitoring via SSE (React + Vite + Tailwind)
• Routing Topology Graph: interactive React Flow visualization with TLS/SSL, ports, health status
• Backends View: discovered Docker containers + static upstreams in a single table
• AI Analysis Page: provider catalog, model selection, analysis history, cost tracking
• Configuration editor with live toggles for all WAF settings
• Upstream/domain/route management -- add backends, domains, and routing from the UI
• IP ACL management -- add/remove whitelist and blacklist entries in real-time
• Upstream health panel -- live backend status, circuit breaker state, active connections
• Event detail view -- click any event to see full findings, matched patterns, scores
• REST API for programmatic control (stats, events, config, routing, IP ACL, AI, Docker)
• Prometheus-compatible /metrics endpoint for Grafana/monitoring integration
• Structured access logging (JSON or text) with configurable levels
• Hot-reload of configuration with persistence to disk
• /healthz endpoint for Kubernetes liveness/readiness probes
• In-memory or file-based event storage (up to 100K events)

Developer Experience

• MCP server with 21 tools over stdio + SSE transports (Claude Code, Claude Desktop, VS Code)
• Functional options API for library mode
• Event callbacks for custom alerting
• check command for dry-run request testing
• validate command for config file verification
• HTTP/2 support with ALPN negotiation
• WebSocket proxy support (transparent Upgrade forwarding)
• < 1ms p99 latency overhead target

Quick Start

Standalone Reverse Proxy

# Install
go install github.com/guardianwaf/guardianwaf/cmd/guardianwaf@latest

# Create minimal config
cat > guardianwaf.yaml <<EOF
mode: enforce
listen: ":8088"
upstreams:
  - name: app
    targets:
      - url: "http://localhost:3000"
routes:
  - path: /
    upstream: app
dashboard:
  enabled: true
  listen: ":9443"
  api_key: "change-me"
EOF

# Run
guardianwaf serve

Multi-Domain with TLS

listen: ":8088"

tls:
  enabled: true
  listen: ":8443"
  http_redirect: true
  cert_file: "/etc/certs/default.pem"
  key_file: "/etc/certs/default-key.pem"

upstreams:
  - name: api
    load_balancer: weighted
    targets:
      - url: "http://api1:3000"
        weight: 3
      - url: "http://api2:3000"
        weight: 1
    health_check:
      enabled: true
      interval: 10s
      path: /healthz

  - name: web
    targets:
      - url: "http://web:8000"

virtual_hosts:
  - domains: ["api.example.com"]
    tls:
      cert_file: "/etc/certs/api.pem"
      key_file: "/etc/certs/api-key.pem"
    routes:
      - path: /
        upstream: api

  - domains: ["www.example.com", "example.com"]
    routes:
      - path: /
        upstream: web

routes:
  - path: /
    upstream: web

Go Library (Middleware)

go get github.com/guardianwaf/guardianwaf

waf, err := guardianwaf.New(guardianwaf.Config{
    Mode:      guardianwaf.ModeEnforce,
    Threshold: guardianwaf.ThresholdConfig{Block: 50, Log: 25},
    Challenge: guardianwaf.ChallengeConfig{Enabled: true, Difficulty: 20},
})
if err != nil {
    log.Fatal(err)
}
defer waf.Close()

http.ListenAndServe(":8088", waf.Middleware(myHandler))

Sidecar (Docker / Kubernetes)

docker run -d -p 8088:8088 \
  ghcr.io/guardianwaf/guardianwaf:latest \
  sidecar --upstream http://app:3000

Docker Compose with Auto-Discovery

No upstream config needed -- just add gwaf.* labels to your containers:

services:
  guardianwaf:
    image: ghcr.io/guardianwaf/guardianwaf:latest
    ports:
      - "80:8088"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./guardianwaf.yaml:/etc/guardianwaf/guardianwaf.yaml:ro
    command: ["serve", "-c", "/etc/guardianwaf/guardianwaf.yaml"]

  # Auto-discovered backend (weight: 3)
  api:
    image: myapp:latest
    labels:
      gwaf.enable: "true"
      gwaf.host: "api.example.com"
      gwaf.upstream: "api-pool"
      gwaf.port: "3000"
      gwaf.weight: "3"
      gwaf.health.path: "/healthz"

  # Same upstream pool (weight: 1) = load balanced
  api-2:
    image: myapp:latest
    labels:
      gwaf.enable: "true"
      gwaf.host: "api.example.com"
      gwaf.upstream: "api-pool"
      gwaf.port: "3000"
      gwaf.weight: "1"
      gwaf.health.path: "/healthz"

  # Different service on different domain
  web:
    image: nginx:alpine
    labels:
      gwaf.enable: "true"
      gwaf.host: "www.example.com"

Scale instantly: docker compose up -d --scale api=5 -- GuardianWAF detects all 5 instances automatically.

Deployment Topologies

A) Standalone (replaces nginx):
   Internet --> GuardianWAF(:443 + :80) --> backend-api:3000
                                        --> backend-web:8000

B) Behind CDN:
   Cloudflare --> GuardianWAF(:8088) --> backends
   (TLS handled by Cloudflare)

C) Kubernetes Sidecar:
   Ingress --> GuardianWAF(:8088) --> app(:3000)

D) Embedded Library:
   Go app --> waf.Middleware(handler)

Why GuardianWAF?

GuardianWAF was built to eliminate the trade-offs other WAF solutions force: complex rule sets, dependency trees, vendor lock-in, or requiring a host process. One binary, zero dependencies, transparent scoring.

Comparison as of March 2026. Check each project for current status.

Architecture

                          GuardianWAF Pipeline
                          ====================

  HTTP Request
       |
       v
  +-----------+   +-------------+   +-----------+   +------------+   +-----------+
  |  IP ACL   |-->| Threat Intel|-->|   CORS    |-->| Rate Limit |-->|    ATO    |
  |   (100)   |   |    (125)    |   |   (150)   |   |    (200)   |   |   (250)   |
  +-----------+   +-------------+   +-----------+   +------------+   +-----------+
                                                                            |
       +--------------------------------------------------------------------+
       |
       v
  +-------------+   +------------+   +------------+   +------------+   +-----------+
  | API Security|-->| Sanitizer  |-->| Detection  |-->| Bot Detect |-->|  Response |
  |    (275)    |   |    (300)   |   |    (400)   |   |    (500)   |   |   (600)   |
  +-------------+   +------------+   +------------+   +------------+   +-----------+
                                                                              |
       +----------------------------------------------------------------------+
       |
       v
  +-----------+    +----------------+
  |    JS     |--->|   Upstream     |
  | Challenge |    | Load Balancer  |
  +-----------+    +----------------+
  (score 40-79)    |  |  |  |  |
                   v  v  v  v  v
                  Backend Targets
                  (health checked,
                   circuit breaker)

Each layer runs in order and can pass, log, challenge, or block the request. The detection layer runs 6 independent detectors (SQLi, XSS, LFI, CMDi, XXE, SSRF) and produces a cumulative threat score. Bot detection scores between 40-79 trigger a JavaScript proof-of-work challenge instead of blocking outright.

Detection Engine

GuardianWAF uses a tokenizer-based scoring system instead of binary allow/block rules. HTTP requests are lexically decomposed into typed tokens, scored against attack patterns, and evaluated with configurable thresholds.

Example: How scoring produces graduated responses

Input: "O'Brien"
  -> Single apostrophe              score: 10
  -> Total: 10                      -> ALLOW (below log threshold)

Input: "' OR 'a'='a"
  -> Apostrophe + OR keyword        score: 30
  -> Tautology pattern              score: +55
  -> Total: 85                      -> BLOCK (above block threshold)

Input: Suspicious bot (UA: curl, high RPS)
  -> Bot score: 55                  -> JS CHALLENGE (proof-of-work page)
  -> Browser solves SHA-256 puzzle  -> Sets cookie, request passes
  -> Bot can't solve               -> Stays blocked

This graduated response eliminates most false positives while catching real attacks. Every blocked request includes the full score breakdown for transparent, data-driven tuning.

See Detection Engine docs for the full pattern scoring table.

Installation

go install

go install github.com/guardianwaf/guardianwaf/cmd/guardianwaf@latest

Binary Download

# Linux (amd64)
curl -Lo guardianwaf https://github.com/guardianwaf/guardianwaf/releases/latest/download/guardianwaf-linux-amd64
chmod +x guardianwaf
sudo mv guardianwaf /usr/local/bin/

# macOS (arm64)
curl -Lo guardianwaf https://github.com/guardianwaf/guardianwaf/releases/latest/download/guardianwaf-darwin-arm64
chmod +x guardianwaf
sudo mv guardianwaf /usr/local/bin/

Docker (GHCR)

docker pull ghcr.io/guardianwaf/guardianwaf:latest

Build from Source

git clone https://github.com/guardianwaf/guardianwaf.git
cd guardianwaf
make build
# Binary: ./guardianwaf

Configuration

Minimal guardianwaf.yaml to protect a backend:

mode: enforce
listen: ":8088"

upstreams:
  - name: backend
    targets:
      - url: "http://localhost:3000"

routes:
  - path: /
    upstream: backend

waf:
  detection:
    threshold:
      block: 50
      log: 25
  challenge:
    enabled: true
    difficulty: 20

dashboard:
  enabled: true
  listen: ":9443"
  api_key: "your-secret-key"

Configuration layering: defaults -> YAML file -> environment variables (GWAF_ prefix) -> CLI flags.

See Configuration Reference for the complete YAML schema.

Dashboard

GuardianWAF includes a built-in web dashboard accessible on the configured listen address (default :9443).

Monitoring (/)

• Real-time traffic monitoring (requests/sec, blocks/sec, challenges, latency)
• Security event feed with filtering by action, IP, path, score
• Click any event to see full details: findings, matched patterns, threat scores
• Attack type breakdown and top source IPs charts
• Upstream health: backend status, circuit breaker state, active connections

Configuration (/config)

• Upstream management: add/remove backends, set load balancing strategy and weights
• Virtual host management: add/remove domains, configure per-domain routing
• Route management: path-to-upstream mapping with prefix stripping
• WAF settings: toggle detectors, adjust thresholds and multipliers
• JS Challenge: enable/disable, set difficulty
• Bot detection: mode, scanner blocking, behavioral thresholds
• IP ACL: add/remove whitelist and blacklist entries in real-time
• Rate limiting, sanitizer, response protection toggles

Routing (/routing)

• Topology Graph -- interactive React Flow visualization of the full request path: Clients -> WAF -> VHosts -> Routes -> Upstreams -> Targets, with TLS/SSL indicators, ports, health status, circuit breaker state
• Backends -- Docker-discovered services table + static upstreams, with container name, image, target URL, upstream pool, weight, health check path
• Configure -- form-based upstream/route/vhost management with save & rebuild

AI Analysis (/ai)

• Provider catalog (400+ from models.dev) with search and model details
• Model selection with context window, cost, reasoning/tool_call capabilities
• API key management with connection testing
• Manual "Analyze Now" trigger with instant verdict display
• Analysis history with expandable results, threats, verdicts, costs
• Usage stats: tokens/hour, requests/hour, total cost, AI blocks

REST API: The dashboard exposes a full REST API for programmatic management, protected by API key authentication.

Access at http://localhost:9443 (enabled by default in standalone mode).

Library Usage

Minimal

waf, err := guardianwaf.New(guardianwaf.Config{
    Mode:      guardianwaf.ModeEnforce,
    Threshold: guardianwaf.ThresholdConfig{Block: 50, Log: 25},
})
if err != nil {
    log.Fatal(err)
}
defer waf.Close()

http.ListenAndServe(":8088", waf.Middleware(myHandler))

Advanced (Functional Options)

waf, err := guardianwaf.New(guardianwaf.Config{},
    guardianwaf.WithMode(guardianwaf.ModeEnforce),
    guardianwaf.WithThreshold(60, 30),
    guardianwaf.WithDetector("sqli", true, 1.5),   // 50% more sensitive
    guardianwaf.WithDetector("xss", true, 0.5),     // 50% less sensitive
    guardianwaf.WithIPWhitelist("10.0.0.0/8"),
    guardianwaf.WithIPBlacklist("203.0.113.0/24"),
    guardianwaf.WithBotDetection(true),
    guardianwaf.WithSecurityHeaders(true),
    guardianwaf.WithDataMasking(true),
    guardianwaf.WithMaxEvents(50000),
)
if err != nil {
    log.Fatal(err)
}
defer waf.Close()

// Event callback for custom alerting
waf.OnEvent(func(event guardianwaf.Event) {
    if event.Action.String() == "block" {
        fmt.Printf("[BLOCKED] %s %s from %s (score: %d)\n",
            event.Method, event.Path, event.ClientIP, event.Score)
    }
})

// Manual request check (without middleware)
result := waf.Check(req)
fmt.Printf("Score: %d, Blocked: %v, Findings: %d\n",
    result.TotalScore, result.Blocked, len(result.Findings))

MCP Integration

GuardianWAF includes a built-in Model Context Protocol server that enables AI agents to monitor, query, and manage the WAF through structured tool calls. Two transports: stdio (local CLI) and SSE (remote HTTP with API key auth).

15 MCP tools:

Claude Code (stdio):

{
  "mcpServers": {
    "guardianwaf": {
      "command": "guardianwaf",
      "args": ["serve", "-c", "guardianwaf.yaml"]
    }
  }
}

Claude Desktop / VS Code (SSE — remote):

{
  "mcpServers": {
    "guardianwaf": {
      "url": "http://your-waf-host:9443/mcp/sse",
      "headers": { "X-API-Key": "your-api-key" }
    }
  }
}

Then ask: "Show me the latest blocked requests and blacklist the top attacking IP."

See MCP Integration docs for the complete tool reference, SSE protocol details, and curl examples.

Performance

GuardianWAF targets sub-millisecond p99 latency overhead per request.

Design choices for performance:

• Zero-allocation hot paths with sync.Pool for request contexts
• Atomic counters for statistics (no mutex contention)
• Radix tree for IP lookups (O(k) where k = address bits)
• Token bucket rate limiter (O(1) per check)
• State-machine tokenizer (no regex on the hot path)
• Circuit breaker with atomic state transitions (lock-free)

Documentation

Full documentation site: guardianwaf.com/docs

Project Structure

guardianwaf/
├── cmd/guardianwaf/       # CLI entry point (serve, sidecar, check, validate)
├── internal/
│   ├── engine/            # Core WAF engine, pipeline, scoring, access logging, panic recovery
│   ├── config/            # YAML parser + serializer, config structs, env loading, validation
│   ├── layers/
│   │   ├── ipacl/         # IP whitelist/blacklist (radix tree, runtime add/remove, auto-ban)
│   │   ├── threatintel/   # Threat intelligence feeds (IP/domain reputation, LRU cache)
│   │   ├── cors/          # CORS validation (origin allowlist, preflight handling)
│   │   ├── ratelimit/     # Token bucket rate limiter (dynamic rule add/remove)
│   │   ├── ato/           # Account takeover protection (brute force, credential stuffing)
│   │   ├── apisecurity/   # API authentication (JWT validation, API keys)
│   │   ├── sanitizer/     # Request normalization and validation
│   │   ├── detection/     # Attack detectors (sqli/xss/lfi/cmdi/xxe/ssrf) with dynamic exclusions
│   │   ├── botdetect/     # Bot detection (JA3/JA4, UA, behavior)
│   │   ├── challenge/     # JS proof-of-work challenge (SHA-256 PoW)
│   │   ├── response/      # Response protection (headers, masking, error pages)
│   │   └── rules/         # Custom rule engine (geo-aware, dashboard CRUD)
│   ├── proxy/             # Reverse proxy, load balancer, circuit breaker, router, WebSocket
│   ├── tls/               # TLS cert store, SNI selection, hot-reload, HTTP/2
│   ├── acme/              # ACME client (RFC 8555), HTTP-01 challenge, cert cache
│   ├── dashboard/         # React UI, REST API, SSE, routing graph, AI page, Docker services
│   ├── ai/                # AI threat analysis (models.dev catalog, OpenAI client, batch analyzer)
│   ├── docker/            # Docker auto-discovery (socket client, label parser, event watcher)
│   ├── mcp/               # MCP JSON-RPC server and 15 tool definitions
│   ├── geoip/             # GeoIP database with auto-download and runtime refresh
│   └── events/            # Event storage (memory ring buffer, JSONL file, event bus)
├── guardianwaf.go         # Public API for library mode
├── options.go             # Functional options (WithMode, WithThreshold, etc.)
├── examples/              # Library and backend examples
├── docs/                  # Documentation (docker-discovery, ai-analysis, etc.)
├── testdata/              # Test configs and attack payloads
├── scripts/               # Attack simulation, smoke tests, real E2E tests
├── Dockerfile             # Multi-stage Alpine build
├── docker-compose.yml     # Standalone + auto-discovery example with gwaf.* labels
└── Makefile               # build, test, lint, bench, fuzz, cover, docker-test

Contributing

Contributions are welcome. GuardianWAF values quality over velocity -- clean code, thorough tests, and zero external dependencies.

1. Fork the repository.
2. Create a feature branch.
3. Run make test and make vet to verify all tests pass.
4. New features should include tests.
5. No external dependencies -- everything is implemented from scratch.
6. Submit a pull request with a clear description of changes.

See CONTRIBUTING.md for full guidelines.

License

MIT -- the core WAF is fully open source. Enterprise features (cluster mode, commercial support) will be available under a separate commercial license in the future.

Author

Ersin Koc / x.com/ersinkoc

• GitHub: @ersinkoc
• Website: guardianwaf.com