Verification Settings

Console → WAF → [domain] → Protection — This page covers visitor verification and automatic protection settings. Every change takes effect immediately; there is no separate save button.

Protection Mode

Choose the verification type applied to all visitors. JS Challenge and CAPTCHA cannot be active at the same time.

Mode	What it does	When to use
Off	No verification; rules continue to run	Normal traffic conditions
JS Challenge	HEIMWALL’s built-in JS challenge; no external provider needed	Default choice; quickly filters bots
CAPTCHA	Third-party CAPTCHA provider; visual verification	Mobile/API clients or clients that cannot execute JavaScript

When Auto-Protection is active, the system can temporarily switch the mode when the RPS threshold is exceeded. A live badge appears on the card in that case; your permanent selection is not changed.

CAPTCHA Settings

You must configure a provider before the CAPTCHA mode can be enabled. Supported providers:

Provider	Notes
hCaptcha	Privacy-focused; free tier available
reCAPTCHA v2	Google infrastructure; widely recognised
FriendlyCaptcha	Bot-proof, JavaScript-based; no user interaction required
MTCaptcha	GDPR-compliant; European servers
ALTCHA	Open-source, proof-of-work based; no external service required

Console → Protection → CAPTCHA Settings → Edit
Select a provider from the list
Obtain your Site Key and Secret Key from the provider’s dashboard (for ALTCHA: Challenge URL and HMAC Secret)
Enter the keys and save

Challenge HTTP Response Code

Choose the HTTP status code returned with the challenge page. The default is 503 Service Unavailable.

Why 503? Bots and crawlers interpret 503 as a temporary error; returning 200 would let them treat the challenge page as a successful response.

When should you change it? If another reverse proxy (e.g. Cloudflare, a second WAF) sits in front of HEIMWALL, it may log 503 as an error. Selecting 200 or 204 avoids that log noise.

Challenge Duration Settings

Controls how long a visitor’s verification remains valid and how long the JS challenge page waits before appearing.

Setting	Default	Range	Description
JS Clearance	30 min	5–1440 min	A visitor who passes JS is not re-challenged for this duration
CAPTCHA Clearance	60 min	5–1440 min	A visitor who passes CAPTCHA is not re-challenged for this duration
JS Delay	1500 ms	100–10000 ms	How long the JS challenge page waits before the verification runs

CAPTCHA clearance is typically set longer than JS clearance because CAPTCHA is a stronger verification.

The JS delay gives legitimate browsers enough time to complete the verification; setting it too low can cause problems on slow connections.

Client Hints Policy

Browsers send Sec-CH-UA and similar Client Hints headers on some requests. If these headers are inconsistent with the User-Agent, the visitor may be a bot or a tool disguised as a browser. This policy controls what happens in that case.

Policy	Behaviour
Compatibility	Client Hints are not checked; maximum compatibility (default)
Balanced	Inconsistencies are logged but no action is taken
Strict	Inconsistent Client Hints → selected action (CAPTCHA or Block)

Bot-Score Engine

Every request is automatically assigned a bot score from 0 to 100. You can run this engine in passive monitoring or automatic action (enforce) mode.

For a detailed explanation and threshold calibration, see Bot Score.

Auto-Protection

When requests per second (RPS) exceeds the configured threshold, the system automatically starts a challenge; when traffic returns to normal and the standby period elapses, it stops automatically.

Setting	Description
RPS Threshold	Challenge starts when requests per second exceed this value (10–5000)
Standby	How many seconds after the threshold is crossed before the challenge activates (10–3600 s)
Challenge Window	How long the challenge stays active after traffic normalises (60–3600 s)
Challenge Type	JS Challenge or CAPTCHA

Advanced parameters

Default values suit most scenarios. The parameters below are for fine-tuning when needed:

Parameter	Default	Description
Velocity Factor	×10	A “velocity breach” is triggered when current RPS exceeds the historical baseline by this multiplier
Baseline Window	300 s	Time window over which the baseline RPS average is calculated
Minimum Baseline RPS	50	Auto-protection does not activate for traffic below this level
Minimum Pressure IPs	20	If the number of distinct IPs is below this, the event is not treated as an attack
Rearm Cooldown	300 s	Waiting period before the next trigger after the challenge closes

Circuit breaker: Automatically disables the challenge when the origin error rate rises — opening a challenge when the origin cannot respond is counterproductive.

Parameter	Default	Description
CB Window	60 s	Time window over which the error rate is measured
Max Error Rate	50%	The circuit breaker trips when the error rate exceeds this
Min Samples	5	Minimum number of requests required before a decision is made
Half-Open Period	30 s	Retry window after the circuit breaker trips

Global Rate-Limit

A domain-wide request limit applied to all endpoints. Unlike rule-level rate limiting, this applies everywhere without any rule condition.

Setting	Description
Request Count	Maximum requests allowed within the window
Window	Duration after which the counter resets (seconds)
IPv6 Prefix	Prefix length used to group IPv6 addresses from the same network (/29–/64)

Requests from IPs that exceed this threshold before the window resets are rejected with 429 Too Many Requests.

For per-endpoint limits, see Rate Limiting.

Auto-Block

Automatically and temporarily blocks IPs that repeatedly fail challenges or constantly hit rate limits.

Setting	Description
Failure Count	IP is blocked after this many failures
Window	Duration over which failures are counted (minutes)
Block Duration	How long the IP stays on the blocklist (seconds)
IPv6 Prefix	Prefix length used to group IPv6 addresses from the same network

The IP is removed automatically when the block duration expires; no manual action is required.