Migrating From Another Firewall¶

Nobody adopts a firewall from nothing. You already have Wordfence, a ModSecurity ruleset, or a page of Cloudflare rules, and the real evaluation question is "can I express what I have today?"

This page answers it for the three, starting with the part that saves the most time.

What does not map¶

Read this first. Finding it on day three is expensive.

This runs at your origin¶

Cloudflare, Akamai and any other edge WAF make their decision before the request reaches your server. This library runs inside your application, after PHP has started. Moving a rule here does not stop the traffic arriving; it stops the traffic being served.

That matters for exactly one class of rule: the ones you have for bandwidth or for keeping load off the origin. A volumetric flood blocked at Cloudflare costs you nothing; the same flood blocked here still costs a PHP worker per request.

Everything else — blocking, challenging, rate limiting, geographic rules — moves fine, and gains something in the process: rules live in your repository, in review, deployed with the code they protect.

Response inspection¶

ModSecurity's phase 3 and 4 rules inspect the response. This library evaluates requests only — response-side evaluation is #69 and not in 2.x. CRS's response-leak categories load and never fire.

What Wordfence knows and this does not¶

Wordfence runs inside WordPress. It knows which user is logged in, which files changed since yesterday, and what a core file is supposed to contain. This runs before WordPress boots, and knows the request.

So these do not move, and nothing here replaces them:

What does move is everything Wordfence does at the request layer, and it moves into configuration you can review and deploy.

From ModSecurity / OWASP CRS¶

The closest migration of the three, because this library runs real CRS through kanopi/crs-engine — the same rule files, the same anomaly scoring, the same rule IDs.

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\Crs"
    response: block
    weight: 50
    enable: true
    config:
      paranoia: 1
      mode: monitor          # DetectionOnly, while you port exclusions
      disabled_rules: [942130]
      anomaly_thresholds:
        inbound: 5

Your exclusions are the part worth carrying over carefully. SecRuleRemoveById lines are a record of every false positive somebody already paid for, and the rule IDs are identical here, so they transfer one for one.

Custom SecRule directives do not transfer as syntax. A rule matching a URI, a header or a parameter is a URL rule with the same variables under different names:

SecRule REQUEST_URI "@beginsWith /wp-admin" "id:1000,phase:1,deny,status:403"

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\Url"
    response: block
    metadata:
      name: admin-paths
      status_code: 403
    config:
      - "path@starts_with:/wp-admin"

What has no equivalent: chained rules (chain), Lua scripts, persistent collections (SecAction initcol), and anything in phases 3–5.

From Cloudflare firewall rules¶

Cloudflare's expression language maps field for field onto rule variables; what changes is that the decision now happens at your origin.

A rule like (ip.geoip.country eq "CN" and http.request.uri.path contains "/wp-login") becomes a group:

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\GeoLocation"
    response: block
    metadata:
      name: cn-login
      provider: cloudflare
      source: header
    config:
      - type: AND
        rules:
          - "country:CN"
          - "path@contains:/wp-login"

See Conditional Logic for the full operator set.

Cloudflare's Managed Rules are a commercial WAF ruleset, not something to port line-by-line. The equivalent here is CRS, which is the open ruleset their managed rules are historically derived from.

From Wordfence¶

Wordfence is configured through a UI rather than a file, so this maps capability to capability rather than syntax to syntax. Everything below is request-layer, which is the part that moves.

The login protection is worth spelling out, because Wordfence's version counts by IP and the version here can count by account:

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\RateLimit"
    response: block
    enable: true
    metadata:
      name: login-throttle
    config:
      - path: /wp-login.php
        rate: 5
        sample: 300
        key: [post.log]        # WordPress posts the username as `log`
      - path: /wp-login.php
        rate: 50
        sample: 300            # and the address, much looser

Verify the migration rather than trusting it¶

Every guide above is a translation, and translations are worth checking:

1. Start in a mode that cannot cause an outage. mode: monitor on CRS, metadata.mode: log on an individual rule, or global.mode: log for everything. Each evaluates fully and enforces nothing — the same request, with the same rules, differing only in that setting:

monitor: ALLOWED  GET /search?q=1%27+UNION+SELECT
block:   BLOCKED  GET /search?q=1%27+UNION+SELECT

2. Replay the requests you know about. For each rule you moved, check the request it was supposed to catch:

vendor/bin/firewall-check --config=firewall.yml --url='/wp-login.php' --ip=203.0.113.5 --explain

--explain lists every rule that evaluated and every rule that never ran, which is usually the answer to "why didn't my rule fire".

3. Check the rules you did not mean to change. Request something ordinary — a home page, an asset, a logged-in editor's path — and confirm it is still ALLOWED.

4. Lint before deploying.

vendor/bin/firewall-check --config=firewall.yml --lint

It reports rules that cannot match, unreachable rules, duplicate names, and the specific mistakes that look correct: an identity-keyed rate limit with no address-keyed companion, a bot score compared the wrong way round, a schedule that cannot be read.

5. Then ask the environment.

vendor/bin/firewall-doctor firewall.yml

See Diagnosing for what it checks.