Reading attack logs and forensics
Where attack history, timelines, and forensics live in the console, what each attack record field means, and how to tell a real attack from a traffic spike.
Last updated
On this page
Every attack the agent sees is recorded with the numbers you need for a post-mortem or a support ticket. This page shows where that data lives and how to read it.
Where attack data lives
Open the server in the console and go to its Live metrics tab. Three views matter:
- Attack history — one row per recorded attack.
- Attack timeline (
attack_timeline) — state transitions: when detection fired, when mitigation engaged, when it ended. - Recent events (
recent_events) — the agent's latest event entries.
What each attack record field means
| Field | Meaning |
|---|---|
number | Sequential attack number — quote it in tickets |
type | The attack classification |
start_time / end_time | When detection opened and closed the incident |
duration_seconds | Total length of the attack |
mitigated | Whether the agent actively dropped traffic |
mitigation_seconds | How long mitigation was engaged |
peak_pps / avg_pps / p95_pps | Packet-rate peak, average, and 95th percentile |
peak_bps | Peak bandwidth of the flood |
ips_involved | How many source IPs took part |
top_countries | Top source countries, each with ips, peak_pps, and pct |
forensics_dir | On-disk directory with the attack's forensics |
Telling a real attack from a traffic spike
Three signals separate an attack from a busy evening:
mitigatedistrueandmitigation_secondsis a real share ofduration_seconds— the agent found offending traffic worth dropping, not just volume.- The spike factor was clearly exceeded. Compare
attack.current_ppsagainstattack.spike_pps_threshold(baseline × spike factor). A borderline crossing that ends in seconds is usually a flash crowd; a sustained multiple of baseline is an attack. - Duration and source count. A long
duration_secondswith highips_involvedpoints to a distributed flood; a short spike from few sources rarely is.
Getting alerted
The agent can push alerts to your systems through the webhook alerter, configured with
alerter.* keys in /etc/openshield/openshield.yaml. The metrics payload reports its
health: alerter.webhook_set, alerter.queued, alerter.sent, and alerter.last_error.
If last_error is set, alerts are queuing but not arriving — see
Common errors.