Detection

Heimnull checks every active host’s traffic every second, inbound and outbound, against its hostgroup’s limits. It needs no sampling of its own and never waits on a database: detection runs in memory, as the flows arrive.

What’s measured

For each of your hosts, in each direction, and for each hostgroup as a whole:

Metric
bps, pps, fps	Bits, packets and flow records per second (for packet-sampling exporters, flows equal packets)
tcp_*, udp_*, icmp_*, other_*	Bits and packets per second by protocol
syn_pps	TCP packets with SYN and without ACK. From flow records it’s an approximation: the packets of flows whose combined flags have SYN and no ACK. That’s exact for spoofed floods (one-packet flows) and leaves normal connections out
frag_bps, frag_pps	IP fragments
amp_bps, amp_pps	UDP from the amplification source ports (DNS, NTP, SSDP, CLDAP, memcached…), first fragments only

Plus up to 16 flex rules per hostgroup.

A flow that lasted several seconds is spread over its duration, so a long download reported at once never looks like a spike. A flow record that arrives late (routers with a flow cache report flows seconds after they end) is counted from its arrival, at its own rate.

When an attack starts and ends

Every second, for each metric with a limit on:

1. Rate = the average over the window (5 seconds), leaving out the newest settle delay (2 seconds) for datagrams still in flight.
2. A limit triggers once it’s been exceeded for 3 evaluations in a row (Consecutive evaluations).
3. The attack ends when every metric that triggered has stayed below limit × 0.7 (Hysteresis) for 30 seconds (End after).
4. A new trigger within 60 seconds (Cooldown) of the end re-opens the same attack.

The window and settle delay are global (Settings → Detection); the rest is per hostgroup.

Detection starts collecting an attack’s evidence on the first second over the limit, so by the time it triggers, it already has a few seconds of fingerprint.

Hostgroups and carpet bombing

Limits come from the host’s hostgroup: the one with the most specific prefix covering it. Each hostgroup also has group limits on the sum over all its hosts. When a group limit triggers and no single host crossed its own limit, the attack’s type is carpet_bombing, and its record lists the most-targeted hosts.

Attack types

From the attack’s fingerprint:

Type	When
syn_flood	TCP over 50% of packets, and over 70% of TCP is SYN without ACK
udp_amplification:<protocol>	One amplification source port carries over 60% of the bytes (for example udp_amplification:dns)
fragment_flood	Over 50% fragments
icmp_flood	Over 70% ICMP
carpet_bombing	A group limit, with no single host over its own
unknown_volumetric	None of the above

What’s recorded

For each attack: its target, direction, type, triggers, peak, a 1-second series from a minute before the start, the top sources, source ASes and countries, histograms of ports, protocols, packet sizes and TCP flags, and a sample of up to 500 flow records (Settings → Detection). See the attack page.

Baselines

Static limits catch floods. Baselines catch traffic that’s unusual for a particular host at a particular time, even below the limits.

• Learning. Every hour, Heimnull computes each host’s and each hostgroup’s typical peak for the coming hour of the week, from the same hour in each of the last 4 weeks (the most recent counting most). Detected attacks are left out, so an attack never becomes “normal”.
• Learning period. A host needs 14 days of history before its baseline can trigger.
• Trigger. A metric triggers when its rate is above the learned peak × the multiplier (3) and above the metric’s floor, for 3 seconds in a row.
• Observe mode (the default). An anomaly is recorded as observed, and notified only if you route attack_observed. It’s never mitigated, and stays out of the red strip. If a static limit or flex rule then triggers too, it becomes a normal attack.
• Active mode. A baseline trigger is an attack like any other.

Host pages and the hostgroup editor draw the learned band against the recorded peaks, so you can judge a baseline before switching it to active. The baseline’s hours follow the time zone in Settings → Detection.

How fast

Heimnull’s own share, from the first packet of an attack to the attack’s record:

Attack against the limit	Time
5 times or more	5.5 seconds
2.5 to 5 times	6.5 seconds
Just over	up to 9.5 seconds

Add the time the router takes to export the traffic:

• Packet sampling (Juniper MX inline monitoring, sFlow): about a second. A real flood is detected about 7 seconds after it starts.
• Flow-cache export (MikroTik, J-Flow, NetFlow v9): the router’s inactive timeout. With 5 seconds on a MikroTik, about 10 seconds; at its 15-second default, about 20.

Announcing a mitigation takes under half a second more.