Skip to main content

Trail and Audit Evidence

Trail is the immutable audit surface for actors, resources, changes, request context, and integrity metadata. Use it to reconstruct who changed what, when, and with which result.

Do not use Trail as a synonym for every observability surface:

SurfacePrimary evidence
kt events or GET /v1/events with required sinceRuntime governance outcomes and request-policy activity
HistoryCaptured conversation and session content when enabled
InboxHuman-review work items and decisions
TrailControl-plane actions, resource changes, audit chronology, and record integrity

Search the console​

Open Trail and narrow the result with:

  • date range;
  • event category;
  • actor type or actor ID;
  • resource type;
  • event name;
  • verdict; and
  • read-only state.

Start from an exact request ID, event ID, resource ID, or short UTC window when available. Expand only when the investigation requires it.

The current console does not provide access-key-prefix lookup as an active search filter. Use supported actor, request, resource, and event fields instead of assuming a key filter was applied.

Read an event​

The detail view can expose:

  • actor identity and ARN;
  • source, name, category, and read-only classification;
  • request ID and event ID;
  • event time and duration;
  • request method and path;
  • response status and recorded error details;
  • the primary resource type, ID, and ARN;
  • record and previous hashes;
  • before/after change records;
  • additional event data; and
  • full event JSON.

Fields are event-dependent. A missing optional field is not proof that the corresponding activity did not happen.

Reconstruct a change​

For an administrative mutation:

  1. Anchor on the resource ID or request ID.
  2. Confirm actor, organization, region, and UTC time.
  3. Read the before/after change record.
  4. Identify referenced roles, policies, agents, gateways, or other resources.
  5. Check response status and error fields.
  6. Follow adjacent events only as far as needed to explain the operation.
  7. Correlate runtime Events through kt events or the Events API; add History separately when customer traffic is part of the question and capture is enabled.

An HTTP success can still require verification of the resulting resource state. Trail records the operation; the owning detail page confirms current state.

Export evidence from the console​

Open Trail and choose the visible Evidence exports action to queue a date-bounded evidence export. The direct path is /trail?view=exports. Raw-data exports are available as CSV or JSON; the same view also offers the supported compliance-report formats. This export workflow uses its own start date, end date, and format. It does not inherit the filters from the Trail event list.

Before queueing an export:

  • set and record the requested date range;
  • confirm the organization and region;
  • choose a format appropriate for the reviewer; and
  • note that the export contains decision-event evidence, not a dump of the immutable Trail records currently visible in the list.

After the job completes, compare the returned integrity.artifact_sha256 with the downloaded bytes and inspect GET /v1/exports/jobs/{job_id}/manifest when a manifest is available. Record the job parameters, integrity values, reviewer, and storage location. To export immutable Trail records with Trail-specific filters, use kt trail export.

Verify with the CLI​

Use kt trail verify for hash-chain and digest checks:

kt trail verify \
  --org-id 550e8400-e29b-41d4-a716-446655440000 \
  --start-time 2026-07-01T00:00:00Z \
  --end-time 2026-07-08T00:00:00Z \
  --deep \
  --json

Standard verification checks digest links inside a nonempty selected window. Deep verification is limited to 90 days and recomputes event record hashes, sequence continuity, and links between returned events. Neither mode performs cryptographic DSSE-envelope verification or checks the inbound link of the first returned record. Equal, reversed, or empty windows fail. A single-event command checks only the fetched event's recorded hash presence.

Use kt trail export for paginated JSON, JSONL, or CSV exports. See Trail CLI for exact commands and compression behavior.

Build an evidence packet​

Include:

  • purpose and review owner;
  • organization, region, and UTC window;
  • filter or command parameters;
  • event, request, actor, and resource IDs;
  • configuration or rollout version when relevant;
  • integrity-verification output;
  • exported file digest and protected location;
  • known gaps or unavailable fields; and
  • conclusion and next owner.

Minimize copied request or response content. Never include credentials, one-time secrets, payment identifiers, or unrelated personal data.

Failed or incomplete evidence​

If verification reports a gap or failure:

  1. Preserve the exact JSON output.
  2. Do not relabel the result as verified.
  3. Confirm organization, region, and time boundaries.
  4. Repeat only to rule out a transient retrieval error.
  5. Escalate through the approved audit-integrity workflow.

If a Trail record is absent, check whether the action belongs in the runtime Events query, capture-enabled History, or another surface and whether the selected scope is correct. Absence from one search is not proof of non-occurrence.

Retention and access​

Trail exports can contain sensitive operational metadata. Apply your approved:

  • access controls;
  • encryption;
  • retention schedule;
  • legal hold;
  • reviewer logging; and
  • deletion process.

Tagging or exporting an audit record does not change the authoritative retention policy.

Next steps​