---
title: "Incident forensics, DSAR and event commands"
description: "Reference for nova forensics timeline, nova dsar for subject-rights requests, and opt-in lifecycle events and webhooks with nova events."
canonical: https://novafabric.ai/docs/cli-reference/incidents-and-events/
last_updated: 2026-11-21
source: https://github.com/MSKazemi/novafabric/blob/main/docs/cli-reference.md
---

# Incident forensics, DSAR and event commands

Part of the [NovaFabric CLI reference](https://novafabric.ai/docs/cli-reference/). Both `nova` and `novafabric` run the same binary.

## Incident forensics and subject-rights commands (experimental, ADR-0155/0161)

Read-only reconstructions over already-sealed evidence supplied as a JSON
document. Missing evidence is shown as `gaps`, never raised (fail-open); the
commands print references and states only.

### nova forensics timeline (experimental, ADR-0155)

Render an incident's forensic timeline: a deterministic
(byte-identical-on-re-run) view over the incident's collected sealed evidence.

```bash
nova forensics timeline incident-evidence.json
nova forensics timeline incident-evidence.json --json
```

Options:
- `<evidence>` (positional, required) — JSON: `{incident_id, events: [{ts, source_capsule, seq, kind}], gaps?}`
- `--json` — emit the timeline as JSON

Exit codes: `0` (timeline rendered), `2` (missing or malformed input).

---

### nova dsar assemble (experimental, ADR-0161)

Assemble a subject's cross-capsule DSAR package: a deterministic assembly of
every capsule that processed a subject, keyed on the **HMAC pseudonym** — the
raw subject id never enters the artifact.

```bash
nova dsar assemble subject-records.json
nova dsar assemble subject-records.json --json
```

Options:
- `<document>` (positional, required) — JSON: `{subject_hmac, records: [{capsule_id, categories}], gaps?}`
- `--json` — emit the DSAR package as JSON

Exit codes: `0` (package rendered), `2` (missing or malformed input).

---

### nova dsar sla (experimental, ADR-0161)

Compute a DSAR's turnaround against a deadline (default GDPR Art. 12(3), one
month). `met_deadline` is a factual `fulfilled_at <= deadline` comparison over
recorded timestamps — evidence a request was met on time, not a compliance
verdict.

```bash
nova dsar sla request.json
nova dsar sla request.json --json
```

Options:
- `<document>` (positional, required) — JSON: `{request_open, fulfilled_at, deadline?, subject_hmac?}` (ISO 8601 UTC)
- `--json` — emit the SLA record as JSON

Exit codes: `0` (record rendered, whether or not the deadline was met), `2` (bad input).

---

## Lifecycle events and webhooks (experimental, ADR-0137)

Opt-in outbound surface: on defined lifecycle transitions NovaFabric emits one
structured, non-sensitive event record to a local append-only `events.jsonl`
and, optionally, POSTs it to user-configured webhook URLs so your **own**
CI/automation can react. Strictly opt-in — nothing is emitted until you set
`NOVA_EVENTS_LOG` and/or `NOVA_EVENTS_WEBHOOK`; there is no default
destination. Delivery is emit-and-forget: fail-safe (a broken webhook can
never break a capture or validation), bounded retries (`NOVA_EVENTS_MAX_RETRIES`,
default 2), no queue, no delivery guarantee — the local log is the durable
record. Payloads carry only refs, digests, enums, and counts (never
prompt/response text or secrets) and pass the capsule secret scanner before
leaving the process. Optional HMAC-SHA256 signing (`NOVA_EVENTS_SIGN_SECRET`)
adds a `signature` field and an `X-NovaFabric-Signature` header.

Wired transitions in this slice (**works today**): `capsule.created`
(`nova capture`) and `capsule.validated` (`nova validate` on a capsule).
The remaining taxonomy (`promotion.*`, `policy.failed`, `retention.applied`,
`promotion.bypass.*`) is defined in `schemas/lifecycle-event.schema.json` and
can be emitted manually; wiring those transitions is **planned** (ADR-0137 P3),
as are the local command sink, `tail --follow`, and NovaSeal signing.

### nova events tail

```bash
export NOVA_EVENTS_LOG=~/.novafabric/events.jsonl
nova events tail                                  # summary lines
nova events tail --type capsule.created --json    # filter + raw JSON
nova events tail --since 2026-07-15T00:00:00Z --last 10
```

### nova events emit

Manually emit one event through the configured sinks — for testing a wired CI
hook end-to-end.

```bash
NOVA_EVENTS_WEBHOOK=https://ci.internal.example/nova-hook \
nova events emit --type policy.failed \
  --subject policy:promotion:agent-a@1.4.0 \
  --payload '{"gate": "eval-regression", "decision": "deny"}'
```

Exit 1 when no sink is configured; delivery itself is best-effort.

---
