Mitigation

Heimnull mitigates attacks by announcing routes to your routers over BGP. Nothing is announced until a hostgroup’s action asks for it: the default action is notify.

Mitigation needs the trial or a paid license. In Free mode, attacks are detected and notified, mitigations are withdrawn, and manual mitigation is turned off.

Blackholes

A blackhole (remote-triggered blackhole, RTBH) is a route for the attacked address (/32 or /128) with your blackhole community, which your router turns into a discard route. It drops all traffic to the address, so the attack stops and so does the host.

• Communities come from the hostgroup if it sets any, else from the BGP page. A blackhole without one is refused.
• Next hop: each session’s own, usually an address the router routes to discard.
• Local preference (iBGP only) and MED, from the hostgroup or BGP page.
• Upstream RTBH. Your router can pass the route on to your transit providers with their blackhole community, so they drop the attack before it reaches your link. See Juniper MX.

FlowSpec

FlowSpec (RFC 8955 for IPv4, RFC 8956 for IPv6) sends the router a filter rule instead of a route: it drops or rate-limits only the attack, and the host stays reachable.

Heimnull builds the rules from the attack’s fingerprint. The address on your side is the destination for inbound attacks and the source for outbound ones.

Attack	Rule
SYN flood	TCP with SYN and without ACK, plus the destination ports if at most 4 of them carry 90%
Amplification	UDP from the reflector’s source port, in the packet length range holding 90% of packets; plus a rule for fragments if they’re 20% or more
Fragment flood	Fragments only
ICMP flood	ICMP (or ICMPv6) in the packet length range
Anything else	The dominant protocol (90% or more) and its ports

A fingerprint with nothing to match but the address would make a rule that’s really a blackhole: Heimnull refuses it for FlowSpec, and goes straight to a blackhole for FlowSpec, escalating to a blackhole.

The action is the hostgroup’s: discard, or rate limit to a rate in bits per second (sent as bytes per second, as the RFC requires), optionally redirect to a route target (a scrubbing VRF) and mark DSCP.

The life of a mitigation

pending → announcing (or dry_run) → active → withdrawing → withdrawn or expired, or refused or failed on the way.

• Row first. A mitigation is recorded before anything is announced. If announcing fails, it’s failed, and retried every 10 seconds until it would have expired.
• Duration. It lasts the hostgroup’s ban duration (15 minutes by default).
• Repeat offenders. With escalation on, each earlier mitigation of the same address in the last 24 hours doubles the duration, up to the maximum (1 day by default).
• Expiry. If the attack is still active and Extend while the attack continues is on, the mitigation is extended by the ban duration, never past the maximum. Otherwise it’s withdrawn.
• Probe at expiry. When upstream RTBH drops the attack before it reaches you, the attack looks over even while it continues. At expiry, Heimnull withdraws the blackhole and keeps watching; if the attack is still there, it’s detected again and blackholed again (for twice as long, with escalation on).
• Withdraw on attack end, instead of at expiry, if the hostgroup’s Withdraw says so.
• Cap. At most 100 mitigations are active at once (Settings → Mitigation). Further ones are refused and notified.
• Dry run records what would be announced, with the preview, and announces nothing.

Escalation

With FlowSpec, escalating to a blackhole, Heimnull starts with FlowSpec, and adds a blackhole for the same address when the attack stays above the hostgroup’s escalate above rate (any rate, by default) for escalate after seconds (60), counted from the later of the FlowSpec announcement and the moment the rate crossed. A dip below the rate resets the timer.

For inbound attacks the rate is the one delivered past the router, so that FlowSpec doing its job isn’t mistaken for failure. That needs the router to sample the interfaces facing your networks too, with the exporter set to Sampled on both sides. Without it, Heimnull sees only the arriving rate, which FlowSpec doesn’t change, so FlowSpec will always escalate to a blackhole. Outbound attacks are measured after the filter already.

Escalation on transit congestion

FlowSpec drops an attack at your router, after it has crossed your transit link. It protects the target, but a link the attack fills stays full for everyone else. With Also escalate when a transit link is congested:

• While a FlowSpec mitigation that may escalate is active, Heimnull reads the SNMP counters of every Transit and Peering interface every 5 seconds.
• A link is congested when every reading over the last 15 seconds was at or above 95% of its capacity (the subscribed rate, else the port speed). A link of unknown capacity is never congested.
• The attack sending the most over a congested link (and at least 10% of its own traffic over it) is blackholed. The link then waits 60 seconds for the upstream blackhole to take effect before the next attack on it is escalated.

The blackholed address goes offline. This only relieves the link if your router passes blackholes on to the transit provider (upstream RTBH).

Safety checks

Every announcement, automatic or manual, passes the same checks, in the API before it’s accepted, before it’s announced, and every time it’s reconciled:

1. The address on your side is inside your networks.
2. It isn’t covered by a whitelist entry exempt from mitigation, and a blackhole doesn’t cover any whitelisted address.
3. Address families match (IPv4 prefixes with IPv4 next hops).
4. A blackhole is a /32 or /128, unless the hostgroup allows aggregate blackholes, and then no shorter than its minimum prefix (/24 and /48 by default).
5. The communities are valid, and a blackhole has at least one.
6. The cap on active mitigations, and the emergency withdraw-all, are respected.
7. For FlowSpec: the rule matches more than the address, its ports are valid, and at least one session announces FlowSpec for the family.

A refusal is recorded on the mitigation with the reason, in the audit log, and as a mitigation_refused notification. A mitigation that no longer passes (its address was whitelisted afterward) is withdrawn.

Reconciliation

Every 30 seconds, at start and whenever the BGP speaker reconnects, Heimnull compares what should be announced with what the BGP speaker holds: missing routes are added, unexpected ones withdrawn, and routes with the wrong attributes announced again. Each correction is recorded in the BGP events and the audit log.

So a restart never withdraws anything by mistake: mitigations live in the database, and Heimnull announces them again when it’s back. During an upgrade, the BGP sessions drop for a few seconds and the routers withdraw Heimnull’s routes, then receive them again.

Emergency withdraw-all

See Attacks and Mitigations.