Wafcontrol | Documentation

Documentation

Install and operate OWASP WAFControl

Getting Started

Overview

OWASP WAFControl is an open-source project that creates a user-friendly web dashboard for managing ModSecurity and the OWASP Core Rule Set (CRS). This project makes it easier for security teams to set up and manage these tools without needing advanced technical skills or command-line experience. The dashboard automates installation and configuration, allowing users to efficiently monitor and control web application security. Its goal is to help DevSecOps teams and security engineers improve their workflows while enhancing security and visibility. Overall, WAFControl aims to make advanced web application firewall management accessible to everyone.

System Requirements

  • OS: Ubuntu 22.04+ or Debian 11+
  • Memory: 4 GB RAM minimum
  • Disk: 20 GB+ free
  • Python: 3.10+ required
  • Services: PostgreSQL, Redis, Celery

Before you install

Read this section carefully before running the installer. It explains what the system does, what it installs, how it behaves with existing services, and how to size and secure your deployment.

Scope & capabilities

The system provides a full web dashboard to install, configure, and manage ModSecurity and the OWASP Core Rule Set (CRS) without command-line usage. It includes attack logging with a dedicated critical view, top attacker analytics, a CRS rule browser/editor with toggles, a CRS version switcher, a custom rule builder, and complete ModSecurity settings control—all from the browser.

  • No command-line skills are required for normal operation.
  • All actions are performed locally on the target server where the installer is executed.
  • Target audience: DevSecOps teams, security engineers, and system administrators who want a faster, safer way to run ModSecurity + CRS.

Supported platforms

  • Web servers: Nginx and Apache. Both installation and ongoing management are automated.
  • Operating systems: Ubuntu 22.04+ or Debian 11+.
  • Runtime & services: Python 3.10+, PostgreSQL (recommended), Redis, Celery, Django, Gunicorn.

Installer behavior

The installer prepares the server and deploys ModSecurity + OWASP CRS alongside the dashboard. It can run in two modes:

  • IP mode: Serves the dashboard at SERVER_IP:PORT (default port 7000).
  • Domain mode: Serves the dashboard on your domain (HTTP/HTTPS). Let’s Encrypt SSL can be enabled automatically.

Existing components are detected and reused. If your web server or database already exists, the installer does not reinstall or reconfigure networking; it only applies app configuration and creates the database if needed. If missing, the installer sets them up locally.

  • Optional HTTP Basic Auth can be enabled in addition to the dashboard’s admin login.
  • Installer runs are idempotent; if a step fails, fix and rerun safely.

Database & logs

WAFControl uses PostgreSQL by default for reliability and performance. SQLite is supported for light or demo deployments but has inherent limitations.

  • A scheduled task runs every minute to read ModSecurity logs and store detected attacks in the DB.
  • Raw logs remain on disk; the app does not alter or delete them.
  • You can configure a retention window (days) for database events.

Security model

  • Local-only DB: Installer never enables remote access or changes existing DB networking.
  • Credentials: You define dashboard admin credentials; Basic Auth can add an extra layer.
  • TLS: Let’s Encrypt supported in domain mode.

Sizing & retention

  • Minimum: 4 GB RAM, 20 GB+ disk.
  • For heavy traffic: increase RAM/CPU and adjust log retention.
  • Raw logs managed by system logrotate; app doesn’t rotate logs itself.

Services & operations

systemctl status wafcontrol
systemctl status wafcontrol-celery-worker
systemctl status wafcontrol-celery-beat
journalctl -u wafcontrol -e
journalctl -u wafcontrol-celery-worker -e
journalctl -u wafcontrol-celery-beat -e
  • Services start automatically after installation.
  • Use PostgreSQL backup tools for DB and normal file backups for configs.

Limitations & roadmap

  • Current release supports single-server setup.
  • Multi-node and remote agents planned for future updates.
  • Export and maintenance tools coming in later versions.

Install

This installer will automatically set up Python, PostgreSQL, Redis, Celery, Django, Gunicorn, and your selected web server (Nginx/Apache). After completion, services will be up and running.

Easy install

curl -fsSL https://wafcontrol.org/download/install.sh -o install.sh

chmod +x install.sh

sudo ./install.sh

Installer flow (questions)

  • Web server: nginx (default) or apache.
  • Run mode: ip (SERVER_IP:PORT) or domain (HTTP/HTTPS).
  • SSL: Let’s Encrypt optional in domain mode.
  • PostgreSQL: Reuse existing or install new. Password auto-generated if left empty.
  • Basic Auth: Optional pre-login layer.
  • Summary: Selections confirmed before proceeding.

Service commands

After installation, check services:

systemctl status wafcontrol
systemctl status wafcontrol-celery-worker
systemctl status wafcontrol-celery-beat

Use journalctl -u to view detailed logs for each service.

Uninstall

WAFControl includes a safe uninstaller that removes only WAFControl components. It will not remove Nginx or PostgreSQL packages.

Overview

The uninstallation process is interactive and designed to avoid breaking existing infrastructure. It removes WAFControl services, runtime files, and WAFControl-specific Nginx configuration (if you choose).

Important:
  • Do NOT remove Nginx or PostgreSQL if they existed on the server before WAFControl.
  • Removing them can break other applications and cause irreversible data loss.
  • If you remove system services manually, you accept full responsibility.

Recommended (safe)

Run the uninstaller:

curl -fsSL https://raw.githubusercontent.com/wafcontrol/install/refs/heads/main/uninstall.sh -o uninstall.sh

The script will ask before removing:

  • WAFControl systemd services
  • Runtime directory: /run/wafcontrol
  • WAFControl Nginx changes (vhost, modsec dir, injected lines, dynamic module)
  • Project directory (optional): /opt/WafControl
  • Installer state file (optional): /var/lib/wafcontrol-installer/state.env

What gets removed

  • /etc/nginx/conf.d/wafcontrol.conf (if present)
  • /etc/nginx/modsec/ (WAFControl ModSecurity + CRS directory)
  • Injected lines in /etc/nginx/nginx.conf:
    • load_module ... ngx_http_modsecurity_module.so;
    • # WAFCONTROL-BEGIN block
  • Dynamic module file (path discovered via nginx -V), example:
    • /usr/lib/nginx/modules/ngx_http_modsecurity_module.so
  • Systemd unit files:
    • /etc/systemd/system/wafcontrol.service
    • /etc/systemd/system/wafcontrol-celery-worker.service
    • /etc/systemd/system/wafcontrol-celery-beat.service
  • /run/wafcontrol
  • /opt/WafControl (optional)

Manual uninstall (fallback)

If you do not have uninstall.sh, you can remove WAFControl manually:

sudo systemctl disable --now wafcontrol wafcontrol-celery-worker wafcontrol-celery-beat || true
sudo rm -f /etc/systemd/system/wafcontrol*.service
sudo systemctl daemon-reload

sudo rm -f /etc/nginx/conf.d/wafcontrol.conf
sudo rm -rf /etc/nginx/modsec
sudo sed -i '/load_module .*ngx_http_modsecurity_module.so/d' /etc/nginx/nginx.conf
sudo sed -i '/# WAFCONTROL-BEGIN/,/# WAFCONTROL-END/d' /etc/nginx/nginx.conf

MOD_DIR="$(nginx -V 2>&1 | sed -n 's/.*--modules-path=\([^ ]*\).*/\1/p' | tail -n1)"
sudo rm -f "$MOD_DIR/ngx_http_modsecurity_module.so"

sudo nginx -t && sudo systemctl reload nginx || sudo nginx -s reload

Important notes

  • PostgreSQL databases are not removed by the uninstaller.
  • Nginx packages are not removed by the uninstaller.
  • Project directory removal is optional. If you plan to reinstall, you may keep /opt/WafControl.