How OpenShield mitigation works

The OpenShield-XDP packet pipeline, ban tiers, baselines, and protected sources — and how to read an attack while it happens.

Last updated

On this page

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.

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