Rule changes¶
New to WAF rules? Read WAF basics (中文) and start from the recipes.
The execution module applies rule changes — including the challenge, rate-limit and cache suggestions from alerts — to three Cloudflare phases:
--phase |
Cloudflare phase | Write-token permission |
|---|---|---|
custom (default) |
http_request_firewall_custom — custom (WAF) rules |
Zone → WAF: Edit |
ratelimit |
http_ratelimit — rate-limit rules |
Zone → WAF: Edit |
cache |
http_request_cache_settings — cache rules |
Zone → Cache Rules: Edit |
It uses the same separate write token as blocking (CF_WRITE_TOKEN) and needs the archive for backups and the audit log. With several zones configured, add --zone NAME|ID.
Commands¶
flarehound rules list [--phase custom|ratelimit|cache] # each rule with a plain-words explanation
flarehound rules recipes # ready-made rules, explained
flarehound rules recipe NAME [--path P] [--action A] [--ips IPS] [--asns ASNS] [--header NAME --secret-env VAR] [--skip SCOPES]
flarehound rules add --action ACTION --expr EXPR --desc TEXT [--before N|ID] [--disabled] [--skip SCOPES]
flarehound rules edit N|ID [--expr EXPR] [--action ACTION] [--desc TEXT] [--enabled true|false]
flarehound rules delete N|ID
flarehound rules move N|ID (--before N|ID | --last)
flarehound rules backups # snapshots taken before each change
flarehound rules restore BACKUP_ID # put a phase back as it was
flarehound rules log # execution audit log
flarehound ratelimit add --path PATTERN [--requests 20 --period 10 --timeout 10 --action managed_challenge]
flarehound cache add --path PATTERN [--ttl 1d]
Nis the rule's position inrules list;IDis the Cloudflare rule ID (or itsref).--pathtakes a pattern with*wildcard and turns it into an expression (/x→eq,/x*→starts_with, other*patterns →wildcard);--exprtakes a full expression instead.rules addneeds--action(a Cloudflare action such asblockormanaged_challenge),--expr(or--path) and--desc.- Skip rules (
--action skip) must say what they skip:--skip rules(the remaining custom rules — the default),ratelimit,managed(managed rules),bots(Super Bot Fight Mode),legacy(security level, browser integrity check, UA blocking, zone lockdown …), comma-separated. FlareHound builds theaction_parametersCloudflare requires; editing a skip rule into another action removes them. - Recipes build a complete rule from a few inputs and place it by the skips → blocks → challenges order:
protect-paths,ratelimit-paths,allow-service,allow-verified-bots,challenge-cloud-on-paths. Each prints what it does, why, the rule in plain words and any caveat before the usual confirmation. A secret header value is read from the environment variable named by--secret-env, never from the command line. See WAF basics. ratelimit addbuilds a per-IP rule (counted per IP and data center):--requestsper--periodseconds, mitigation--timeoutseconds, default actionmanaged_challenge.cache addbuilds a rule that makes matching requests eligible for cache with an edge TTL overriding the origin (--ttl, default1d; Go durations orNd).--observe 5m(custom and rate-limit changes) watches the changed rule's firewall events afterwards and reports the count. Zero only means "no matching traffic yet or not ingested"; on plans without firewall events it is skipped.
Examples:
flarehound rules add --action managed_challenge \
--expr 'starts_with(http.request.uri.path, "/login")' --desc "challenge login" --before 1
flarehound rules edit 3 --enabled false
flarehound rules move 3 --last
flarehound ratelimit add --path '/rank' --requests 20 --period 10
flarehound cache add --path '/assets/*' --ttl 1d
Safety¶
Every change goes through the same steps:
- Show the full change: all fields and the insert position for an add, field-by-field
old → newfor an edit, the full rule for a delete, positions for a move, and every rule that comes back / is removed / is changed / moves for a restore. Warnings are printed (e.g. inserting ahead of existing rules, disabling or deleting a protection). - Confirm with
y/N. There is deliberately no--yes— passing it is an error — and no batch mode. - Back up the whole phase first, exactly as Cloudflare returned it: to the archive (
rule_backups) and tobackups/<zone>/<phase>-<time>-v<version>.jsonin the data directory (mode 0600). - Apply, then read back and compare every field set by the change and the rule's position (fields Cloudflare adds by itself are allowed). A mismatch is reported as an error together with the restore command.
- Log to the append-only
rule_changestable: time, phase, operation, rule, before/after JSON, backup ID, verified or not, details (including API rejections). View it withflarehound rules log.
Guard rails:
- Expressions are syntax-checked locally with FlareHound's rules-language parser before anything is sent.
- Quotas per plan are checked before adding:
| Phase | Free | Pro | Business | Enterprise |
|---|---|---|---|---|
| Custom rules | 5 | 20 | 100 | 1,000 |
| Rate-limit rules | 1 | 2 | 5 | 100 |
| Cache rules | 10 | 25 | 50 | 300 |
- On Free, the rate-limit period and mitigation timeout must both be 10 seconds.
- Rules owned by the blocking module (
flarehound-prefix) cannot be changed here — useblock/unblock. - Rules are handled as raw JSON, so fields FlareHound does not model (skip parameters, rate-limit details, logging …) survive edits and restores.
- New rules get a
refstarting withfhx-, used to find them on read-back.
Restore¶
flarehound rules restore BACKUP_ID replaces the whole phase with the snapshot. It takes a fresh backup first, so a restore can itself be undone, and is confirmed and verified like any other change. Every successful change prints its undo command:
Done — … (verified by read-back). Backup #12: data/backups/example.com/custom-20261117-091500-v7.json
Undo: flarehound rules restore 12
Cloudflare matches rules by ref: in a live test, rules with a ref kept their IDs after a whole-phase restore, so their hit history continues. If the backup contains rules without a ref, FlareHound warns that they may get new IDs. Restoring a phase also restores FlareHound's blocking rules in it — run flarehound blocks afterwards to reconcile.