Developer documentation

CAIN Drift

Last reviewed 31 August 2026

All docs

Status: PARTIAL - Baselines, observations, comparisons, findings, evidence, and lifecycle management are operational. CLI and MCP integration pending.

Overview#

CAIN Drift detects meaningful changes in autonomous AI systems before drift becomes an incident. It is part of CAIN Trust Fabric and integrates with existing CAIN infrastructure.

Architecture#

BASELINE → OBSERVE → COMPARE → DETECT → CLASSIFY → CORRELATE → EVIDENCE → IMPACT → GOVERN → REMEDIATE → VERIFY

Key Principle: Drift detects. Governance decides. Enforcement enforces. Evidence records.

Drift Classes#

Class	Description	Detects
`data_drift`	Statistical changes in data distributions	PSI, JS divergence, KS test, mean/variance shift
`model_drift`	Changes in AI model configuration	Provider, version, temperature, system prompt, tools
`tool_drift`	Changes in tool/MCP configurations	Schema, permissions, endpoint, version, capabilities
`policy_drift`	Changes in authorization policies	Rules, risk thresholds, approval requirements
`agent_behavior_drift`	Changes in agent behavior patterns	Action frequency, tool selection, denial rate
`security_drift`	Changes in security posture	Attack surface, credentials, suspicious activity
`compliance_drift`	Changes in compliance posture	Compliance score, open findings
`configuration_drift`	Changes in system configuration	Config changes
`trajectory_drift`	Changes in execution trajectories	Trajectory patterns
`evidence_drift`	Changes in evidence patterns	Evidence volume, types, integrity

API Endpoints#

Health & Status#

GET /fabric/drift/health     - Service health check
GET /fabric/drift/status     - Service status
GET /fabric/drift/stats      - Drift statistics

Baselines#

POST /fabric/drift/baselines           - Create baseline
GET  /fabric/drift/baselines           - List baselines
GET  /fabric/drift/baselines/{id}    - Get baseline
POST /fabric/drift/baselines/{id}/activate   - Activate baseline
POST /fabric/drift/baselines/{id}/archive    - Archive baseline

Detection#

POST /fabric/drift/observe   - Observe current state and detect drift
POST /fabric/drift/compare    - Compare current state against baseline

Findings#

GET  /fabric/drift/findings                    - List findings
GET  /fabric/drift/findings/{id}               - Get finding
GET  /fabric/drift/findings/{id}/history       - Get status history
GET  /fabric/drift/findings/{id}/impact        - Get impact assessment
POST /fabric/drift/findings/{id}/acknowledge   - Acknowledge finding
POST /fabric/drift/findings/{id}/investigate   - Mark investigating
POST /fabric/drift/findings/{id}/mitigate      - Mark mitigated
POST /fabric/drift/findings/{id}/resolve       - Mark resolved
POST /fabric/drift/findings/{id}/accept        - Accept risk
POST /fabric/drift/findings/{id}/false_positive - Mark as false positive

Authentication#

All endpoints require tenant query parameter. Additional authentication may be required for production use.

Finding Lifecycle#

detected → acknowledged → investigating → mitigated → resolved
                                                      ↘ accepted
                                                      ↘ false_positive

Evidence Chain#

Every drift detection produces evidence in the CAIN Evidence Fabric:

{
  "drift_id": "...",
  "tenant": "...",
  "baseline": {...},
  "observation": {...},
  "comparison": {...},
  "finding": {...},
  "classification": "...",
  "severity": "...",
  "metrics": {
    "baseline_value": ...,
    "current_value": ...,
    "delta": ...,
    "delta_percent": ...,
    "threshold": ...,
    "confidence": ...
  },
  "evidence_chain": ["baseline", "observation", "comparison", "finding"]
}

Compliance Integration#

Drift triggers reassessment but does NOT automatically fail controls. The compliance engine determines actual control status.

Severity Levels#

Severity	Description
`critical`	Credentials, permissions, or safety config changed
`high`	Model, version, schema, or endpoint changed
`medium`	Description, configuration, or state changed
`low`	Minor changes detected

CLI Commands#

cain drift status --tenant <tenant>
cain drift baselines --tenant <tenant>
cain drift observe --tenant <tenant> --entity-id <id> --current-state <json>
cain drift compare --tenant <tenant> --entity-id <id> --current-state <json>
cain drift findings --tenant <tenant> [--severity <sev>] [--status <status>]
cain drift inspect --tenant <tenant> --finding-id <id>

Limitations#

CLI: Commands implemented but require testing
MCP: Tools not yet implemented
Agent Behavior Drift: Partial - requires trajectory data
Security Drift: Partial - requires live security events
Real-time SSE: Events emit to observability, Redis pub/sub not implemented

Production Status#

Component	Status
Baselines	OPERATIONAL
Observations	OPERATIONAL
Comparisons	OPERATIONAL
Findings	OPERATIONAL
Evidence	OPERATIONAL
Lifecycle	OPERATIONAL
CLI	IMPLEMENTED (pending test)
MCP	NOT IMPLEMENTED
Portal Docs	THIS DOCUMENT

Contact#

For issues or questions, see CAIN Studio Platform documentation.