Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Observability › Signals and Events

Signals and Events

Purpose

Show operators where signals land in the Manager and how Hosting events differ from Virtualization security logs. This is not a lossless SIEM and not a public event stream.

Audience

Anyone investigating authentication failures, scans, or Hosting collector output.

Edition

SHARED security-log path. Hosting projection APIs are ENTERPRISE_ONLY.

Status

SUPPORTED. Do not claim lossless or exactly-once delivery.

Prerequisites

  • Agent online and uploading
  • Admin JWT to list logs
  • For Hosting: Hosting Agent whose collectors are not all source_not_present

Required permissions

Admin for list APIs. Agent JWT for ingest (runtime, not browsers).

Dependencies

PostgreSQL security-log storage. Agent local spool (example bounds under Agent logging.batch).

Configuration

Virtualization log monitors (example): log_monitoring.enabled: true, files such as /var/log/auth.log with parsers: [ssh].

Hosting: hosting.sources[] identifiers in Signal classes.

Procedure

  1. Confirm Agent heartbeat (zwallctl list-agents, console status).
  2. List security logs: GET /api/v1/security-logs and GET /api/v1/security/logs (admin; limit/offset on the ingest family). Filters used by operators include log_type, agent_id, severity, action, source_ip.
  3. Dashboard: GET /api/v1/dashboard/logs, /api/v1/dashboard/security-events. WebSocket companion is /api/v1/dashboard/ws (console only — not a public stream product).
  4. CLI: zwallctl list-events --hours 24 --limit 100. zwallctl log lists lines; zwallctl log --follow prints not implemented.
  5. Hosting (Enterprise): GET /api/v1/agents/:id/hosting/events (optional limit 1–100, default 50). Projection keys only: event_id, source, category, severity, timestamp, parser, contract_version, review_state.
  6. Do not use Hosting event APIs expecting source_ip or raw payload.

Canonical security-log identity fields include log_type, source_ip, action, severity (plus destination/MAC/protocol/ports/details/rule_id when present). Hosting network types reject unrestricted packet fields on ingest.

Heartbeat carries health and, on Hosting, observation_only plus Hosting status. Heartbeat is not a SIEM.

Verification

  • A known SSH failure on a monitored Virtualization host appears as a security log with log_type / source_ip / action / severity.
  • A Hosting SSH collector event appears in the Hosting projection without requiring a customer IP field.
  • Empty Hosting list with permission_blocked sources is explained, not a silent bus failure.

Expected result

Operators can list events centrally. They cannot treat the list as a compliance-grade WORM audit.

Failure modes

Scroll sideways to see the full table. Use the arrow keys when focused.

SymptomMeaningAction
No security logsAgent upload errors; log_monitoring offAgent journal; Missing telemetry
Hosting emptyACL/pathsource state in Hosting status
IPs missing on Hosting APIcategory-safe contractuse security logs on Virtualization Agents if you need source_ip
WebSocket disconnectconsole hub, not a product streamrefresh session
zwallctl log --follow no-opnot implementedpoll list-events

Troubleshooting

Diagnostics, Hosting telemetry. Detection families (brute-force, RBL, ModSecurity observation, SSH/sudo alerts, temp-to-perm) are implemented services, not a guarantee every parser is production-certified. Alert .../test routes are not daily operator procedures.

Security considerations

Do not paste raw details or JWTs into tickets. Hosting redaction is part of the contract. Hosting sources are excluded from automatic/provider AI.

Limitations

No exactly-once delivery guarantee. Hosting projection omits raw bodies by design. AI Preview may read allowed security-event types when invoked; it does not subscribe to Hosting sources.