☁️ Cloudflare Executive Report

Turn Cloudflare analytics into executive-ready PDF reports with security scores, NIST mappings, and multi-zone portfolio views.

🎯 Why this tool exists

Cloudflare dashboard data is great for daily ops, but executives need more:

Cloudflare Executive Report fills that gap with local caching and deterministic PDF generation.

✨ What you get

📊 See it in action

Try the sample reports (generated from synthetic data):

*SVG/high quality = larger file size, sharper visuals for printing

🚀 Quick start (30 seconds)

pip install cloudflare-executive-report
cf-report init
cf-report sync --last 30
cf-report report -o security-report.pdf

That's it. You just generated your first executive report.

🎚️ Report profiles (choose your depth)

🔐 API token setup

Create a read-only API token in Cloudflare Dashboard → Manage Account → Account API Tokens

Required permissions

✅ Required = Tool won't work | ⚠️ Recommended = Full features | ℹ️ Nice-to-have = Better validation

Quick validation

# Shows exactly which permissions you have
cf-report validate

Security notes

• 🔒 Read-only only - The tool never needs write permissions
• 💾 All data stays local - Cached in ~/.cf-report/, no telemetry
• 📖 Full security guide → - Step-by-step token creation, data storage details, and security checklist

📈 How scoring works

Only risk takeaways affect your score. Everything else (win, action, comparison, observation) is informational.

Score = max(0, 100 - (total_risk_weight / 60) * 100)

⏱️ Data retention (by Cloudflare plan)

Days outside these windows = unavailable (cached, no API calls)

⚙️ Quick config (~/.cf-report/config.yaml)

api_token: "cfat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
cache_dir: "~/.cf-report/cache"
history_dir: "~/.cf-report/history"
log_level: "info"
exclude_types:
  - email

zones:
  - id: "abc123..."
    name: "example.com"

pdf:
  profile: "executive" # minimal | executive | detailed
  chart_format: "png" # png | svg
  map_format: "png" # png | svg
  colors:
    primary: "#2563eb" # your brand color
    accent: "#f38020"

email:
  enabled: true
  smtp_host: "smtp.example.com"
  recipients:
    - "security@example.com"

ai-summary:
  enabled: true
  model: "openrouter/google/gemma-2-9b-it:free"

🛠️ CLI cheat sheet

# Sync data
cf-report sync --last 30                    # Last 30 days
cf-report sync --zone example.com --last 7  # Single zone

# Generate report
cf-report report -o report.pdf              # Basic PDF
cf-report report -o report.pdf --email      # PDF + email
cf-report report -o report.pdf --profile minimal  # Override PDF profile
cf-report report --exclude-types email,cache # Exclude specific streams
cf-report report --skip-zone-health         # Skip health checks

# Manage zones
cf-report zones list
cf-report zones add --id abc123 --name example.com

# Clean cache
cf-report clean --older-than 90

# Generate report with AI summary and send it by email
cf-report report -o report.pdf --email --ai-summary

📚 Documentation

❓ Common questions

How accurate are the metrics? Trend-oriented approximations. Use for executive posture guidance, not packet-level forensics.

Can I run this in CI/CD? Yes - works headless. Set CF_REPORT_API_TOKEN (preferred) and pass --config to a non-secret config file.

What if I have 100+ zones? Works fine. Sync may take a while initially, but caching helps.

📦 Links

• PyPI
• GitHub
• Issues

📄 License

MIT - go wild. See LICENSE.