A security event is recorded when the edge blocks, challenges or logs a request: a WAF rule, a rate limit, an IP or country rule, a shield, or an origin TLS error (525/526). Events reach the dashboard shortly after they happen and are kept for 30 days.
Event fields
| Field | Meaning |
|---|---|
ts | Time of the request. |
action | block, challenge, log or allow. |
host, method, path, status | The request and the status the edge answered. |
ip, country_code, asn | The client's address, its country and network. |
rule_id, rule_name, attack_type, msg | The rule that matched and why. Rate limiting rules appear as rate_rule:<id>; origin TLS errors as origin_tls. |
user_agent, tls_fingerprint | The client software. |
Explore events in the dashboard
Go to Analytics › Traffic and scroll to Security events.
- Time range: last 5 minutes, 15 minutes, hour, 24 hours or 7 days, or a Custom range.
- Filters: select Add filter, or the + / − buttons on any value in the table, to include or exclude a field (is / is not). Filters show as chips you can toggle or remove.
- Search: free text over path, IP, rule, user agent and other fields.
- Histogram: events over time by action; select a bar to zoom into its interval.
- Breakdown: events by action, top rules, top rate limiting rules and top countries.
- Rows: open a row for every field, as a table or JSON; choose visible fields with Columns.
- Live: streams new events as they arrive. It pauses while the pointer is over the list, while you browse it or scroll, and while the browser tab is hidden.
Read events with the API
| Route | Answer |
|---|---|
GET /v1/orgs/{org}/zones/{zone}/events | Events, newest first: items and next_cursor for the next page. |
GET /v1/orgs/{org}/zones/{zone}/events/summary | total, by_action, top_rules, top_rate_rules, top_countries. |
GET /v1/orgs/{org}/zones/{zone}/events/histogram?step=<s> | Events per interval and action; step from 1 to 86400 seconds, at most 1000 intervals (omit for an automatic step of at most 60 intervals). |
GET /v1/orgs/{org}/zones/{zone}/events/stream | Live stream (Server-Sent Events). |
Any role of the organization can read them, including read-only and zone-scoped tokens.
Parameters
| Parameter | Meaning |
|---|---|
since, until | RFC 3339 times. Default: the last 24 hours; at most 31 days. |
action, rule_id, rule_name, rate_rule, ip, country, host, path, status | Include only events with this value. Repeatable (up to 20 values each). |
not_action, not_ip, … | The same fields with not_: exclude events with this value. |
q | Free-text search, up to 200 characters. |
limit, cursor | Page size (default 100, at most 1000) and the next_cursor of the previous page (/events only). |
curl -s "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events?action=block&country=CN¬_path=/health&limit=50" \
-H "Authorization: Bearer $OPENWAF_TOKEN"Live stream
/events/stream accepts the same filters and sends Server-Sent Events:
| Event | Data |
|---|---|
ready | Stream parameters (poll_ms, heartbeat_ms, max_age_s). |
event | One security event, with an id. |
ping | Keep-alive when nothing happened for a while. |
bye | The stream ends after 10 minutes; reconnect with Last-Event-ID to resume where you left off. |
curl -sN "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/events/stream?action=block" \
-H "Authorization: Bearer $OPENWAF_TOKEN" -H "Accept: text/event-stream"An organization can hold up to 10 streams at once; more answer 429 (too_many_streams).
Related
- WAF: the rules behind the events.
- Troubleshooting 525 and 526: origin TLS events.