docs(audit): document the HEC audit destination

docs/admin-guide/audit-log.md

@@ -1,6 +1,6 @@
 ---
 title: Audit log
-description: Turn on the audit log to see who did what in Semaphore, and send audit events from Semaphore Pro to a SIEM.
+description: Turn on the audit log to see who did what in Semaphore, and send audit events from Semaphore Pro to a SIEM over Syslog or HEC.
 ---
 
 # Audit log
@@ -118,8 +118,9 @@ to the server log and the action continues as usual.
 
 ## Export to a SIEM <FeatureState feature="audit-siem-export" /> {#siem-export}
 
-Semaphore Pro can send audit events to a Syslog receiver over TLS, such as rsyslog or Vector. The receiver
-can store them or pass them on to your SIEM.
+Semaphore Pro can send audit events to a Syslog receiver over TLS, such as rsyslog or Vector, and to any
+receiver of the Splunk HTTP Event Collector (HEC) protocol, such as Splunk, Vector, Fluent Bit, the
+OpenTelemetry Collector or Cribl. You can set up one Syslog and one HEC destination, or both at once.
 
 You will need:
 
@@ -170,17 +171,60 @@ Semaphore records an event every time it starts. After the restart, look for it
 `event_code` is `audit.lifecycle`, `action` is `start`, and `metadata.destinations` includes your
 destination ID.
 
+### Send events over HEC {#hec}
+
+You will need the HEC endpoint URL, a HEC token, a name for this destination such as `security-hec`, and the
+CA certificate of the receiver if the Semaphore host does not trust it already.
+
+```json
+{
+  "audit": {
+    "enabled": true,
+    "instance_id": "prod-eu",
+    "splunk_hec": {
+      "id": "security-hec",
+      "url": "https://splunk.example.com:8088/services/collector/event",
+      "token": "<HEC token>",
+      "index": "security",
+      "ca_file": "/etc/semaphore/siem-ca.pem"
+    }
+  }
+}
+```
+
+Or using environment variables:
+
+```bash
+SEMAPHORE_AUDIT_SPLUNK_HEC_ID=security-hec
+SEMAPHORE_AUDIT_SPLUNK_HEC_URL=https://splunk.example.com:8088/services/collector/event
+SEMAPHORE_AUDIT_SPLUNK_HEC_TOKEN='<HEC token>'
+SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security
+SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem
+```
+
+`id`, `url` and `token` are required, and the URL must start with `https://`. Use a different `id` than for
+Syslog. `source` and `sourcetype` default to `semaphore` and `semaphore:audit`. Certificates are checked the
+same way as for Syslog, and the standard `HTTPS_PROXY` and `NO_PROXY` variables apply.
+
+Semaphore sends up to 100 events per request. The `event` field of each HEC event holds the audit event JSON,
+`time` is the event time, and `host` is the HA node ID, or the instance ID on a single node.
+
+Restart Semaphore, then check that events arrive as described [above](#verify-siem-delivery).
+
 ### How events are delivered {#delivery}
 
 - If the receiver is down, events wait in the database and are sent when it is back. Users don't notice
   anything.
 - After network errors, restarts or an HA failover, some events can arrive twice. Use `event_id` to drop
   duplicates and `seq` to put events in order.
-- If a connection breaks without an error, the event sent at that moment can be lost.
-- In an [HA installation](/admin-guide/ha), one node sends events at a time. If Redis is unavailable,
+- Over Syslog, if a connection breaks without an error, the event sent at that moment can be lost.
+- In an [HA installation](/admin-guide/ha), one node at a time sends events to each destination. If Redis is unavailable,
   sending pauses, and events are still recorded.
+- Over HEC, an event counts as sent only after the receiver answers with a 2xx status. Any other answer,
+  including 4xx, is retried. If the receiver crashes after answering, events it had not stored yet can be
+  lost.
 
-Each event is sent as an RFC 5424 Syslog message with the event JSON as its body. `HOSTNAME` is the HA node
+Over Syslog, each event is sent as an RFC 5424 Syslog message with the event JSON as its body. `HOSTNAME` is the HA node
 ID, or the instance ID on a single node, and `MSGID` is the event code.
 
 The examples below are minimal and only show how to receive the events. They accept a connection from any
@@ -234,15 +278,43 @@ path = "/var/log/semaphore-audit.json"
 encoding.codec = "json"
 ```
 
+### Vector HEC example {#vector-hec}
+
+```toml
+[sources.semaphore_audit_hec]
+type = "splunk_hec"
+address = "0.0.0.0:8088"
+valid_tokens = ["<HEC token>"]
+tls.enabled = true
+tls.crt_file = "/etc/vector/cert.pem"
+tls.key_file = "/etc/vector/key.pem"
+
+[sinks.semaphore_audit_file]
+type = "file"
+inputs = ["semaphore_audit_hec"]
+path = "/var/log/semaphore-audit.json"
+encoding.codec = "json"
+```
+
+### Splunk example {#splunk}
+
+Create a HEC token in Splunk (**Settings → Data inputs → HTTP Event Collector**), allow the `security` index
+for it, and set `url` to `https://<splunk>:8088/services/collector/event`. To find the events, search for
+`index=security sourcetype="semaphore:audit"`.
+
+Leave **Enable indexer acknowledgement** off for this token: Semaphore does not use it.
+
 ### Troubleshoot export {#troubleshoot-export}
 
-- **Semaphore does not start.** Check that both `audit.syslog.id` and `audit.syslog.address` are set and
-  that the CA file contains PEM certificates.
+- **Semaphore does not start.** Check that both `audit.syslog.id` and `audit.syslog.address` are set, or
+  `audit.splunk_hec.id`, `url` and `token` for HEC, and that the CA file contains PEM certificates.
 - **The TLS connection fails.** Check that the receiver certificate matches `server_name` and is signed by
   a CA that Semaphore trusts.
 - **Events do not arrive.** Check the Semaphore server log and the receiver log. After a failure, Semaphore
   waits a little before it tries again.
 - **Some events arrive twice.** This can happen after retries and failovers. Drop duplicates by `event_id`.
+- **HEC answers 400, 401 or 403.** Check the token, the indexes it is allowed to write to, and that indexer
+  acknowledgement is off for it. The token never appears in the Semaphore log.
 
 ## What is not recorded {#not-recorded}
 

docs/reference/configuration.md

@@ -311,6 +311,15 @@ Recording who did what in Semaphore, and sending the events to a SIEM. See [Audi
 | `audit.syslog.timeout` <Pro /><br />`SEMAPHORE_AUDIT_SYSLOG_TIMEOUT` | string<br />Default: `10s` | Limits connecting to the receiver and sending events. |
 | `audit.syslog.ca_file` <Pro /><br />`SEMAPHORE_AUDIT_SYSLOG_CA_FILE` | string | PEM file with extra CA certificates to trust. |
 | `audit.syslog.server_name` <Pro /><br />`SEMAPHORE_AUDIT_SYSLOG_SERVER_NAME` | string | Name to check in the receiver certificate. |
+| `audit.splunk_hec.id` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_ID` | string | Names the destination. Keep it when the URL changes. A new ID starts with new events. |
+| `audit.splunk_hec.url` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_URL` | string | Full HEC endpoint, for example https://hec.example:8088/services/collector/event. |
+| `audit.splunk_hec.token` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_TOKEN` | string | HEC token sent as "Authorization: Splunk \<token>". Secret: keep it out of shell history and version control. |
+| `audit.splunk_hec.index` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX` | string | Target index. Empty uses the default index of the token. |
+| `audit.splunk_hec.source` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_SOURCE` | string<br />Default: `semaphore` | HEC source of every event. |
+| `audit.splunk_hec.sourcetype` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_SOURCETYPE` | string<br />Default: `semaphore:audit` | HEC sourcetype of every event. |
+| `audit.splunk_hec.timeout` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_TIMEOUT` | string<br />Default: `10s` | Bounds one HTTP request with one batch of events. |
+| `audit.splunk_hec.ca_file` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE` | string | PEM bundle added to the system roots. |
+| `audit.splunk_hec.server_name` <Pro /><br />`SEMAPHORE_AUDIT_SPLUNK_HEC_SERVER_NAME` | string | Overrides the name checked in the receiver certificate. |
 
 ## Debugging {#debugging}
 

i18n/de/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md

@@ -1,6 +1,6 @@
 ---
 title: Audit-Protokoll
-description: Aktivieren Sie das Audit-Protokoll, um zu sehen, wer was in Semaphore getan hat, und senden Sie Audit-Ereignisse aus Semaphore Pro an ein SIEM.
+description: Aktivieren Sie das Audit-Protokoll, um zu sehen, wer was in Semaphore getan hat, und senden Sie Audit-Ereignisse aus Semaphore Pro per Syslog oder HEC an ein SIEM.
 ---
 
 # Audit-Protokoll
@@ -121,8 +121,9 @@ Semaphore einen Fehler in das Server-Log, und die Aktion läuft wie gewohnt weit
 
 ## Export an ein SIEM <FeatureState feature="audit-siem-export" /> {#siem-export}
 
-Semaphore Pro kann Audit-Ereignisse über TLS an einen Syslog-Empfänger senden, etwa rsyslog oder Vector.
-Der Empfänger kann sie speichern oder an Ihr SIEM weiterleiten.
+Semaphore Pro kann Audit-Ereignisse über TLS an einen Syslog-Empfänger senden, etwa rsyslog oder Vector,
+und an jeden Empfänger des Splunk-HTTP-Event-Collector-Protokolls (HEC), etwa Splunk, Vector, Fluent Bit, den
+OpenTelemetry Collector oder Cribl. Sie können ein Syslog- und ein HEC-Ziel einrichten, oder beide gleichzeitig.
 
 Sie benötigen:
 
@@ -174,17 +175,62 @@ Semaphore nicht.
 Semaphore zeichnet bei jedem Start ein Ereignis auf. Suchen Sie es nach dem Neustart beim Empfänger:
 `event_code` ist `audit.lifecycle`, `action` ist `start`, und `metadata.destinations` enthält Ihre Ziel-ID.
 
+### Ereignisse über HEC senden {#hec}
+
+Sie benötigen die URL des HEC-Endpunkts, ein HEC-Token, einen Namen für dieses Ziel, etwa `security-hec`, und
+das CA-Zertifikat des Empfängers, falls der Semaphore-Host ihm nicht bereits vertraut.
+
+```json
+{
+  "audit": {
+    "enabled": true,
+    "instance_id": "prod-eu",
+    "splunk_hec": {
+      "id": "security-hec",
+      "url": "https://splunk.example.com:8088/services/collector/event",
+      "token": "<HEC token>",
+      "index": "security",
+      "ca_file": "/etc/semaphore/siem-ca.pem"
+    }
+  }
+}
+```
+
+Oder mit Umgebungsvariablen:
+
+```bash
+SEMAPHORE_AUDIT_SPLUNK_HEC_ID=security-hec
+SEMAPHORE_AUDIT_SPLUNK_HEC_URL=https://splunk.example.com:8088/services/collector/event
+SEMAPHORE_AUDIT_SPLUNK_HEC_TOKEN='<HEC token>'
+SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security
+SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem
+```
+
+`id`, `url` und `token` sind erforderlich, und die URL muss mit `https://` beginnen. Verwenden Sie eine andere
+`id` als für Syslog. `source` und `sourcetype` haben die Standardwerte `semaphore` und `semaphore:audit`.
+Zertifikate werden wie bei Syslog geprüft, und die Standardvariablen `HTTPS_PROXY` und `NO_PROXY` werden
+beachtet.
+
+Semaphore sendet bis zu 100 Ereignisse pro Anfrage. Das Feld `event` jedes HEC-Ereignisses enthält das
+Audit-Ereignis-JSON, `time` ist der Zeitpunkt des Ereignisses, und `host` ist die HA-Knoten-ID oder auf einem
+einzelnen Knoten die Instanz-ID.
+
+Starten Sie Semaphore neu und prüfen Sie dann, ob Ereignisse wie [oben](#verify-siem-delivery) beschrieben ankommen.
+
 ### Wie Ereignisse zugestellt werden {#delivery}
 
 - Ist der Empfänger nicht erreichbar, warten die Ereignisse in der Datenbank und werden gesendet, sobald er
   wieder da ist. Benutzer merken davon nichts.
 - Nach Netzwerkfehlern, Neustarts oder einem HA-Failover können manche Ereignisse doppelt ankommen. Nutzen
   Sie `event_id`, um Duplikate zu verwerfen, und `seq`, um Ereignisse zu ordnen.
-- Bricht eine Verbindung ohne Fehlermeldung ab, kann das in diesem Moment gesendete Ereignis verloren gehen.
-- In einer [HA-Installation](/admin-guide/ha) sendet jeweils ein Knoten Ereignisse. Ist Redis nicht
+- Bricht bei Syslog eine Verbindung ohne Fehlermeldung ab, kann das in diesem Moment gesendete Ereignis verloren gehen.
+- In einer [HA-Installation](/admin-guide/ha) sendet jeweils nur ein Knoten Ereignisse an jedes Ziel. Ist Redis nicht
   erreichbar, pausiert das Senden, und Ereignisse werden weiter aufgezeichnet.
+- Bei HEC gilt ein Ereignis erst als gesendet, wenn der Empfänger mit einem 2xx-Status antwortet. Jede andere
+  Antwort, auch 4xx, wird wiederholt. Stürzt der Empfänger nach der Antwort ab, können Ereignisse verloren
+  gehen, die er noch nicht gespeichert hatte.
 
-Jedes Ereignis wird als Syslog-Nachricht nach RFC 5424 mit dem Ereignis-JSON als Inhalt gesendet. `HOSTNAME`
+Bei Syslog wird jedes Ereignis als Syslog-Nachricht nach RFC 5424 mit dem Ereignis-JSON als Inhalt gesendet. `HOSTNAME`
 ist die HA-Knoten-ID oder auf einem einzelnen Knoten die Instanz-ID, und `MSGID` ist der Ereigniscode.
 
 Die folgenden Beispiele sind minimal und zeigen nur, wie die Ereignisse empfangen werden. Sie nehmen
@@ -239,16 +285,43 @@ path = "/var/log/semaphore-audit.json"
 encoding.codec = "json"
 ```
 
+### Vector-HEC-Beispiel {#vector-hec}
+
+```toml
+[sources.semaphore_audit_hec]
+type = "splunk_hec"
+address = "0.0.0.0:8088"
+valid_tokens = ["<HEC token>"]
+tls.enabled = true
+tls.crt_file = "/etc/vector/cert.pem"
+tls.key_file = "/etc/vector/key.pem"
+
+[sinks.semaphore_audit_file]
+type = "file"
+inputs = ["semaphore_audit_hec"]
+path = "/var/log/semaphore-audit.json"
+encoding.codec = "json"
+```
+
+### Splunk-Beispiel {#splunk}
+
+Erstellen Sie in Splunk ein HEC-Token (**Settings → Data inputs → HTTP Event Collector**), erlauben Sie ihm
+den Index `security` und setzen Sie `url` auf `https://<splunk>:8088/services/collector/event`. Um die
+Ereignisse zu finden, suchen Sie nach `index=security sourcetype="semaphore:audit"`.
+
+Lassen Sie **Enable indexer acknowledgement** für dieses Token ausgeschaltet: Semaphore verwendet es nicht.
+
 ### Fehlerbehebung beim Export {#troubleshoot-export}
 
-- **Semaphore startet nicht.** Prüfen Sie, dass `audit.syslog.id` und `audit.syslog.address` gesetzt sind
-  und die CA-Datei PEM-Zertifikate enthält.
+- **Semaphore startet nicht.** Prüfen Sie, dass `audit.syslog.id` und `audit.syslog.address` gesetzt sind,
+  oder bei HEC `audit.splunk_hec.id`, `url` und `token`, und dass die CA-Datei PEM-Zertifikate enthält.
 - **Die TLS-Verbindung schlägt fehl.** Prüfen Sie, dass das Zertifikat des Empfängers zu `server_name` passt
   und von einer CA signiert ist, der Semaphore vertraut.
 - **Ereignisse kommen nicht an.** Prüfen Sie das Semaphore-Server-Log und das Log des Empfängers. Nach einem
   Fehler wartet Semaphore kurz, bevor es es erneut versucht.
 - **Manche Ereignisse kommen doppelt an.** Das kann nach Wiederholungen und Failovers passieren. Verwerfen
   Sie Duplikate anhand von `event_id`.
+- **HEC antwortet mit 400, 401 oder 403.** Prüfen Sie das Token, die Indizes, in die es schreiben darf, und dass die Indexer-Bestätigung dafür ausgeschaltet ist. Das Token erscheint nie im Semaphore-Log.
 
 ## Was nicht aufgezeichnet wird {#not-recorded}