Guide 39 of 61 · Investigating and recovering
Send agent events to your SIEM
Turn on agentgarmd's exporters: OCSF events to your SIEM, OTel GenAI spans and token metrics to your collector, and notice when an export stops.
Built, not yet claimed preview: this guide describes a package that has not passed its release gate.
Turn on agentgarmd's exporters in default.yaml, ship the OCSF file of events and findings to your SIEM, send the OTel GenAI spans and token metrics to your collector over OTLP, know which field holds what, and notice when an export stops.
1. Decide what may leave the machine
Each machine's agentgarmd exports what it has stored itself. On a fleet, Central Lite can forward the security and audit events every machine uploads instead, with one SIEM credential (Send the fleet's security events to Splunk or Sentinel); the two can run side by side. Every field the event taxonomy marks personal, such as a principal, a path, a remote host or a free-text reason, leaves only as a keyed hash under your tenant's pseudonymisation key. Prompt and response text never leave. A node enrolled in Central Lite uses the key Central Lite gave it, so the hashes join across your machines; a node never enrolled uses a key of its own. Central Lite forwards the hashes nodes uploaded unchanged, so the same person carries the same pseudonym in both exports and they join in your SIEM.
Under the non-monitoring compliance profile (non_monitoring in a policy) only security and audit events and decisions leave, with personal fields removed rather than hashed, besides the hourly activity aggregates; no span, metric or cost row is produced. agentgarm status shows the profile on its compliance profile line.
agentgarm statusSee also
Prepare a works-council or DPIA packGenerate templates that describe what your deployment collects, keeps and sends, and switch the fleet to the non-monitoring profile during talks.
2. Turn on the export in default.yaml
The export is the host-scope export section, read from default.yaml only and bounded by the policy schema; without it nothing is exported. Add it to the default.yaml in your policy directory (/etc/agentgarm/agents.d on a root Linux install), then restart agentgarmd, which reads the directory when it starts. On a node enrolled in Central Lite, put the export section in the policy bundle Central Lite publishes instead: while a bundle is in force, it replaces the agents.d files and a local file is not read.
A new export starts from what is stored after it is turned on: nothing older is sent. If default.yaml stops loading, the export pauses where it was, and what is stored meanwhile is held to the non-monitoring profile.
export:
window_seconds: 60 # the token metrics window, 10 to 3600 seconds
file: # <state>/export
ocsf: true # ocsf.jsonl: OCSF 1.9.0 events and findings
otel: false # otel.jsonl: the same spans and metrics as OTLP/JSON lines
focus: false # the daily FOCUS cost files
otlp:
endpoint: https://otel-collector.example.internal:4318 # /v1/traces and /v1/metrics below it
tls_spki_sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
traces: true
metrics: truesudo systemctl restart agentgarmd # Linux
sudo launchctl kickstart -k system/com.agentgarm.agentgarmd # macOSsystemctl --user restart agentgarmd # Linux
launchctl kickstart -k gui/$(id -u)/com.agentgarm.agentgarmd # macOS3. Ship the OCSF file to your SIEM
With file.ocsf on, agentgarmd appends OCSF 1.9.0 events and findings, one JSON object per line, to ocsf.jsonl in its own export directory, a 0700 directory in its state directory: root's on a root install, yours on a no-root one. Point your log shipper at that file; it rotates past max_file_bytes (64 MiB by default) to ocsf.jsonl.1 and on, keeping max_files (8 by default). The file is readable only by agentgarmd's user (root on a root install, you on a no-root install), so run the shipper as that user.
Delivery is at least once: a write that fails is retried whole, so a line can repeat. Deduplicate on metadata.uid, the event or decision id. OCSF goes to the file only; the OTLP sink carries no OCSF.
A file section also turns on, unless you set them to false as the example does, otel (the spans and token metrics as OTLP/JSON lines in otel.jsonl) and focus (each day's FOCUS cost rows as focus-<day>.csv, kept 31 days).
Every hold placed on a task, and every kill order a machine applies, is a record too preview: a task suspended (Medium) and a machine locked down (High) are Detection Findings (2004) with the hold, the order id, the reason and the assurance of the stop, and an order lifted locally by root is a High alert; a task resumed and a lockdown lifted are Base Events (0). An evidence bundle carries its own OCSF copy of one task's records, apart from this file.
sudo tail -n 1 /var/lib/agentgarm/export/ocsf.jsonl4. Send spans and token metrics over OTLP
The otlp sink posts protobuf to /v1/traces and /v1/metrics under the endpoint: a span for each model call, local runtime call and MCP call, and each window's delta token metrics. The endpoint must be https://, and tls_spki_sha256, the lowercase hex SHA-256 of the collector's public key, is required: the pin is the trust anchor. http:// is refused even on loopback, since any local user could take the port while the collector is down. No credential is ever sent.
An outage is retried with backoff, honouring Retry-After. The queue holds 256 requests and 8 MiB; past that the oldest is dropped and alerted.
5. Map the fields
Denies and asks are Detection Findings (2004), with the rule id in finding_info.analytic.uid; bypass, tamper and degraded-assurance alerts are Detection Findings too, and DLP findings are Data Security Findings (2006) carrying rule ids, never the secret. Tool, model and MCP calls are API Activity (6003), file operations File System Activity (1001) and connections Network Activity (4001). What OCSF has no place for is under unmapped.agentgarm: the event type, the layer, the assurance level and the minimised payload. On a Mac preview, the airbag's decisions on desktop input (DesktopInputEvent: the target app, the element's role and title, the poster, the action and the rule id) and the capture monitor's changes (CaptureEvent: the privacy service, the change, the sensitive app and the action) have no OCSF class either: they are Base Events (0) with the payload there.
metadata.correlation_uid is the task id, so a task's events group together; in OTel, every span of a task shares a trace id, a keyed hash of the task id. A hook's tool call is in OCSF only, never a span.
See also
Trace what one agent task didFind an agent's task in the dashboard, read every decision its policy made with the rule behind it, and follow the run from first decision to last.
6. Notice when an export stops
Exporting never holds up enforcement: it runs on its own thread, and the store keeps every record within its retention whatever happens to it. A refused configuration, a file it cannot write, a full queue, a 15-minute collector outage or a missing key raises a host-wide AssuranceDegraded with the reason EXPORT_DEGRADED, chained in the audit log. agentgarm status does not show the exporters' state; these alerts are their record.
Each day, except under the non-monitoring profile, the token counts in the OTel metrics, the OCSF calls and the FOCUS rows are checked against each other, and a disagreement raises the same alert. For evidence that must verify, export the audit chain as OCSF and check it with agentgarm audit verify.
See also
Export and verify the audit logExport AgentGarm's hash-chained audit log, check it against the node key that signs its heads, and know what a passing or broken check tells you.