nself waf

Manage the built-in Web Application Firewall — enable, disable, check status, and generate traffic reports. The WAF is powered by Coraza with the OWASP Core Rule Set and is free for all nSelf installations.

Quick start

# Check WAF status
nself waf status

# Enable the WAF (detection mode — logs but does not block)
nself waf enable --mode detect

# Enable the WAF (prevention mode — blocks matched requests)
nself waf enable --mode block

# Generate a WAF traffic report for the last 24 hours
nself waf report

Synopsis

nself waf <SUBCOMMAND> [FLAGS]

Description

nSelf ships a WAF based on Coraza, a Go-native WAF engine integrated directly into the nginx reverse proxy layer. It enforces the OWASP Core Rule Set (CRS) by default, protecting against SQL injection, XSS, path traversal, remote code execution, and other OWASP Top 10 attack classes.

The WAF operates in one of two modes. Detection mode logs rule matches without dropping requests — useful for tuning before going live. Prevention mode blocks matched requests with a 403 response and logs the event. You can run detection mode for a period, review the report, add exclusions for any false positives, then switch to prevention.

WAF is free and part of the Security-Always-Free doctrine. It runs without a license key. The Cloudflare WAF integration (if you proxy nSelf through Cloudflare) is configured separately through your Cloudflare dashboard.

Subcommands

nself waf status

Show the current WAF state: enabled or disabled, active mode, CRS version, and recent event counts.

nself waf status
# WAF:        enabled
# Mode:       prevention
# Engine:     Coraza 3.x + OWASP CRS 4.3
# Matches:    12 (last 24h)
# Blocked:    12 (prevention mode)
# False pos:  0 known exclusions

nself waf enable

Enable the WAF. Requires --mode to specify detection or prevention.

nself waf enable --mode detect     # log only, do not block
nself waf enable --mode block      # block matched requests (alias: prevent)
nself waf enable --mode block --env staging

nself waf mode

Switch the active mode without fully re-enabling the WAF.

nself waf mode detect    # switch to detection
nself waf mode block     # switch to prevention

nself waf report

Generate a summary report of WAF matches, top triggered rules, and blocked IPs over a time window.

nself waf report                # last 24 hours (default)
nself waf report --since 7d     # last 7 days
nself waf report --json         # machine-readable output
nself waf report --output /tmp/waf-report.json

Flags

Detection mode vs prevention mode

Examples

Run in detection mode for a week, then switch to prevention

# Week 1: log-only
nself waf enable --mode detect

# After review
nself waf report --since 7d --json > waf-week1.json
# (review for false positives, add exclusions as needed)

# Week 2: block
nself waf mode block

Get the top blocked IPs as JSON

nself waf report --json | jq '.top_blocked_ips[:10]'

Check WAF on staging

nself waf status --env staging

OWASP Core Rule Set

The OWASP CRS is bundled with every nSelf installation. The version included is listed innself waf status. Rule updates ship with nSelf CLI updates — run nself update to get the latest CRS without any separate configuration.

By default, the CRS runs at paranoia level 1 (recommended for most deployments). Higher paranoia levels increase false-positive risk — tune with the report before raising the level.

Related

• nself security — full security audit including WAF status
• nself doctor — system diagnostics including WAF configuration check
• nself logs — view raw WAF event logs from the nginx service