diff --git a/docs/admin-guide/audit-log.md b/docs/admin-guide/audit-log.md index c2afbe86..12271460 100644 --- a/docs/admin-guide/audit-log.md +++ b/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 {#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": "", + "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='' +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 = [""] +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://: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} diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index d3ce1864..d07d6926 100644 --- a/docs/reference/configuration.md +++ b/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`
`SEMAPHORE_AUDIT_SYSLOG_TIMEOUT` | string
Default: `10s` | Limits connecting to the receiver and sending events. | | `audit.syslog.ca_file`
`SEMAPHORE_AUDIT_SYSLOG_CA_FILE` | string | PEM file with extra CA certificates to trust. | | `audit.syslog.server_name`
`SEMAPHORE_AUDIT_SYSLOG_SERVER_NAME` | string | Name to check in the receiver certificate. | +| `audit.splunk_hec.id`
`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`
`SEMAPHORE_AUDIT_SPLUNK_HEC_URL` | string | Full HEC endpoint, for example https://hec.example:8088/services/collector/event. | +| `audit.splunk_hec.token`
`SEMAPHORE_AUDIT_SPLUNK_HEC_TOKEN` | string | HEC token sent as "Authorization: Splunk \". Secret: keep it out of shell history and version control. | +| `audit.splunk_hec.index`
`SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX` | string | Target index. Empty uses the default index of the token. | +| `audit.splunk_hec.source`
`SEMAPHORE_AUDIT_SPLUNK_HEC_SOURCE` | string
Default: `semaphore` | HEC source of every event. | +| `audit.splunk_hec.sourcetype`
`SEMAPHORE_AUDIT_SPLUNK_HEC_SOURCETYPE` | string
Default: `semaphore:audit` | HEC sourcetype of every event. | +| `audit.splunk_hec.timeout`
`SEMAPHORE_AUDIT_SPLUNK_HEC_TIMEOUT` | string
Default: `10s` | Bounds one HTTP request with one batch of events. | +| `audit.splunk_hec.ca_file`
`SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE` | string | PEM bundle added to the system roots. | +| `audit.splunk_hec.server_name`
`SEMAPHORE_AUDIT_SPLUNK_HEC_SERVER_NAME` | string | Overrides the name checked in the receiver certificate. | ## Debugging {#debugging} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/de/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 220ef103..aa136414 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/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 {#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": "", + "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='' +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 = [""] +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://: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} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/es/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index c2f21e79..e03cb672 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Registro de auditoría -description: Active el registro de auditoría para ver quién hizo qué en Semaphore y envíe los eventos de auditoría de Semaphore Pro a un SIEM. +description: Active el registro de auditoría para ver quién hizo qué en Semaphore y envíe los eventos de auditoría de Semaphore Pro a un SIEM mediante Syslog o HEC. --- # Registro de auditoría @@ -123,8 +123,9 @@ un error en el registro del servidor y la acción continúa con normalidad. ## Exportar a un SIEM {#siem-export} -Semaphore Pro puede enviar eventos de auditoría a un receptor Syslog mediante TLS, como rsyslog o Vector. El -receptor puede guardarlos o reenviarlos a su SIEM. +Semaphore Pro puede enviar eventos de auditoría a un receptor Syslog mediante TLS, como rsyslog o Vector, y a +cualquier receptor del protocolo Splunk HTTP Event Collector (HEC), como Splunk, Vector, Fluent Bit, el +OpenTelemetry Collector o Cribl. Puede configurar un destino Syslog y uno HEC, o ambos a la vez. Necesitará: @@ -176,17 +177,62 @@ arranca. Semaphore registra un evento cada vez que arranca. Tras el reinicio, búsquelo en el receptor: `event_code` es `audit.lifecycle`, `action` es `start` y `metadata.destinations` incluye el ID de su destino. +### Enviar eventos por HEC {#hec} + +Necesitará la URL del endpoint HEC, un token HEC, un nombre para este destino, como `security-hec`, y el +certificado de la CA del receptor si el host de Semaphore aún no confía en ella. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +O mediante variables de entorno: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` y `token` son obligatorios, y la URL debe empezar por `https://`. Use un `id` distinto del de +Syslog. `source` y `sourcetype` toman por defecto los valores `semaphore` y `semaphore:audit`. Los +certificados se comprueban igual que en Syslog, y se aplican las variables estándar `HTTPS_PROXY` y +`NO_PROXY`. + +Semaphore envía hasta 100 eventos por solicitud. El campo `event` de cada evento HEC contiene el JSON del +evento de auditoría, `time` es la hora del evento y `host` es el ID del nodo HA, o el ID de instancia en un +solo nodo. + +Reinicie Semaphore y compruebe que los eventos llegan como se describe [arriba](#verify-siem-delivery). + ### Cómo se entregan los eventos {#delivery} - Si el receptor no está disponible, los eventos esperan en la base de datos y se envían cuando vuelve. Los usuarios no notan nada. - Tras errores de red, reinicios o una conmutación por error en HA, algunos eventos pueden llegar dos veces. Use `event_id` para descartar duplicados y `seq` para ordenar los eventos. -- Si una conexión se corta sin error, el evento enviado en ese momento puede perderse. -- En una [instalación HA](/admin-guide/ha), un solo nodo envía eventos a la vez. Si Redis no está +- Por Syslog, si una conexión se corta sin error, el evento enviado en ese momento puede perderse. +- En una [instalación HA](/admin-guide/ha), un solo nodo a la vez envía eventos a cada destino. Si Redis no está disponible, el envío se pausa y los eventos se siguen registrando. +- Por HEC, un evento se considera enviado solo cuando el receptor responde con un estado 2xx. Cualquier otra + respuesta, incluida 4xx, se reintenta. Si el receptor falla después de responder, pueden perderse los + eventos que aún no había guardado. -Cada evento se envía como un mensaje Syslog RFC 5424 con el JSON del evento como cuerpo. `HOSTNAME` es el ID +Por Syslog, cada evento se envía como un mensaje Syslog RFC 5424 con el JSON del evento como cuerpo. `HOSTNAME` es el ID del nodo HA, o el ID de instancia en un solo nodo, y `MSGID` es el código del evento. Los ejemplos siguientes son mínimos y solo muestran cómo recibir los eventos. Aceptan conexiones de cualquier @@ -240,16 +286,43 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Ejemplo de Vector con HEC {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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" +``` + +### Ejemplo de Splunk {#splunk} + +Cree un token HEC en Splunk (**Settings → Data inputs → HTTP Event Collector**), permítale el índice +`security` y defina `url` como `https://:8088/services/collector/event`. Para encontrar los eventos, +busque `index=security sourcetype="semaphore:audit"`. + +Deje desactivada la opción **Enable indexer acknowledgement** en este token: Semaphore no la usa. + ### Solucionar problemas de exportación {#troubleshoot-export} -- **Semaphore no arranca.** Compruebe que `audit.syslog.id` y `audit.syslog.address` están definidos y que - el archivo de la CA contiene certificados PEM. +- **Semaphore no arranca.** Compruebe que `audit.syslog.id` y `audit.syslog.address` están definidos, o + `audit.splunk_hec.id`, `url` y `token` para HEC, y que el archivo de la CA contiene certificados PEM. - **La conexión TLS falla.** Compruebe que el certificado del receptor coincide con `server_name` y está firmado por una CA en la que Semaphore confía. - **Los eventos no llegan.** Revise el registro del servidor de Semaphore y el registro del receptor. Tras un fallo, Semaphore espera un poco antes de volver a intentarlo. - **Algunos eventos llegan dos veces.** Puede ocurrir tras reintentos y conmutaciones. Descarte los duplicados por `event_id`. +- **HEC responde 400, 401 o 403.** Compruebe el token, los índices en los que tiene permiso de escritura y que la confirmación del indexador esté desactivada. El token nunca aparece en el registro de Semaphore. ## Qué no se registra {#not-recorded} diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/fr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 624f76ee..a6491c15 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Journal d'audit -description: Activez le journal d'audit pour savoir qui a fait quoi dans Semaphore, et envoyez les événements d'audit de Semaphore Pro vers un SIEM. +description: Activez le journal d'audit pour savoir qui a fait quoi dans Semaphore, et envoyez les événements d'audit de Semaphore Pro vers un SIEM via Syslog ou HEC. --- # Journal d'audit @@ -125,8 +125,10 @@ Le journal d'audit ne gêne jamais vos utilisateurs. Si un événement ne peut p ## Exporter vers un SIEM {#siem-export} -Semaphore Pro peut envoyer les événements d'audit à un récepteur Syslog via TLS, comme rsyslog ou Vector. Le -récepteur peut les stocker ou les transmettre à votre SIEM. +Semaphore Pro peut envoyer les événements d'audit à un récepteur Syslog via TLS, comme rsyslog ou Vector, et à +tout récepteur du protocole Splunk HTTP Event Collector (HEC), comme Splunk, Vector, Fluent Bit, +l'OpenTelemetry Collector ou Cribl. Vous pouvez configurer une destination Syslog et une destination HEC, ou +les deux à la fois. Il vous faut : @@ -180,17 +182,62 @@ Semaphore enregistre un événement à chaque démarrage. Après le redémarrage `event_code` vaut `audit.lifecycle`, `action` vaut `start` et `metadata.destinations` contient l'ID de votre destination. +### Envoyer les événements via HEC {#hec} + +Il vous faut l'URL du point de terminaison HEC, un jeton HEC, un nom pour cette destination, par exemple +`security-hec`, et le certificat de l'autorité de certification du récepteur si l'hôte Semaphore ne lui fait +pas déjà confiance. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +Ou avec des variables d'environnement : + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` et `token` sont obligatoires, et l'URL doit commencer par `https://`. Utilisez un `id` différent de +celui de Syslog. `source` et `sourcetype` valent par défaut `semaphore` et `semaphore:audit`. Les certificats +sont vérifiés comme pour Syslog, et les variables standard `HTTPS_PROXY` et `NO_PROXY` s'appliquent. + +Semaphore envoie jusqu'à 100 événements par requête. Le champ `event` de chaque événement HEC contient le JSON +de l'événement d'audit, `time` est l'heure de l'événement et `host` est l'ID du nœud HA, ou l'ID d'instance +sur un seul nœud. + +Redémarrez Semaphore, puis vérifiez que les événements arrivent comme décrit [plus haut](#verify-siem-delivery). + ### Comment les événements sont livrés {#delivery} - Si le récepteur est indisponible, les événements attendent dans la base de données et sont envoyés à son retour. Les utilisateurs ne remarquent rien. - Après des erreurs réseau, des redémarrages ou une bascule HA, certains événements peuvent arriver en double. Utilisez `event_id` pour écarter les doublons et `seq` pour remettre les événements dans l'ordre. -- Si une connexion se coupe sans erreur, l'événement envoyé à ce moment-là peut être perdu. -- Dans une [installation HA](/admin-guide/ha), un seul nœud envoie les événements à la fois. Si Redis est +- Avec Syslog, si une connexion se coupe sans erreur, l'événement envoyé à ce moment-là peut être perdu. +- Dans une [installation HA](/admin-guide/ha), un seul nœud à la fois envoie les événements à chaque destination. Si Redis est indisponible, l'envoi est suspendu et les événements continuent d'être enregistrés. +- Avec HEC, un événement n'est considéré comme envoyé qu'après une réponse du récepteur avec un statut 2xx. + Toute autre réponse, y compris 4xx, entraîne une nouvelle tentative. Si le récepteur tombe en panne après + avoir répondu, les événements qu'il n'avait pas encore stockés peuvent être perdus. -Chaque événement est envoyé sous forme de message Syslog RFC 5424 dont le corps est le JSON de l'événement. +Avec Syslog, chaque événement est envoyé sous forme de message Syslog RFC 5424 dont le corps est le JSON de l'événement. `HOSTNAME` est l'ID du nœud HA, ou l'ID d'instance sur un seul nœud, et `MSGID` est le code de l'événement. Les exemples ci-dessous sont minimaux et montrent seulement comment recevoir les événements. Ils acceptent la @@ -244,16 +291,44 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Exemple Vector avec HEC {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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" +``` + +### Exemple Splunk {#splunk} + +Créez un jeton HEC dans Splunk (**Settings → Data inputs → HTTP Event Collector**), autorisez-lui l'index +`security` et définissez `url` sur `https://:8088/services/collector/event`. Pour retrouver les +événements, recherchez `index=security sourcetype="semaphore:audit"`. + +Laissez **Enable indexer acknowledgement** désactivé pour ce jeton : Semaphore ne l'utilise pas. + ### Résoudre les problèmes d'export {#troubleshoot-export} -- **Semaphore ne démarre pas.** Vérifiez que `audit.syslog.id` et `audit.syslog.address` sont définis et - que le fichier de l'autorité de certification contient des certificats PEM. +- **Semaphore ne démarre pas.** Vérifiez que `audit.syslog.id` et `audit.syslog.address` sont définis, ou + `audit.splunk_hec.id`, `url` et `token` pour HEC, et que le fichier de l'autorité de certification contient + des certificats PEM. - **La connexion TLS échoue.** Vérifiez que le certificat du récepteur correspond à `server_name` et qu'il est signé par une autorité de certification en laquelle Semaphore a confiance. - **Les événements n'arrivent pas.** Consultez le journal du serveur Semaphore et celui du récepteur. Après un échec, Semaphore attend un peu avant de réessayer. - **Certains événements arrivent en double.** Cela peut arriver après des nouvelles tentatives et des bascules. Écartez les doublons grâce à `event_id`. +- **HEC répond 400, 401 ou 403.** Vérifiez le jeton, les index dans lesquels il peut écrire, et que l'accusé de réception de l'indexeur est désactivé pour lui. Le jeton n'apparaît jamais dans le journal de Semaphore. ## Ce qui n'est pas enregistré {#not-recorded} diff --git a/i18n/it/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/it/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 0538dc7f..549ae826 100644 --- a/i18n/it/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/it/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Log di audit -description: Attiva il log di audit per vedere chi ha fatto cosa in Semaphore e invia gli eventi di audit da Semaphore Pro a un SIEM. +description: Attiva il log di audit per vedere chi ha fatto cosa in Semaphore e invia gli eventi di audit da Semaphore Pro a un SIEM tramite Syslog o HEC. --- # Log di audit @@ -122,8 +122,10 @@ errore nel log del server e l'azione prosegue normalmente. ## Esportare verso un SIEM {#siem-export} -Semaphore Pro può inviare gli eventi di audit a un ricevitore Syslog tramite TLS, come rsyslog o Vector. Il -ricevitore può salvarli o inoltrarli al tuo SIEM. +Semaphore Pro può inviare gli eventi di audit a un ricevitore Syslog tramite TLS, come rsyslog o Vector, e a +qualsiasi ricevitore del protocollo Splunk HTTP Event Collector (HEC), come Splunk, Vector, Fluent Bit, +l'OpenTelemetry Collector o Cribl. Puoi configurare una destinazione Syslog e una HEC, oppure entrambe +insieme. Ti servono: @@ -175,17 +177,61 @@ avvia. Semaphore registra un evento a ogni avvio. Dopo il riavvio, cercalo sul ricevitore: `event_code` è `audit.lifecycle`, `action` è `start` e `metadata.destinations` include l'ID della tua destinazione. +### Inviare eventi tramite HEC {#hec} + +Ti servono l'URL dell'endpoint HEC, un token HEC, un nome per questa destinazione, ad esempio `security-hec`, +e il certificato della CA del ricevitore se l'host di Semaphore non si fida già di essa. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +Oppure con le variabili d'ambiente: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` e `token` sono obbligatori e l'URL deve iniziare con `https://`. Usa un `id` diverso da quello di +Syslog. `source` e `sourcetype` hanno come valori predefiniti `semaphore` e `semaphore:audit`. I certificati +vengono verificati come per Syslog e valgono le variabili standard `HTTPS_PROXY` e `NO_PROXY`. + +Semaphore invia fino a 100 eventi per richiesta. Il campo `event` di ogni evento HEC contiene il JSON +dell'evento di audit, `time` è l'ora dell'evento e `host` è l'ID del nodo HA, oppure l'ID dell'istanza su un +singolo nodo. + +Riavvia Semaphore, poi controlla che gli eventi arrivino come descritto [sopra](#verify-siem-delivery). + ### Come vengono consegnati gli eventi {#delivery} - Se il ricevitore non è disponibile, gli eventi attendono nel database e vengono inviati quando torna. Gli utenti non si accorgono di nulla. - Dopo errori di rete, riavvii o un failover HA, alcuni eventi possono arrivare due volte. Usa `event_id` per scartare i duplicati e `seq` per ordinare gli eventi. -- Se una connessione si interrompe senza errori, l'evento inviato in quel momento può andare perso. -- In un'[installazione HA](/admin-guide/ha), un solo nodo alla volta invia gli eventi. Se Redis non è +- Con Syslog, se una connessione si interrompe senza errori, l'evento inviato in quel momento può andare perso. +- In un'[installazione HA](/admin-guide/ha), un solo nodo alla volta invia gli eventi a ogni destinazione. Se Redis non è disponibile, l'invio si ferma e gli eventi continuano a essere registrati. +- Con HEC, un evento conta come inviato solo dopo che il ricevitore risponde con uno stato 2xx. Qualsiasi altra + risposta, compresa 4xx, viene ritentata. Se il ricevitore si blocca dopo aver risposto, gli eventi che non + aveva ancora salvato possono andare persi. -Ogni evento viene inviato come messaggio Syslog RFC 5424 con il JSON dell'evento come corpo. `HOSTNAME` è +Con Syslog, ogni evento viene inviato come messaggio Syslog RFC 5424 con il JSON dell'evento come corpo. `HOSTNAME` è l'ID del nodo HA, oppure l'ID dell'istanza su un singolo nodo, e `MSGID` è il codice dell'evento. Gli esempi seguenti sono minimi e mostrano solo come ricevere gli eventi. Accettano connessioni da qualsiasi @@ -240,16 +286,44 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Esempio Vector con HEC {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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" +``` + +### Esempio Splunk {#splunk} + +Crea un token HEC in Splunk (**Settings → Data inputs → HTTP Event Collector**), consenti l'indice `security` +per il token e imposta `url` su `https://:8088/services/collector/event`. Per trovare gli eventi, +cerca `index=security sourcetype="semaphore:audit"`. + +Lascia disattivata l'opzione **Enable indexer acknowledgement** per questo token: Semaphore non la usa. + ### Risolvere i problemi di esportazione {#troubleshoot-export} -- **Semaphore non si avvia.** Verifica che siano impostati sia `audit.syslog.id` sia `audit.syslog.address` - e che il file della CA contenga certificati PEM. +- **Semaphore non si avvia.** Verifica che siano impostati sia `audit.syslog.id` sia `audit.syslog.address`, + oppure `audit.splunk_hec.id`, `url` e `token` per HEC, e che il file della CA contenga certificati PEM. - **La connessione TLS non riesce.** Verifica che il certificato del ricevitore corrisponda a `server_name` e sia firmato da una CA considerata attendibile da Semaphore. - **Gli eventi non arrivano.** Controlla il log del server di Semaphore e il log del ricevitore. Dopo un errore, Semaphore attende un po' prima di riprovare. - **Alcuni eventi arrivano due volte.** Può succedere dopo tentativi ripetuti e failover. Scarta i duplicati tramite `event_id`. +- **HEC risponde 400, 401 o 403.** Controlla il token, gli indici in cui può scrivere e che la conferma dell'indexer sia disattivata. Il token non compare mai + nel log di Semaphore. ## Cosa non viene registrato {#not-recorded} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/ja/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index c59d80df..44dda7bd 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: 監査ログ -description: 監査ログを有効にして Semaphore で誰が何をしたかを確認し、Semaphore Pro から監査イベントを SIEM に送信します。 +description: 監査ログを有効にして Semaphore で誰が何をしたかを確認し、Semaphore Pro から監査イベントを Syslog または HEC で SIEM に送信します。 --- # 監査ログ @@ -94,7 +94,7 @@ SEMAPHORE_AUDIT_TRUSTED_PROXY_CIDRS='["10.0.0.0/8"]' ## SIEM にエクスポートする {#siem-export} -Semaphore Pro は、rsyslog や Vector などの Syslog レシーバーに TLS で監査イベントを送信できます。レシーバーはイベントを保存したり、SIEM に転送したりできます。 +Semaphore Pro は、rsyslog や Vector などの Syslog レシーバーに TLS で監査イベントを送信できるほか、Splunk、Vector、Fluent Bit、OpenTelemetry Collector、Cribl など、Splunk HTTP Event Collector (HEC) プロトコルに対応する任意のレシーバーにも送信できます。Syslog と HEC の送信先をそれぞれ 1 つずつ、または両方を同時に設定できます。 必要なもの: @@ -140,14 +140,51 @@ Semaphore を再起動します。設定が無効な場合や CA ファイルを Semaphore は起動のたびにイベントを記録します。再起動後、レシーバーでそのイベントを探してください。`event_code` が `audit.lifecycle`、`action` が `start` で、`metadata.destinations` に送信先の ID が含まれています。 +### HEC でイベントを送信する {#hec} + +HEC エンドポイントの URL、HEC トークン、この送信先の名前(例: `security-hec`)、そして Semaphore ホストがまだ信頼していない場合はレシーバーの CA 証明書が必要です。 + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +環境変数を使う場合: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`、`url`、`token` は必須で、URL は `https://` で始まる必要があります。`id` は Syslog とは別の値にしてください。`source` と `sourcetype` の既定値は `semaphore` と `semaphore:audit` です。証明書は Syslog と同じ方法で検証され、標準の `HTTPS_PROXY` と `NO_PROXY` 環境変数が適用されます。 + +Semaphore は 1 回のリクエストで最大 100 件のイベントを送信します。各 HEC イベントの `event` フィールドには監査イベントの JSON が入り、`time` はイベントの時刻、`host` は HA ノード ID(単一ノードではインスタンス ID)です。 + +Semaphore を再起動し、[上記](#verify-siem-delivery)のとおりイベントが届くことを確認してください。 + ### イベントの配信方法 {#delivery} - レシーバーが停止している間、イベントはデータベースで待機し、復旧すると送信されます。ユーザーは何も気付きません。 - ネットワークエラー、再起動、HA のフェイルオーバーの後は、一部のイベントが二重に届くことがあります。`event_id` で重複を取り除き、`seq` で順序を並べてください。 -- エラーなしで接続が切れた場合、その時点で送信したイベントが失われることがあります。 -- [HA 構成](/admin-guide/ha) では、一度に 1 つのノードがイベントを送信します。Redis が利用できない間は送信が一時停止しますが、イベントの記録は続きます。 +- Syslog では、エラーなしで接続が切れた場合、その時点で送信したイベントが失われることがあります。 +- [HA 構成](/admin-guide/ha) では、一度に 1 つのノードが、各送信先にイベントを送信します。Redis が利用できない間は送信が一時停止しますが、イベントの記録は続きます。 +- HEC では、レシーバーが 2xx ステータスで応答して初めて、イベントが送信済みとして扱われます。4xx を含むそれ以外の応答では再試行します。レシーバーが応答後にクラッシュした場合、まだ保存されていなかったイベントが失われることがあります。 -各イベントは、イベントの JSON を本文とする RFC 5424 の Syslog メッセージとして送信されます。`HOSTNAME` は HA ノード ID(単一ノードではインスタンス ID)、`MSGID` はイベントコードです。 +Syslog では、各イベントは、イベントの JSON を本文とする RFC 5424 の Syslog メッセージとして送信されます。`HOSTNAME` は HA ノード ID(単一ノードではインスタンス ID)、`MSGID` はイベントコードです。 以下の例は最小限の構成で、イベントの受信方法を示すだけです。ポートに到達できるすべてのクライアントからの接続を受け付けます。本番環境では、Semaphore サーバーだけがイベントを送信できるようにレシーバーを保護してください。 @@ -198,12 +235,37 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Vector HEC の例 {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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 の例 {#splunk} + +Splunk で HEC トークンを作成し (**Settings → Data inputs → HTTP Event Collector**)、そのトークンに `security` インデックスを許可して、`url` を `https://:8088/services/collector/event` に設定します。イベントを探すには、`index=security sourcetype="semaphore:audit"` を検索します。 + +このトークンでは **Enable indexer acknowledgement** をオフのままにしてください。Semaphore はこの機能を使いません。 + ### エクスポートのトラブルシューティング {#troubleshoot-export} -- **Semaphore が起動しない。** `audit.syslog.id` と `audit.syslog.address` の両方が設定されていること、CA ファイルに PEM 証明書が含まれていることを確認してください。 +- **Semaphore が起動しない。** `audit.syslog.id` と `audit.syslog.address` の両方が設定されていること(HEC の場合は `audit.splunk_hec.id`、`url`、`token`)、CA ファイルに PEM 証明書が含まれていることを確認してください。 - **TLS 接続に失敗する。** レシーバーの証明書が `server_name` と一致し、Semaphore が信頼する CA によって署名されていることを確認してください。 - **イベントが届かない。** Semaphore のサーバーログとレシーバーのログを確認してください。失敗した後、Semaphore は少し待ってから再試行します。 - **一部のイベントが二重に届く。** 再試行やフェイルオーバーの後に起こることがあります。`event_id` で重複を取り除いてください。 +- **HEC が 400、401 または 403 を返す。** トークン、そのトークンが書き込みを許可されているインデックス、およびそのトークンでインデクサー確認応答がオフになっていることを確認してください。トークンが Semaphore のログに表示されることはありません。 ## 記録されない操作 {#not-recorded} diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/ko/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index fb0ccbe5..d63cfab0 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/ko/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: 감사 로그 -description: 감사 로그를 켜서 Semaphore에서 누가 무엇을 했는지 확인하고, Semaphore Pro에서 감사 이벤트를 SIEM으로 보냅니다. +description: 감사 로그를 켜서 Semaphore에서 누가 무엇을 했는지 확인하고, Semaphore Pro에서 감사 이벤트를 Syslog 또는 HEC로 SIEM에 보냅니다. --- # 감사 로그 @@ -94,7 +94,7 @@ SEMAPHORE_AUDIT_TRUSTED_PROXY_CIDRS='["10.0.0.0/8"]' ## SIEM으로 내보내기 {#siem-export} -Semaphore Pro는 rsyslog나 Vector 같은 Syslog 수신기로 TLS를 통해 감사 이벤트를 보낼 수 있습니다. 수신기는 이벤트를 저장하거나 SIEM으로 전달할 수 있습니다. +Semaphore Pro는 rsyslog나 Vector 같은 Syslog 수신기로 TLS를 통해 감사 이벤트를 보낼 수 있고, Splunk, Vector, Fluent Bit, OpenTelemetry Collector, Cribl 같은 Splunk HTTP Event Collector(HEC) 프로토콜 수신기로도 보낼 수 있습니다. Syslog 대상과 HEC 대상을 각각 하나씩 설정하거나 둘 다 동시에 설정할 수 있습니다. 필요한 것: @@ -140,14 +140,51 @@ Semaphore를 다시 시작하세요. 설정이 잘못되었거나 CA 파일을 Semaphore는 시작할 때마다 이벤트를 기록합니다. 다시 시작한 후 수신기에서 해당 이벤트를 찾으세요. `event_code`는 `audit.lifecycle`, `action`은 `start`이고, `metadata.destinations`에 대상 ID가 들어 있습니다. +### HEC로 이벤트 보내기 {#hec} + +HEC 엔드포인트 URL, HEC 토큰, 이 대상의 이름(예: `security-hec`)이 필요하며, Semaphore 호스트가 수신기를 아직 신뢰하지 않는다면 수신기의 CA 인증서도 필요합니다. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +환경 변수를 사용하는 경우: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url`, `token`은 필수이며 URL은 `https://`로 시작해야 합니다. Syslog와는 다른 `id`를 사용하세요. `source`와 `sourcetype`의 기본값은 `semaphore`와 `semaphore:audit`입니다. 인증서는 Syslog와 같은 방식으로 검증되며, 표준 `HTTPS_PROXY`와 `NO_PROXY` 변수가 적용됩니다. + +Semaphore는 요청 하나에 최대 100개의 이벤트를 보냅니다. 각 HEC 이벤트의 `event` 필드에는 감사 이벤트 JSON이 들어 있고, `time`은 이벤트 시각이며, `host`는 HA 노드 ID(단일 노드에서는 인스턴스 ID)입니다. + +Semaphore를 다시 시작한 다음, [위](#verify-siem-delivery)에서 설명한 대로 이벤트가 도착하는지 확인하세요. + ### 이벤트 전달 방식 {#delivery} - 수신기가 중단되면 이벤트는 데이터베이스에서 기다렸다가 수신기가 복구되면 전송됩니다. 사용자는 아무것도 알아차리지 못합니다. - 네트워크 오류, 재시작, HA 장애 조치 후에는 일부 이벤트가 두 번 도착할 수 있습니다. `event_id`로 중복을 제거하고 `seq`로 순서를 맞추세요. -- 오류 없이 연결이 끊기면 그 순간에 보낸 이벤트가 유실될 수 있습니다. -- [HA 설치](/admin-guide/ha)에서는 한 번에 하나의 노드가 이벤트를 보냅니다. Redis를 사용할 수 없으면 전송이 일시 중지되고 이벤트 기록은 계속됩니다. +- Syslog에서는 오류 없이 연결이 끊기면 그 순간에 보낸 이벤트가 유실될 수 있습니다. +- [HA 설치](/admin-guide/ha)에서는 한 번에 하나의 노드가 각 대상에 이벤트를 보냅니다. Redis를 사용할 수 없으면 전송이 일시 중지되고 이벤트 기록은 계속됩니다. +- HEC에서는 수신기가 2xx 상태로 응답한 뒤에야 이벤트가 전송된 것으로 처리됩니다. 4xx를 포함한 다른 모든 응답은 재시도됩니다. 수신기가 응답한 뒤에 중단되면, 아직 저장하지 못한 이벤트가 유실될 수 있습니다. -각 이벤트는 이벤트 JSON을 본문으로 하는 RFC 5424 Syslog 메시지로 전송됩니다. `HOSTNAME`은 HA 노드 ID(단일 노드에서는 인스턴스 ID)이고 `MSGID`는 이벤트 코드입니다. +Syslog에서는 각 이벤트가 이벤트 JSON을 본문으로 하는 RFC 5424 Syslog 메시지로 전송됩니다. `HOSTNAME`은 HA 노드 ID(단일 노드에서는 인스턴스 ID)이고 `MSGID`는 이벤트 코드입니다. 아래 예시는 최소 구성이며 이벤트를 받는 방법만 보여 줍니다. 포트에 접근할 수 있는 모든 클라이언트의 연결을 받습니다. 운영 환경에서는 Semaphore 서버만 이벤트를 보낼 수 있도록 수신기를 보호하세요. @@ -198,12 +235,37 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Vector HEC 예시 {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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 예시 {#splunk} + +Splunk에서 HEC 토큰을 만들고(**Settings → Data inputs → HTTP Event Collector**), 토큰에 `security` 인덱스를 허용한 다음 `url`을 `https://:8088/services/collector/event`로 설정합니다. 이벤트를 찾으려면 `index=security sourcetype="semaphore:audit"`을 검색하세요. + +이 토큰에서는 **Enable indexer acknowledgement**를 꺼 두세요. Semaphore는 이 기능을 사용하지 않습니다. + ### 내보내기 문제 해결 {#troubleshoot-export} -- **Semaphore가 시작되지 않습니다.** `audit.syslog.id`와 `audit.syslog.address`가 모두 설정되어 있고 CA 파일에 PEM 인증서가 들어 있는지 확인하세요. +- **Semaphore가 시작되지 않습니다.** `audit.syslog.id`와 `audit.syslog.address`가 모두 설정되어 있는지(HEC는 `audit.splunk_hec.id`, `url`, `token`), CA 파일에 PEM 인증서가 들어 있는지 확인하세요. - **TLS 연결이 실패합니다.** 수신기의 인증서가 `server_name`과 일치하고 Semaphore가 신뢰하는 CA가 서명했는지 확인하세요. - **이벤트가 도착하지 않습니다.** Semaphore 서버 로그와 수신기 로그를 확인하세요. 실패 후 Semaphore는 잠시 기다렸다가 다시 시도합니다. - **일부 이벤트가 두 번 도착합니다.** 재시도와 장애 조치 후에 생길 수 있습니다. `event_id`로 중복을 제거하세요. +- **HEC가 400, 401 또는 403으로 응답합니다.** 토큰, 토큰이 쓸 수 있는 인덱스, 그리고 토큰에서 인덱서 확인 응답이 꺼져 있는지 확인하세요. 토큰은 Semaphore 로그에 나타나지 않습니다. ## 기록되지 않는 작업 {#not-recorded} diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/pt/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 02cc30e7..48e9db1c 100644 --- a/i18n/pt/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/pt/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Log de auditoria -description: Ative o log de auditoria para ver quem fez o quê no Semaphore e envie eventos de auditoria do Semaphore Pro para um SIEM. +description: Ative o log de auditoria para ver quem fez o quê no Semaphore e envie eventos de auditoria do Semaphore Pro para um SIEM por Syslog ou HEC. --- # Log de auditoria @@ -121,8 +121,9 @@ erro no log do servidor e a ação continua normalmente. ## Exportar para um SIEM {#siem-export} -O Semaphore Pro pode enviar eventos de auditoria para um receptor Syslog via TLS, como rsyslog ou Vector. O -receptor pode armazená-los ou repassá-los para o seu SIEM. +O Semaphore Pro pode enviar eventos de auditoria para um receptor Syslog via TLS, como rsyslog ou Vector, e +para qualquer receptor do protocolo Splunk HTTP Event Collector (HEC), como Splunk, Vector, Fluent Bit, o +OpenTelemetry Collector ou Cribl. Você pode configurar um destino Syslog e um HEC, ou ambos ao mesmo tempo. Você vai precisar de: @@ -173,17 +174,60 @@ Semaphore não inicia. O Semaphore registra um evento sempre que inicia. Após reiniciar, procure-o no receptor: `event_code` é `audit.lifecycle`, `action` é `start` e `metadata.destinations` inclui o ID do seu destino. +### Enviar eventos por HEC {#hec} + +Você vai precisar da URL do endpoint HEC, de um token HEC, de um nome para este destino, como `security-hec`, +e do certificado da CA do receptor, caso o host do Semaphore ainda não confie nela. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +Ou usando variáveis de ambiente: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` e `token` são obrigatórios, e a URL deve começar com `https://`. Use um `id` diferente do usado +no Syslog. `source` e `sourcetype` têm como padrão `semaphore` e `semaphore:audit`. Os certificados são +verificados do mesmo modo que no Syslog, e as variáveis padrão `HTTPS_PROXY` e `NO_PROXY` se aplicam. + +O Semaphore envia até 100 eventos por requisição. O campo `event` de cada evento HEC contém o JSON do evento +de auditoria, `time` é a hora do evento e `host` é o ID do nó HA, ou o ID da instância em um único nó. + +Reinicie o Semaphore e verifique se os eventos chegam como descrito [acima](#verify-siem-delivery). + ### Como os eventos são entregues {#delivery} - Se o receptor estiver fora do ar, os eventos aguardam no banco de dados e são enviados quando ele voltar. Os usuários não percebem nada. - Após erros de rede, reinicializações ou um failover de HA, alguns eventos podem chegar duas vezes. Use `event_id` para descartar duplicatas e `seq` para ordenar os eventos. -- Se uma conexão cair sem erro, o evento enviado naquele momento pode ser perdido. -- Em uma [instalação HA](/admin-guide/ha), um nó por vez envia os eventos. Se o Redis estiver indisponível, +- Por Syslog, se uma conexão cair sem erro, o evento enviado naquele momento pode ser perdido. +- Em uma [instalação HA](/admin-guide/ha), um nó por vez envia os eventos a cada destino. Se o Redis estiver indisponível, o envio pausa e os eventos continuam sendo registrados. +- Por HEC, um evento só conta como enviado depois que o receptor responde com um status 2xx. Qualquer outra + resposta, incluindo 4xx, é tentada de novo. Se o receptor falhar depois de responder, eventos que ele ainda + não tinha armazenado podem ser perdidos. -Cada evento é enviado como uma mensagem Syslog RFC 5424 com o JSON do evento como corpo. `HOSTNAME` é o ID +Por Syslog, cada evento é enviado como uma mensagem Syslog RFC 5424 com o JSON do evento como corpo. `HOSTNAME` é o ID do nó HA, ou o ID da instância em um único nó, e `MSGID` é o código do evento. Os exemplos abaixo são mínimos e mostram apenas como receber os eventos. Eles aceitam conexões de qualquer @@ -237,16 +281,44 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Exemplo de Vector com HEC {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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" +``` + +### Exemplo de Splunk {#splunk} + +Crie um token HEC no Splunk (**Settings → Data inputs → HTTP Event Collector**), permita o índice `security` +para ele e defina `url` como `https://:8088/services/collector/event`. Para encontrar os eventos, +pesquise por `index=security sourcetype="semaphore:audit"`. + +Deixe **Enable indexer acknowledgement** desativado para este token: o Semaphore não o usa. + ### Solucionar problemas de exportação {#troubleshoot-export} -- **O Semaphore não inicia.** Verifique se `audit.syslog.id` e `audit.syslog.address` estão definidos e se - o arquivo da CA contém certificados PEM. +- **O Semaphore não inicia.** Verifique se `audit.syslog.id` e `audit.syslog.address` estão definidos, ou + `audit.splunk_hec.id`, `url` e `token` no caso do HEC, e se o arquivo da CA contém certificados PEM. - **A conexão TLS falha.** Verifique se o certificado do receptor corresponde a `server_name` e se foi assinado por uma CA em que o Semaphore confia. - **Os eventos não chegam.** Verifique o log do servidor do Semaphore e o log do receptor. Após uma falha, o Semaphore espera um pouco antes de tentar de novo. - **Alguns eventos chegam duas vezes.** Isso pode acontecer após novas tentativas e failovers. Descarte duplicatas pelo `event_id`. +- **O HEC responde 400, 401 ou 403.** Verifique o token, os índices nos quais ele pode gravar e se a confirmação do indexador está desativada para ele. O token nunca + aparece no log do Semaphore. ## O que não é registrado {#not-recorded} diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/ru/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 5e5b2cf6..b0dfbf9e 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Журнал аудита -description: Включите журнал аудита, чтобы видеть, кто что сделал в Semaphore, и отправляйте события аудита из Semaphore Pro в SIEM. +description: Включите журнал аудита, чтобы видеть, кто что сделал в Semaphore, и отправляйте события аудита из Semaphore Pro в SIEM по Syslog или HEC. --- # Журнал аудита @@ -117,8 +117,9 @@ SEMAPHORE_AUDIT_TRUSTED_PROXY_CIDRS='["10.0.0.0/8"]' ## Экспорт в SIEM {#siem-export} -Semaphore Pro может отправлять события аудита в приёмник Syslog по TLS, например rsyslog или Vector. -Приёмник может сохранять их или передавать дальше в ваш SIEM. +Semaphore Pro может отправлять события аудита в приёмник Syslog по TLS, например rsyslog или Vector, и в +любой приёмник протокола Splunk HTTP Event Collector (HEC), например Splunk, Vector, Fluent Bit, +OpenTelemetry Collector или Cribl. Можно настроить одно назначение Syslog и одно HEC или оба сразу. Вам понадобятся: @@ -168,17 +169,60 @@ Semaphore всегда проверяет сертификат приёмник Semaphore записывает событие при каждом запуске. После перезапуска найдите его в приёмнике: `event_code` равен `audit.lifecycle`, `action` — `start`, а `metadata.destinations` содержит ID вашего назначения. +### Отправка событий по HEC {#hec} + +Понадобятся URL конечной точки HEC, токен HEC, имя для этого назначения, например `security-hec`, и +CA-сертификат приёмника, если хост Semaphore ещё не доверяет ему. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +Или с помощью переменных окружения: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` и `token` обязательны, а URL должен начинаться с `https://`. Используйте `id`, отличный от +`id` для Syslog. По умолчанию `source` равен `semaphore`, а `sourcetype` — `semaphore:audit`. Сертификаты +проверяются так же, как для Syslog, и действуют стандартные переменные `HTTPS_PROXY` и `NO_PROXY`. + +Semaphore отправляет до 100 событий в одном запросе. Поле `event` каждого события HEC содержит JSON события +аудита, `time` — время события, а `host` — ID узла HA или ID установки на одном узле. + +Перезапустите Semaphore и проверьте, что события приходят, как описано [выше](#verify-siem-delivery). + ### Как доставляются события {#delivery} - Если приёмник недоступен, события ждут в базе данных и отправляются, когда он вернётся. Пользователи ничего не заметят. - После сетевых ошибок, перезапусков или переключения узлов HA некоторые события могут прийти дважды. Используйте `event_id`, чтобы отбросить дубликаты, и `seq`, чтобы восстановить порядок. -- Если соединение оборвётся без ошибки, событие, отправленное в этот момент, может потеряться. -- В [установке HA](/admin-guide/ha) события отправляет один узел за раз. Если Redis недоступен, отправка +- При отправке по Syslog, если соединение оборвётся без ошибки, событие, отправленное в этот момент, может потеряться. +- В [установке HA](/admin-guide/ha) в каждое назначение события отправляет один узел за раз. Если Redis недоступен, отправка приостанавливается, а события продолжают записываться. +- По HEC событие считается отправленным, только когда приёмник ответил статусом 2xx. Любой другой ответ, в том + числе 4xx, приводит к повторной попытке. Если приёмник аварийно завершится после ответа, события, которые он + ещё не сохранил, могут потеряться. -Каждое событие отправляется как сообщение Syslog RFC 5424, телом которого служит JSON события. `HOSTNAME` — +По Syslog каждое событие отправляется как сообщение Syslog RFC 5424, телом которого служит JSON события. `HOSTNAME` — ID узла HA или ID установки на одном узле, а `MSGID` — код события. Примеры ниже минимальны и показывают только, как принимать события. Они принимают подключение от любого @@ -232,16 +276,43 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Пример Vector с HEC {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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 {#splunk} + +Создайте в Splunk токен HEC (**Settings → Data inputs → HTTP Event Collector**), разрешите ему индекс +`security` и задайте `url` равным `https://:8088/services/collector/event`. Чтобы найти события, +выполните поиск `index=security sourcetype="semaphore:audit"`. + +Оставьте для этого токена выключенной опцию **Enable indexer acknowledgement**: Semaphore её не использует. + ### Устранение неполадок экспорта {#troubleshoot-export} -- **Semaphore не запускается.** Проверьте, что заданы и `audit.syslog.id`, и `audit.syslog.address`, а - файл CA содержит сертификаты PEM. +- **Semaphore не запускается.** Проверьте, что заданы и `audit.syslog.id`, и `audit.syslog.address` (для HEC — + `audit.splunk_hec.id`, `url` и `token`), а файл CA содержит сертификаты PEM. - **TLS-соединение не устанавливается.** Проверьте, что сертификат приёмника соответствует `server_name` и подписан CA, которому доверяет Semaphore. - **События не приходят.** Проверьте серверный журнал Semaphore и журнал приёмника. После сбоя Semaphore немного ждёт перед следующей попыткой. - **Некоторые события приходят дважды.** Так бывает после повторных попыток и переключений узлов. Отбрасывайте дубликаты по `event_id`. +- **HEC отвечает 400, 401 или 403.** Проверьте токен, индексы, в которые ему разрешена запись, и что подтверждение индексатора для него выключено. Токен никогда не попадает в журнал Semaphore. ## Что не записывается {#not-recorded} diff --git a/i18n/sr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/sr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 875b1dbd..b7ed4ccf 100644 --- a/i18n/sr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/sr/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: Dnevnik revizije -description: Uključite dnevnik revizije da biste videli ko je šta uradio u Semaphore-u i šaljite događaje revizije iz Semaphore Pro u SIEM. +description: Uključite dnevnik revizije da biste videli ko je šta uradio u Semaphore-u i šaljite događaje revizije iz Semaphore Pro u SIEM preko Syslog-a ili HEC-a. --- # Dnevnik revizije @@ -118,7 +118,9 @@ grešku u dnevnik servera, a radnja se nastavlja kao i obično. ## Izvoz u SIEM {#siem-export} Semaphore Pro može da šalje događaje revizije Syslog prijemniku preko TLS-a, na primer rsyslog-u ili -Vector-u. Prijemnik može da ih čuva ili prosleđuje vašem SIEM-u. +Vector-u, kao i svakom prijemniku protokola Splunk HTTP Event Collector (HEC), na primer Splunk-u, Vector-u, +Fluent Bit-u, OpenTelemetry Collector-u ili Cribl-u. Možete podesiti jedno Syslog i jedno HEC odredište, ili +oba odjednom. Biće vam potrebni: @@ -170,17 +172,60 @@ Semaphore beleži događaj pri svakom pokretanju. Posle ponovnog pokretanja potr `event_code` je `audit.lifecycle`, `action` je `start`, a `metadata.destinations` sadrži ID vašeg odredišta. +### Slanje događaja preko HEC-a {#hec} + +Potrebni su vam URL HEC krajnje tačke, HEC token, naziv ovog odredišta, na primer `security-hec`, i +sertifikat CA prijemnika ako mu host Semaphore-a već ne veruje. + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +Ili pomoću promenljivih okruženja: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`, `url` i `token` su obavezni, a URL mora da počinje sa `https://`. Koristite drugačiji `id` nego za +Syslog. `source` i `sourcetype` imaju podrazumevane vrednosti `semaphore` i `semaphore:audit`. Sertifikati se +proveravaju na isti način kao za Syslog, a važe standardne promenljive `HTTPS_PROXY` i `NO_PROXY`. + +Semaphore šalje do 100 događaja po zahtevu. Polje `event` svakog HEC događaja sadrži JSON događaja revizije, +`time` je vreme događaja, a `host` je ID HA čvora, ili ID instance na jednom čvoru. + +Ponovo pokrenite Semaphore, a zatim proverite da događaji stižu kako je opisano [iznad](#verify-siem-delivery). + ### Kako se događaji isporučuju {#delivery} - Ako prijemnik nije dostupan, događaji čekaju u bazi podataka i šalju se kada se vrati. Korisnici ništa ne primećuju. - Posle mrežnih grešaka, ponovnih pokretanja ili HA failover-a neki događaji mogu stići dvaput. Koristite `event_id` da odbacite duplikate i `seq` da poređate događaje. -- Ako se veza prekine bez greške, događaj poslat u tom trenutku može da se izgubi. -- U [HA instalaciji](/admin-guide/ha) događaje šalje jedan po jedan čvor. Ako Redis nije dostupan, slanje se +- Preko Syslog-a, ako se veza prekine bez greške, događaj poslat u tom trenutku može da se izgubi. +- U [HA instalaciji](/admin-guide/ha) događaje svakom odredištu šalje jedan po jedan čvor. Ako Redis nije dostupan, slanje se pauzira, a događaji se i dalje beleže. +- Preko HEC-a se događaj smatra poslatim tek kada prijemnik odgovori statusom 2xx. Svaki drugi odgovor, + uključujući 4xx, ponavlja se. Ako prijemnik padne nakon odgovora, događaji koje još nije sačuvao mogu da se + izgube. -Svaki događaj se šalje kao Syslog poruka po RFC 5424 sa JSON-om događaja kao telom. `HOSTNAME` je ID HA +Preko Syslog-a se svaki događaj šalje kao Syslog poruka po RFC 5424 sa JSON-om događaja kao telom. `HOSTNAME` je ID HA čvora, ili ID instance na jednom čvoru, a `MSGID` je kôd događaja. Primeri u nastavku su minimalni i samo pokazuju kako se primaju događaji. Prihvataju vezu od bilo kog klijenta @@ -234,16 +279,44 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Primer za Vector sa HEC-om {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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" +``` + +### Primer za Splunk {#splunk} + +Napravite HEC token u Splunk-u (**Settings → Data inputs → HTTP Event Collector**), dozvolite mu indeks +`security` i podesite `url` na `https://:8088/services/collector/event`. Da biste pronašli događaje, +pretražite `index=security sourcetype="semaphore:audit"`. + +Ostavite **Enable indexer acknowledgement** isključeno za ovaj token: Semaphore ga ne koristi. + ### Rešavanje problema sa izvozom {#troubleshoot-export} -- **Semaphore se ne pokreće.** Proverite da su podešeni i `audit.syslog.id` i `audit.syslog.address` i da - CA datoteka sadrži PEM sertifikate. +- **Semaphore se ne pokreće.** Proverite da su podešeni i `audit.syslog.id` i `audit.syslog.address`, ili + `audit.splunk_hec.id`, `url` i `token` za HEC, i da CA datoteka sadrži PEM sertifikate. - **TLS veza ne uspeva.** Proverite da sertifikat prijemnika odgovara `server_name` i da ga je potpisao CA kome Semaphore veruje. - **Događaji ne stižu.** Proverite dnevnik servera Semaphore-a i dnevnik prijemnika. Posle greške Semaphore malo sačeka pre ponovnog pokušaja. - **Neki događaji stižu dvaput.** To se može desiti posle ponovljenih pokušaja i failover-a. Odbacite duplikate prema `event_id`. +- **HEC odgovara sa 400, 401 ili 403.** Proverite token, indekse u koje sme da piše i da je potvrda indeksera za njega isključena. Token se nikada ne pojavljuje + u dnevniku Semaphore-a. ## Šta se ne beleži {#not-recorded} diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md b/i18n/zh/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md index 51de90de..3020a14d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/admin-guide/audit-log.md @@ -1,6 +1,6 @@ --- title: 审计日志 -description: 启用审计日志,查看谁在 Semaphore 中做了什么,并将审计事件从 Semaphore Pro 发送到 SIEM。 +description: 启用审计日志,查看谁在 Semaphore 中做了什么,并将审计事件从 Semaphore Pro 通过 Syslog 或 HEC 发送到 SIEM。 --- # 审计日志 @@ -94,7 +94,7 @@ SEMAPHORE_AUDIT_TRUSTED_PROXY_CIDRS='["10.0.0.0/8"]' ## 导出到 SIEM {#siem-export} -Semaphore Pro 可以通过 TLS 将审计事件发送到 Syslog 接收器,例如 rsyslog 或 Vector。接收器可以存储这些事件,也可以转发给你的 SIEM。 +Semaphore Pro 可以通过 TLS 将审计事件发送到 Syslog 接收器,例如 rsyslog 或 Vector,也可以发送到任何支持 Splunk HTTP Event Collector (HEC) 协议的接收器,例如 Splunk、Vector、Fluent Bit、OpenTelemetry Collector 或 Cribl。你可以分别设置一个 Syslog 目标和一个 HEC 目标,也可以同时设置两个。 你需要准备: @@ -140,14 +140,51 @@ Semaphore 始终验证接收器的证书,并使用 TLS 1.2 或更高版本。` Semaphore 每次启动时都会记录一个事件。重启后,在接收器中查找它:`event_code` 为 `audit.lifecycle`,`action` 为 `start`,`metadata.destinations` 中包含你的目标 ID。 +### 通过 HEC 发送事件 {#hec} + +你需要 HEC 端点 URL、HEC 令牌、此目标的名称(例如 `security-hec`),以及接收器的 CA 证书(如果 Semaphore 主机尚未信任它)。 + +```json +{ + "audit": { + "enabled": true, + "instance_id": "prod-eu", + "splunk_hec": { + "id": "security-hec", + "url": "https://splunk.example.com:8088/services/collector/event", + "token": "", + "index": "security", + "ca_file": "/etc/semaphore/siem-ca.pem" + } + } +} +``` + +或使用环境变量: + +```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='' +SEMAPHORE_AUDIT_SPLUNK_HEC_INDEX=security +SEMAPHORE_AUDIT_SPLUNK_HEC_CA_FILE=/etc/semaphore/siem-ca.pem +``` + +`id`、`url` 和 `token` 为必填项,URL 必须以 `https://` 开头。请使用与 Syslog 不同的 `id`。`source` 和 `sourcetype` 默认为 `semaphore` 和 `semaphore:audit`。证书的检查方式与 Syslog 相同,并且标准的 `HTTPS_PROXY` 和 `NO_PROXY` 变量同样适用。 + +Semaphore 每个请求最多发送 100 个事件。每个 HEC 事件的 `event` 字段包含审计事件 JSON,`time` 是事件时间,`host` 是 HA 节点 ID(单节点时为实例 ID)。 + +重启 Semaphore,然后按[上文](#verify-siem-delivery)所述确认事件已送达。 + ### 事件的投递方式 {#delivery} - 如果接收器不可用,事件会在数据库中等待,待接收器恢复后再发送。用户不会察觉到任何变化。 - 在网络错误、重启或 HA 故障转移之后,部分事件可能会到达两次。使用 `event_id` 去除重复事件,使用 `seq` 排列事件顺序。 -- 如果连接在没有报错的情况下中断,当时发送的事件可能会丢失。 -- 在 [HA 安装](/admin-guide/ha) 中,同一时间只有一个节点发送事件。如果 Redis 不可用,发送会暂停,但事件仍会继续记录。 +- 通过 Syslog 发送时,如果连接在没有报错的情况下中断,当时发送的事件可能会丢失。 +- 在 [HA 安装](/admin-guide/ha) 中,同一时间只有一个节点向每个目标发送事件。如果 Redis 不可用,发送会暂停,但事件仍会继续记录。 +- 通过 HEC 发送时,只有接收器返回 2xx 状态后,事件才算已发送。任何其他响应(包括 4xx)都会重试。如果接收器在响应后崩溃,尚未存储的事件可能会丢失。 -每个事件都以 RFC 5424 Syslog 消息发送,消息正文为事件 JSON。`HOSTNAME` 是 HA 节点 ID(单节点时为实例 ID),`MSGID` 是事件代码。 +通过 Syslog 发送时,每个事件都以 RFC 5424 Syslog 消息发送,消息正文为事件 JSON。`HOSTNAME` 是 HA 节点 ID(单节点时为实例 ID),`MSGID` 是事件代码。 以下示例是最简配置,仅演示如何接收事件。它们接受任何能访问该端口的客户端的连接。在生产环境中,请保护接收端,确保只有你的 Semaphore 服务器能向其发送事件。 @@ -198,12 +235,37 @@ path = "/var/log/semaphore-audit.json" encoding.codec = "json" ``` +### Vector HEC 示例 {#vector-hec} + +```toml +[sources.semaphore_audit_hec] +type = "splunk_hec" +address = "0.0.0.0:8088" +valid_tokens = [""] +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 示例 {#splunk} + +在 Splunk 中创建 HEC 令牌(**Settings → Data inputs → HTTP Event Collector**),允许它使用 `security` 索引,并将 `url` 设置为 `https://:8088/services/collector/event`。要查找这些事件,请搜索 `index=security sourcetype="semaphore:audit"`。 + +请对此令牌关闭 **Enable indexer acknowledgement**:Semaphore 不使用它。 + ### 导出故障排除 {#troubleshoot-export} -- **Semaphore 无法启动。** 检查是否同时设置了 `audit.syslog.id` 和 `audit.syslog.address`,以及 CA 文件是否包含 PEM 证书。 +- **Semaphore 无法启动。** 检查是否同时设置了 `audit.syslog.id` 和 `audit.syslog.address`(使用 HEC 时为 `audit.splunk_hec.id`、`url` 和 `token`),以及 CA 文件是否包含 PEM 证书。 - **TLS 连接失败。** 检查接收器证书是否与 `server_name` 匹配,并由 Semaphore 信任的 CA 签发。 - **事件没有到达。** 检查 Semaphore 服务器日志和接收器日志。失败后,Semaphore 会稍等片刻再重试。 - **部分事件到达两次。** 这可能在重试和故障转移后发生。按 `event_id` 去除重复事件。 +- **HEC 返回 400、401 或 403。** 检查令牌、其允许写入的索引,以及该令牌已关闭索引器确认。令牌不会出现在 Semaphore 日志中。 ## 不记录的内容 {#not-recorded}