CAIN Control

All docs

CAIN Control Documentation#

Status: PRODUCTION#

CAIN Control is production-ready. It provides the authorization layer that answers WHAT an actor is allowed to do, UNDER WHAT CONDITIONS, and WHO CAN STOP IT.

---

What is CAIN Control?#

CAIN Control is the permission and control layer for CAIN Trust Fabric:

• CAIN Identity answers: WHO is acting?
• CAIN Control answers: WHAT is that actor allowed to do, and WHO CAN STOP IT?

IDENTITY → CONTROL → POLICY → RISK → DECISION → ENFORCEMENT → ACTION → EVIDENCE

---

Core Capabilities#

Agent Controls#

• Pause / resume / kill agents
• Set action frequency limits
• Set concurrent action limits
• View agent control status

Tool Controls#

• Enable / disable tools
• Set risk levels
• Require approval for high-risk tools
• Restrict tools to specific agents
• Restrict tools to specific identities
• Associate tools with policies

Policy Management#

• Create / update / version policies
• Activate / deactivate policies
• Rollback to previous versions
• Full policy audit history

Kill Switch#

• Tenant-wide emergency stop
• Immediately blocks all consequential actions
• Cannot be bypassed

---

Architecture#

┌─────────────────────────────────────────────────────────────────┐
│                     CAIN Control                                  │
├─────────────────────────────────────────────────────────────────┤
│  Control Engine                                                  │
│  ├── Agent state management (active/paused/killed)              │
│  ├── Tool enable/disable                                        │
│  ├── Policy evaluation                                          │
│  ├── Kill switch                                                │
│  └── Rate limiting                                              │
│                                                                  │
│  Control API                                                    │
│  ├── /fabric/control/agents/*    - Agent controls              │
│  ├── /fabric/control/tools/*     - Tool controls                │
│  ├── /fabric/control/policies/* - Policy management            │
│  ├── /fabric/control/kill-switch - Emergency stop              │
│  └── /fabric/control/evaluate    - Control decisions           │
│                                                                  │
│  Integration                                                    │
│  └── CAIN Identity → CAIN Control → CAIN Enforcement           │
└─────────────────────────────────────────────────────────────────┘

---

API Reference#

Kill Switch#

# Check kill switch status
curl https://cainstudio.online/fabric/control/kill-switch \
  -H "X-API-Key: your-key"

# Activate kill switch
curl -X POST https://cainstudio.online/fabric/control/kill-switch/activate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "security incident"}'

# Deactivate kill switch
curl -X POST https://cainstudio.online/fabric/control/kill-switch/deactivate \
  -H "X-API-Key: your-key"

Agent Controls#

# Pause an agent
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/pause \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "maintenance"}'

# Resume an agent
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/resume \
  -H "X-API-Key: your-key"

# Kill an agent (permanent)
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/kill \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "compromised"}'

# List agent controls
curl https://cainstudio.online/fabric/control/agents \
  -H "X-API-Key: your-key"

Tool Controls#

# Create tool control
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_level": "high",
    "requires_approval": true,
    "allowed_agents": ["agent:xxx"],
    "allowed_identities": ["urn:cain:identity:agent:yyy"]
  }'

# Disable tool
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool/disable \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "vulnerability found"}'

# Enable tool
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool/enable \
  -H "X-API-Key: your-key"

Policies#

# Create policy
curl -X POST https://cainstudio.online/fabric/control/policies \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "high-risk-tool-policy",
    "description": "Restricts high-risk tool usage",
    "rules": [
      {"action": "tool:write", "risk_level": "high", "requires_approval": true}
    ]
  }'

# Activate policy
curl -X POST https://cainstudio.online/fabric/control/policies/pol:xxx/activate \
  -H "X-API-Key: your-key"

# Rollback policy
curl -X POST https://cainstudio.online/fabric/control/policies/pol:xxx/rollback?version=2 \
  -H "X-API-Key: your-key"

Control Evaluation#

# Evaluate (records decision)
curl -X POST https://cainstudio.online/fabric/control/evaluate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "urn:cain:identity:agent:xxx",
    "agent_id": "agent:yyy",
    "action": "tool:read",
    "tool": "my-tool"
  }'

# Simulate (no recording, no execution)
curl -X POST https://cainstudio.online/fabric/control/simulate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "urn:cain:identity:agent:xxx",
    "agent_id": "agent:yyy",
    "action": "tool:read",
    "tool": "my-tool"
  }'

---

Fail-Closed Behavior#

CAIN Control is fail-closed. The following ALWAYS result in DENY:

• Tenant kill switch active
• Agent is paused
• Agent is killed
• Tool is disabled
• Identity not in allowed list
• Agent not in allowed list
• Control service unavailable

Only ALLOW permits execution.

---

Integration with CAIN Enforcement#

CAIN Control integrates with make_cain_decision in CAIN Private:

Request Action
    ↓
CAIN Identity (verify WHO)
    ↓
CAIN Control (verify WHAT allowed)
    ↓
CAIN Enforcement (ALLOW/DENY)
    ↓
Execute or Block
    ↓
Evidence

---

Security Properties#

Property	Implementation
Fail-closed	Unknown/error = DENY
Kill switch	Tenant-wide, immediate
Tenant isolation	Tenant from API key hash
Audit trail	Full decision and action history
No bypass	Control is enforcement gate

---

See Also#

• CAIN Identity - Verifiable identity
• CAIN Private - Private AI agent environment
• CAIN Architecture - Trust Fabric overview