Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Concepts › Event Model

Event Model

SharedStatus: SUPPORTED with qualifiersAudience: security engineer, incident operator

Purpose

Describe what operators see in the Manager: security logs from Agents, Hosting category-safe projections, and detection-originated families — without inventing a complete event taxonomy or a compliance audit log.

Concept

Two operator-visible event surfaces:

  1. Security logs ingested by Agents (POST /api/v1/security-logs) and listed by administrators (GET /api/v1/security-logs, /api/v1/security/logs, dashboard logs). Canonical identity fields include log_type, source_ip, action, severity, plus destination/MAC/protocol/port/details/rule_id when present.
  2. Hosting events — the same ingest path after Hosting normalization, but the admin Hosting UI/API projects only event_id, source, category, severity, timestamp, parser, contract_version, review_state. Raw details and customer IPs are not in that projection.

Hosting network detector types (vertical/horizontal scan, SYN fan-out, UDP scan, burst, TCP-flag anomaly, closed-port when inferable, unique dest port/host rate) must be action: logged and must not carry unrestricted packet fields on the request.

Data/control flow

  1. Virtualization Agent: eBPF ring-buffer / log monitors (example SSH parser on /var/log/auth.log) → local spool → Manager.
  2. Hosting Agent: file collectors + loader socket → category-safe records → Manager. Source ids such as hosting.ssh.auth.v1 are parser identities, not public SKUs.
  3. Manager detection services (brute-force, scan/flood, RBL, ModSecurity observation, SSH/sudo alerts, temp-to-perm) may originate additional families. Not every parser is production-certified.
  4. Console reads lists and WebSocket dashboard updates.
  5. AI Preview may read allowed security-event types under Preview rules. Hosting sources are excluded from automatic/provider AI.

Where events live: Agent local buffer, Manager PostgreSQL, console views. There is no customer-facing event bus product.

Boundaries

  • Do not claim exactly-once or lossless delivery.
  • Hosting SOURCE_NOT_PRESENT / permission_blocked means no events from that collector until the operator fixes path/ACL.
  • ModSecurity Hosting path is global metadata only.
  • Certificate-expiry Hosting helper is loopback TLS metadata, not a certificate transparency log.
  • Alert .../test and analyze-now routes are not daily operator APIs.

Edition differences

Community: security logs, dashboard logs, 3-Agent cap.
Enterprise: Hosting projection APIs, additional detection/license gates, AI Preview with Hosting exclusion.

Common misconceptions

  • “Hosting events include the attacker IP like security logs.” Not in the Hosting projection.
  • “Empty Hosting events means the Agent is dead.” Check source state and loader socket first.
  • “ModSecurity source is a WAF you tune per site.” Global metadata only in this inventory.
  • “All log_type values are a published enum.” Document families you actually enable; do not invent codes.