Review WAF detections

Open Firewall → Detections for every request the WAF matched a rule against. Logs still record WAF activity as ordinary application entries; this view is the typed, filterable one.

Each row is one inspected transaction: a request, a client WebSocket message or a response. Expand it to see the request line with its query string, the recorded request headers, the stage, the scoring mode and combined scores, one card per ruleset that matched (version, ruleset stage, effective mode, blocking and detection scores against its threshold, marked Exceeded when the ruleset reached it), and the individual findings with the ruleset each came from and the value it matched. Filter by decision, mode, stage, ruleset, rule, severity, route, minimum score, host, or source address. A rule is identified by its ruleset and rule ID together; two rulesets may use the same rule ID.

A WebSocket message has its own detection with the originating connection ID and message index. ConnectionClosed means Prevention rejected the message and closed the connection with status 1008. A gRPC request's detection carries the cumulative score of its inspected messages. See WAF inspected traffic for message limits and large-body behavior.

A response detection has stage Response, with one detection per response and the request's correlation ID. ResponseDecisionLoggedOnly means the response would have been blocked, but it was streaming or had already started.

The row's score adds blocking and detection scores. That total alone does not explain a blocking decision: detection scores cannot contribute to blocking, and Per ruleset mode compares each ruleset with its own threshold. Use the expanded evaluations and the scoring guide to interpret the decision.

Request context and redaction

Edge redacts a detection before writing it, so a secret you mark as sensitive never reaches the log. With request context on, a detection records:

  • the query string, with the value of every sensitive query key replaced by ‹redacted›;
  • the request headers, at most 64 and up to 1,024 characters per value. Allowlist mode keeps the values of the recorded headers and redacts the rest; Redact sensitive keeps every value except the sensitive headers. Sensitive headers such as Authorization, Cookie and X-Api-Key are redacted in both modes;
  • each finding's matched value, cut to the configured length. A value from a sensitive header, or from a query, form or JSON field named like a sensitive query key, is redacted whole; so are cookie values while Cookie is sensitive and JWT values while Authorization is. Sensitive key=value or JSON pairs inside a value are masked.

The detail shows each redacted value as a redacted chip and notes when headers were left out. Request bodies and uploaded content are never recorded beyond matched values. Only a request that produces a detection is captured, and redaction happens once: changing the lists affects new detections only.

Each WAF policy chooses Record request context and its Header values mode; with capture off, its detections record only the method, host, path and findings. Docker-discovered routes use the clearplane.proxy.waf.request-context.enabled and clearplane.proxy.waf.request-context.header-capture-mode labels. The lists and the global switch live in Firewall settings.

Tune a route before Prevention

Select a route, either with the route scope or the route filter. The Noisy rules panel ranks the rules that produced the most detections on that route in the last 7 days, with the targets and field names they matched most often.

From a noisy rule or from a finding, choose Exclude to add an exclusion to the route's effective WAF policy:

  • Disable this rule in the policy stops the rule for every field on the policy's routes.
  • Skip this rule for a field with this exact name stops it only for that target and field name, for example the content form field.
  • Skip this rule for field names starting with covers families of fields, for example every $.items[ JSON path.

Before you save, the dialog names the policy and the routes it reaches, and shows how many of this route's findings from the last 7 days the exclusion would have suppressed, with examples. An exclusion on the Global policy applies to every route that follows it. Saving changes only the policy's rule tuning, so you need WAF policies: Write; it also works on a policy defined by container labels. The exclusion applies to new requests once the configuration is applied.

Prefer the narrowest exclusion that stops the false positive. For applications that many installations share, an exclusion ruleset may already cover it.

Neither the Noisy rules report nor the exclusion preview reads recorded request context.

Every detection is recorded; none are sampled. A rule that matches a large share of your traffic will produce a correspondingly large number of rows until retention removes them, which is itself the signal that the rule needs an exclusion.

Reason codes and fingerprints

A finding's reason code is an identifier defined by the ruleset that matched, such as sql-union-select or xss-event-handler. Reason codes are ruleset data rather than a fixed Clearplane list, so new content brings new codes without a Clearplane release. Two rulesets may use the same code for the same class of finding; the ruleset ID and rule ID beside it together identify which rule fired.

The fingerprint column is filled in only by fingerprint detectors, which summarise how a value parsed instead of naming a pattern. A SQL fingerprint is the libinjection token signature of the value, such as s&1; an HTML fingerprint names the construct that triggered it, such as tag:script or attr:onmouseover. A fingerprint is a compact description of the input's shape, not a copy of the input.

Ruleset authors define both: see condition reason codes, detector pattern reasons and the tokenizer reference.

What the WAF inspects

Rules match against named targets. Targets lists every field a rule can inspect, and Facts and limits lists the parser facts, measures and structural limits. A body sent without a Content-Type is parsed as a form.

The engine never resolves or expands an XML entity and never loads an external DTD. A general entity reference is inspected as the literal text &name; wherever it appears, in content and in attribute values alike, and a declaration contributes its replacement text, system identifier or public identifier as a declaration rather than as document content.

GraphQL field paths use the schema field name, so an alias cannot hide __schema; aliases are only counted. Fragment spreads are recorded, never expanded. The engine parses the document and never executes it.

Bodies are decoded for inspection only. Edge always forwards the original bytes upstream; decompression and transcoding never change the proxied request.

Firewall settings

Open System → Settings → Firewall to bound body decoding and to decide what detections record. Each WAF policy sets its own scoring mode; see scoring and paranoia levels.

The body decoding settings apply to every route; Resource settings lists them with their defaults. Firewall settings are staged with the rest of the configuration.

Maximum file content bytes is how many leading bytes of each uploaded file rules may inspect; 0 inspects file names, content types and archive entry names only.

Raw body window characters and Maximum raw body characters govern raw-body inspection. Maximum raw body characters caps how much of a decoded body those windows cover — beyond it raw text is not scanned; structured parsing remains subject to the policy's effective body and parser limits. Lower both if large bodies dominate your traffic; raise them if you need raw coverage of larger bodies.

Under Detection context, Record request context off stops capture on every route, whatever its policy says. Recorded headers lists the header values that Allowlist policies keep. Sensitive headers and Sensitive query keys are redacted in every mode, and their names match without regard to case. Matched value length keeps 0–160 characters of each matched value; 0 keeps none.

The rule language reference explains the targets, reason codes and integrity vectors behind a finding.