> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Forensics

> Replayable, content-addressed audit trail for every detection decision — rule evaluations, state transitions, and policy snapshots

The forensic model records every decision the detection engine makes as an immutable database row. Use it to answer "why did this incident fire?", "what policy was in effect?", and "which check caused the transition?" — without re-running the data.

## What gets recorded

Three row types are written for every check that flows through detection:

* **Rule evaluations** — one row per rule evaluated against a check result. Captures rule type (`consecutive_failures`, `response_time`, ...), region, inputs, `outputMatched` flag, and the policy snapshot hash.
* **State transitions** — one row per status edge walked (`WATCHING → TRIGGERED`, `TRIGGERED → CONFIRMED`, `CONFIRMED → RESOLVED`, ...). Carries `triggeringEvaluationIds`, `checkId`, `policySnapshotHashHex`, and `engineVersion`. The `reason` field distinguishes detection-engine causes (`trigger`, `confirm`, `resolve`, `auto_clear`, `reopen`) from user-driven actions (`manually_resolved`).
* **Policy snapshots** — content-addressed by SHA-256 of the policy JSON. The exact policy that was active at evaluation time, even if the monitor has been edited since.

All rows are tagged with `organizationId` and the originating `checkId`, so you can thread a single check execution across both writes.

## Endpoints

All endpoints are read-only and live under `/api/v1/forensics/`:

| Endpoint                                        | Purpose                                                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `GET /forensics/incidents/{id}/timeline`        | Full timeline for an incident: transitions + triggering evaluations + active policy snapshot                  |
| `GET /forensics/traces/{checkId}`               | Everything recorded for a single check execution                                                              |
| `GET /forensics/policy-snapshots/{hashHex}`     | Fetch a policy snapshot by its SHA-256 hash                                                                   |
| `GET /forensics/monitors/{id}/rule-evaluations` | Paginated list of rule evaluations for a monitor (filters: `ruleType`, `region`, `onlyMatched`, `from`, `to`) |
| `GET /forensics/monitors/{id}/transitions`      | Paginated list of state transitions for a monitor (filters: `from`, `to`)                                     |

## CLI

```bash theme={null}
devhelm forensics timeline <incident-id>
devhelm forensics trace <check-id>
devhelm forensics snapshot <hash-hex>
devhelm forensics evaluations --monitor-id <uuid> --only-matched
devhelm forensics transitions --monitor-id <uuid> --from 2026-04-01T00:00:00Z
```

Every command supports `--output json|yaml|table` and the standard auth flags.

## SDKs

<CodeGroup>
  ```typescript TypeScript theme={null}
  import {Devhelm} from '@devhelm/sdk'

  const client = new Devhelm({token: process.env.DEVHELM_API_TOKEN!})

  const timeline = await client.forensics.incidentTimeline(incidentId)
  const trace = await client.forensics.checkTrace(checkId)
  const snapshot = await client.forensics.policySnapshot(hashHex)

  const {data: evals} = await client.forensics.monitorRuleEvaluations(monitorId, {
    onlyMatched: true,
    ruleType: 'consecutive_failures',
  })
  ```

  ```python Python theme={null}
  from devhelm import Devhelm

  client = Devhelm(token=os.environ["DEVHELM_API_TOKEN"])

  timeline = client.forensics.incident_timeline(incident_id)
  trace = client.forensics.check_trace(check_id)
  snapshot = client.forensics.policy_snapshot(hash_hex)

  page = client.forensics.monitor_rule_evaluations(
      monitor_id,
      only_matched=True,
      rule_type="consecutive_failures",
  )
  ```
</CodeGroup>

## MCP tools

The DevHelm MCP server exposes the same read path to AI agents:

* `get_incident_timeline(incident_id)` — replay why an incident fired
* `get_check_trace(check_id)` — inspect a single check execution
* `get_policy_snapshot(hash_hex)` — fetch the exact policy active at a past moment
* `list_monitor_rule_evaluations(monitor_id, ...)` — audit rule firings
* `list_monitor_transitions(monitor_id, ...)` — reconstruct monitor lifecycle

See the [MCP tools reference](/sdk/mcp/tools-reference#forensics) for full signatures.

## Use cases

* **Incident replay**: a customer asks "why did we get paged?" — the timeline endpoint returns the check, policy, and rules involved, no log scraping needed.
* **Policy change review**: before editing a trigger rule, fetch the snapshot hash that fired the last incident and diff it against the new policy.
* **False-positive audit**: list `rule-evaluations?onlyMatched=true` for a monitor over the last 7 days to spot noisy rules.
* **Cross-region analysis**: filter `rule-evaluations?region=us-east` to see how one region contributed to confirmation.

## Retention

| Row type          | Retention  | Notes                                                                   |
| ----------------- | ---------- | ----------------------------------------------------------------------- |
| Rule evaluations  | 30 days    | High-volume hypertable (\~288M rows/day at scale); compressed at 7 days |
| State transitions | 2 years    | Low-volume, high audit value                                            |
| Policy snapshots  | Indefinite | Content-addressed by SHA-256; deleting would orphan references          |

## Next steps

<CardGroup cols={2}>
  <Card title="Incident Timeline" icon="timeline" href="/incidents/timeline">
    Human-facing view of an incident's lifecycle — status changes, updates, and notifications.
  </Card>

  <Card title="Incident Policies" icon="sliders" href="/incidents/policies">
    Configure the trigger and recovery rules that forensics record.
  </Card>

  <Card title="MCP Tools Reference" icon="robot" href="/sdk/mcp/tools-reference">
    Let an AI agent query the forensic model directly.
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference">
    Full schema for every forensic endpoint.
  </Card>
</CardGroup>