This page documents every configurable property in WAF Auto-Block, with types, defaults, and constraints taken directly from theDocumentation 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.
WafAutoblockOptions C# source. All values can be set in appsettings.json or via environment variables. Environment variables always take precedence over file-based values, and use double underscores as separators — for example, Cloudflare__ApiToken maps to Cloudflare.ApiToken in JSON.
CloudflareOptions
TheCloudflare section provides the credentials and target identifiers the service needs to query Cloudflare analytics and manage the account-level IP blocklist. All four fields are required — the service skips polling entirely if any of them is missing or empty.
Cloudflare API bearer token. This token is sent as
Authorization: Bearer <token> on every request to the Cloudflare GraphQL and REST APIs. Scope it to the minimum permissions described in the Security page.Environment variable: Cloudflare__ApiTokenThe Cloudflare zone ID (not the zone name) for the zone whose WAF analytics you want to monitor. You can find this value in the Cloudflare dashboard under Overview for your domain.Environment variable:
Cloudflare__ZoneTagCloudflare account ID used for all account-level list management operations (add/remove IP entries). This must be the account that owns the IP list referenced by
BlocklistId.Environment variable: Cloudflare__AccountIdEither the UUID of an existing Cloudflare account-level IP list, or a symbolic name prefixed with
$ (for example $auto_blocked_ips). When using a symbolic name the service resolves it to a list UUID at startup. In Docker Compose env files, escape the dollar sign as $$ so Compose passes the literal $ character to the container.Environment variable: Cloudflare__BlocklistIdPollingOptions
ThePolling section controls how frequently the worker runs and how large the analytics lookback window is. These settings directly affect both detection latency and the load placed on the Cloudflare GraphQL API.
How often (in seconds) the worker wakes up and runs a full poll-and-cleanup cycle. Values below 1 are treated as 1. Shorter intervals mean faster blocking reactions but more API calls per hour.Environment variable:
Polling__IntervalSecondsThe lookback window (in seconds) used when querying Cloudflare WAF analytics. The code default is 20 seconds; the recommended production value is 300 (five minutes) to match
HttpStatusDetection.WindowSeconds. Always set this explicitly in production.Environment variable: Polling__WindowSecondsMaximum random jitter (in milliseconds) added before each poll cycle begins. The actual delay is a random value between 0 and this number. This prevents multiple instances or restarts from hammering the Cloudflare API simultaneously.Environment variable:
Polling__JitterMillisecondsThe
WindowSeconds defaults differ between PollingOptions (20 seconds in code) and HttpStatusDetectionOptions (300 seconds). Always set Polling.WindowSeconds explicitly to your intended window in production.StorageOptions
TheStorage section configures where WAF Auto-Block writes its local SQLite state. The database records every active block, the associated Cloudflare list item ID, and the expiry timestamp so the cleanup loop can remove blocks automatically when their TTL elapses.
Path to the SQLite database file. Relative paths are resolved from the application working directory. The directory component is created automatically if it does not exist, so you do not need to pre-create it. When running in Docker, mount a host volume at
./data to ensure the database persists across container restarts.Environment variable: Storage__DatabasePathRuleMonitorOptions (Rules[])
TheRules array defines the Cloudflare WAF rules that WAF Auto-Block will react to. Each element is an independent rule definition. Only rules that are explicitly listed here — and have Enabled set to true — can ever trigger a block. Unknown or unconfigured RuleId values encountered in analytics are silently ignored.
Display name used in log output and as the comment on Cloudflare list entries. Choose a short, descriptive slug — for example
php_scan or geo_block. This value has no effect on matching logic.Environment variable: Rules__0__Name, Rules__1__Name, …Exact Cloudflare WAF rule ID to monitor. Matching is case-insensitive. You can find rule IDs in the Cloudflare WAF dashboard or via the Cloudflare API. Only events whose
ruleId matches this value will count toward the threshold.Environment variable: Rules__0__RuleId, Rules__1__RuleId, …Minimum number of WAF hit events from a single IP within the polling window required to trigger a block. There is no built-in default — this must be configured explicitly for every rule. A value of
1 blocks on the first observed hit.Environment variable: Rules__0__Threshold, Rules__1__Threshold, …Block duration in minutes. The service records this expiry time in SQLite and removes the IP from the Cloudflare list when the TTL elapses. Minimum effective value is 1 minute. Common values:
240 (4 hours), 1440 (24 hours).Environment variable: Rules__0__TtlMinutes, Rules__1__TtlMinutes, …Whether this rule definition is active. Set to
false to pause a rule without removing it from configuration. Disabled rules are never matched and never trigger blocks.Environment variable: Rules__0__Enabled, Rules__1__Enabled, …HttpStatusDetectionOptions
TheHttpStatusDetection section enables an additional detection layer that works independently of WAF rule IDs. Instead of watching for specific WAF rule hits, this module analyzes HTTP response-code patterns per source IP and blocks IPs that exhibit anomalous error behavior within the configured window.
Master switch for the entire HTTP status detection subsystem. When
false, neither the per-code rules nor the distributed path detector runs, regardless of their individual Enabled flags.Environment variable: HttpStatusDetection__EnabledLookback window (in seconds) used when querying Cloudflare HTTP analytics. Defaults to 300 seconds (five minutes). Keep this aligned with
Polling.WindowSeconds unless you have a specific reason to diverge.Environment variable: HttpStatusDetection__WindowSecondsArray of
HttpStatusCodeRuleOptions objects. Each entry defines detection thresholds for a single HTTP status code. See HttpStatusCodeRuleOptions below.Environment variable prefix: HttpStatusDetection__Codes__0__, HttpStatusDetection__Codes__1__, …Configuration for the distributed path detector, which groups suspicious error paths across multiple source IPs. See DistributedPathDetectionOptions below.
HttpStatusCodeRuleOptions (HttpStatusDetection.Codes[])
Each element in theCodes array monitors a single HTTP status code and evaluates three independent thresholds against every source IP seen in the analytics window. An IP is blocked only when all enabled thresholds are simultaneously exceeded.
The HTTP status code to monitor. Must be in the range 100–599. Typical values are
400, 403, 404, and 500.Environment variable: HttpStatusDetection__Codes__0__StatusCodeWhether this per-code rule is active. Set to
false to disable detection for this specific status code without removing the configuration entry.Environment variable: HttpStatusDetection__Codes__0__EnabledMinimum total error hits across all configured status codes for a given IP within the window. This guards against false positives from IPs that hit only a handful of errors.Environment variable:
HttpStatusDetection__Codes__0__MinTotalErrorsMinimum number of distinct request paths the IP must have touched across all configured codes. A high distinct-path count distinguishes systematic scanning from isolated errors.Environment variable:
HttpStatusDetection__Codes__0__MinDistinctPathsMinimum ratio of this status code’s hits to the IP’s total hits across all configured status codes. Expressed as a decimal between
0.0 and 1.0. For example 0.7 means at least 70% of the IP’s total errors must be this specific code.Environment variable: HttpStatusDetection__Codes__0__MinCodeRatioBlock duration in minutes for IPs matched by this code rule. Uses the same TTL pipeline as WAF rule blocks.Environment variable:
HttpStatusDetection__Codes__0__TtlMinutesLabel used in log output and Cloudflare list entry comments for blocks triggered by this rule. If left empty the service uses
http_status_{statusCode} as the default label.Environment variable: HttpStatusDetection__Codes__0__NameDistributedPathDetectionOptions
The distributed path detector groups error signals by request path across multiple source IPs. A path is flagged as suspicious when too many distinct IPs are hitting it with errors. IPs that participate in enough suspicious paths are then blocked. This approach catches coordinated scans where each individual IP keeps its hit count low.Whether distributed path detection is active. Can be enabled independently of the per-code
Codes rules.Environment variable: HttpStatusDetection__DistributedPathDetection__EnabledList of HTTP status codes to include when grouping path-level signals. Recommended values:
[404, 400, 500, 403]. When this array is non-empty it takes precedence over the legacy single StatusCode field. Set individual elements via environment variables as StatusCodes__0, StatusCodes__1, etc.Environment variable: HttpStatusDetection__DistributedPathDetection__StatusCodes__0, …__1, …Legacy single-code fallback. Used only when
StatusCodes is empty. Retained for backwards compatibility.Environment variable: HttpStatusDetection__DistributedPathDetection__StatusCodeMinimum total error count on a single path (across all source IPs) before that path is considered suspicious.Environment variable:
HttpStatusDetection__DistributedPathDetection__MinPathTotalErrorsMinimum number of distinct source IPs that must have hit a path (above
MinPathTotalErrors) for that path to be flagged as suspicious.Environment variable: HttpStatusDetection__DistributedPathDetection__MinDistinctIpsPerPathMinimum number of hits a single IP must have across all currently suspicious paths before it is considered a candidate for blocking.Environment variable:
HttpStatusDetection__DistributedPathDetection__MinIpHitsOnSuspiciousPathsMinimum number of distinct suspicious paths an IP must appear on before it is blocked. Raising this above 1 reduces false positives against IPs that hit only a single popular scan target.Environment variable:
HttpStatusDetection__DistributedPathDetection__MinDistinctSuspiciousPathsPerIpBlock duration in minutes for IPs blocked by the distributed path detector.Environment variable:
HttpStatusDetection__DistributedPathDetection__TtlMinutesLabel used in logs and Cloudflare list entry comments for blocks triggered by this detector.Environment variable:
HttpStatusDetection__DistributedPathDetection__NamePaths to exclude from suspicious-path analysis. Supports an exact match or a prefix wildcard using a trailing
* — for example /api/health* excludes all paths beginning with /api/health. Common exclusions: /, /favicon.ico.Environment variable: HttpStatusDetection__DistributedPathDetection__ExcludedPaths__0, …__1, …Complete Example
The followingappsettings.json block shows all sections populated with realistic production-ready values. Copy and adjust to your environment — at minimum fill in the four Cloudflare credentials and replace the placeholder RuleId values with your actual Cloudflare WAF rule IDs.
.env file passed to Docker — follows the same structure with __ as the section separator: