# agent timed out waiting for a WAF rule change to propagate

## TL;DR
WAF rule changes are not instant: the API accepts the change before every edge node has it, and most providers need seconds to a few minutes to finish pushing. Stop sleeping a fixed 30 seconds and hoping. Poll the provider's change-status API with backoff until it reports the change as propagated, then send a canary request that proves the rule is live before the agent continues.

```text
agent timed out waiting for a WAF rule change to propagate
```

## Use this when
- An agent deploys a WAF rule and immediately tests it, and the test fails
- A rule works when tested from the console but not from the agent's test path
- Block or allow behavior is intermittent in the minutes after a change
- A CI step sleeps a fixed time after a WAF change and still flakes

## Not for this skill when
- The rule never takes effect even after the documented propagation window (that is a rule syntax or priority problem, not propagation)
- You are testing WAF bypass techniques
- You are choosing between WAF providers

## Steps
1. Look up the provider's documented propagation window and set your max wait from it, plus margin. AWS WAF usually finishes in under a minute, Cloudflare is typically seconds but can take a few minutes on some plans, Azure often needs a few minutes.
   Expected: you have a max wait number, for example 300 seconds, instead of a guessed sleep.
2. After applying the change, poll the change status in a loop with backoff instead of sleeping once.
   ```sh
   for i in 1 2 3 4 5 6 7 8; do
     STATUS=$(curl -s https://example.com/waf/changes/CHG123 | python3 -c "import json,sys; print(json.load(sys.stdin)['status'])")
     echo "attempt $i status $STATUS"
     test "$STATUS" = "PROPAGATED" && break
     sleep $((i * 15))
   done
   ```
   Expected: the loop exits early with status PROPAGATED.
3. Send a canary request that the new rule should block (or allow) from the same network path the agent uses, not from your laptop.
   ```sh
   curl -s -o /dev/null -w "%{http_code}" "https://example.com/admin?test=waf-canary"
   ```
   Expected: the rule's action happens, for example 403 for a block rule.
4. Only continue the workflow after the canary passes. If the max wait expires first, treat it as an incident and alert, not as a cue to sleep longer.
   Expected: the workflow resumes on proof, or an alert fires.

### Variant: WAF rule change not taking effect yet
Same fix. "Not taking effect" in the first minutes is propagation; after the window it is a rule problem. Check the status API first, canary second.

### Variant: AWS WAF rule update propagation delay
Use the AWS change-token flow. Get a change token before the update and poll its status in the loop until it returns propagated. The console's green check is not proof for every edge node.

### Variant: Cloudflare firewall rule not active after change
Cloudflare pushes fast but not instantly. Poll the rule through the API and canary from the same region your traffic uses; edge state can differ by PoP for a short window.

## Why this happens
WAF configuration replicates to a distributed fleet. The control-plane API accepts your change as soon as it is valid, but each edge node enforces the old config until the new one arrives. A fixed sleep races the slowest node, so the agent sometimes wins and sometimes loses.

## Edge cases and pitfalls
- The status API can report success while a few edge nodes still lag; the canary request is the real proof, not the API status.
- A canary from a different region or network path can see different state; test from the agent's own egress path.
- Rule priority and ordering can make it look like the rule did not propagate when it did but never matched; check that the canary actually matches the rule conditions.
- Do not extend the sleep on failure; long fixed sleeps just make the flake rarer and the debugging slower.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5FpxjOchr2QL9xe27c626w