WafWay Documentation

Welcome to WafWay documentation. WafWay is an enterprise-grade Web Application Firewall that protects your applications from SQL injection, XSS, and other OWASP Top 10 threats.

Quick Start

Get WafWay running in just a few commands:

1. Download the Binary

# Using curl
curl -sSL https://get.wafway.io | sh

# Or download directly
wget https://github.com/wafway/wafway/releases/latest/download/wafway-linux-amd64
chmod +x wafway-linux-amd64
sudo mv wafway-linux-amd64 /usr/local/bin/wafway

2. Create Configuration

# Create config directory
sudo mkdir -p /etc/wafway

# Create basic config
sudo tee /etc/wafway/wafway.yaml << 'EOF'
edition: community

server:
  listen_addr: "0.0.0.0"
  http_port: 80
  admin_port: 8080

backend:
  url: "http://127.0.0.1:3000"  # Your application
  timeout: 30s

protection:
  mode: "medium"
  sqli:
    enabled: true
  xss:
    enabled: true
  rate_limit:
    enabled: true
    requests_per_minute: 100

dashboard:
  enabled: true
  username: "admin"
EOF

3. Start WafWay

# Run directly
sudo wafway --config /etc/wafway/wafway.yaml

# Or as a service
sudo systemctl enable wafway
sudo systemctl start wafway

4. Access Dashboard

Open your browser and navigate to http://your-server:8080 to access the dashboard.

System Requirements

Linux Installation

WafWay supports all major Linux distributions including Ubuntu, Debian, CentOS, RHEL, and AlmaLinux.

Using the Install Script (Recommended)

curl -sSL https://get.wafway.io | sh

This script will:

• Download the latest WafWay binary
• Create necessary directories
• Install the systemd service
• Create a default configuration

Manual Installation

# Create service user
sudo useradd --system --no-create-home --shell /sbin/nologin wafway

# Create directories
sudo mkdir -p /opt/wafway /etc/wafway /var/log/wafway /var/lib/wafway

# Download binary
sudo wget -O /opt/wafway/wafway \
    https://github.com/wafway/wafway/releases/latest/download/wafway-linux-amd64

# Set permissions
sudo chmod 755 /opt/wafway/wafway
sudo chown -R wafway:wafway /var/log/wafway /var/lib/wafway

# Create symlink
sudo ln -sf /opt/wafway/wafway /usr/local/bin/wafway

Docker Installation

# Quick start with Docker
docker run -d \
    -p 80:80 \
    -p 8080:8080 \
    -e BACKEND_URL=http://host.docker.internal:3000 \
    wafway/waf:latest

# With docker-compose
version: '3.8'
services:
  waf:
    image: wafway/waf:latest
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - ./wafway.yaml:/etc/wafway/wafway.yaml
      - waf-data:/var/lib/wafway
    restart: unless-stopped

volumes:
  waf-data:

Nginx Integration

WafWay can be deployed in front of Nginx or behind it, depending on your architecture.

Option 1: WAF in Front of Nginx (Recommended)

# Traffic flow: Internet -> WafWay:80 -> Nginx:8080 -> App

# 1. Update Nginx to listen on port 8080
server {
    listen 8080;  # Changed from 80
    server_name example.com;

    # Trust WAF headers
    set_real_ip_from 127.0.0.1;
    real_ip_header X-Forwarded-For;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

# 2. Configure WafWay
backend:
  url: "http://127.0.0.1:8080"  # Points to Nginx

Option 2: Nginx in Front of WAF

# Traffic flow: Internet -> Nginx:80 -> WafWay:8081 -> App

# Nginx config
server {
    listen 80;

    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

# WafWay config
server:
  listen_addr: "127.0.0.1"  # Local only
  http_port: 8081

backend:
  url: "http://127.0.0.1:3000"

Basic Configuration

The main configuration file is located at /etc/wafway/wafway.yaml.

# Complete configuration example
edition: enterprise

server:
  listen_addr: "0.0.0.0"
  http_port: 80
  https_port: 443
  read_timeout: 30s
  write_timeout: 30s

backend:
  url: "http://127.0.0.1:8000"
  timeout: 30s
  health_check_path: "/health"
  health_check_interval: 30s

protection:
  mode: "medium"  # paranoid, high, medium, low, detect

dashboard:
  enabled: true
  port: 8080
  username: "admin"

logging:
  level: "info"
  file: "/var/log/wafway/waf.log"

Protection Modules

WafWay includes multiple protection modules that can be individually enabled and configured:

Rate Limiting

Configure rate limiting to prevent abuse:

rate_limit:
  enabled: true
  requests_per_minute: 100
  window_size: 60
  ban_duration: 10m
  whitelist:
    - "10.0.0.0/8"      # Internal network
    - "192.168.0.0/16"  # Private network

Geo Blocking

Block or allow traffic by country:

geo_block:
  enabled: true
  geoip_path: "/etc/wafway/GeoLite2-Country.mmdb"
  blocked_countries:
    - "XX"  # Unknown
  allowed_countries: []  # Empty = allow all except blocked
  block_tor: true
  block_vpns: false

Accessing Dashboard

The dashboard is available at http://your-server:8080 by default. On first login:

1. Enter the username (default: admin)
2. Enter your password (must be set up via the hashpass tool)
3. The password is securely hashed using bcrypt

Password Setup

WafWay uses industry-standard bcrypt password hashing. Use the included hashpass tool to generate password hashes:

# Generate a password hash
./hashpass "YourSecurePassword123!"

# Output:
# Password hash generated successfully!
# Add this to your wafway.yaml configuration:
#
# dashboard:
#   password_hash: "$2a$12$xxx..."

Add the generated hash to your configuration:

dashboard:
  enabled: true
  username: "admin"
  password_hash: "$2a$12$Z8IZk0PNoxgQm9UUNwESi.eHEgKrQKPlB9UiIzrBZSg8NiNQgZQ.O"

Secure Tokens

WafWay generates cryptographically secure session tokens using Go's crypto/rand package. Tokens are:

• 256-bit random values (32 bytes)
• Base64-URL encoded for safe transmission
• Valid for 24 hours by default
• Automatically cleaned up when expired

Creating Custom Rules

WafWay supports custom rules with full CRUD operations and database persistence:

# Create a custom rule via API
curl -X POST http://localhost:8080/api/v1/rules \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block Admin Access",
    "description": "Block direct access to admin paths",
    "pattern": "^/admin",
    "action": "block",
    "target": "uri",
    "enabled": true,
    "priority": 100
  }'

Rule Patterns

Custom rules support regular expressions for pattern matching:

Actions

• block - Block the request and return 403
• log - Log the request but allow it through
• allow - Explicitly allow (whitelist)

Rules API

Traffic Data

WafWay collects and aggregates traffic data for analytics. Access via the REST API:

# Get traffic data for the last 24 hours
curl http://localhost:8080/api/v1/traffic \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
[
  {
    "timestamp": "2026-01-02T12:00:00Z",
    "total_requests": 1250,
    "blocked_count": 45,
    "allowed_count": 1205,
    "bytes_in": 524288,
    "bytes_out": 2097152,
    "avg_latency_ms": 12.5
  }
]

Top Paths

# Get most accessed paths
curl "http://localhost:8080/api/v1/traffic/top-paths?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
[
  {
    "path": "/api/users",
    "request_count": 5420,
    "blocked_count": 12,
    "avg_latency_ms": 8.3
  }
]

Attack Logs

All blocked requests are logged with full details:

# Get recent attacks
curl "http://localhost:8080/api/v1/traffic/attacks?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response
[
  {
    "id": "1735812345-123456789",
    "timestamp": "2026-01-02T14:25:45Z",
    "source_ip": "192.168.1.100",
    "method": "GET",
    "path": "/api/users?id=1' OR '1'='1",
    "attack_type": "sqli",
    "rule_name": "SQL Injection Detection",
    "severity": "high",
    "action": "blocked"
  }
]

Storage Configuration

WafWay uses SQLite for persistent storage of rules, attack logs, and traffic data:

storage:
  type: "sqlite"
  path: "/var/lib/wafway/wafway.db"

# Data retention settings (optional)
# Older data is automatically cleaned up
retention:
  request_logs: 7d    # Keep request logs for 7 days
  attack_logs: 30d    # Keep attack logs for 30 days
  traffic_stats: 90d  # Keep aggregated stats for 90 days

API Overview

WafWay provides a REST API for programmatic access to all features.

Base URL: http://your-server:8080/api/v1

Authentication

All API requests require a Bearer token:

# Login to get token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

# Response
{
  "token": "xxx-your-token-xxx",
  "expires_at": "2026-01-03T00:00:00Z"
}

# Use token in requests
curl http://localhost:8080/api/v1/stats \
  -H "Authorization: Bearer xxx-your-token-xxx"

Endpoints