Developer documentation

7-Moat Architecture

Last reviewed 31 August 2026

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.