Developer documentation

7-Moat Architecture

Last reviewed 31 August 2026

All docs

CAIN 7-Moat Architecture#

Status: Canonical Version: 1.0 Last Updated: 2026-09-10

The CAIN Trust Fabric is organized into seven defensive moats. Each moat is an independent security layer that an attacker must defeat in sequence. No single moat grants authorization; every moat enforces its own boundaries.

MOAT #1: TRUST STATE#

Purpose: Determine the current evidence-backed trust state of every relevant principal/agent.

Core Question: "WHO DO WE TRUST RIGHT NOW?"

Key Components:

trust_state.py - Deterministic trust computation
TrustState enum: UNKNOWN, NORMAL, TRUSTED, DEGRADED, REQUIRES_REVIEW, SUSPENDED, REVOKED
compute_trust_deterministic() - Evidence-derived trust from real CAIN records
get_authorization_decision() - Trust + Risk → Authorization Decision matrix

Evidence Sources:

Fabric decisions (verdicts, outcomes)
Trajectory outcomes
Anomaly events
Risk events

Fail-Closed Principles:

UNKNOWN/ERROR never become TRUSTED
Missing evidence never improves trust
REVOKED always DENYs

MOAT #2: SECURITY-CONTEXT CONTINUITY#

Purpose: Preserve authenticated identity, authority, delegation, intent, policy, trust, constraints, and provenance across every system boundary.

Core Question: "DOES AUTHORITY AND SECURITY CONTEXT SURVIVE EVERY BOUNDARY?"

Key Components:

security_context.py - Security context envelope
SecurityContextEnvelope - Full context preservation
Boundary validation at every hop
Context binding to execution provenance

Continuity Verification:

Identity persists across boundaries
Authority scope maintained
Delegation chain unbroken
Intent hash validated
Policy version consistent
Trust state current
Constraints honored

MOAT #3: TRUST GRAPH#

Purpose: Connect principals, agents, authority, delegation, intent, policy, trust, decisions, tools, resources, execution, effects, evidence, causality, and incidents into a tenant-isolated historical relationship graph.

Core Question: "HOW IS EVERYTHING CONNECTED?"

Key Components:

trust_graph.py - Graph-based trust relationships
Node types: PRINCIPAL, RESOURCE, POLICY, ATTESTATION, PROVENANCE_RECORD
Relation types: TRUSTED_BY, AUTHORIZED_BY, DELEGATED_TO, BOUND_TO, CAUSED, COULD_REACH
query_blast_radius() - Compute reachable resources through trust edges
get_edges(), get_node() - Graph traversal

Graph Analysis:

Direct reach (through direct relationships)
Delegated reach (through delegation chains)
Indirect reach (transitive trust)
Effect reach (downstream effects)
Unknown reach (target not in graph)

MOAT #4: EXECUTION PROVENANCE & ATTESTATION#

Purpose: Prove what actually executed, under whose authority, with which policy, trust state, security context, software components, tools, MCP servers, execution path, effect, and evidence.

Core Question: "CAN WE PROVE WHAT ACTUALLY HAPPENED?"

Key Components:

ExecutionProvenanceRecord - Binds DECISION → EXECUTION → EFFECT
ProofCenter - Generates machine-readable proofs
AttestationClaim - Claim-specific attestation (PROVEN, VERIFIED, OBSERVED, ASSERTED, UNVERIFIED, UNKNOWN)
SecurityContextEnvelope - Full security context for execution

Database Tables:

execution_provenance_records
execution_trust_signals
execution_effects

Attack Detection:

Tool substitution
Policy version mismatch
Trust version mismatch
Authority mismatch
Resource mismatch
Replay detection

MOAT #5: PREDICTIVE TRUST & BLAST RADIUS#

Purpose: Before consequential execution, determine what an actor could reach, affect, or cause, using trust, authority, graph, risk, impact, causal, and counterfactual analysis.

Core Question: "WHAT COULD HAPPEN BEFORE WE LET IT HAPPEN?"

Key Components:

predictive_trust_decision() - Pre-authorization predictive analysis
Counterfactual scenarios (deny, constrain, approve)
Causal dependency analysis (OBSERVED, VERIFIED, MODELED, INFERRED, UNKNOWN)
Policy-governed blast-radius thresholds

Analysis Dimensions:

WHO (identity, authority, delegation chain)
WHAT (proposed action, resource)
WHAT REACHABLE (through graph traversal)
WHAT AFFECTED (downstream resources)
WHAT IF DENIED/MODIFIED/APPROVED (counterfactuals)
WHAT UNKNOWN (uncertainty analysis)

Uncertainty Classification:

KNOWN: Evidence-backed, verified
OBSERVED: Directly observed
VERIFIED: Independently verified
MODELED: Model-based prediction
INFERRED: Extrapolated from evidence
UNKNOWN: No evidence available

Adversarial Resistance:

Graph poisoning detection
False dependency edges
Hidden resources
Authority escalation
Delegation escalation
Trust manipulation
Cross-tenant traversal

MOAT #6: ADVERSARIAL TRUST ENGINE#

Purpose: Continuously attack CAIN's own trust assumptions in controlled environments to discover authority escalation, context attacks, replay, graph poisoning, provenance failure, MCP/tool substitution, cross-tenant attacks, trust manipulation, and other failures.

Core Question: "CAN CAIN BREAK ITS OWN TRUST GUARANTEES, DETECT THE FAILURE, AND CONTAIN IT?"

Key Components:

adversarial_engine.py - Continuous attack testing
60+ deterministic attack types across 14 categories
Attack chaining with multi-step scenarios
Trust signal emission on verified violations
Predictive blast-radius comparison

Attack Categories: 1. IDENTITY - spoofing, substitution, credential misuse, context mismatch 2. AUTHORITY - privilege escalation, authority widening, unauthorized delegation 3. DELEGATION - escalation, transitive privilege, delegation replay 4. GRAPH - poisoning, false edges, hidden resources, cross-tenant traversal 5. TRAJECTORY - replay, manipulation, effect spoofing, gradual escalation 6. POLICY - bypass, stale policy, version substitution 7. TRUST - manipulation, state confusion, fake evidence 8. TOOL/MCP - substitution, identity spoofing, capability escalation 9. SECURITY_CONTEXT - mutation, substitution, widening, replay 10. PROVENANCE - substitution, evidence tampering, attestation replay 11. EXECUTION - stale authorization, effect mismatch, duplicate execution 12. MEMORY/EVIDENCE - poisoning, false provenance, signal injection 13. CROSS_TENANT - identity, authority, graph, evidence, trust traversal 14. COUNTERFACTUAL - manipulation, prediction poisoning

Attack Outcomes:

NOT_EXECUTED - Attack was not run
EXECUTED_AND_BLOCKED - Control held
EXECUTED_AND_DETECTED - Attack detected
EXECUTED_AND_CONTAINED - Attack contained
EXECUTED_AND_ESCAPED - Attack succeeded
FALSE_POSITIVE - Test infrastructure error
UNKNOWN - Cannot determine result
ERROR - Execution error

Feedback Loop:

ATTACK → DETECT → VERIFY → CONTAIN → EVIDENCE → TRUST UPDATE → RE-EVALUATE → PROVE

Anti-Gaming:

Verifies attacks actually executed
Distinguishes NOT_EXECUTED from blocked
Independent verification preferred over self-reported

MOAT #7: AUTONOMOUS TRUST CONTROL LOOP#

Purpose: Connect verified evidence, trust state, prediction, decisions, enforcement, execution, outcomes, adversarial results, and future trust into a governed continuous feedback loop.

Core Question: "CAN VERIFIED EXPERIENCE CONTINUOUSLY CHANGE FUTURE TRUST AND DECISIONS?"

Key Components:

cain_sentinel.py - Autonomous monitoring and response
cain_sentinel_api.py - REST API for sentinel operations
Incident lifecycle management
Recovery and re-verification workflows
Integration with all other moats

Control Loop:

DRIFT → DETECT → IMPACT → SENTINEL → CONTROL → ENFORCEMENT → RECOVERY → RE-VERIFICATION → EVIDENCE

Subsystem Integration:

Drift Engine: Detects configuration, model, policy drift
Impact Engine: Computes causal impact models
Adversarial Engine: Runs continuous attack tests
Trust Graph: Maintains relationship graph
Trust State: Computes evidence-backed trust
Provenance: Binds decisions to executions

Trust State Machine:

TRUSTED - System is fully trustworthy
DEGRADED - Trust is reduced, enhanced monitoring
AT_RISK - Trust is compromised, intervention needed
CONTAINED - Entity isolated, preventing spread
QUARANTINED - Entity severed, awaiting review
REVOKED - Trust explicitly revoked
RECOVERING - Remediation in progress
REVERIFYING - Trust re-verification running
RESTORED - Trust restored after incident
UNKNOWN - Cannot determine trust state

Response Actions:

MONITOR - Enhanced monitoring
ESCALATE - Manual review required
CONTAIN - Isolate to prevent spread
ISOLATE - Separate from other entities
QUARANTINE - Sever, awaiting review
REVOKE - Permanent trust revocation
ROLLBACK - Revert to previous state
RESTORE - Restore to trusted state
REVERIFY - Re-verify trust claims
ACCEPT - Accept current state
KILL - Terminate execution

Fail-Closed Principles:

Unknown/error must NEVER become TRUSTED
Missing Impact must NEVER become TRUSTED
Missing evidence must NEVER become TRUSTED
Verification failure must NEVER become TRUSTED
Authorization failure must NEVER become TRUSTED
Stale baseline must NEVER become TRUSTED
Unknown identity must NEVER become TRUSTED
Unknown policy must NEVER become TRUSTED
Ambiguous recovery must NEVER become TRUSTED
Unavailable Control service must NEVER become TRUSTED
Unknown/error must NEVER become ALLOW

Moat Dependencies#

┌─────────────────────────────────────────────────────────────────┐
│ MOAT #7: AUTONOMOUS CONTROL LOOP                                 │
│   Consumes outputs from all other moats                          │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #6: ADVERSARIAL ENGINE                                     │
│   Tests all other moats; emits trust signals                    │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #5: PREDICTIVE TRUST + BLAST RADIUS                       │
│   Pre-execution analysis; causal + counterfactual                │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #4: EXECUTION PROVENANCE + ATTESTATION                    │
│   Binds decision → execution → effect                           │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #3: TRUST GRAPH                                           │
│   Reachability, blast radius, graph relationships               │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #2: SECURITY-CONTEXT CONTINUITY                           │
│   Preserves identity, authority, context across boundaries     │
└─────────────────────────────────────────────────────────────────┘
         ▲
         │
┌────────┴────────────────────────────────────────────────────────┐
│ MOAT #1: TRUST STATE                                           │
│   Evidence-derived trust computation                            │
└─────────────────────────────────────────────────────────────────┘

Testing Requirements#

Every moat requires: 1. Acceptance tests - Core functionality works 2. Security tests - Attack vectors blocked 3. Tenant isolation tests - Cross-tenant access prevented 4. Stale-state tests - Expired data handled correctly 5. Graph integrity tests - Poisoning detected 6. Non-execution tests - Counterfactuals don't execute real actions

Evidence References#

Each moat produces durable, tenant-scoped evidence containing:

evidence_id - Unique identifier
tenant - Tenant scope
timestamp - When recorded
version - Data version for staleness
integrity_hash - Tamper detection

Evidence is never deleted, only superseded with new versions.

Governance#

All seven moats are governed by CAIN Policy. Policy changes require: 1. Proposed via governance mechanism 2. Approved by authorized actors 3. Applied atomically across all moats 4. Version tracked for rollback

No moat can be bypassed by policy. Policy governs the moats, but cannot disable them.