WAF Migration Playbook: Change Platforms Safely

Moving web applications from one WAF platform to another means re-creating years of rule tuning, exclusions and virtual patches on a new engine, and the usual shortcuts, switching the new WAF to log-only indefinitely or leaving the old path reachable, quietly remove protection from the applications that need it most. WAF migrations happen when moving from appliances or host modules to a cloud edge service, changing cloud or CDN provider, consolidating after a merger, or moving API traffic to a gateway with built-in filtering. This playbook covers what has to move besides rules, cutover patterns, tuning the new engine, translating virtual patches and exclusions, certificate and key custody, the identities a WAF holds, rollback and decommissioning. It is vendor-neutral and based on OWASP guidance and NIST controls. What a WAF does and how to tune one in steady state is covered in the Web Application Firewall Guide; this page does not repeat it.

Key takeaways

Rules are only part of the move. Exclusions, virtual patches, rate limits, client IP handling, TLS keys, origin restrictions, logging pipelines and management credentials all carry state.
Detection-only is a phase, not a destination. Run the new WAF in detection mode with a dated exit, compare verdicts against the old one, then block.
Every virtual patch needs an owner and a test. Re-create each one from its CVE and test it against a safe reproduction, or confirm the code fix has shipped and retire it.
Change origin restrictions in the same change as DNS. An origin that still accepts the old provider's address ranges, or any address, is a bypass.
Re-issue keys rather than move them. Use new TLS certificates and new API tokens for the new platform, and revoke what the old provider held.

What has to move

Build the inventory per protected hostname or application, because cutover will happen at that level.

Object	Migration approach	Watch for
DNS records (CNAME or A to the WAF edge)	Lower TTLs, then repoint per hostname	Forgotten hostnames and wildcard records still pointing at the old edge
TLS certificates and private keys	Issue new certificates for the new edge; use provider-managed or new keys	Uploading the same private key to a second provider; old provider still holding it
Origin restrictions (IP allowlists, mutual TLS, shared secret headers, tunnels)	Add the new edge, test, then remove the old one in the cutover change	Origins left open to any address, or to the old provider's shared ranges
Managed rule sets and their version	Map rule categories; note different rule IDs and scoring	Coverage gaps where the new rule set lacks an equivalent category
Custom rules and virtual patches	Re-create from intent and CVE; test each one	Patches for vulnerabilities fixed long ago, still blocking real traffic
Rule exclusions	Re-create narrowly per path and parameter	Broad exclusions turned into "disable the whole category"
Rate limits, bot and geo rules	Translate thresholds; validate against current traffic	Different counting windows and keys changing what triggers
API schemas and positive security models	Import OpenAPI definitions if supported; validate in detection mode	Out-of-date schemas blocking new endpoints
Client IP handling (forwarded headers)	Configure the origin to trust forwarded headers only from the new edge	Logs and rate limits keyed on the WAF's address, or trust of spoofed headers
Request body and header inspection limits	Record the new platform's limits per application	Large uploads or bodies passing uninspected
Logs, SIEM parsers and alerts	Build parsers and alerts before cutover	A detection gap while new log fields are unparsed
Configuration as code and management API tokens	New modules and new scoped tokens	Old provider tokens still valid in pipelines

Choosing a cutover pattern

Pattern	How it works	Choose it when	Trade-off
Hostname by hostname DNS cutover	Repoint one application at a time to the new edge	Most migrations; each application has its own owner and tests	Two platforms to operate for the duration
Weighted or canary routing	Send a small share of traffic to the new WAF, then increase	High-traffic applications where a full switch is risky	Split logs; issues affect only part of the users and are harder to reproduce
Chained (new in front of old, or behind)	Traffic passes both; the new one in detection mode	You need a verdict comparison on identical traffic	Added latency, client IP handling twice, double TLS termination
Traffic mirroring to a detection-only instance	Copy requests to the new engine without serving responses	Self-hosted or gateway deployments that support mirroring	Mirrored data needs the same protection as production traffic
Single switch	All hostnames repointed in one window	Few applications, simple rules, strong rollback	All tuning problems surface at once

Decision guidance: a small organisation with a handful of sites can usually run the new WAF in detection mode for one to two weeks, then switch per hostname. A large estate should group applications into waves by risk and traffic pattern, start with low-risk static sites, and leave applications with heavy custom tuning, payment pages and APIs with schema enforcement until the team has learned the new engine. Applications in scope for PCI DSS must stay protected throughout; the live WAF guide covers what requirement 6.4.2 asks for.

Tuning the new engine before blocking

Rule engines score and match differently, so a rule set that blocks nothing legitimate on the old platform will produce new false positives on the new one. The OWASP Core Rule Set documentation describes the pattern most engines share.

Start at a low paranoia level: CRS describes paranoia level 1 as baseline security with a minimal need for tuning. A "detection paranoia level" set higher than the blocking level runs the extra rules for logging without letting them block. This is a useful way to preview stricter rules on the new platform.
Use the standard blocking threshold once tuned: CRS gives an example of a mature installation at paranoia level 1 with an inbound anomaly score threshold of 5, which blocks attacks immediately.
Write narrow exclusions: CRS distinguishes configure-time exclusions (remove a rule everywhere) from runtime exclusions (remove a rule or a single parameter for one path). Prefer the narrowest form, for example excluding one parameter on one URL from one rule, over removing a rule or tag globally.
Replay real traffic: compare the old and new verdicts for the same requests. Every request the new WAF would block and the old one passed needs a decision: true positive the old one missed, or false positive to tune.
Set a dated exit from detection mode: our recommendation is no more than 30 days per wave. An open-ended detection phase is how WAFs end up never blocking.

The OWASP Core Rule Set Guide explains paranoia levels and anomaly scoring in more depth.

Translating virtual patches and custom rules

The OWASP Virtual Patching Cheat Sheet recommends establishing an expedited review process before an incident, testing both exploit attempts and legitimate workflows, and defining monitoring and rollback criteria before enabling blocking. Apply the same discipline to every patch you carry across.

List every virtual patch with its CVE or internal finding: owner, affected application, date added, and whether the code fix has shipped.
Retire patches whose fix is confirmed in production: by evidence from the vulnerability scanner or a retest, not by assumption.
Prefer positive security for what remains: the cheat sheet recommends allow list patches (for example, only one parameter, only integers) over block list signatures, which are easier to evade.
Test each patch on the new platform: against a safe reproduction of the issue in a test environment, and against normal application use.
Record an expiry: each virtual patch should have a review date tied to the code fix. See the Virtual Patching and Compensating Controls Guide.

For custom rules, record the intent in plain words (block this path from outside the corporate network, rate limit the login endpoint per client) and rebuild from that, not from the old syntax.

Certificates, keys and origin lockdown

A cloud WAF that terminates TLS holds your certificate private key, and a change of provider is the natural point to rotate it. The Imperva breach shows why: a database snapshot made for testing during Imperva's own move to the cloud was later accessed with a stolen API key, exposing customer API keys and customer-provided SSL certificates, and customers were told to upload new certificates and reset keys.

New edge, new keys: issue fresh certificates for the new platform, or use its managed certificates, rather than uploading the private key the old provider held.
Revoke and delete at exit: once the old edge no longer serves traffic, revoke certificates it held and delete uploaded keys from its console.
Lock the origin in the same change: restrict the origin to the new edge using mutual TLS, a tunnel or the provider's published ranges, and remove the old provider's ranges in the cutover change. Cloud WAF address ranges are shared across customers, so an allowlist of ranges alone lets any customer of that provider reach your origin; add mutual TLS or a secret header.
Trust forwarded headers only from the edge: configure the origin to take the client address from forwarded headers only when the request arrives from the new edge.

Where identity fits

A WAF and its management plane are non-human identities with significant reach. In the Capital One breach, a misconfigured WAF's cloud role credentials were used to read data from storage, which is the clearest example of why a WAF's own permissions matter.

Cloud roles: a self-hosted WAF on cloud instances should have a role scoped to what it needs (often nothing beyond log shipping), not inherited broad storage access.
Management API tokens: pipelines that deploy WAF configuration as code need tokens scoped to the zones or policies they manage, stored in a secrets manager. Revoke the old provider's tokens when its configuration stops being deployed. See the Web application firewall (WAF) integration security guide.
Admin accounts: federate console access through SSO with phishing-resistant MFA, and remove local admin accounts on the old platform after logs are exported.

The phased playbook

Phase 0, inventory and baseline: every hostname, origin, rule, exclusion, virtual patch and token. Record a baseline for 30 days: blocked requests by category, false positive reports, and latency.
Phase 1, build: configure the new platform as code, with logging to the SIEM and parsers and alerts in place before traffic arrives.
Phase 2, detection mode: route a low-risk wave through the new WAF in detection mode, or mirror or chain traffic, and compare verdicts.
Phase 3, block per wave: switch to blocking with the agreed threshold, then repoint DNS and lock the origin in the same change.
Phase 4, high-risk applications: payment pages, login flows and APIs with schema enforcement, each with application owner sign-off and a rehearsed rollback.
Phase 5, freeze the old platform: set it to reject or alert, and watch for any request that still reaches it.
Phase 6, decommission: see below.

Rollback

Agree triggers per application: for example a rise in 403 responses on authenticated sessions above twice baseline for 15 minutes (our recommendation), with the application owner and the WAF owner named as deciders.
Roll back the rule, not the platform, first: a narrow runtime exclusion or a single rule switched to detection is a smaller change than returning DNS.
Keep the old edge able to serve until the freeze ends: with the old origin allowlist entry ready to re-add, documented in the runbook.
Never roll back by exposing the origin directly: that removes protection for every user.

Decommissioning the old WAF

Remove old ranges and secrets from origins: allowlist entries, shared secret headers and client certificates the old edge used.
Delete DNS records and verification tokens: stale records pointing at an old provider can sometimes be claimed by another customer of that provider; remove them.
Revoke certificates, API tokens and roles: including cloud roles attached to old self-hosted instances.
Export logs for retention: keep WAF logs for the period your policy sets (NIST SP 800-53 AU-11) before the account closes.
Sanitise appliances and images: they hold private keys and logs with request data; follow NIST SP 800-88 Rev. 2 and record it (MP-6).

Detection and measurement

Metric or signal	Why it matters	Target (our recommendation)
Share of hostnames in blocking mode on the new WAF	Shows the migration finished, not just moved	100% of in-scope hostnames
Requests reaching origins not via the new edge	Detects origin bypass	Zero
Virtual patches without owner, CVE and review date	Shows carried-over rules without justification	Zero
False positive reports per week after blocking	Tuning quality on the new engine	At or below baseline within 30 days
Exclusions scoped wider than one path	Shows tuning by removal	Each one reviewed and justified
Old platform tokens, keys and roles still valid	Orphaned access	Zero after decommission

Alert on exploitation attempts against public applications (ATT&CK T1190) in the new log format from day one, so the migration does not create a blind spot.

Common failure patterns

Permanent detection mode: the new WAF logs but never blocks because no one owns the exit date.
Origin left open: DNS moved, origin still accepts traffic from anywhere or from the old provider.
Global exclusions to stop complaints: a whole rule category disabled on day one and never restored.
Virtual patches lost: a patch protecting an unfixed application was not in the inventory.
Client IP lost: rate limits and logs keyed on the edge's address, so abuse is invisible or every user is throttled together.
Old provider keeps your keys: uploaded private keys and API tokens left in an account no one logs into.

Framework mapping

Activity	NIST SP 800-53 Rev 5	NIST CSF 2.0	Other
Boundary protection on the new edge	SC-7	PR.IR-01	ATT&CK T1190
Monitoring and verdict comparison	SI-4, AU-6	DE.CM-01	CIS 13.10
Virtual patches as flaw remediation bridge	SI-2	PR.PS-02	OWASP Virtual Patching Cheat Sheet
Rule and routing change control	CM-3, CM-6	PR.PS-01	Not mapped
TLS keys and certificates	SC-12, SC-8	PR.DS-02	Not mapped
Management tokens and roles	AC-6, IA-5	PR.AA-05	Not mapped
Log retention and sanitisation	AU-11, MP-6	PR.DS-01	Not mapped

Practitioner checklist

Inventory hostnames, origins, rules, exclusions, virtual patches, limits, certificates and tokens per application.
Build parsers and alerts for the new log format before any traffic moves.
Run detection mode with a dated exit and compare verdicts on real traffic.
Write exclusions per path and parameter, not per rule category.
Retire virtual patches whose fix is proven; re-create and test the rest with owners and review dates.
Issue new certificates and tokens for the new platform; never re-upload the old private key.
Lock origins to the new edge with more than a shared address range, in the same change as DNS.
Agree rollback triggers per application and roll back rules before platforms.
Revoke the old platform's certificates, tokens and roles, delete stale DNS records and export logs.

Web application firewall (WAF) migration playbook: change WAF platforms without opening gaps