Kapkandocs
GitHub

Escalation ladders

A single mitigation method fires the same response the instant an attack is detected. An escalation ladder instead steps the response up the longer an attack persists — declaratively, where FastNetMon makes you write a callback script.

escalation:                         # supersedes `mitigation` when present
  - { after_seconds: 0,   action: none }       # alert only at first
  - { after_seconds: 30,  action: flowspec }   # still under attack after 30s → surgical drop
  - { after_seconds: 120, action: blackhole }  # still under attack after 120s → blackhole
flowspec:
  action: discard

How rungs apply

Each rung's after_seconds is measured from the attack's start. A rung applies once that much time has elapsed and the attack is still active — no end event yet, i.e. traffic is still above threshold through the unban hysteresis.

  • The first rung must be at 0 seconds.
  • action is none (alert only), flowspec, or blackhole.
  • A ladder may only hold or strengthen the response (none is weaker than flowspec, which is weaker than blackhole). De-escalating between rungs is a config error.

Make-before-break

Climbing to a rung is make-before-break: the new rung is announced first, and the previous one is withdrawn only after that succeeds — so the victim is never momentarily unprotected mid-switch. If the announce fails, the ban holds the working rung and retries on the next tick. If several rungs come due at once (a long-running attack, or the daemon catching up after a pause), the ban jumps straight to the highest due rung and never announces the rungs it skips.

Lifecycle and compatibility

The ladder is per-hostgroup overridable and shares the rest of the ban lifecycle: TTL auto-withdrawal, the max_active_bans cap, the absolute whitelist, and dry-run (which advances the ladder and logs each rung but never announces).

When no escalation block is set, the single mitigation method behaves exactly as a one-rung ladder at 0 seconds — full backward compatibility. The current rung and method are visible per ban in /api/v1/bans (escalation, escalation_step).

Related