WAFio Documentation

WAFio is a self-hosted Web Application Firewall and kernel-level security platform. It runs entirely on your infrastructure — no cloud dependency, no data leaves your network.

Quick Start (install.sh)

The fastest way to deploy WAFio is the all-in-one installer script. One command — downloads garble-obfuscated binaries, installs PostgreSQL + TimescaleDB, runs migrations, creates your admin account, provisions mTLS certificates, and starts all three components as systemd services.

curl -fsSL https://wafio.cloud/install.sh | sudo bash

curl -fsSL https://wafio.cloud/install.sh | sudo bash -s -- --component waf-agent

Verify Services

After installation, verify all services are running:

sudo systemctl status wafio wafio-waf-agent wafio-host-agent

# View live logs
sudo journalctl -u wafio -f
sudo journalctl -u wafio-waf-agent -f
sudo journalctl -u wafio-host-agent -f

PostgreSQL Already Installed?

If your server already has PostgreSQL running, the installer asks for your connection details. It creates a dedicated wafio database — your existing databases are not touched. Required: PostgreSQL 14+ with TimescaleDB extension.

Upgrading an Existing Install

Re-running the installer on a server that already has WAFio is safe and idempotent. The script auto-detects an existing install and switches to upgrade mode:

• Stops the running services before replacing binaries (no "text file busy")
• Preserves your config.yaml — JWT secret and database credentials are kept, so users stay logged in and login keeps working (a timestamped .bak is saved)
• Skips admin, project, and credential creation — no duplicate projects, no setup errors
• Keeps existing agent *.env files and certificates
• Refreshes binaries, frontend assets, database migrations, and security data, then restarts services

# Same command — upgrades in place
curl -fsSL https://wafio.cloud/install.sh | sudo bash

Architecture

WAFio uses a hub-and-spoke architecture. The Control Plane is the central brain — it stores configuration, aggregates telemetry, and pushes rule updates to agents over a gRPC mTLS channel.

Component Roles

How Agents Connect

Agents connect to the control plane over gRPC using mutual TLS (mTLS). Each agent presents a client certificate provisioned from the Credentials page. The certificate's SHA-256 fingerprint identifies which project the agent belongs to — no additional API key needed at runtime.

On connect, the control plane pushes a bundle containing the full WAF configuration. The agent applies it and begins inspecting traffic. Subsequent configuration changes are pushed automatically without restarting the agent.

Storage

Security Data Setup

WAFio requires external threat intelligence data — GeoIP databases, OWASP CRS rules, IP reputation lists, JA3 fingerprints, and bot signatures. This data is not bundled in the binary and must be downloaded separately.

Download Everything (Recommended)

# Download all security data (no MaxMind account required)
./wafio fetch-data

# Output example:
# ── GeoIP country  ✓  (DB-IP free, 2026-05)
# ── GeoIP city     ✓  (DB-IP free, 2026-05)
# ── GeoIP ASN      ✓  (DB-IP free, 2026-05)
# ── OWASP CRS      ✓  v4.x (147+ rule files)
# ── FireHOL L1     ✓  (812,291 entries)
# ── FireHOL L2     ✓  (additional 1.4M entries)
# ── JA3 blacklist  ✓  (Salesforce + abuse.ch)
# ── Bot UA list    ✓  (nginx bad-bot-blocker)
# ✅  All security data fetched successfully

What Gets Downloaded

GeoIP Provider: DB-IP vs MaxMind

By default, WAFio downloads from DB-IP — a free GeoIP provider with no account or license key required. If you need MaxMind GeoLite2, obtain a free license key at maxmind.com and set it in config:

geo:
  maxmind_license_key: "YOUR_FREE_LICENSE_KEY_HERE"

Then re-run ./wafio fetch-data --force.

Keeping Data Fresh

GeoIP databases update monthly. FireHOL and JA3 lists update daily. Recommended monthly cron:

# /etc/cron.d/wafio-update-security-data
0 3 1 * * root /opt/wafio/wafio fetch-data --profile all >> /var/log/wafio/fetch-data.log 2>&1

Setup Wizard (Manual Install)

On first launch of a manually installed control plane, WAFio shows a 3-step Setup Wizard at http://your-server:9087. It configures the control plane, runs database migrations, and creates your first admin account.

After the Wizard

1. Log in with your admin credentials at http://your-server:9087/login
2. Click New Project to create your first security project
3. Go to Credentials and provision an mTLS certificate for each agent
4. Deploy WAF and/or Host agents using the certificates

Manual Install

# Download WAFio bundles
curl -fsSL "https://wafio.cloud/api/download/controlplane" -o wafio-controlplane.tar.gz
curl -fsSL "https://wafio.cloud/api/download/waf-agent" -o wafio-waf-agent.tar.gz
curl -fsSL "https://wafio.cloud/api/download/host-agent" -o wafio-host-agent.tar.gz

# Verify checksums (from manifest)
MANIFEST=$(curl -fsSL https://wafio.cloud/api/download/manifest)
# Extract sha256 values and verify with sha256sum

docker compose up -d db

cp config/config.example.yaml config/config.yaml

server:
  http_addr: ":9087"
  env: production

database:
  host: localhost
  port: 5432
  name: wafio
  user: wafio
  password: your-db-password

jwt:
  secret: "your-32-char-secret-here"

# Run migrations + start server
./wafio serve --migrate

# Or run in background
nohup ./wafio serve --migrate > wafio-server.log 2>&1 &

scp wafio-waf-agent user@agent-server:/usr/local/bin/
scp ca.crt client.crt client.key user@agent-server:/etc/wafio/certs/

WAFIO_GRPC_SERVER=your-control-plane:9090 \
WAFIO_CA_CERT=/etc/wafio/certs/ca.crt \
WAFIO_CLIENT_CERT=/etc/wafio/certs/client.crt \
WAFIO_CLIENT_KEY=/etc/wafio/certs/client.key \
WAFIO_AGENT_NAME=edge-waf-prod \
WAFIO_LISTEN_ADDR=:8080 \
WAFIO_UPSTREAM=http://localhost:3000 \
./wafio-waf-agent

curl "http://your-agent:8080/?id=1' OR '1'='1"
# Expected: 403 Forbidden (if blocking mode is enabled)

Dashboard Tour

The WAFio dashboard gives you a real-time view of your infrastructure's security posture. Here is a walkthrough of every section.

Projects List

The projects list is your starting point. Each project represents an isolated security environment — with its own agents, credentials, WAF rules, and event log.

Projects list — create and manage isolated security environments

Project Overview

The Overview shows the health of all protection layers: WAF Agents, Firewall, Runtime Security, and Hosts. Key metrics include Security Score, WAF latency SLA, total blocked requests, and critical event count.

Project Overview — system health, security score, and protection coverage

WAF Agents

The WAF Agents page lists all registered agents for this project. Each agent card shows its online status, protected application count, and last connection time. Click View applications → to configure per-app WAF rules.

WAF Agents — register and manage HTTP inspection agents

Firewall

The Firewall page manages the eBPF kernel firewall on each host. Configure inbound/outbound rules, IP blocklists, country blocking, and SYN flood protection. Rules are applied instantly via BPF maps — no iptables, no service restart.

Firewall — kernel-level L3/L4 packet filtering via eBPF/XDP

Runtime Security

Runtime Security uses eBPF tracepoints to monitor process execution, file access, network connections, and privilege escalation — at the kernel level, with zero application instrumentation. Events are categorized by severity (INFO, LOW, MEDIUM, HIGH, CRITICAL).

Runtime Security — syscall-level tracing for anomaly detection

Hosts

The Hosts page lists all machines running the WAFio host agent. Each entry shows online status, OS and kernel version, CPU/memory info, host key prefix, and last-seen time.

Hosts — register and monitor all machines running the host agent

Credentials

Credentials provisions mTLS client certificates for agents. The private key is shown once at provisioning time — download and store it securely. It is never stored on the control plane.

Credentials — provision and manage mTLS client certificates for agents

Audit Log

The Audit Log records every action taken by project members: logins, configuration changes, credential provisioning, agent registration, and WAF rule changes. Use it for compliance, incident investigation, and change tracking.

Audit Log — immutable record of all project actions

WAF Agent Setup

The WAF agent is a lightweight HTTP reverse-proxy sidecar. Deploy it in front of any HTTP/HTTPS application. It intercepts every request, runs it through the detection pipeline, and either forwards, logs, or blocks it — in under 5ms p99.

Detection Pipeline

Systemd Service

[Unit]
Description=WAFio WAF Agent
After=network.target

[Service]
Type=notify
ExecStart=/usr/local/bin/wafio-waf-agent
ExecReload=/bin/kill -USR2 $MAINPID
Restart=on-failure
RestartSec=5s
Environment=WAFIO_GRPC_SERVER=10.1.1.2:9090
Environment=WAFIO_CA_CERT=/etc/wafio/certs/ca.crt
Environment=WAFIO_CLIENT_CERT=/etc/wafio/certs/client.crt
Environment=WAFIO_CLIENT_KEY=/etc/wafio/certs/client.key
Environment=WAFIO_AGENT_NAME=waf-prod-01
Environment=WAFIO_LISTEN_ADDR=:8080
Environment=WAFIO_UPSTREAM=http://localhost:3000

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now wafio-waf-agent
systemctl status wafio-waf-agent

Zero-Downtime Reload

The WAF agent supports graceful restarts via tableflip. Send SIGUSR2 (or systemctl reload wafio-waf-agent) to perform a zero-downtime restart. Supports Type=notify in systemd — sends READY=1 only after the first bundle is received from the control plane.

Key Environment Variables

Host Agent Setup

The host agent runs on Linux and provides two capabilities: a kernel-level eBPF firewall (XDP/TC) and runtime security tracing (syscall/tracepoint hooks). It requires root privileges and Linux kernel 5.8+ with BTF enabled.

Register a Host

1. Go to Hosts in your project sidebar
2. Click Register Host
3. Enter a name and description
4. Copy the generated host key — pass this to the agent via WAFIO_HOST_KEY

Systemd Service

[Unit]
Description=WAFio Host Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/wafio-host-agent
Restart=on-failure
RestartSec=5s
Environment=WAFIO_GRPC_SERVER=10.1.1.2:9090
Environment=WAFIO_CA_CERT=/etc/wafio/certs/ca.crt
Environment=WAFIO_CLIENT_CERT=/etc/wafio/certs/client.crt
Environment=WAFIO_CLIENT_KEY=/etc/wafio/certs/client.key
Environment=WAFIO_HOST_KEY=your-host-key-here

[Install]
WantedBy=multi-user.target

What the Host Agent Monitors

Container Enrichment

The host agent polls Docker/containerd sockets every 10 seconds to map cgroup IDs → container metadata (image, name, labels, Kubernetes pod/namespace). All trace events from containers are automatically tagged with this context. Degrades gracefully if no Docker socket is present.

Credentials (mTLS)

Every agent authenticates to the control plane using a mutual TLS client certificate. WAFio uses its own internal CA per project — no public CA involved.

Provisioning a Credential

1. Navigate to Credentials in your project
2. Enter a descriptive name (e.g. waf-prod-edge or host-vpn-server)
3. Set expiry in days (default: 365)
4. Click Provision
5. The modal shows the one-time credential bundle — copy or download it immediately

Credential Bundle Contents

Revoking a Credential

Click Revoke next to any issued credential. The agent loses its connection within seconds. Revocation is immediate and permanent — provision a new credential to reconnect.

Firewall

The WAFio firewall operates at the kernel level using eBPF XDP and TC hooks. It processes packets before they reach the kernel's network stack — orders of magnitude faster than iptables or nftables.

Firewall Rule Types

Rule Application

Rules are pushed to the agent as BPF map updates — they take effect instantly with no traffic interruption. No agent restart needed. Changes reflect in the dashboard within 1–2 seconds.

Enforcement Modes

Runtime Security

Runtime security uses eBPF tracepoints to hook into kernel syscalls — detecting suspicious behavior at the source rather than relying on log-based detection after the fact.

Detection Rules

WAFio ships with built-in detection rules seeded at project creation. Rules cannot be deleted (only disabled). Custom rules can be added, updated, or deleted by project owners. Each rule has ordered AND-ed conditions and an action:

Condition Fields

Rules can match on: comm, parent_comm, grandparent_comm, event_name, category, severity, filename, addr, port, uid, gid, addr_family, flags, is_container, container_image.

Supported operators: eq, neq, in, not_in, contains, starts_with, glob, gte, lte.

Example: Suppress Noisy Docker Events

conditions:
  - field: comm
    op: eq
    value: containerd-shim
action: suppress

SIEM Export

Runtime security events can be exported to external SIEM systems via webhook or stdout. Configure in the project settings under Data Retention & Export.

Detection Engine

WAFio's detection pipeline runs two independent analysis layers on every HTTP request. Both results are combined by the Decision Engine to produce a final verdict.

Layer 1: Semantic Engine (14 Analyzers)

Fourteen AST/parser-based analyzers run in parallel — each specialized for a specific attack category. They operate on decoded, normalized input with multiple smudge attempts to defeat evasion techniques. Each input is gated by a fast pre-filter, so only the analyzers relevant to a given payload actually run.

Layer 2: OWASP CRS v4

Coraza runs OWASP Core Rule Set v4 in DetectionOnly mode — it never blocks directly. Matched rule IDs are fed into the Decision Engine. When all semantic engines return clean and skip_coraza_when_semantic_clean: true (default), CRS attack-category results are suppressed to reduce false positives.

Decision Engine

For each matched CRS rule, the Decision Engine looks up its RuleMeta: attack category, base score, sensitivity level, and confidence multiplier. Rules above the project's sensitivity threshold are silently dropped. Remaining scores are summed:

total_score = Σ (base_score × confidence) for each matched rule

if total_score >= block_threshold  → BLOCK
if total_score >= log_threshold    → LOG
else                               → ALLOW

If both the semantic engine and CRS agree on the same attack category, the score is elevated via cross-engine boost.

Sensitivity Levels

Tuning False Positives

• Lower the project sensitivity level (Aggressive → Balanced → Safe)
• Raise the block_threshold in project WAF config
• Add path exceptions for known-safe routes (health checks, webhooks)
• Enable skip_coraza_when_semantic_clean: true (default) to suppress CRS noise when semantic engine finds nothing
• Bump individual CRS rule Sensitivity to 3 for known-noisy rules in decision.go

Configuration Reference

Configuration is loaded in priority order: config/config.yaml → WAFIO_* environment variables → CLI flags. Every YAML key maps to an env var: server.http_addr → WAFIO_SERVER_HTTP_ADDR.

Required Settings

Hot-Reload vs Restart Required

Common Settings

server:
  http_addr: ":9087"          # HTTP listen address
  grpc_addr: ":9090"          # gRPC listen address for agents
  env: production             # "development" or "production"

database:
  host: localhost
  port: 5432
  name: wafio
  user: wafio
  password: secret
  max_conns: 20

jwt:
  secret: "change-me-in-production"
  expiry_hours: 24

smtp:
  host: smtp.example.com
  port: 587
  user: noreply@example.com
  password: smtp-password

crs:
  path: "./security-data/crs"

WAF Project Config (per-project JSON)

{"block_threshold": 5.0,
  "log_threshold": 2.0,
  "sensitivity": 2,
  "skip_coraza_when_semantic_clean": true,
  "geo_block_countries": [],
  "bot_protection": true,
  "rate_limit_rps": 100
}

Downloads

WAFio is free to download from the wafio.cloud portal — no account, signup, or API key required. Every download is recorded anonymously (component, version, and network metadata) for release analytics; no personal data is collected.

Download Endpoints

Using the API

# Check current version and checksums
curl -s https://wafio.cloud/api/download/manifest | python3 -m json.tool

# Download WAF agent bundle (no key needed)
curl -fsSL "https://wafio.cloud/api/download/waf-agent" -o wafio-waf-agent.tar.gz

# Verify checksum
EXPECTED=$(curl -s https://wafio.cloud/api/download/manifest \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['bundles']['waf-agent']['sha256'])")
echo "$EXPECTED  wafio-waf-agent.tar.gz" | sha256sum -c

Bundle Contents

Each bundle is a .tar.gz archive containing the binary and an install.sh helper script. Binaries are built with garble obfuscation (-literals -seed=random) for distribution — symbol names, package paths, and string literals are obfuscated in every release.

Error Responses