# How OpenShield mitigation works

> The OpenShield-XDP packet pipeline, ban tiers, baselines, and protected sources — and how to read an attack while it happens.
>
> Canonical: https://xdp.network/docs/products/openshield-mitigation · Updated 2026-08-17

OpenShield-XDP makes drop decisions inside the NIC driver hook, so floods are answered
before the kernel allocates a socket buffer. This page explains the pipeline a packet
travels, the state the agent keeps, and what an attack looks like from your console.

## The XDP pipeline

Every arriving packet runs through five stages, chained in order:

1. **Prefilter** — cheap sanity checks: header parsing, fragment drops, and a panic
   circuit breaker that sheds load if the CPU is overwhelmed.
2. **Access** — the whitelist first, then bans and blackholes. Whitelisted sources pass
   here, before any drop logic; known-bad sources and blackholed destinations drop.
3. **Inspect** — protocol-level analysis: L4 validation, UDP amplification heuristics, and
   L7 signature matching.
4. **State** — per-source accounting and connection tracking.
5. **Mitigate** — rate limits, protocol caps, and drop verdicts. Offending packets get
   `XDP_DROP` and never reach the network stack; everything else passes to your
   application.

Because verdicts happen at the earliest point a packet can be handled, mitigation runs at
line rate with sub-millisecond overhead.

## Whitelist and ban tiers

Bans come in two tiers, and the ban stage consults the stricter one first:

- **Pinned bans** are never evicted by flood churn: your manual blacklist entries and the
  heavy or repeat offenders the kernel mirrors there.
- **Regular bans** live in a churn-tolerant map — during a flood, the least-recently-used
  entries evict to make room for new offenders.

The console's **Control** tab manages the whitelist and the manual blacklist.

## Protected sources

The agent continuously tracks sources with proven legitimate presence — for example,
clients holding an established TCP connection. Protected sources are exempt from the
rate-limit and spike triggers, so your real users survive a flood aimed at you. During an
engagement the protected set freezes: existing members stay, and new sources must prove
themselves before joining. Bans always outrank protection — the ban stage runs first.

## Rate limits and learned baselines

Static rate limits alone either drop legitimate bursts or let slow floods through, so caps
work together with baselines:

- **Per-port caps** limit how many packets per second (and bytes per second) any
  destination port may receive.
- **Baselines** are exponential moving averages the agent learns per port and per
  protocol. A port crosses the line early when it is over the cap *and* over roughly 8×
  its own baseline — a spike relative to what that port normally sees, not an absolute
  guess.
- **Aggregate protocol caps** bound ICMP and UDP as a whole, catching carpet-bombing and
  rotation floods that no single-port cap would see.

Baselines only learn from calm windows, so a long attack cannot teach the agent that
flood levels are normal.

## Blackholes and the SYN-proxy companion

A **blackhole** drops all traffic toward one destination IP on the server, except sources
with a live exemption (established connections are re-proven and exempted automatically).
Use it to sacrifice a targeted IP so the rest of the host stays reachable.

The optional **SYN-proxy companion** answers SYN floods on the agent's behalf so half-open
handshakes never exhaust your stack. The install wizard probes the server for
compatibility before letting you enable it.

## What an attack lifecycle looks like

1. **Detect** — the current packet rate climbs past the baseline times the spike factor.
   The agent flips into the attack state and records the threshold it crossed.
2. **Mitigate** — offending packets drop at the NIC, offending sources are banned with an
   expiry, and brand-new sources can be refused outright. Legitimate traffic keeps passing
   through the whitelist and protected sources.
3. **Normalize** — when rates fall back to baseline, the attack closes with a record:
   type, duration, peak and average rates, sources involved, and whether mitigation
   engaged.

## What to do during an attack

- **Read the attack banner** in the live console: current rate versus the spike trigger,
  IPs banned, and new sources blocked tell you whether mitigation is coping. A healthy
  pass rate next to a climbing drop rate means it is.
- **Check Top offenders** for the heaviest sources and the **Attack origins** map for the
  geographic shape of the flood.
- **Keep the agent running.** Do not restart it or flush bans mid-attack — that throws
  away the ban list, the learned baseline, and the protected set, and lets banned sources
  straight back in.
- **Keep the forensics.** Each closed attack records a forensics directory on the server
  (report, involved IPs, config snapshot, and packet captures when recorded); quote the
  attack number and that directory if you open a ticket.

:::warning
Do not null-route the server or restart its networking during an attack. Taking your own
IP offline does the attacker's job for them.
:::

## Reading logs

The console's **Logs** tab streams the agent's own log entries, filterable by level
(info, warn, error) and by message text. The **Attacks** tab adds the **Recent state
changes** card — when detection fired, when mitigation engaged, when it ended — next to
the full attack history table.

## Next steps

- [OpenShield-XDP](/docs/products/openshield-xdp)
- [L7 Shield](/docs/products/l7-shield)