WAF rulesets

Clearplane ships no WAF ruleset and has no built-in fallback. A WAF policy does not supply rules. If no compatible ruleset is active, the WAF inspects nothing; Clearplane shows an attention item when an enabled WAF policy covers routes in that state.

Ruleset releases

Each ruleset has its own current release, identified by a ruleset ID and version. Several rulesets can be active together. Activating a new version replaces the current version of that identity while keeping other rulesets active. Installing a release alone does not change inspection.

Signed releases arrive through Cloud ruleset updates. Operators can write and test custom rules in rulesets of their own.

First release candidate

The first content release covers eight category rulesets. These are reviewed candidate drafts; production publication is pending.

Ruleset Coverage and compatibility guidance
clearplane-protocol HTTP policy, framing and incomplete inspection
clearplane-scanners Known scanner signatures
clearplane-sql-injection SQL syntax and fingerprints
clearplane-xss Cross-site scripting
clearplane-command-injection Shell and command injection
clearplane-path-traversal Traversal and sensitive paths
clearplane-api-schema Configured API-schema violations
clearplane-data-leakage Response disclosure

Which rulesets apply to a route

Every active, compatible ruleset applies to every route with an effective WAF policy, unless that policy disables its ruleset ID. The policy chooses the Standard or Management profile from each applicable ruleset. Rulesets of kind Exclusion require an explicit policy opt-in; activation alone never selects them. See exclusion rulesets before enabling application-specific exceptions.

For Docker-discovered routes, use clearplane.proxy.waf.disabled-rulesets for ruleset IDs to skip and clearplane.proxy.waf.exclusion-rulesets for Exclusion IDs to select. See the configuration catalog.

The WAF policy API disables a ruleset through a rulesetOverrides entry with rulesetId and enabled: false, opts into Exclusion rulesets through exclusionRulesets, and extends the protocol ruleset through additionalAllowedMethods and additionalAllowedRequestContentTypes. Each rule reference includes both its ruleset ID and rule ID, so an exclusion cannot accidentally target a same-numbered rule in another ruleset.

Route mode and ruleset stage

A ruleset's stage and the mode of the route's WAF policy jointly determine whether its matches can contribute to blocking. A route without an effective WAF policy is not inspected.

Policy mode Ruleset stage Effective mode
Detection Detection or Prevention Detection; findings only
Prevention Detection Detection; findings only
Prevention Prevention Prevention; eligible scores can block

A disabled ruleset is always Off for that policy's routes. Read scoring and paranoia levels for how eligible scores reach a blocking decision.

Operate rulesets

Open WAF → Rulesets to see each ruleset's source, kind, current version, stage, update strategy and last update. Cloud entries also show publication age and the last successful check for that ruleset. Release notes shows the offered release before download and retains installed release notes for offline use. Operators with WAF rulesets: Manage can:

  • Activate version — choose an installed release and start it in Detection or Prevention. The dialog lists incompatible releases but prevents selecting them.
  • Promote — move the current release from Detection to Prevention.
  • Roll back — restore the previous verified release at its last stage.
  • Deactivate — stop the ruleset on every route.
  • Update strategy — save a per-ruleset Cloud update preference or follow the system default. Custom rules have no update strategy. The preference takes effect when WAF ruleset updates are enabled under System → Settings → Cloud.
  • Open a ruleset — browse its current rules, see which rules are disabled and disable or restore an individual rule.

Moving a ruleset to a resource group requires WAF rulesets: Write. Read permission allows browsing without exposing signed envelopes, rule patterns, or signatures.

Copying a rule into a custom draft requires WAF rulesets: Manage and does expose that rule's patterns, since the copy is editable. See write custom WAF rules.

Activation actions include the generation shown by the page. If another operator changes activation state first, the action is refused and the page reloads. Check the new state before trying again.

Disable a ruleset rule

A rule that is wrong for every application does not need disabling route by route. Open the ruleset from the Rulesets page, find the rule and select Disable rule. Operators need WAF rulesets: Manage to disable or restore rules.

The disabled rule is inactive on every route that uses the ruleset, and a WAF policy cannot turn it back on. Select Restore in the ruleset to let each policy's settings apply again. The change reaches the gateway with the next configuration apply.

Each entry shows its current state:

  • Disabled — the rule is in the active release and inactive on every route.
  • Rule changed since — the release changed this rule after it was disabled. The entry stays applied, because rule identifiers are only unique within a ruleset version and a later release can retire and reuse one. Review it and re-add it against the current release if the rule still deserves to be off.
  • Not in this release — the active release no longer contains that rule. The entry is kept and has no effect.
  • Ruleset inactive — the whole ruleset is deactivated, so nothing from it is inspecting traffic.

To silence a noisy rule on one application rather than everywhere, use its WAF policy's disabled rules and target exclusions instead, described under WAF policies.

Rule memory

Compiled rules live in the gateway's memory, and each ruleset costs a different amount. The Rule memory panel on the Rulesets page shows what the running rulesets currently use, what the gateway has available, the threshold above which a change is refused, and the measured cost of each installed ruleset. Before Edge measures a release, the list shows its estimated cost with ~. Cloud measures compiled memory with the publishing engine; Edge uses 75% of that estimate to allow for shared structures only when the engine, .NET runtime and architecture identities match. Missing or mismatched estimates use a conservative default. Edge’s own measurement takes precedence, and estimates never bypass admission limits. Estimates assume the Linear regex engine, so under Backtracking the list shows only Edge's own measurements.

Before compiling a new set of rulesets, Edge projects what they will cost and compares it against the threshold. A configuration revision whose rulesets would not fit is refused: the revision fails, the previously published rulesets keep serving traffic, and no request goes uninspected. A revision that changes no ruleset content is never refused, because nothing has to be compiled.

If a change is refused, disable rulesets in WAF policies whose routes do not need them, deactivate a ruleset, or give the Edge container more memory and restart it. CLEARPLANE_EDGE_BOOTSTRAP_WAF_MEMORY_ADMISSION_PERCENT adjusts the threshold; see the configuration catalog. Raising it trades safety margin for capacity.

Regex engine

By default the WAF compiles every pattern into a linear-time automaton, the Linear engine. No request can make linear matching slow, but compiled rules use far more memory than ordinary regular expressions: all Clearplane rulesets together use roughly 800 MB, command injection alone about 250 MB. Edge's default 2 GiB memory limit fits a selection of rulesets, not all of them, and updating a ruleset briefly holds its old and new versions together. To run every ruleset on the Linear engine, raise the Edge container's memory limit, for example to 4 GiB.

The Backtracking engine compiles the same rulesets into about 60 MB and reaches the same verdicts on their integrity tests, but a crafted request can make a pattern slow. Each request therefore gets a regex time limit, 50 ms by default. A single slow match can overrun it once, so a request uses at most about twice the limit. When a request reaches the limit:

  • Block (the default) rejects it on routes whose WAF policy can block, like any exhausted inspection budget. Detection routes forward and log it.
  • Allow forwards it without the remaining rules and logs it. An attacker who can trigger the limit can then skip rules.

Either way the detection records RegexTimeLimitExceeded. Even with Block, a flood of slow requests can load Edge's CPU.

Choose the engine under System → Settings → Edge → WAF regex engine, or with the clearplane.edge.waf.regex.engine, clearplane.edge.waf.regex.time-limit-milliseconds and clearplane.edge.waf.regex.time-limit-action labels on the Edge container. A change recompiles every active ruleset when the configuration is next applied, and the memory check above applies as usual.

Cloud ruleset updates

With WAF ruleset updates on under System → Settings → Cloud, Core checks Cloud periodically. You can also select Check now above the ruleset list. The panel shows when the last check ran and, if it failed, a short error code such as ManifestUnavailable. Installed rulesets keep enforcing whatever the result.

Core downloads each new release, verifies it against the signing keys built into this Clearplane version, and installs it. The signature authenticates both the payload and the envelope’s UTC signedAt; that time must fall inside the key’s validity window. A release signed within the window stays trusted after the key expires. Overlapping windows allow rotation without invalidating installed releases. Trust is bound to the anchor's public key, not only its key ID: removing an anchor, or re-pinning its key ID to a different public key, revokes the releases verified under the old key until a release signed by the current key is installed. Emergency revocation therefore requires a gateway update or an operator pin change. Edge receives verified rulesets from Core and holds no signing keys. CLEARPLANE_CORE_BOOTSTRAP_WAF_RULESET_SIGNING_KEYS pins keys as whitespace-delimited key-id|not-before|not-after|base64-public-key entries with UTC ISO 8601 dates; see the configuration catalog. The ruleset's update strategy then decides whether the release becomes current. Automatic updates never reactivate a ruleset you deactivated and never demote one you promoted.

The default strategy is set under System → Settings → Cloud, with an optional per-ruleset override:

Strategy Automatic behavior
Manual Install the release and wait for operator activation.
Detection Activate new releases in Detection.
Prevention Start a ruleset’s first automatic activation in Detection, then promote after the observation window. A ruleset with prior Prevention history receives later releases at its current stage.

First promotion observation window (hours) defaults to 24 and accepts 1–168. The window starts only after Edge reports that the intended version is serving in Detection; with manual Apply, the page shows that it is waiting for Detection to apply. The pending window survives a Core restart. At its deadline, promotion requires a fresh matching Edge report. It is a time delay, without an automatic false-positive assessment; review WAF detections during the window.

A newer first release restarts observation after it reaches Edge. Changing the window length recalculates the deadline from its original start. Selecting Manual or Detection, deactivating or rolling back, or turning updates or Cloud integration off cancels the pending promotion. Losing connectivity to Cloud does not cancel it. Promote can end observation early after confirmation, and explicit activation in Prevention takes effect immediately. Configuration Apply still controls when any stage change reaches Edge.

Cloud staff can hold a release at 0%, expand a stable installation cohort from 1–99%, or offer it to everyone at 100%. Cloud offers each installation the newest compatible release it is eligible for, retaining an earlier eligible offer during rollout. A later check can offer a new release when its rollout expands.

The version column shows Cloud offers when a newer release is waiting, for example under Manual. It shows Withdrawn by Cloud when Cloud withdrew the current release but the fallback was not applied, and No longer offered when Cloud stopped listing a ruleset, which keeps enforcing. Every automatic activation appears on the dashboard's attention list.

If a release is withdrawn, Cloud offers a compatible replacement and reports the withdrawn version explicitly. Under Manual, Clearplane reports the withdrawal for operator action; automatic strategies can apply the replacement at the current stage. Cloud refuses withdrawal unless a non-withdrawn fallback at 100% rollout covers every gateway version supported by the withdrawn release.

See Cloud data and consent for what each request sends and which delivery records Cloud retains.

WAF policies

A WAF policy holds a route's complete firewall configuration: mode, profile, scoring, paranoia levels, disabled rulesets and exclusions, body, stream and response inspection, bot challenges, optional API schemas and what detections record. Manage policies under WAF → WAF policies; you need WAF policies: Read to view them, Write to create and edit them, and Manage to delete them. The API is /api/waf-policies on the management API route.

Like other policy families, a policy is Global or Route, and each route has a WAF state. Inherit uses the enabled Global policy, On uses the route's own policy, and Off turns the WAF off for the route. A route that is On whose policy is disabled gets no WAF; it never falls back to the Global policy. A policy's mode is Detection or Prevention. Routing → Proxy routes shows each route's effective WAF mode, or Off.

A new installation ships the Global policy Default WAF (default-waf) in Detection. It inspects nothing until a ruleset is active, and the attention list warns about that. Clear the warning in one of three ways:

  • turn on Cloud integration and WAF ruleset updates under System → Settings → Cloud to download the Clearplane rulesets;
  • publish a custom ruleset;
  • disable Default WAF and every other enabled WAF policy.

The editor lists the routes a policy reaches; a Global policy reaches every route that inherits the WAF. Saving a Prevention policy whose reach grows asks you to confirm the routes it will block on.

The editor lists active rulesets and their stages. You can switch off a ruleset's Enabled toggle or set its threshold for Per ruleset scoring. Exclusion rulesets are listed separately for explicit opt-in. Additional allowed methods and Additional request content types extend the protocol ruleset's method and content-type policy for the policy's routes only.

Disabled rules and target exclusions identify both a ruleset and a rule. A target exclusion matches a target name exactly or by prefix. The editor warns about inactive rulesets, rules missing from the current release, targets a rule no longer inspects, and body limits above a ruleset's profile. These references remain editable and do not block saving a structurally valid policy.

Container labels can create an inline policy for a discovered route. Its labelled settings are read-only here, but its disabled rules, target exclusions and per-ruleset thresholds stay editable, and discovery keeps them.

Release changes and rollback

Release changes do not invalidate a saved WAF policy. References to inactive rulesets, retired rules, or retired targets become policy warnings. Those references remain saved; they have no effect while their targets are absent. If a release lowers its body-size limit, inspection uses the lower limit and records a warning. Malformed policy settings, such as an invalid threshold, are still rejected.

A current release that needs a newer Clearplane version is skipped without stopping other compatible rulesets or configuration changes. Clearplane retains the release and shows WAF rulesets need a newer Clearplane version as an attention item. A release signed by a key Core no longer trusts is skipped the same way, marked Untrusted signing key and reported as WAF rulesets are signed by a key this installation no longer trusts. Check active versions and stages after a change, then use WAF detections to see which rulesets actually matched traffic.

Core retains activation history per ruleset. Roll back selects that identity's previous verified release and restores its last stage; it leaves other rulesets in place. A rollback requires a previous release in that ruleset's own history.

For release JSON and profile fields, see Ruleset format.