326 lines
6.8 KiB
Markdown
326 lines
6.8 KiB
Markdown
# Cloudflare MCP Tools Usage Guide
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Configure Environment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
python3 -m cloudflare.mcp.waf_intelligence.mcp_server --file terraform/waf.tf --format text
|
|
```
|
|
|
|
#### 2. Generate Security Rules
|
|
```bash
|
|
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:**
|
|
|
|
```hcl
|
|
# 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
|
|
|
|
```bash
|
|
# Initialize Terraform
|
|
terraform init
|
|
|
|
# Plan changes
|
|
terraform plan
|
|
|
|
# Apply DNS configuration
|
|
terraform apply
|
|
```
|
|
|
|
## 🛡️ Configuring WAF Security
|
|
|
|
### 1. Basic WAF Rules
|
|
|
|
```hcl
|
|
# 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
|
|
|
|
```hcl
|
|
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
|
|
|
|
```hcl
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Use the invariant checker to validate configuration
|
|
python3 scripts/invariant_checker_py.py
|
|
```
|
|
|
|
### 2. Monitor Tunnel Health
|
|
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# Verify token permissions
|
|
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
|
|
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
|
|
```
|
|
|
|
**Tunnel Connectivity**
|
|
```bash
|
|
# Check cloudflared service status
|
|
cloudflared tunnel list
|
|
```
|
|
|
|
**DNS Issues**
|
|
```bash
|
|
# 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. |