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.

Getting Started

The fastest way to deploy WAFio is with the all-in-one installer script. It handles everything: license activation, PostgreSQL setup, binary download, security data, database migrations, admin account, agent provisioning, and systemd services — in a single run.

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

Verify Services

After installation, you can verify all three 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 will create a dedicated wafio database and role — your existing databases are not touched.

Required: PostgreSQL 14+ with the TimescaleDB extension. The installer enables it automatically if TimescaleDB is installed but the extension is not yet active in the wafio database.

Fresh PostgreSQL Install

If no PostgreSQL is detected, the installer installs the latest PostgreSQL and TimescaleDB packages for your distro (Ubuntu/Debian via apt, RHEL/Rocky/CentOS via dnf/yum), then creates the wafio database automatically.

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.

On connect, the control plane pushes a bundle containing the full WAF configuration. The agent applies this configuration and begins inspecting traffic. Any subsequent configuration change is pushed automatically without restarting the agent.

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)

Run this single command from the directory where the wafio binary lives:

# 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.9.0 (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 (34s)

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 (slightly more accurate), obtain a free license key at maxmind.com/en/geolite2/signup and set it in config:

geo:
  maxmind_license_key: "YOUR_FREE_LICENSE_KEY_HERE"

Then re-run ./wafio fetch-data --force to download MaxMind databases.

Profile Shortcuts

Use --profile to download only the components a specific binary needs:

Useful Options

# Update only GeoIP databases (e.g. monthly refresh)
./wafio fetch-data --only geoip

# Force re-download everything (overwrite existing files)
./wafio fetch-data --force

# Download a specific CRS version
./wafio fetch-data --crs-version v4.9.0

# Use MaxMind key from CLI (overrides config)
./wafio fetch-data --maxmind-key YOUR_KEY_HERE

Keeping Data Fresh

GeoIP databases are updated monthly by DB-IP/MaxMind. FireHOL and JA3 lists update daily. We recommend adding a monthly cron job:

# /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. This wizard configures the control plane, runs database migrations, and creates your first admin account.

The wizard is safe to interrupt — if you close the browser, it will resume from the last completed step when you return. Once all three steps are complete, the wizard never appears again.

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 (see WAF Agent Setup)

Quick Start (Manual)

This guide walks you through deploying WAFio manually — control plane first, then agents.

docker compose up -d db manticore

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"

logs:
  manticore_index: waf_events

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

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

# Copy binary + certs to agent machine
scp wafio-waf-agent user@agent-server:/usr/local/bin/
scp ca.crt client.crt client.key user@agent-server:/etc/wafio/certs/

# Start the agent
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 page shows the health of all four protection layers at a glance: WAF Agents, Firewall, Runtime Security, and Hosts. Key metrics include the Security Score gauge, WAF latency SLA, total blocked requests, and critical events 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, how many applications it is protecting, and when it last connected.

WAF Agents — register and manage HTTP inspection agents

Click View applications → on an agent card to see the upstream apps protected by that agent, and to configure per-app WAF rules (sensitivity level, block threshold, custom exclusions).

Firewall

The Firewall page manages the eBPF kernel firewall on each host. Select a host to 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 — all at the kernel level, with zero application instrumentation.

Runtime Security — syscall-level tracing for anomaly detection

Select a host to view its live event stream. Events are categorized by severity (INFO, LOW, MEDIUM, HIGH, CRITICAL). Detection rules are Falco-compatible — you can write conditions on process name, parent process, filename, network address, UID, and more.

Hosts

The Hosts page lists all machines running the WAFio host agent. Each host entry shows its online status, hardware fingerprint, registered host key, and the last time it was seen. This is also where you register new hosts before deploying the host agent.

Hosts — register and monitor all machines running the host agent

Credentials

Credentials provisions mTLS client certificates for agents. Each certificate is signed by the project's internal CA. The private key is shown once at provisioning time — download and store it securely.

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.

How It Works

Systemd Service

For production deployment, install the agent as a 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 — the new process inherits all listening sockets before the old one drains and exits.

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 a Linux kernel 5.8+ with BTF enabled.

Register a Host

Before deploying the agent, register the host in the dashboard:

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

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

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 is 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 will lose its connection within seconds. Revocation is immediate and permanent — provision a new credential if you need to reconnect the agent.

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. The agent does not need to be restarted. Changes are reflected in the dashboard within 1–2 seconds.

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. Each rule has ordered conditions (all AND-ed) and an action:

Condition Fields

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

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

Example: Suppress Noisy Docker Events

# Suppress all events from the 'containerd-shim' process
conditions:
  - field: comm
    op: eq
    value: containerd-shim
action: suppress

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

Eight AST/parser-based analyzers run in parallel — each specialized for a specific attack category:

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.

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. The 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

Sensitivity Levels

Tuning False Positives

• Lower the project sensitivity level (Safe → Balanced)
• 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 results when the semantic engine finds nothing

Configuration Reference

Configuration is loaded in priority order: config/config.yaml → WAFIO_* environment variables → CLI flags.

Every YAML key maps to an environment variable: server.http_addr → WAFIO_SERVER_HTTP_ADDR.

Required Settings

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

logs:
  manticore_addr: "127.0.0.1:9306"
  manticore_index: waf_events

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

crs:
  path: "./security-data/crs"   # path to OWASP CRS rules

WAF Project Config (per-project JSON)

Each project stores its WAF configuration as a JSON blob. These settings control blocking behavior for that project:

{"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
}

License & Hardware Binding

WAFio uses a hardware-bound license model. Your license key is tied to the machine where the control plane runs — it cannot be used on a different machine without re-issuance.

Obtaining a License

1. Register at wafio.cloud
2. Log in to your portal account
3. Navigate to the dashboard and click Generate License Key
4. The portal will issue a license key for your account

Activating a License

# Activate license on the control plane machine
./wafio license activate --key LICENSE-XXXX-XXXX-XXXX

# Verify activation
./wafio license status

Hardware Binding

When the control plane starts with a license key, it computes a hardware fingerprint from the machine's CPU, motherboard, and network interface identifiers. This fingerprint is recorded on the licensing server. If the fingerprint changes (e.g. machine migration), the license enters a grace period of 72 hours — contact support for re-issuance.

Free Tier Entitlements