Security event connectors

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/connectors-security"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/be7bde10-bf83-43da-8d48-69f8e50dfb67/social-card.svg?v=3e7ae33eec8b" alt="Security event connectors" width="600" height="315"></a>

Runtime-security tools post their alerts to Watchtower; each kept alert becomes a log record in logs_v1, searchable with the normal logs API and usable in the normal log alert rules. Watchtower builds no detection engine: the detection stays in Falco, Tetragon, Wazuh or your scanner.

Tool

Guide

Falco

falco.md

Tetragon

tetragon.md

Wazuh

wazuh.md

Anything that emits OCSF (DLP scanners, AI-remediation tools, cloud findings)

kind generic, below

Set up

  1. POST /v1/projects/{p}/security-sources with {"kind": "falco|tetragon|wazuh|generic", "filters": {"min_priority": "warning", "rules": [], "namespaces": []}} (needs manage_credentials).

  2. The response holds intake_path (/v1/security/{source_id}) and a secret, shown once. Only its SHA-256 is stored.

  3. Point the tool at https://<edge>/v1/security/{source_id} and send the secret as Authorization: Bearer <secret> or X-Watchtower-Secret: <secret>.

A wrong secret is 401; an unknown or deleted source is 404.

Filters are required

These feeds are high volume, so a source without filters is rejected (422 filters_required). Filters run at the edge, before Kafka:

  • min_priority: debug, info, notice, warning (default), error, critical, alert, emergency. Lower events are dropped.

  • rules: when not empty, only these rule names are kept.

  • namespaces: when not empty, events from other Kubernetes namespaces are dropped. Events without a namespace (host events) are not affected.

Drops are counted in wt_edge_security_dropped_total{reason="priority|rule|namespace"} on the edge's metrics endpoint.

What a log record carries

Resource service.name = security-<kind>. Attributes: security.source, security.rule, security.priority, security.tags (array), event.category = intrusion_detection, plus k8s.namespace.name, k8s.pod.name, container.id, host.name and similar fields from the payload. trace_id is set when the payload carries a 32-hex trace_id. Only these fixed names are emitted; a wt.* key in a payload is never copied.

Generic (OCSF)

Events are mapped by class_uid: Detection Finding 2004 (rule finding_info.title), API Activity 6003 (rule api.operation), Account Change 3001 and Authentication 3002 (rule activity_name). Any other class is kept verbatim: rule ocsf.<class_uid>, body the event JSON. severity_id 1..6 maps to info, notice, warning, error, critical, alert. A body is one event, a JSON array, {"events": [...]} or NDJSON (at most 1 MiB). The outbound direction (audit export in OCSF) is in the SIEM reference.

Delivery is at-least-once: a sender that retries can produce a duplicate record.

Updated