Web Application Firewall user guide

Use this guide to understand the WAF Console, its role-based pages, and the workflows for protecting and investigating traffic.

In-app help: click the ? icon in the top header from any page to open this guide inside the Console, filtered to what’s relevant to your role.

Table of Contents

1. First Login
2. Roles & Permissions
3. Core Concepts
4. Feature Reference
5. Workflows
6. The Approval Queue
7. Troubleshooting
8. Glossary
9. Tips & Shortcuts

First Login

Option 1: OIDC SSO (recommended for production)

1. Click Sign in with SSO on the login page.
2. Select your organization’s identity provider.
3. Complete your organization’s authentication flow. You’re redirected back to the Console already signed in.

OIDC providers are configured by a security_admin/owner under Settings → OIDC (see Settings).

Option 2: Username / password (bootstrap and dev use)

1. Enter your username and password on the login page.
2. Click Sign in.

This path exists for initial bootstrap and local/dev environments before SSO is configured. Prefer SSO once an OIDC provider is set up — password accounts aren’t subject to your identity provider’s own MFA/conditional-access policies.

There is currently no self-service MFA enrollment inside the Console. If your organization requires MFA, enforce it at the identity-provider level (via SSO) rather than expecting an in-app prompt.

What determines what you can see

After login, the Console reads your role (GET /v1/me) and uses it to decide which sidebar items and actions are visible. See Roles & Permissions — most day-to-day triage and configuration work only requires analyst or policy_editor; the handful of infrastructure-level pages (Nodes, Certificates, DDoS, CAPTCHA Providers, Alert Rules, Setup Wizard, Settings, ML Tuning) require security_admin or above.

Roles & Permissions

The Console enforces a strict role hierarchy — a higher role automatically has everything a lower role has:

Pages gated to security_admin or above: DDoS Operations, Nodes, Certificates, CAPTCHA Providers, Alert Rules, Setup Wizard, Settings, ML Tuning. Every other page (Overview, Events, Policies, Audit, Reputation, Exports, Servers, Sites, Managed Rules, Rule Updates, FP Triage, Confidence, API Security, Challenge Analytics, Abuse, Exceptions, Approvals) is visible to any signed-in role, though write actions inside them may still be checked server-side against your role.

Role assignments are managed under Settings → RBAC by a security_admin/owner (see Settings).

Core Concepts

A few ideas recur across almost every page — understand these first and the rest of the Console follows a consistent pattern.

Tenant & Environment. Every piece of configuration (policies, sites, rules) belongs to a tenant (your organization/account) and an environment (e.g. local, staging, prod). Switch between them using the tenant/environment selectors in the top header — almost every page’s data changes based on this selection.

Policy bundles are versioned. A “policy” is never edited in place. Each save creates a new immutable version. You promote a version through environments (e.g. staging → prod), and you can always roll back to a previous version. This is true for Policies, Sites (published as versioned “site-sets”), and Managed Rule packages.

Detection vs. blocking. New protection (a new policy, a new managed-rule package, a new API spec) should generally start in detection mode — the WAF logs what it would have blocked without actually blocking it. Review those would-block events, tune out false positives, then switch to blocking. This detect-first pattern is the single most important habit for avoiding an outage caused by your own rules.

The 202 = “submitted for approval” convention. Several sensitive actions — activating a managed-rule package in production, publishing an API security spec, enabling ML auto-apply enforcement, creating a DDoS mitigation — don’t take effect immediately if your environment has approval policies configured. The Console tells you this clearly (a banner or toast saying the action was submitted for approval, not applied) and the request appears in Approvals for a second qualified person to approve. This is not a bug or a stuck UI — it’s how change control works. See The Approval Queue.

Confidence and rollback are recommendations, not automation. The Confidence page computes a confidence score for a rule package rollout and can recommend a rollback based on false-positive rate and sample size — but it never automatically deactivates or reverts anything. A human always makes the final call.

Feature Reference

Pages are grouped the way you’ll actually use them, not alphabetically.

Monitoring & triage

Overview — your landing dashboard: event volume, certificate/node/DDoS health at a glance, plus an onboarding checklist if your tenant is still mid-setup. Read-only; links out to the pages behind each stat.

Events — the ground truth of what the WAF did to every request: filter by rule ID, action, severity, type, or time range; click a row for full detail (payload, matched rules, source IP hash, country, ASN). Nearly every other page (FP Triage, ML, Exceptions) links back to specific events shown here.

Audit — tamper-evident trail of privileged actions (policy publishes, rollbacks, certificate changes, logins) for compliance. Filter by actor/action/date, run Verify chain to confirm the hash chain hasn’t been tampered with, and Export to CSV/JSON/JSONL for external review.

Policy & rules lifecycle

Policies — author, version, and deploy your WAF enforcement policy. Use the guided New Policy wizard for a first policy, or the structured editor / raw YAML editor for changes. Promote moves a version to the next environment (approval-gated for production); Rollback or Emergency Rollback reverts. Select two versions to open a side-by-side diff.

Managed Rules — import and tune third-party rule packages (OWASP CRS and others). The Configure Managed Rules wizard imports a baseline package; the Packages tab activates a package (may return “submitted for approval” — see Core Concepts); Coverage shows seeded/skipped rule stats; CRS Config edits paranoia level and anomaly-score thresholds; Exclusions lets you scope out specific false positives.

Rule Updates — preview and roll out new upstream versions of your managed rule packages, per environment. Refresh Preview diffs your current version against the latest available; Promote activates, compiles, stages, and publishes it; Rollback reverts.

FP Triage (False Positive Triage) — your false-positive workbench: Noisy Rules and FP Trend are read-only diagnostics; Suggested Exclusions lets you apply an ML-suggested exclusion in one click; ML Signals lets you mark specific ML-scored events as false positives, feeding the scoring model’s feedback loop.

Confidence — computes a confidence score for a rule package rollout (rule conformance, false-positive count, sample size) and keeps a history of past rollback recommendations. Use the Guided Check wizard or the manual form. Recommendation only — see Core Concepts.

Exceptions (labeled “Exceptions” in the sidebar) — the human review queue for requesting, approving, or rejecting managed-rule overrides. Create Exception submits a request (environment, rule, request ID, reason, suggested mode); a second reviewer Approves (which creates the override) or Rejects it. Also includes an ML Scores tab for browsing scored events.

Traffic & infrastructure

Sites — defines which hostnames/paths are protected and where traffic is proxied (host → backend + policy environment), per node group. Edits are staged locally, then Validate and Save & Publish together as one atomic, versioned change. The per-row Protection badge tells you whether healthy edge nodes are actually running that site’s current policy — green means fully converged. Version History lets you roll back to a previous site-set.

Servers — runtime engine configuration (resource limits and other non-policy settings) per node group, with version history and live node status.

Nodes (security_admin+) — read-only inventory of registered edge/data-plane nodes: region, group, and the policy version each is currently running. No edit actions here by design; it’s a status view.

Certificates (security_admin+) — TLS certificate lifecycle. Server Certificates: upload a certificate (wizard or raw PEM); delete is blocked with a clear message if the certificate is still in use by a site. Priority Rules control SNI matching order when multiple certificates could match a hostname. CA Bundles manage your trust store. Renewal Status shows auto-renewal state.

Exports — configure where security events are forwarded for SIEM/log analysis (Splunk HEC, generic webhook, syslog/CEF/LEEF). Dry Run tests a destination without sending real data; Flush/Replay manage the delivery buffer; each destination shows a live health check. (This is distinct from the CSV/JSON export button on the Audit page, which is a one-off download, not a standing destination.)

Bot, abuse & DDoS defense

DDoS Operations (security_admin+) — auto-detected mitigations, anomaly campaigns, and the underlying EWMA anomaly-detection engine. Dashboard for charts; Active Mitigations to approve/reject/clear pending mitigations (note: “Reject” and “Clear” both permanently discard the mitigation — there’s no “send back for review” state); Recent DDoS Events to resolve a campaign; Threshold/Limit Config for global and per-IP rate limits; Anomaly Detection for live baseline status.

Reputation — IP/ASN/subject block and allow lists, country/ASN geo-blocking, and external threat-intelligence feed integration. Add entries individually or bulk-import; the Threat Feeds tab (with its own Guided Setup wizard) polls external feeds on a schedule you control.

Abuse — targeted behavioral mitigations (allow/monitor/block/challenge) scoped by IP, country, ASN, header, or cookie, with an expiry — distinct from both DDoS (volumetric) and Reputation (static lists). Use the Configure Abuse Detection wizard for common patterns, or add mitigations directly.

Challenge Analytics — outcomes for bot challenges served to visitors (served/solved/failed rates), JA3 fingerprint summary, and CAPTCHA success rate, plus a Simulator tab to dry-run a challenge against a test URL. Challenge rules themselves (which routes get challenged, at what risk threshold) are configured inside your Policy bundle, not on this page.

CAPTCHA Providers (security_admin+) — configure third-party CAPTCHA providers (Cloudflare Turnstile, reCAPTCHA, hCaptcha) that your challenge rules can use: site key, secret (write-only, shown masked after saving), score threshold, and a fail-open toggle for provider outages.

API protection

API Security — OpenAPI-schema-based protection for your APIs. Specs tab: import an OpenAPI spec or use the New Spec wizard, then Stage → review Diagnostics → Publish Now (or leave staged; a banner keeps track across reloads). Overrides tab: relax or tighten enforcement for a specific route or field. Discovered Routes: the WAF observes real traffic and surfaces routes not covered by any spec — Import as Spec to bring them under protection. Protocols tab: GraphQL guards (query depth, field count, cost, alias limits, introspection) and gRPC guards (max message size, frame count, allowed methods).

Machine learning

ML Tuning (security_admin+) — tune and operate the ML risk-scoring engine. Scoring Config: edit thresholds/signal weights (approval-gated) and toggle Auto-Apply Enforcement separately (also approval-gated — a pending banner shows while awaiting a second approver). Kill Switch: immediately halt scoring for a given scorer if it’s misbehaving, and resolve once safe. Model Registry: onboard a new model version via wizard, then activate or roll back. Scored Events: browse individual scoring decisions with a top-contributing-factors breakdown. Performance: model accuracy/drift metrics over time.

Administration

Alert Rules (security_admin+) — condition → action rules that fire on matching security events: multiple field/operator/value conditions, and multiple actions (in-app notification, webhook, email). Use this to get paged when something specific happens instead of watching Events all day.

Approvals — the central inbox for every “submitted for approval” action across the Console (managed rules, API security, ML, reputation bulk actions, DDoS mitigations). Inbox tab to approve or reject with an optional reason (you can’t approve your own request twice if distinct-approver policy is on); Policies tab to configure how many approvers are required per action type, and whether they must be distinct people.

Setup Wizard (security_admin+) — first-run guided onboarding: create your tenant and first site, publish a starter policy (with baseline challenge rules included), and add a SIEM export destination. Four steps, each skippable, with progress saved automatically so you can leave and come back.

Settings

Settings (security_admin+) provides platform administration in three tabs: API Tokens (create/revoke tokens for automation), OIDC (add/remove SSO identity providers), and RBAC (assign roles to users — the same seven roles described in Roles & Permissions).

Workflows

Real tasks span multiple pages. These are the journeys you’ll repeat most often.

Protect a new site, start to finish

1. Sites → Add Site → enter domain, upstream URL, and select a policy environment (a site can’t be enabled without one). Validate, then Save & Publish.
2. Policies → New Policy → start from Recommended — observe first (detection mode, fail-closed, CRS anomaly detection on, no blocking yet). Validate and create the version; if your environment requires approval it stays a draft until approved.
3. Events → confirm events are arriving for your new site with the expected policy version attributed to them.
4. Sites → check the Protection column goes green — this confirms edge nodes have actually converged on the new policy and site-set, not just that you clicked Save.
5. Once you’re comfortable with what detection mode is (and isn’t) flagging, promote the policy toward blocking mode.

Roll out a managed rule package safely

1. Managed Rules → Configure Managed Rules wizard → import the package in Detection mode with a conservative paranoia level (start at 1).
2. Let it run and collect data, then check FP Triage → Noisy Rules and Suggested Exclusions for anything firing on legitimate traffic.
3. Apply exclusions for genuine false positives (FP Triage → Apply Exclusion, or Managed Rules → Exclusions).
4. Confidence → run a check for the package; review the score before increasing paranoia level or moving toward blocking.
5. Raise paranoia level or lower anomaly thresholds gradually — both changes make enforcement stricter, so change one variable at a time and watch FP Trend.

Investigate and resolve a false positive

1. Events → find the blocked/challenged request in question; note the request ID, rule ID, and policy version.
2. FP Triage → ML Signals or Noisy Rules to see if it’s part of a pattern, not a one-off.
3. If it’s genuinely a false positive: FP Triage → Apply Exclusion, scoped as narrowly as possible (specific rule + route/parameter, not a blanket disable).
4. If it needs a second opinion first: Exceptions → Create Exception with the request ID and reason, and let a second reviewer approve it.
5. Confirm in Events that subsequent identical requests are no longer flagged.

Bring an API under protection

1. API Security → Import Spec (or New Spec wizard) with your OpenAPI document.
2. Specs tab → Stage, then review Diagnostics for anything the spec doesn’t account for.
3. Discovered Routes → check for real traffic hitting routes your spec doesn’t cover; Import as Spec to close the gap.
4. Publish Now once diagnostics are clean (or leave it staged — the banner persists across reloads so you won’t lose track).
5. Use Overrides for any route/field that needs different enforcement than the spec default.

Respond to a DDoS/abuse incident

1. DDoS Operations → Dashboard to confirm you’re actually looking at an anomaly, and Anomaly Detection for current EWMA baseline status.
2. Active Mitigations → review what was auto-detected; Approve legitimate mitigations, Reject false triggers.
3. Recent DDoS Events → Resolve the campaign once traffic normalizes.
4. For a narrower, non-volumetric pattern (specific IPs/ASNs/headers behaving abusively rather than a traffic flood), use Abuse instead — it’s built for scoped, expiring mitigations rather than global thresholds.

The Approval Queue

If you submit a sensitive change and see a message like “submitted for approval” instead of a normal success toast, that’s expected behavior, not an error — your environment has an approval policy configured for that action type. Here’s what happens next:

1. Your request appears in Approvals → Inbox for anyone with a qualifying role.
2. A second person (a different person, if your policy requires distinct approvers) reviews and Approves or Rejects, optionally with a reason.
3. Once the required number of approvals is met, the change is applied automatically — you don’t need to do anything further.
4. You can track a pending change from wherever you submitted it (most pages show a persistent “pending approval” banner) or from the Approvals inbox itself.

Approval requirements themselves (how many approvers, whether they must be distinct) are set per action type under Approvals → Policies by a security_admin/owner.

Troubleshooting

A node shows “Unhealthy” on the Overview dashboard, but I just deployed it. Health is computed client-side from the node’s last heartbeat — a node is marked unhealthy once it’s gone quiet for roughly 3× the normal ~60-second heartbeat interval. A brand-new node can briefly show this state before its first heartbeats land; give it a minute and refresh. If it stays unhealthy, check Nodes for its last-seen timestamp.

I published a policy but Events still shows the old version. Check Sites → Protection for the affected site. A green badge means edge nodes have converged on the new policy; if it’s not green, nodes haven’t picked up the change yet (propagation delay) or there’s a routing mismatch — check Nodes for the version each node reports.

My change says “submitted for approval” and I don’t see it applied. This is expected for approval-gated action types — see The Approval Queue. It is not stuck; it’s waiting on a second reviewer.

I can’t see a page that a colleague says they can see. Check your role under your profile, and compare against the Roles & Permissions table. Several infrastructure pages require security_admin or above. Ask an existing security_admin/owner to adjust your role under Settings → RBAC.

I rejected a DDoS mitigation but it’s gone, not sitting somewhere for review. By design, Reject and Clear are the same underlying action — both permanently discard the mitigation. There’s no “send back for review” queue for DDoS mitigations. If you rejected something in error, you’ll need to recreate it.

A managed-rule package activation didn’t take effect immediately. Check whether it returned a “submitted for approval” message — production activations are commonly approval-gated. Check Approvals → Inbox.

I can’t delete a certificate. The Console blocks deletion of any certificate still referenced by a site’s priority rules, with a message telling you why. Remove or repoint the referencing site first (Sites or Certificates → Priority Rules), then delete.

Glossary

Tips & Shortcuts

• Start everything in detection mode. New policies, new managed-rule packages, new API specs — all of it. You cannot lower risk by skipping this step to “save time.”
• Tune one variable at a time. Raising paranoia level and lowering anomaly thresholds are both stricter changes — do them separately so you know which one caused any new false positives.
• Use the Protection badge on Sites, not just a green toast, to confirm a rollout actually reached the edge. A successful save means your change was accepted; a green Protection badge means it’s actually running.
• Scope exclusions as narrowly as possible (specific rule + route/parameter) rather than broadly disabling a rule — a blanket exclusion silently reopens whatever that rule was protecting against.
• When escalating an incident, always capture the request ID, policy version, engine, and matched-rule evidence from the Events detail view — this is what any investigation will need first.
• Check Approvals regularly if you’re a security_admin/owner. Pending requests don’t page anyone by default; set up an Alert Rule if you want to be notified instead of checking manually.
• Two versions selected on the Policies page opens a diff — useful before promoting or rolling back, so you know exactly what’s changing.

Need Help?

1. Click the ? icon in the Console header to open this guide in context.
2. When escalating an incident, include the request ID, policy version, engine, and matched-rule evidence from the Events detail view.