vm-cloudflare/USAGE_GUIDE.md

Cloudflare MCP Tools Usage Guide

🚀 Quick Start

1. Configure Environment

# Copy and edit the environment file
cp .env.example .env

# Edit with your Cloudflare credentials
nano .env

Required Credentials:

• CLOUDFLARE_API_TOKEN: API token with Zone:Read, Zone:Write permissions
• CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID

2. Load Environment

# Source the environment
source .env

# Set Python path for MCP servers
export PYTHONPATH="/Users/sovereign/work-core"

🔧 Available MCP Tools

Cloudflare Safe MCP (cloudflare.mcp.cloudflare_safe)

Tools for managing Cloudflare infrastructure:

1. Take Snapshot of Current State

python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

# Set environment
os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_snapshot(scopes=['zones', 'tunnels', 'access_apps'])
print('Snapshot ID:', result['data']['snapshot_id'])
print('Summary:', result['summary'])
"

2. List DNS Zones

python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_snapshot(scopes=['zones'])
zones = result['data']['counts']['zones']
print(f'Found {zones} DNS zones')
"

3. Check Tunnel Status

python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ['CLOUDFLARE_API_TOKEN'] = 'your_token'
os.environ['CLOUDFLARE_ACCOUNT_ID'] = 'your_account_id'

server = CloudflareServer()
result = server.cf_tunnel_status()
print('Tunnel status:', result)
"

WAF Intelligence MCP (cloudflare.mcp.waf_intelligence.mcp_server)

Tools for security analysis and rule generation:

1. Analyze WAF Configuration

python3 -m cloudflare.mcp.waf_intelligence.mcp_server --file terraform/waf.tf --format text

2. Generate Security Rules

python3 -c "
from cloudflare.mcp.waf_intelligence.orchestrator import WAFIntelligence

waf_intel = WAFIntelligence()
analysis = waf_intel.analyze_and_recommend('terraform/waf.tf')
print('Security recommendations:', analysis)
"

🌐 Setting Up Domains

1. Configure DNS Records via Terraform

Example DNS Configuration:

# terraform/dns.tf
resource "cloudflare_zone" "domains" {
  for_each = toset(["vaultmesh.org", "offsec.global"])
  
  zone = each.key
  plan = "free"
}

resource "cloudflare_record" "root_a" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "@"
  value   = "192.168.1.100"  # Your server IP
  type    = "A"
  proxied = true
}

2. Apply DNS Configuration

# Initialize Terraform
terraform init

# Plan changes
terraform plan

# Apply DNS configuration
terraform apply

🛡️ Configuring WAF Security

1. Basic WAF Rules

# terraform/waf.tf
resource "cloudflare_ruleset" "security_rules" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "Security Rules"
  kind    = "zone"
  phase   = "http_request_firewall_custom"

  # Block admin access from untrusted IPs
  rules {
    action      = "block"
    expression  = "(http.request.uri.path contains '/admin') and not (ip.src in {192.168.1.1 10.0.0.1})"
    description = "Block admin access from untrusted IPs"
    enabled     = true
  }
}

2. Enable Managed WAF

resource "cloudflare_ruleset" "managed_waf" {
  for_each = cloudflare_zone.domains
  
  zone_id = each.value.id
  name    = "Managed WAF"
  kind    = "zone"
  phase   = "http_request_firewall_managed"

  # Cloudflare Managed Ruleset
  rules {
    action = "execute"
    action_parameters {
      id = "efb7b8c949ac4650a09736fc376e9aee"
    }
    expression  = "true"
    description = "Execute Cloudflare Managed Ruleset"
    enabled     = true
  }
}

🌉 Setting Up Cloudflare Tunnels

1. Configure Tunnels

# terraform/tunnels.tf
resource "cloudflare_tunnel" "vaultmesh" {
  account_id = local.account_id
  name       = "vaultmesh-tunnel"
  secret     = var.tunnel_secret_vaultmesh
}

resource "cloudflare_tunnel_config" "vaultmesh" {
  account_id = local.account_id
  tunnel_id  = cloudflare_tunnel.vaultmesh.id

  config {
    # API endpoint
    ingress_rule {
      hostname = "api.vaultmesh.org"
      service  = "http://localhost:8080"
    }
    
    # Dashboard
    ingress_rule {
      hostname = "dash.vaultmesh.org"
      service  = "http://localhost:3000"
    }
  }
}

2. Generate Tunnel Secrets

# Generate secure tunnel secrets
openssl rand -base64 32

# Add to your .env file
TUNNEL_SECRET_VAULTMESH="generated_secret_here"

🔍 Monitoring and Validation

1. Check Current State

# Use the invariant checker to validate configuration
python3 scripts/invariant_checker_py.py

2. Monitor Tunnel Health

# Check tunnel status via MCP
python3 -c "
from cloudflare.mcp.cloudflare_safe.server import CloudflareServer
import os

os.environ.update({
    'CLOUDFLARE_API_TOKEN': 'your_token',
    'CLOUDFLARE_ACCOUNT_ID': 'your_account_id'
})

server = CloudflareServer()
status = server.cf_tunnel_status()
print('Tunnel health:', status)
"

🚨 Common Operations

Adding New Domain

1. Add to Terraform zones list
2. Run terraform apply
3. Verify DNS propagation
4. Configure WAF rules

Updating Security Rules

1. Modify terraform/waf.tf
2. Run terraform plan to preview
3. Apply with terraform apply
4. Validate with WAF Intelligence MCP

Tunnel Management

1. Generate new tunnel secret
2. Update Terraform configuration
3. Apply changes
4. Verify connectivity

📊 Best Practices

Security

• Use least-privilege API tokens
• Enable 2FA on Cloudflare account
• Regular security audits with WAF Intelligence
• Monitor access logs

Operations

• Test changes in staging first
• Use Terraform for all infrastructure changes
• Regular backups of Terraform state
• Monitor tunnel health

Monitoring

• Set up Cloudflare analytics
• Monitor WAF rule effectiveness
• Track DNS resolution times
• Alert on security events

🆘 Troubleshooting

Common Issues

API Token Errors

# Verify token permissions
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
     -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Tunnel Connectivity

# Check cloudflared service status
cloudflared tunnel list

DNS Issues

# Verify DNS resolution
dig yourdomain.com

This guide provides the foundation for managing your Cloudflare infrastructure using the MCP tools. Start with basic DNS setup, then progressively add WAF rules and tunnels as needed.