ZTLayer Logo
Start Building

Migration Guide

Migrating from a legacy DNS-level Web Application Firewall (like Cloudflare WAF, AWS WAF, or Imperva) to an embedded middleware WAF like ZTLayer is a straightforward process. Because ZTLayer operates within your application runtime, you can run both systems in parallel to ensure zero downtime and zero false positives during the transition.

The Zero-Downtime Migration Workflow

We strongly recommend a 3-Phase Migration Strategy: Observation, Shadowing, and Enforcement.

Phase 1: Observation & Rule Translation (Day 1)

Before touching any code, you need to map your existing firewall rules to ZTLayer.

  1. Export Existing Rules: Export your custom WAF rules, IP blocklists, and rate limits from your current provider.
  2. Import via CLI or Dashboard: Use the ZTLayer Dashboard or the ztlayer cli to recreate these rules.
    • Note: Because ZTLayer uses behavioral AI for OWASP Top 10 vulnerabilities, you do not need to manually port over thousands of regex-based SQLi/XSS rules. Only port your business-logic rules (e.g., blocking specific ASNs, custom rate limits).

Phase 2: Shadow Mode / Log-Only (Day 2-4)

Deploy the ZTLayer SDK to your production application, but configure it to log-only (Shadow Mode).

In this mode, ZTLayer will analyze all traffic, evaluate it against your rules, and log the verdict (Block/Allow), but it will never actually block a request.

// Next.js Middleware Example
import { ZTLayer } from '@ztlayer/nextjs';
 
const security = new ZTLayer({
  apiKey: process.env.ZTLAYER_API_KEY,
  // CRITICAL: Set to log-only during migration
  mode: 'log-only' 
});

Let the application run for 48-72 hours. During this time:

  • Review the ZTLayer Dashboard Analytics.
  • Identify any legitimate requests that would have been blocked (False Positives).
  • Create bypass rules or adjust sensitivity settings to correct these false positives.
  • Our Behavioral AI will baseline your normal traffic patterns.

Phase 3: Full Enforcement (Day 5)

Once you are confident that the false-positive rate is practically zero, you can switch ZTLayer to active enforcement.

const security = new ZTLayer({
  apiKey: process.env.ZTLAYER_API_KEY,
  // Switch to enforce mode to actively block threats
  mode: 'enforce' 
});

Deploy the change. Monitor your logs.

Once ZTLayer is actively blocking malicious traffic at the application layer, you can safely disable the WAF features on your legacy DNS provider (while optionally keeping them active for CDN and basic DNS routing).

Specific Provider Migration Notes

Migrating from Cloudflare WAF

Cloudflare relies heavily on IP reputation and static signatures. ZTLayer uses behavioral biometrics.

  • IP Bypass: If you leave Cloudflare in front of ZTLayer as a CDN, you must ensure ZTLayer is parsing the CF-Connecting-IP header instead of the raw socket IP, otherwise all traffic will appear to come from Cloudflare's servers.
  • SDK Configuration: Set trustProxy: true in the ZTLayer SDK configuration so it respects X-Forwarded-For or provider-specific headers.

Migrating from AWS WAF

AWS WAF often uses AWS Managed Rules.

  • ZTLayer's AI engine automatically handles the equivalent of the AWSManagedRulesCommonRuleSet, AWSManagedRulesSQLiRuleSet, and AWSManagedRulesKnownBadInputsRuleSet. You do not need to configure these manually.

Migrating from Imperva / Incapsula

  • Imperva's Advanced Bot Protection relies on injected JavaScript. ZTLayer's React/Next.js Client SDK performs a similar function but without the performance overhead of synchronous blocking scripts. Ensure you install the client-side SDK if you were heavily relying on Imperva's bot mitigation.

Next Steps

  • Production Checklist: Review best practices before completing Phase 3.
  • SDK Hub: Find the exact installation instructions for your framework.