# Cloudflare Control Plane

A programmable, verifiable, policy-driven Cloudflare operating system with MCP as the primary interface layer.

## 🏛️ Architecture Overview

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Intent Layer  │◄──►│   State Layer   │◄──►│  Verify Layer   │
│  (MCP Servers)  │    │   (Terraform)   │    │ (Invariants)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  GitOps Layer   │◄──►│  Cloudflare API │◄──►│ Security Layer  │
│  (Automation)   │    │   (Live State)  │    │   (Layer0)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## 🎯 Core Components

### MCP Interface Layer (Intent)
- **`cloudflare.mcp.cloudflare_safe`**: State mutation operations
- **`cloudflare.mcp.waf_intelligence`**: Analysis & rule synthesis
- **`cloudflare.mcp.oracle_answer`**: Security decision support

### Terraform State Layer (Desired State)
- **DNS Management**: Automated DNS, SPF/DMARC, tunnel routing
- **WAF Security**: Custom rules + managed rulesets
- **Tunnel Infrastructure**: Multi-service ingress routing
- **Bot Management**: Automated detection & mitigation

### GitOps Automation Layer (Change Propagation)
- **WAF Rule Proposer**: Threat-intel driven rule generation
- **Invariant Checker**: Real-time state validation
- **Drift Guardian**: Automated remediation
- **CI/CD Integration**: GitHub Actions + GitLab CI

### Security Framework Layer (Verification)
- **Layer0**: Pre-execution security classification
- **Shadow Classifier**: Threat assessment
- **Preboot Logger**: Security event tracking
- **Invariant Validation**: Continuous compliance checking

## 🔄 Operational Flows

### Threat Intelligence → WAF Enforcement
```
Threat Intel → WAF Proposal → MR Review → Terraform Apply → Invariant Check → Remediation
```

### DNS/Tunnel Management
```
Service Definition → Tunnel Config → DNS Routing → Health Monitoring → Rotation
```

### Security Classification
```
Query → Layer0 Classification → Routing Decision → Execution/Block → Logging
```

## 🛡️ Security Posture

### Risk Mitigations
- **Token Scoping**: Least-privilege API tokens
- **Rate Limiting**: API call throttling
- **Audit Trail**: Comprehensive logging
- **Invariant Checks**: Real-time compliance validation

### Compliance Frameworks
- PCI-DSS 6.6
- OWASP-ASVS 13
- Zero-trust architecture

## 🚀 MCP Server Capabilities

### Cloudflare Safe MCP
```bash
# Tools available
- dns_record_manage
- waf_rule_configure  
- tunnel_health_check
- zone_analytics_query
```

### WAF Intelligence MCP
```bash
# Tools available
- waf_config_analyze
- threat_intel_integrate
- compliance_map_generate
- rule_gap_identify
```

### Oracle Answer MCP
```bash
# Tools available
- security_classify
- routing_decide
- threat_assess
- decision_support
```

## 📊 Monitoring & Observability

### Key Metrics
- DNS resolution latency
- WAF rule effectiveness
- Tunnel health status
- API rate limit utilization
- Invariant compliance rate

### Alerting Triggers
- Invariant violations
- Tunnel connectivity issues
- WAF rule deployment failures
- Security classification anomalies

## 🔧 Development & Extension

### Adding New MCP Servers
1. Follow wrapper pattern in `/.secret/mcp/template.sh`
2. Add health checks and PYTHONPATH injection
3. Register in OpenCode configuration
4. Add to smoke test (`/test_mcp_servers.sh`)

### Extending Terraform Modules
- Maintain compatibility with existing state
- Add corresponding invariant checks
- Update GitOps automation

### Security Framework Integration
- Extend Layer0 classification rules
- Add new threat intelligence sources
- Enhance compliance mappings

## 🎯 Production Readiness

### ✅ Completed
- Deterministic MCP interfaces
- GitOps automation pipeline
- Real-time invariant checking
- Security classification framework

### 🔄 Operational Excellence
- Automated remediation
- Comprehensive monitoring
- Audit trail preservation
- Compliance validation

This control plane represents a **foundational infrastructure layer** that can support higher-level automation, agent systems, and compliance proofs without architectural changes.