vm-cloudflare/CONTROL_PLANE_README.md

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

# Tools available
- dns_record_manage
- waf_rule_configure  
- tunnel_health_check
- zone_analytics_query

WAF Intelligence MCP

# Tools available
- waf_config_analyze
- threat_intel_integrate
- compliance_map_generate
- rule_gap_identify

Oracle Answer MCP

# 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.