CLI Reference
engine
incidents export

`rsigma engine incidents export`

Pull one incident’s bundle from a running daemon and write it to stdout or a file.

Synopsis

rsigma engine incidents export <INCIDENT_ID> [OPTIONS]

Description

An incident groups many detections under one id, and the grouped view alone does not say much: it carries rule keys, counts, and grouping values, not what those rules were looking for or why they matter. A bundle is that incident joined to the ADS documentation of every rule that contributed and the risk entities it overlaps, in one self-contained document. It is what you attach to a ticket, hand to an on-call engineer, or keep as the record of what the detection stack knew at the time.

The command is the client side of GET /api/v1/incidents/{id}/bundle. Incident ids come from GET /api/v1/incidents or from an emitted incident’s incident_id.

Like engine status, it uses a synchronous HTTP client and does not need the daemon build feature, so a lightweight build can pull a bundle from a remote daemon. --addr follows the same convention: it defaults to daemon.api.addr from the resolved config, and a wildcard bind address (0.0.0.0, [::]) is mapped to loopback.

The daemon renders the bundle, so the global --output-format has no say in how it looks. --bundle-format is the only control, and passing an output format prints a warning and is otherwise ignored.

Flags

Flag	Default	Description
`<INCIDENT_ID>`	required	The incident to export.
`--bundle-format <FORMAT>`	`json`	`json` for the full structured document, `markdown` for a human-readable report.
`-o, --output <PATH>`	stdout	Write the bundle here. The file is replaced only after the whole bundle has arrived, so a failed export leaves a previous one intact.
`--addr <HOST:PORT or URL>`	from `daemon.api.addr`	Daemon API address as `host:port` or a full URL. `https://` URLs work for TLS deployments.
`-c, --config <PATH>`	discovery chain	Explicit config file used to resolve the daemon address.
`--auth-token-env <VAR>`	`RSIGMA_API_TOKEN`	Environment variable holding the API bearer token.

Authentication

The bundle route requires the incident-bundles:read permission when the daemon has API authentication enabled. That permission is deliberately separate from the incidents:read that gates the incident list, because a bundle hands out rule documentation and risk entities as well. The built-in reader role (*:read) covers both; see also Security: Daemon API authentication.

The token is read from an environment variable and never taken as an argument, so it does not appear in the process list or in shell history. An unset or empty variable sends no Authorization header at all, which against an authenticated daemon fails with a 401 rather than silently exporting nothing. Use --auth-token-env when the secret lives under a different variable name.

export RSIGMA_API_TOKEN="$(cat /run/secrets/rsigma-token)"
rsigma engine incidents export f8bcd62a829b1126

Examples

Export to stdout and pick the bundle apart

rsigma engine incidents export f8bcd62a829b1126 | jq '.rules[] | {key, count, resolution}'

{"key": "Suspicious PowerShell Download", "count": 4, "resolution": "unique"}
{"key": "a1b2c3d4-0000-0000-0000-000000000001", "count": 2, "resolution": "missing"}

resolution reports how the incident’s rule key resolved against the rule set loaded now: unique, ambiguous when several loaded rules carry the key with differing documentation, and missing when the rule set changed while the incident was open.

A Markdown report for a ticket

rsigma engine incidents export f8bcd62a829b1126 \
  --bundle-format markdown \
  --output incident-f8bcd62a.md

A remote TLS daemon

rsigma engine incidents export f8bcd62a829b1126 --addr https://daemon.internal:9443

Export every open incident

curl -sS -H "Authorization: Bearer $RSIGMA_API_TOKEN" \
  http://127.0.0.1:9090/api/v1/incidents \
  | jq -r '.incidents[] | select(.bundle_ready) | .incident_id' \
  | while read -r id; do
      rsigma engine incidents export "$id" --output "bundles/$id.json"
    done

The bundle_ready filter skips incidents still inside group_wait; those return 409 because their contents can still change. Drop the Authorization header when the daemon has no API auth configured. Listing needs incidents:read; each export needs incident-bundles:read.

Exit codes

Code	Meaning
`0`	The bundle was fetched and written.
`3`	The daemon could not be reached, returned a non-2xx status (`401`/`403` auth, `404` unknown or resolved id, `409` still in `group_wait`, `503` grouping off, …), or the output file could not be written.

A non-2xx response is reported with its status and the daemon’s own explanation, so the reason is visible without a second request:

incident export failed: http://127.0.0.1:9090/api/v1/incidents/nope/bundle?format=json returned HTTP 404
no such open incident
(the id is unknown, or the incident has already resolved and been evicted)