feat(server): write gateway OCSF events to JSONL - #3264
Conversation
Previously, gateway security activity was available only in diagnostic output, and there was no independent record of events that were not associated with a sandbox, such as TLS certificate reloads. Now, configuring `openshell.gateway.ocsf_log` with a path writes every gateway-produced OCSF record to that JSONL file, independently of `RUST_LOG`. Records identify the gateway as their producer and report the gateway operating system even when they describe activity associated with a sandbox. By default, the file rotates daily in UTC, retains seven rotated files, and buffers up to 10,000 records or 16 MiB. This means an external shipper can tail one file per gateway replica and own remote delivery or SIEM conversion. The file is best-effort: queue overflow and write failures discard records, failed writes are not retried, and warnings and metrics report known failures without stopping sandbox operation. Refs #2762 Signed-off-by: Kris Hicks <khicks@nvidia.com>
|
🌿 Preview your docs: https://nvidia-preview-pr-3264.docs.buildwithfern.com/openshell |
| | 5019 | Device Config State Change | `CONFIG:` | | ||
| | 6002 | Application Lifecycle | `LIFECYCLE:` | | ||
|
|
||
| ## SIEM Schema Version Compatibility |
There was a problem hiding this comment.
Should we have a version compatibility option for gateway OCSF as well? Probably yes, so both the gateway and sandbox produced logs can be consumed. It could be a follow up.
There was a problem hiding this comment.
I hadn't realized that was merged; I'm going to look into this more.
| type_label: DeviceTypeId::Server.to_string(), | ||
| name: Some(name.to_string()), | ||
| // Keep the replica identity opaque rather than encoding multiple fields in the UID. | ||
| uid: Some(hostname.to_string()), |
There was a problem hiding this comment.
Could device.uid include the gateway installation identity as well as the replica hostname? Hostnames such as openshell-gateway-0 can repeat across namespaces or clusters, so a SIEM aggregating multiple installations may merge distinct gateways under one device UID. For example, deriving the UID from both name and hostname—or omitting it when global uniqueness cannot be guaranteed—would better preserve the field’s uniqueness contract.
2 participants
Previously, gateway security activity was available only in diagnostic output, and there was no independent record of events that were not associated with a sandbox, such as TLS certificate reloads.
Now, configuring
openshell.gateway.ocsf_logwith a path writes every gateway-produced OCSF record to that JSONL file, independently ofRUST_LOG. Records identify the gateway as their producer and report the gateway operating system even when they describe activity associated with a sandbox. By default, the file rotates daily in UTC, retains seven rotated files, and buffers up to 10,000 records or 16 MiB.This means an external shipper can tail one file per gateway replica and own remote delivery or SIEM conversion. The file is best-effort: queue overflow and write failures discard records, failed writes are not retried, and warnings and metrics report known failures without stopping sandbox operation.
This does not include enabling configuration in helm; that will come in a subsequent PR.
Summary
Related Issue
This PR is plumbing that paves the way for 2762 and 2911 to be implemented
Changes
Testing
mise run pre-commitpassesChecklist