Developer documentation

CAIN Trace

Last reviewed 31 August 2026

All docs

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