Validate edge config candidates

Author: RamazanKara

CHANGELOG.md

@@ -29,6 +29,7 @@
 - Added fixture integration evidence refs and validation coverage for integration evidence.
 - Added Forgejo migration candidate validation for the GitHub Enterprise assessment path.
 - Added identity realm/client candidate validation for the Okta/Auth0 assessment path.
+- Added edge VCL, HAProxy, and Coraza candidate validation for the Cloudflare/Akamai assessment path.
 - Updated CI and release workflows to Node.js 24-native GitHub Actions.
 
 ## 0.1.0 - 2026-05-24

README.md

@@ -116,7 +116,7 @@ Included in the current implementation:
 - OpenTelemetry Collector sketch.
 - ArgoCD starter manifest.
 - Typed migration plan manifest and phase-gate Markdown plan.
-- Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, and identity realm/client candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
+- Validation report with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, and edge VCL/HAProxy/Coraza candidate checks, YAML/JSON parsing, evidence ref checks, secret scan, and optional `promtool`/`kubeconform` checks.
 - Evidence bundle export.
 - Evidence bundle path-safety checks that reject symlinks in exported project sections.
 - No-op assist provider and explicit opt-in LiteLLM assist.
@@ -162,7 +162,7 @@ GitHub Enterprise to Forgejo collects repository, team, branch protection, Actio
 
 Okta/Auth0 to Keycloak/Zitadel collects applications, SAML/OIDC client metadata, groups, policies, MFA settings, redirect URIs, owners, and break-glass account metadata from live Okta/Auth0 APIs or local fixtures. It generates identity migration risk, validated realm/client candidate config, break-glass, cutover, and rollback artifacts.
 
-Cloudflare/Akamai to Varnish/HAProxy/Coraza collects DNS records, WAF rules, cache rules, redirects, origins, TLS settings, bot rules, and page rules from live Cloudflare/Akamai APIs or local fixtures. The Akamai collector uses read-only EdgeGrid-authenticated calls for Edge DNS, Property Manager, and optional AppSec metadata. It generates VCL, HAProxy, Coraza, cache parity, and WAF enforcement review artifacts.
+Cloudflare/Akamai to Varnish/HAProxy/Coraza collects DNS records, WAF rules, cache rules, redirects, origins, TLS settings, bot rules, and page rules from live Cloudflare/Akamai APIs or local fixtures. The Akamai collector uses read-only EdgeGrid-authenticated calls for Edge DNS, Property Manager, and optional AppSec metadata. It generates validated VCL, HAProxy, Coraza, cache parity, and WAF enforcement review artifacts.
 
 OpenAI/Anthropic to vLLM/LiteLLM collects model usage classes, token volumes, latency expectations, sensitive prompt categories, tool usage, and fallback behavior from local fixtures. It can also collect model-grouped aggregate OpenAI completions usage, aggregate Anthropic Messages API usage, available model metadata where exposed, server web-search tool metadata, and hourly peak estimates from live provider APIs without storing prompts or credentials. The path generates self-hosted LLM readiness, LiteLLM routing, vLLM sizing, evaluation, and data sensitivity artifacts.
 

docs/architecture.md

@@ -12,7 +12,7 @@ GitHub Enterprise to Forgejo keeps the same local-first collect, normalize, anal
 
 Okta/Auth0 to Keycloak/Zitadel reuses the same normalized inventory and evidence model, but generates identity-specific planning artifacts and a candidate realm/client YAML instead of Datadog target configs. It supports fixture import and read-only live Okta/Auth0 collectors.
 
-Cloudflare/Akamai to Varnish/HAProxy/Coraza generates edge-specific VCL, HAProxy, and Coraza candidate files plus cache and WAF review reports. It supports fixture import plus read-only live Cloudflare and Akamai collectors.
+Cloudflare/Akamai to Varnish/HAProxy/Coraza generates and validates edge-specific VCL, HAProxy, and Coraza candidate files plus cache and WAF review reports. It supports fixture import plus read-only live Cloudflare and Akamai collectors.
 
 OpenAI/Anthropic to vLLM/LiteLLM generates AI provider readiness, LiteLLM routing, vLLM sizing, evaluation, and data sensitivity artifacts. It supports fixture import plus read-only live OpenAI/Anthropic aggregate usage collectors.
 

docs/cli.md

@@ -27,11 +27,11 @@ The CI test suite also runs this definition-of-done pipeline against the fixture
 
 The checked-in Datadog example can be refreshed with `make example VERSION=0.1.0-dev`. CI also runs `make example-smoke` as part of `make verify` to ensure the example fixture still completes the full pipeline.
 
-`openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, identity realm/client candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
+`openexit validate` performs typed consistency checks, embedded JSON Schema validation, Grafana dashboard candidate validation, Prometheus alert-rule candidate validation, OpenTelemetry collector candidate validation, ArgoCD candidate validation, Forgejo migration candidate validation, identity realm/client candidate validation, edge VCL/HAProxy/Coraza candidate validation, YAML/JSON parse checks, evidence reference checks, secret scanning, and optional external tool checks when `promtool` or `kubeconform` are installed.
 
 `openexit export` refuses to package symlinks from exported project sections, even with `--force`, so evidence bundles cannot accidentally include files from outside the project tree.
 
-Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`; the identity path also supports `realm-client-candidate`.
+Generate individual artifacts with `openexit generate --artifact <name>`. The primary Datadog path supports `mapping`, `assessment`, `risk-register`, `manual-review`, `cost-drivers`, `target-architecture`, `acceptance-criteria`, `rollback-plan`, `runbook`, `restore-drill-checklist`, `alert-shadowing-plan`, `migration-plan`, `grafana-dashboards`, `prometheus-rules`, `opentelemetry`, and `argocd`. The GitHub Enterprise path also supports `forgejo-migration-candidate`; the identity path also supports `realm-client-candidate`; the edge path also supports `vcl-candidates`, `haproxy-candidates`, and `coraza-rule-candidates`.
 
 The GitHub Enterprise to Forgejo fixture path uses local JSON metadata:
 

docs/cloudflare-akamai-to-varnish-haproxy-coraza.md

@@ -50,4 +50,6 @@ Generated artifacts:
 - `cache-parity-report.md`
 - `waf-enforcement-risk-report.md`
 
+Validation checks edge candidates for OpenExit review markers, absence of secret-like content, Varnish backend/cache/page-rule coverage, HAProxy redirect/origin/TLS/health-check coverage, Coraza WAF/bot-rule coverage, and preserved evidence refs.
+
 The assessment flags wildcard and high-TTL DNS records, observe-only or managed WAF rules, challenge actions, cache-key parity issues, redirect pattern translation, origin TLS gaps, low TLS versions, disabled HSTS, and coupled page-rule behavior.

docs/release.md

@@ -16,7 +16,7 @@ Release-blocking v0.1 requirements:
 - Markdown handover artifacts.
 - Grafana, Prometheus, OpenTelemetry, and ArgoCD candidate generators.
 - Typed migration plan manifest with assessment, pilot, shadow, and cutover phase gates.
-- Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, and identity realm/client candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
+- Validation engine with embedded JSON Schema checks, Grafana dashboard, Prometheus alert, OpenTelemetry collector, ArgoCD, Forgejo migration, identity realm/client, and edge VCL/HAProxy/Coraza candidate checks, YAML/JSON parsing, evidence refs, secret scan, optional promtool, and optional kubeconform.
 - Evidence bundle export with checksums and OpenExit version metadata.
 - No-op AI assist and optional external assist behind explicit opt-in.
 - Documentation, examples, CI, release draft workflow, and reproducible release artifacts.
@@ -53,6 +53,7 @@ The AI provider path is complete for local fixture assessment workflows and incl
 - [ ] `validation/validation-report.md` includes `argocd-candidate: passed` for the Datadog definition-of-done pipeline.
 - [ ] `validation/validation-report.md` includes `forgejo-migration-candidate: passed` for the GitHub Enterprise to Forgejo pipeline.
 - [ ] `validation/validation-report.md` includes `identity-realm-client-candidate: passed` for the Okta/Auth0 to Keycloak/Zitadel pipeline.
+- [ ] `validation/validation-report.md` includes `edge-candidates: passed` for the Cloudflare/Akamai to Varnish/HAProxy/Coraza pipeline.
 - [ ] `CHANGELOG.md` has a `0.1.0` section.
 - [ ] Exported bundle README includes version, commit, build date, bundle timestamp, and candidate warning.
 - [ ] Export refuses symlinks in exported project sections, including when `--force` is used.

internal/app/e2e_test.go

@@ -618,20 +618,7 @@ func TestValidationRejectsBrokenIdentityClientCandidate(t *testing.T) {
 
 func TestEdgeFixturePipeline(t *testing.T) {
 	projectDir := filepath.Join(t.TempDir(), "edge-demo")
-	fixturePath := filepath.Join("..", "..", "testdata", "edge", "small.json")
-
-	commands := [][]string{
-		{"init", projectDir, "--source", "edge", "--target", "varnish-haproxy-coraza"},
-		{"collect", "edge-fixture", "--project", projectDir, "--input", fixturePath},
-		{"assess", "--project", projectDir, "--target", "varnish-haproxy-coraza"},
-		{"generate", "--project", projectDir, "--all"},
-		{"validate", "--project", projectDir},
-	}
-	for _, args := range commands {
-		if err := executeForTest(args...); err != nil {
-			t.Fatalf("openexit %s failed: %v", strings.Join(args, " "), err)
-		}
-	}
+	runEdgeFixturePipeline(t, projectDir)
 	for _, rel := range []string{
 		"inventory/openexit.inventory.yaml",
 		"mapping/openexit.mapping.yaml",
@@ -668,6 +655,67 @@ func TestEdgeFixturePipeline(t *testing.T) {
 			t.Fatalf("expected assessment finding %s", id)
 		}
 	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "edge-candidates: passed") {
+		t.Fatalf("expected edge candidate validation marker, got:\n%s", string(report))
+	}
+}
+
+func TestValidationRejectsBrokenEdgeVCLCandidate(t *testing.T) {
+	projectDir := filepath.Join(t.TempDir(), "edge-demo")
+	runEdgeFixturePipeline(t, projectDir)
+	candidatePath := filepath.Join(projectDir, "generated-config", "edge", "varnish", "default.candidate.vcl")
+	data, err := os.ReadFile(candidatePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupt := strings.Replace(string(data), "set beresp.ttl = 86400s", "set beresp.ttl = 60s", 1)
+	if corrupt == string(data) {
+		t.Fatal("test fixture did not contain VCL edge TTL")
+	}
+	if err := os.WriteFile(candidatePath, []byte(corrupt), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeForTest("validate", "--project", projectDir); err == nil {
+		t.Fatal("expected validation to fail when VCL TTL drifts from inventory")
+	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "edge-candidates") || !strings.Contains(string(report), "edge TTL") {
+		t.Fatalf("expected edge candidate TTL failure in validation report, got:\n%s", string(report))
+	}
+}
+
+func TestValidationRejectsBrokenEdgeHAProxyCandidate(t *testing.T) {
+	projectDir := filepath.Join(t.TempDir(), "edge-demo")
+	runEdgeFixturePipeline(t, projectDir)
+	candidatePath := filepath.Join(projectDir, "generated-config", "edge", "haproxy", "haproxy.candidate.cfg")
+	data, err := os.ReadFile(candidatePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	corrupt := strings.Replace(string(data), "ssl verify none sni str(api-origin.example.com)", "ssl verify required sni str(api-origin.example.com)", 1)
+	if corrupt == string(data) {
+		t.Fatal("test fixture did not contain HAProxy TLS verify marker")
+	}
+	if err := os.WriteFile(candidatePath, []byte(corrupt), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeForTest("validate", "--project", projectDir); err == nil {
+		t.Fatal("expected validation to fail when HAProxy TLS verification drifts from inventory")
+	}
+	report, err := os.ReadFile(filepath.Join(projectDir, "validation", "validation-report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(report), "edge-candidates") || !strings.Contains(string(report), "TLS verify none") {
+		t.Fatalf("expected edge candidate TLS verification failure in validation report, got:\n%s", string(report))
+	}
 }
 
 func TestAIProviderFixturePipeline(t *testing.T) {
@@ -773,6 +821,23 @@ func runIdentityFixturePipeline(t *testing.T, projectDir string) {
 	}
 }
 
+func runEdgeFixturePipeline(t *testing.T, projectDir string) {
+	t.Helper()
+	fixturePath := filepath.Join("..", "..", "testdata", "edge", "small.json")
+	commands := [][]string{
+		{"init", projectDir, "--source", "edge", "--target", "varnish-haproxy-coraza"},
+		{"collect", "edge-fixture", "--project", projectDir, "--input", fixturePath},
+		{"assess", "--project", projectDir, "--target", "varnish-haproxy-coraza"},
+		{"generate", "--project", projectDir, "--all"},
+		{"validate", "--project", projectDir},
+	}
+	for _, args := range commands {
+		if err := executeForTest(args...); err != nil {
+			t.Fatalf("openexit %s failed: %v", strings.Join(args, " "), err)
+		}
+	}
+}
+
 func executeForTest(args ...string) error {
 	cmd := NewRootCommand()
 	cmd.SetArgs(args)

internal/generate/markdown.go

@@ -1254,6 +1254,7 @@ func writeEdgeVCLCandidates(ctx *Context) error {
 	fmt.Fprintln(&b, "sub vcl_recv {")
 	for _, rule := range ctx.Inventory.Assets.CacheRules {
 		pattern := vclRegex(rule.Pattern)
+		fmt.Fprintf(&b, "    # cache-rule %s evidence=%s\n", sanitizeConfigValue(rule.ID), rule.EvidenceRef)
 		if strings.EqualFold(rule.Action, "bypass") {
 			fmt.Fprintf(&b, "    if (req.url ~ %q) { return (pass); }\n", pattern)
 			continue
@@ -1264,6 +1265,7 @@ func writeEdgeVCLCandidates(ctx *Context) error {
 	}
 	for _, rule := range ctx.Inventory.Assets.PageRules {
 		if rule.Enabled && containsString(rule.Actions, "cache_everything") {
+			fmt.Fprintf(&b, "    # page-rule %s evidence=%s\n", sanitizeConfigValue(rule.ID), rule.EvidenceRef)
 			fmt.Fprintf(&b, "    if (req.http.host + req.url ~ %q) { unset req.http.Cookie; }\n", vclRegex(rule.Target))
 		}
 	}
@@ -1272,6 +1274,7 @@ func writeEdgeVCLCandidates(ctx *Context) error {
 	fmt.Fprintln(&b, "sub vcl_backend_response {")
 	for _, rule := range ctx.Inventory.Assets.CacheRules {
 		if strings.EqualFold(rule.Action, "cache") && rule.EdgeTTL > 0 {
+			fmt.Fprintf(&b, "    # cache-rule %s evidence=%s\n", sanitizeConfigValue(rule.ID), rule.EvidenceRef)
 			fmt.Fprintf(&b, "    if (bereq.url ~ %q) { set beresp.ttl = %ds; }\n", vclRegex(rule.Pattern), rule.EdgeTTL)
 		}
 	}
@@ -1296,6 +1299,7 @@ func writeVCLBackends(b *strings.Builder, origins []inventory.OriginConfig) {
 		if i == 0 {
 			name = "default"
 		}
+		fmt.Fprintf(b, "# origin %s evidence=%s\n", sanitizeConfigValue(origin.ID), origin.EvidenceRef)
 		fmt.Fprintf(b, "backend %s {\n", name)
 		fmt.Fprintf(b, "    .host = %q;\n", origin.Hostname)
 		fmt.Fprintf(b, "    .port = %q;\n", fmt.Sprintf("%d", origin.Port))
@@ -1326,6 +1330,7 @@ func writeEdgeHAProxyCandidates(ctx *Context) error {
 	}
 	for _, origin := range ctx.Inventory.Assets.Origins {
 		name := configIdentifier(origin.ID)
+		fmt.Fprintf(&b, "    # origin %s evidence=%s\n", sanitizeConfigValue(origin.ID), origin.EvidenceRef)
 		fmt.Fprintf(&b, "    acl host_%s hdr(host) -i %s\n", name, sanitizeConfigValue(origin.HostHeader))
 		fmt.Fprintf(&b, "    use_backend be_%s if host_%s\n", name, name)
 	}
@@ -1346,6 +1351,7 @@ func writeEdgeHAProxyCandidates(ctx *Context) error {
 		if origin.HealthCheck {
 			check = " check"
 		}
+		fmt.Fprintf(&b, "# origin %s evidence=%s\n", sanitizeConfigValue(origin.ID), origin.EvidenceRef)
 		fmt.Fprintf(&b, "backend be_%s\n", name)
 		fmt.Fprintf(&b, "    server %s %s:%d%s%s\n", name, sanitizeConfigValue(origin.Hostname), origin.Port, ssl, check)
 	}
@@ -1371,6 +1377,7 @@ func writeEdgeCorazaCandidates(ctx *Context) error {
 		if !rule.Enabled {
 			action = "pass,nolog"
 		}
+		fmt.Fprintf(&b, "# waf-rule %s evidence=%s\n", sanitizeConfigValue(rule.ID), rule.EvidenceRef)
 		fmt.Fprintf(&b, "SecRule REQUEST_URI \"@contains %s\" \"id:%d,phase:2,%s,msg:'%s'\"\n", corazaMatchValue(rule.Expression), 100000+i, action, sanitizeConfigValue(rule.Name))
 	}
 	for i, rule := range ctx.Inventory.Assets.BotRules {
@@ -1381,6 +1388,7 @@ func writeEdgeCorazaCandidates(ctx *Context) error {
 		if !rule.Enabled {
 			action = "pass,nolog"
 		}
+		fmt.Fprintf(&b, "# bot-rule %s evidence=%s\n", sanitizeConfigValue(rule.ID), rule.EvidenceRef)
 		fmt.Fprintf(&b, "SecRule REQUEST_HEADERS:User-Agent \"@rx .+\" \"id:%d,phase:1,%s,msg:'%s'\"\n", 110000+i, action, sanitizeConfigValue(rule.Name))
 	}
 	if err := os.WriteFile(filepath.Join(dir, "coraza-rules.candidate.conf"), []byte(b.String()), 0o644); err != nil {