vm-cloudflare/gitops/README.md

Phase 6 - GitOps PR Workflows

Cloudflare Mesh Observatory - Automated Drift Remediation & Plan Comments

Overview

Phase 6 completes the observability feedback loop by converting alerts and drift detection into actionable Merge Requests.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Observatory │────▶│   Alerts    │────▶│   GitOps    │
│  (Phase 5A) │     │  (Phase 5B) │     │  (Phase 6)  │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │
       │                   │                   ▼
       │                   │            ┌─────────────┐
       │                   │            │  Drift PR   │
       │                   │            │  Created    │
       │                   │            └─────────────┘
       │                   │                   │
       │                   │                   ▼
       │                   │            ┌─────────────┐
       │                   └───────────▶│  Review &   │
       │                                │   Merge     │
       │                                └─────────────┘
       │                                       │
       └───────────────────────────────────────┘
                   Terraform Apply

Components

File	Purpose
config.yml	GitOps configuration, risk classification, compliance mapping
plan_summarizer.py	Parses terraform plan JSON, scores risk, generates markdown
drift_pr_bot.py	Creates drift remediation MRs in GitLab/GitHub
ci_plan_comment.py	Posts plan summaries as MR comments
webhook_receiver.py	Receives Alertmanager webhooks, triggers pipelines

Quick Start

1. Configure Environment

# Copy and edit config
cd ~/Desktop/CLOUDFLARE/gitops
cp config.yml config.local.yml  # optional local override

# Set environment variables
export GITLAB_TOKEN="glpat-xxxx"
export GITLAB_PROJECT_ID="12345678"
export SLACK_WEBHOOK_URL="https://hooks.slack.com/..."

2. Test Plan Summarizer

# Generate a terraform plan first
cd ../terraform
terraform init
terraform plan -out=plan.tfplan

# Run summarizer
cd ../gitops
python3 plan_summarizer.py --format markdown
python3 plan_summarizer.py --format json

3. Test Drift PR Bot (Dry Run)

python3 drift_pr_bot.py --dry-run

4. Start Webhook Receiver (Optional)

python3 webhook_receiver.py --port 8080
# POST to http://localhost:8080/webhook/alert

Configuration Reference

Risk Classification

The config.yml maps Cloudflare resources to risk levels:

risk:
  dns:
    resource_types:
      - "cloudflare_record"
      - "cloudflare_zone"
    base_risk: "high"

  waf:
    resource_types:
      - "cloudflare_waf_rule"
      - "cloudflare_firewall_rule"
    base_risk: "high"

  actions:
    create:
      modifier: 0      # Neutral
    update:
      modifier: 1      # +1 level
    delete:
      modifier: 2      # +2 levels (always dangerous)

Compliance Frameworks

Map resources/actions to compliance frameworks:

compliance:
  frameworks:
    - name: "SOC2"
      triggers:
        - resource_types: ["cloudflare_zone_settings_override"]
          fields: ["ssl", "always_use_https"]
        - resource_types: ["cloudflare_waf_rule"]
          actions: ["delete"]

    - name: "PCI-DSS"
      triggers:
        - resource_types: ["cloudflare_zone_settings_override"]
          fields: ["min_tls_version"]

Drift PR Settings

drift_pr:
  branch_prefix: "drift/remediation-"
  title_prefix: "Drift Remediation"
  labels:
    - "drift"
    - "terraform"

  # Auto-assign reviewers by category
  reviewer_mapping:
    dns: ["dns-team"]
    waf: ["security-team"]
    tunnels: ["infra-team"]

GitLab CI Integration

Three jobs are added to .gitlab-ci.yml:

1. Plan Comment on MRs

gitops:plan_comment:
  stage: gitops
  script:
    - python3 gitops/ci_plan_comment.py
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Posts a rich markdown comment showing:

• Overall risk level
• Action breakdown (create/update/delete)
• Affected zones
• Compliance flags
• Resource change table

2. Drift Remediation

gitops:drift_remediation:
  stage: gitops
  script:
    - python3 gitops/drift_pr_bot.py
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule" && $GITOPS_DRIFT_CHECK == "true"
    - if: $CI_PIPELINE_SOURCE == "trigger" && $GITOPS_TRIGGER_SOURCE == "alert"

Triggered by:

• Scheduled pipelines (daily drift check)
• Alertmanager webhooks (alert-triggered)

3. Risk Gate

gitops:risk_gate:
  stage: gitops
  script:
    - |
      RISK=$(python3 plan_summarizer.py --format json | ...)
      if [ "$RISK" = "CRITICAL" ]; then
        exit 1
      fi
  allow_failure: true

Blocks auto-merge for CRITICAL risk changes.

Alertmanager Integration

Add Webhook Receiver

Add to observatory/alertmanager/alertmanager.yml:

receivers:
  - name: 'gitops-webhook'
    webhook_configs:
      - url: 'http://gitops-webhook:8080/webhook/alert'
        send_resolved: false

Route Drift Alerts

route:
  routes:
    - match:
        alertname: DNSDriftDetected
      receiver: 'gitops-webhook'
      continue: true

    - match:
        alertname: WAFRuleMissing
      receiver: 'gitops-webhook'
      continue: true

Output Examples

MR Comment

## 🟠 Terraform Plan Summary

**Overall Risk:** 🟠 **HIGH**
**Total Changes:** `5`

**Actions:** create=2, update=2, delete=1

**By Category:**
- dns: 3
- waf: 2

**Affected Zones:** `example.com`, `staging.example.com`

**Compliance Impact:**
- ⚠️ SOC2
- ⚠️ PCI-DSS

### Resource Changes

| Resource | Actions | Risk | Compliance |
|----------|---------|------|------------|
| `cloudflare_record.api` | `delete` | **CRITICAL** | SOC2 |
| `cloudflare_waf_rule.sqli` | `update` | **HIGH** | PCI-DSS |
...

JSON Output

{
  "total_changes": 5,
  "overall_risk": "HIGH",
  "by_action": {"create": 2, "update": 2, "delete": 1},
  "by_risk": {"LOW": 1, "MEDIUM": 1, "HIGH": 2, "CRITICAL": 1},
  "by_category": {"dns": 3, "waf": 2},
  "affected_zones": ["example.com", "staging.example.com"],
  "compliance_violations": ["SOC2", "PCI-DSS"],
  "changes": [...]
}

Environment Variables

Variable	Required	Description
GITLAB_TOKEN	Yes	GitLab API token with api scope
GITLAB_PROJECT_ID	Yes	Target project ID
GITLAB_BASE_URL	No	GitLab instance URL (default: gitlab.com)
GITLAB_TRIGGER_TOKEN	No	For pipeline triggers from webhooks
SLACK_WEBHOOK_URL	No	Slack notifications
GITOPS_DRY_RUN	No	Set true to skip actual PR creation
WEBHOOK_SECRET	No	HMAC secret for webhook verification

Security Considerations

1. Token Scope: Use minimal GitLab token scope (api for MR creation)
2. Webhook Security: Set WEBHOOK_SECRET for signature verification
3. Review Before Merge: Always review auto-generated PRs
4. Compliance Blocking: Consider block_on_violation: true for strict mode

Troubleshooting

Plan Summarizer Fails

# Check terraform plan exists
ls -la terraform/plan.tfplan

# Run terraform show manually
cd terraform
terraform show -json plan.tfplan | head -100

MR Comment Not Posted

# Check CI variables are set
echo $GITLAB_TOKEN
echo $CI_MERGE_REQUEST_IID

# Run comment script manually
python3 ci_plan_comment.py --dry-run

Webhook Not Triggering

# Check webhook receiver logs
curl -X POST http://localhost:8080/webhook/alert \
  -H "Content-Type: application/json" \
  -d '{"alerts":[{"labels":{"alertname":"DNSDriftDetected"}}]}'

# Check Alertmanager config
amtool config show

Next Phases

• Phase 7 (WAF Intelligence): ML-lite analysis of attack patterns
• Phase 8 (Zero Trust Auditor): Identity policy compliance
• Phase 9 (VaultMesh Integration): ProofChain anchoring

---

Phase 6 GitOps - Cloudflare Mesh Observatory