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.

Which rulesets apply to a route

Every active, compatible ruleset applies to every route with an effective WAF policy, unless that policy opts out of 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.opt-out-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 expresses opt-outs through RulesetOverrides entries with RulesetId and OptedOut, Exclusion opt-ins through ExclusionRulesets, and the policy extensions through AllowedMethods and AllowedRequestContentTypes. 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.

An opted-out 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 Firewall → Rulesets to see each ruleset's source, kind, current version, stage, update strategy and last update. 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 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 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, opt WAF policies out of rulesets their routes do not need, 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.

Cloud ruleset updates

With WAF ruleset updates on under 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 manifest-unavailable. 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. Edge receives verified rulesets from Core and holds no signing keys. CLEARPLANE_CORE_BOOTSTRAP_WAF_RULESET_SIGNING_KEYS pins different keys; 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 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 when it would leave installations without a compatible fallback.

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, ruleset opt-outs and exclusions, body, stream and response inspection, bot challenges, an optional API schema and what detections record. Manage policies under Firewall → 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 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 opt out of a ruleset 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.