Challenge suspicious browser requests
Edge can return a proof-of-work page when a browser request meets a configured WAF or rate-limit trigger. The browser searches for a SHA-256 value with the required number of leading zero bits, then receives a clearance cookie. The page loads no external resources and contacts no third-party service.
Enable challenges
Open the route's WAF policy under Firewall → WAF policies, set it to Prevention, then select Proof of work under Bot challenges. Challenges run only on the policy's routes that also redirect HTTP to HTTPS; the attention list names routes where they cannot. Ordinary GET and HEAD requests must use HTTPS and accept text/html or */*. WebSocket upgrades, gRPC traffic and requests that cannot accept HTML keep their protocol behavior.
For a discovered route, add clearplane.proxy.waf.challenge.mode: ProofOfWork alongside clearplane.proxy.waf: "On", clearplane.proxy.waf.mode: Prevention and its HTTPS redirect or certificate configuration. challenge.threshold, challenge.difficulty and challenge.clearance-minutes set the rest of the inline policy's challenge settings. An invalid value rejects the container; without an HTTPS redirect the route never challenges, and discovery records a warning.
Choose a trigger
- Combined score: a request reaches the challenge threshold without reaching its block threshold.
- Challenge rule: a matching request-stage rule uses
action: Challenge, belongs to an effective Prevention ruleset and falls within the policy's blocking paranoia level. Challenge rules add no score. - Rate limit: an applicable policy has Challenge browsers selected as its action and exhausts its limit.
Detection evaluations never trigger challenges. Under Per ruleset scoring, only explicit Challenge rules and Challenge rate limits trigger. The attention panel warns when a configured route has no trigger that can fire.
Blocking and clearance
A WAF block takes precedence over a WAF challenge. Ineligible requests are scored by the other rules as usual; an ineligible request that exceeds a Challenge rate limit receives 429. A valid clearance prevents another challenge, but the WAF still inspects the request and may block it. Clearance bypasses only Challenge rate limit policies: a separate rejecting policy still applies.
The proof form posts to the reserved /_clearplane/challenge path. Verification retains the original ban, access-control and authentication requirements. The token binds the original route and return path; malformed, stale or mismatched submissions terminate locally. The original application receives no proof form.
Privacy and token lifetime
The __Host-clearplane_clearance cookie is Secure, HttpOnly, SameSite=Lax, host-only, and uses Path=/. Its signature binds the client's IPv4 /24 or IPv6 /64 address prefix, the user-agent hash, the hostname and an expiry. A clearance can apply to other challenge-enabled routes on the same host; their WAF and rejecting rate policies still apply.
Pending challenge tokens expire after 300 seconds and bind the same client information plus the return path and original route. They are stateless; this does not provide single-use replay tracking. Changing the bound client information requires a new proof.
Operations
Analytics attributes challenge pages to the Challenge block source. WAF-triggered challenges appear in Detections with decision Challenged. A rate-limit challenge is a rate-limit outcome and does not create a WAF evaluation or an auto-ban violation.
Rotate the challenge clearance key with the stack stopped, using the secret maintenance procedure. Replace service keys if your Compose file uses different ones:
docker compose down &&
docker compose run --rm --no-deps clearplane-core secrets rotate challenge-clearance &&
docker compose up -d --wait
Starting Edge again loads the new key and invalidates all existing clearances and pending challenges. Do not delete or replace individual machine-secret files.
See Challenge actions and scoring and the login-path example when writing a custom challenge rule.