Forensics & Signed Proof
Query an agent's behavioural history, replay its risk posture, and export a tamper-evident, HMAC-signed proof of exactly what you pulled — for incident response and audit.
Overview
When something goes wrong, you need to reconstruct what an agent did — and prove the record wasn't altered after the fact. The forensics endpoint queries an agent's behavioural events with filters, returns an ordered timeline plus a replay summary, and signs the exported set with a tamper-evident proof.
This is the proof pillar at incident time — control C-G1, mapped to NCCoE non-repudiation. The export itself is audited, so pulling forensic data is also on the record.
Querying
GET /v1/agents/{id}/forensics?action_type=output_content_risk&min_risk=0.7&from=2026-05-01&to=2026-05-30&limit=500| Query param | Notes |
|---|---|
action_type | Filter to one event type (e.g. output_content_risk) |
min_risk | Only events with risk_score ≥ this value |
from / to | ISO timestamps bounding the window |
limit | Max events to return (≤ 1000, default 500) |
Response 200:
{
"data": {
"agent_id": "uuid",
"agent_name": "Invoicing Bot",
"filters": { "action_type": "output_content_risk", "min_risk": 0.7, "from": "2026-05-01", "to": "2026-05-30", "limit": 500 },
"summary": {
"event_count": 12,
"band_distribution": { "low": 2, "medium": 4, "high": 6 },
"action_type_counts": { "output_content_risk": 12 },
"first_event_at": "2026-05-03T08:11:00Z",
"last_event_at": "2026-05-29T22:40:00Z"
},
"events": [ /* ordered timeline, ascending by occurred_at */ ],
"proof": {
"algorithm": "HMAC-SHA256",
"content_hash": "sha256:9f2c...",
"signature": "hmac:6b8e...",
"event_count": 12
}
}
}The signed proof
The proof object is computed over a stable projection of the events (id, timestamp, action type, risk score, band) — deliberately excluding mutable or PII-adjacent fields so the hash is reproducible.
content_hash— SHA-256 over the canonical projection. Recompute it from the returned events to confirm nothing was tampered with in transit.signature— HMAC-SHA256 over the content hash, keyed by Kakunin's forensics key. Proves the export came from Kakunin.
If the signing key is unconfigured in an environment, signature is null (not an error) — the content_hash is still returned, so integrity checking still works. In production the signature is always present.
Replay summary
The summary block is a fast read of the agent's posture across the window: how many events landed in each risk band, the distribution across action types, and the timeline bounds. Use it to triage before walking the full events array.
Every export is audited
Each forensic query writes a forensics.exported audit row recording who pulled what, when, the filters used, and the content_hash of the result. The act of investigating is itself non-repudiable.
Delegation Chains (RFC 8693)
Make the human→agent→sub-agent authority chain explicit with RFC 8693 token exchange. Prove who authorised whom, with what scope, for non-repudiation.
OTLP Observability Export
Stream agent risk scores, events, and decision-chain traces to your own observability stack — Datadog, Grafana, Honeycomb, or Splunk — over vendor-neutral OpenTelemetry (OTLP).