chore: pre-migration snapshot
Layer0, MCP servers, Terraform consolidation
This commit is contained in:
Vault Sovereign
326
USAGE_GUIDE.md
Normal file
326
USAGE_GUIDE.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user