Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/proteo5/waf-autoblock/llms.txt

Use this file to discover all available pages before exploring further.

WAF Auto-Block loads its configuration through the standard .NET configuration pipeline. Values are read from appsettings.json, an optional appsettings.Development.json (or any environment-specific override file), and environment variables. Each source can override the previous one, so a value set in an environment variable always wins over one defined in any JSON file.

​
Configuration Sources

The precedence order from lowest to highest is:
  1. appsettings.json — baseline defaults committed to the repository
  2. appsettings.{Environment}.json — environment-specific overrides (e.g. appsettings.Production.json)
  3. appsettings.Local.json — local developer overrides, typically git-ignored
  4. Environment variables — highest priority; always override file-based values
For Docker deployments, environment variables are the recommended approach. They avoid mounting config files into containers, integrate cleanly with secrets managers, and make values visible to container orchestrators like Docker Compose or Kubernetes.
The ASPNETCORE_ENVIRONMENT environment variable controls which environment-specific appsettings.{Environment}.json file is loaded. When not set, it defaults to Production.

​
Top-Level Configuration Areas

The full JSON configuration shape across all sections looks like this: 
{
  "Cloudflare": {
    "ApiToken": "",
    "ZoneTag": "",
    "AccountId": "",
    "BlocklistId": ""
  },
  "Polling": {
    "IntervalSeconds": 15,
    "WindowSeconds": 300,
    "JitterMilliseconds": 2000
  },
  "Storage": {
    "DatabasePath": "./data/state.db"
  },
  "Rules": [
    {
      "Name": "php_scan",
      "RuleId": "<cloudflare-rule-id>",
      "Threshold": 1,
      "TtlMinutes": 1440,
      "Enabled": true
    }
  ],
  "HttpStatusDetection": {
    "Enabled": false,
    "WindowSeconds": 300,
    "DistributedPathDetection": {
      "Enabled": false,
      "StatusCodes": [],
      "StatusCode": 404,
      "MinPathTotalErrors": 20,
      "MinDistinctIpsPerPath": 5,
      "MinIpHitsOnSuspiciousPaths": 2,
      "MinDistinctSuspiciousPathsPerIp": 1,
      "TtlMinutes": 120,
      "Name": "http_404_distributed_scan",
      "ExcludedPaths": []
    },
    "Codes": []
  }
}

​
Cloudflare Settings

These four credentials are all required. The service calls IsConfigured() on startup and refuses to run if any of them is blank.
​
Cloudflare.ApiToken
string
required
A Cloudflare API token with Zone:Read, Zone WAF:Read, and Account Firewall Access Rules:Edit permissions. Keep this value out of source control — supply it via an environment variable or a secrets manager.
​
Cloudflare.ZoneTag
string
required
The Cloudflare Zone ID for the zone whose WAF analytics the service will query. Found on the zone overview page in the Cloudflare dashboard under API > Zone ID.
​
Cloudflare.AccountId
string
required
The Cloudflare Account ID that owns the IP list used for blocking. Found on the account home page in the Cloudflare dashboard.
​
Cloudflare.BlocklistId
string
required
The identifier of the account-level IP list that blocked IPs are written to. Accepts either a UUID or a symbolic name prefixed with $ (e.g. $auto_blocked_ips). When using Docker Compose .env files, escape the dollar sign as $$ to prevent variable substitution.

​
Polling Settings

These values control how often the service queries Cloudflare WAF analytics and how far back each query looks.
​
Polling.IntervalSeconds
integer
default:"15"
How many seconds the service waits between polling cycles. Shorter intervals increase Cloudflare API calls; 15 seconds is a sensible default for most deployments.
​
Polling.WindowSeconds
integer
default:"20"
The lookback window in seconds applied to each WAF analytics query. The C# class default is 20, but appsettings.json sets this to 300 (5 minutes) and it is strongly recommended to set 300 explicitly in your configuration. Keep this aligned with HttpStatusDetection.WindowSeconds unless you have a specific reason to diverge.
​
Polling.JitterMilliseconds
integer
default:"2000"
Maximum random delay added to each polling cycle before the Cloudflare API call is made. Jitter prevents thundering-herd behaviour in multi-instance or scheduled deployments. A value of 2000 means up to 2 seconds of random additional delay per cycle.

​
Storage Settings

WAF Auto-Block uses SQLite to persist block state. The database records which IPs have been blocked and when each block expires, enabling TTL-based automatic unblocking across service restarts.
​
Storage.DatabasePath
string
default:"./data/state.db"
Path to the SQLite database file. Can be relative (resolved from the working directory) or absolute. The service creates the parent directory automatically on first run if it does not already exist. When running in Docker, mount a volume at the parent directory to persist state across container restarts.

​
Learn More

WAF Rules

Configure which Cloudflare WAF rule IDs trigger automatic IP blocking and set per-rule thresholds and TTLs.

HTTP Status Detection

Enable per-IP HTTP error anomaly detection and distributed path scanning for additional coverage.

Environment Variables

Complete reference of every environment variable accepted by the service for Docker deployments.

appsettings.json

View the full JSON configuration shape with all sections and their defaults.

Build docs developers (and LLMs) love

Get started for freeTalk to us