Security event connectors

Embed
Preview of the card
<a href="https://watchtowerops.net/docs/connectors-security"><img src="https://watchtowerops.net/docs/_api/public/orgs/aa5959cb-1a0b-4a9a-bc9a-913e7ac31cd9/spaces/b7aac181-9916-4805-b253-becc5fd2ca62/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. For these runtime tools Watchtower builds no detection engine: the detection stays in Falco, Tetragon, Wazuh or your scanner. Application-layer attacks seen in your own traces (injection, account takeover, abuse) are detected natively by App and API Protection.

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