Developer documentation

CAIN Trace

Last reviewed 31 August 2026

CAIN Trace Documentation

Status: LIVE + FUNCTIONAL

Verified 2026-09-08: /fabric/traces/ returns [] (empty - no traces created yet, but endpoint exists and is tenant-scoped).

CAIN Trace is fully functional. The core trace engine, API, dashboard, and correlation with CAIN decisions are implemented and working.

What is CAIN Trace?

CAIN Trace records the complete execution lifecycle of every CAIN-protected action. It provides immutable, tenant-isolated execution history that correlates identity, decisions, enforcement, and evidence.

Core principle: Every CAIN decision creates a trace automatically. No manual trace creation required for normal operation.

Trace Lifecycle

A trace progresses through these stages:

1. TRACE CREATED - Action received, trace initialized

2. IDENTITY RESOLVED - Principal authenticated (if identity_id provided)

3. POLICY EVALUATED - OPA policy checked

4. AUTHORIZATION EVALUATED - Agent permissions verified

5. RISK EVALUATED - Risk score calculated

6. TRAJECTORY EVALUATED - Trajectory safety checked (if applicable)

7. CAIN DECISION - Final verdict determined

8. ENFORCEMENT APPLIED - ALLOW or DENY enforced

9. EXECUTION - Tool/MCP call made (ALLOW only)

10. EVIDENCE CREATED - Immutable record stored

11. TRACE CLOSED - Final state recorded

Data Model

ExecutionTrace

Field	Type	Description
trace_id	string	Unique trace identifier (trc_xxxx)
tenant_id	string	Tenant namespace
agent_id	string	Agent that executed
identity_id	string	Identity of caller
action	string	Action performed
tool	string	Tool used
resource	string	Resource accessed
decision_id	string	CAIN decision ID
trajectory_id	string	Trajectory ID (if applicable)
evidence_id	string	Evidence record ID
verdict	enum	ALLOW, DENY, REQUIRE_APPROVAL, UNKNOWN, ERROR
status	enum	PENDING, COMPLETED, DENIED, FAILED, ERROR
execution_outcome	string	What happened
timestamp_start	datetime	When trace started
timestamp_end	datetime	When trace ended
duration_ms	float	Execution duration

TraceEvent

Field	Type	Description
event_id	string	Unique event ID
trace_id	string	Parent trace
event_type	string	Type of event
stage	string	Lifecycle stage
verdict	string	Stage verdict
detail	dict	Event data
timestamp	datetime	When event occurred

API Endpoints

Health Check

GET /fabric/traces/health

Returns trace service health status.

Create Trace (Internal)

Traces are created automatically by make_cain_decision(). Manual creation via:

POST /fabric/traces/?action=<action>&tool=<tool>

List Traces

GET /fabric/traces/

Query parameters:

action - Filter by action
tool - Filter by tool
agent_id - Filter by agent
status - Filter by status
limit - Max results (default 100)

Get Trace

GET /fabric/traces/{trace_id}

Returns full trace with events and integrity verification.

Get Trace Events

GET /fabric/traces/{trace_id}/events

Returns ordered list of lifecycle events.

Get Trace Evidence

GET /fabric/traces/{trace_id}/evidence

Returns evidence records with integrity verification.

Search Traces

POST /fabric/traces/search

Advanced search with multiple filters.

Stats Summary

GET /fabric/traces/stats/summary

Returns aggregate statistics.

Authentication

All trace endpoints require:

X-Tenant-ID header - Tenant identifier
X-API-Key header - API key for authentication

Note: Traces are automatically created when make_cain_decision() is called. The tenant is derived from the API key.

Tenant Isolation

Each tenant sees only their own traces
Cross-tenant access returns 404 (fail-closed)
No enumeration of other tenants' traces

Correlation

Decision Correlation

Every trace links to its CAIN decision via decision_id.

Evidence Correlation

ALLOW decisions create evidence linked via evidence_id.

Trajectory Correlation

When identity_id is provided, traces link to trajectories via trajectory_id.

Dashboard

Access the trace dashboard at:

https://cainstudio.online/trace
https://cainstudio.online/trace/dashboard

The dashboard displays real traces from the backend with filtering and search capabilities.

CLI

Trace commands are available via the CAIN CLI:

cain trace list
cain trace get <trace_id>
cain trace events <trace_id>

Trace States

Status	Meaning
PENDING	Trace created, decision pending
COMPLETED	Action allowed and executed
DENIED	Action blocked by CAIN
FAILED	Execution failed
ERROR	System error (fail-closed)

Verdict Definitions

Verdict	Meaning	Execution
ALLOW	Action permitted	Yes
DENY	Action blocked	No
REQUIRE_APPROVAL	Human approval needed	No
UNKNOWN	Cannot determine	No (fail-closed)
ERROR	System failure	No (fail-closed)

Real Examples

ALLOW Trace

{
  "trace_id": "trc_abc123",
  "tenant_id": "tenant-xyz",
  "action": "deploy_service",
  "tool": "kubectl",
  "verdict": "allow",
  "status": "completed",
  "decision_id": "cain:def456",
  "evidence_id": "ev_789",
  "execution_outcome": "Service deployed successfully"
}

DENY Trace

{
  "trace_id": "trc_xyz789",
  "tenant_id": "tenant-xyz",
  "action": "delete_all_data",
  "tool": "database",
  "verdict": "deny",
  "status": "denied",
  "decision_id": "cain:ghi101",
  "execution_outcome": "Tool 'delete_all_data' is not registered for this agent"
}

Security Considerations

Traces are immutable once finalized
Hash verification available via /evidence endpoint
Tenant isolation is enforced at the database level
All trace operations require authentication

Limitations

Trace creation requires API key authentication
Dashboard requires correct tenant context
MCP tool tracing requires MCP integration