feat: validate config files against published JSON Schema at runtime

.github/workflows/release.yml

@@ -523,9 +523,10 @@ jobs:
       - name: Generate versioned JSON Schema
         run: |
           mkdir -p release
-          node scripts/generate-schema.mjs --version ${{ needs.bump-version.outputs.version }} --print > release/awf-config.schema.json
+          node scripts/generate-schema.mjs --version ${{ needs.bump-version.outputs.version }} --print > release/awf-config.v1.schema.json
+          cp release/awf-config.v1.schema.json release/awf-config.schema.json
           echo "=== Schema preview (first 10 lines) ==="
-          head -10 release/awf-config.schema.json
+          head -10 release/awf-config.v1.schema.json
 
       - name: Generate checksums
         run: |
@@ -653,6 +654,7 @@ jobs:
             release/awf.tgz
             release/containers.txt
             release/awf-config.schema.json
+            release/awf-config.v1.schema.json
             release/checksums.txt
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

containers/agent/Dockerfile

@@ -9,29 +9,45 @@ ARG BASE_IMAGE=ubuntu:22.04
 
 FROM ${BASE_IMAGE}
 
-# Switch to Azure apt mirror for faster, more reliable package fetches in CI
-# GitHub Actions runners are Azure-hosted; azure.archive.ubuntu.com is geographically closer
-# Handles both traditional sources.list (jammy) and DEB822 format (noble+)
-RUN if [ -f /etc/apt/sources.list ]; then \
-      sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
-      sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
-    fi && \
-    if [ -d /etc/apt/sources.list.d ]; then \
-      find /etc/apt/sources.list.d -name '*.sources' -exec \
-        sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
-      find /etc/apt/sources.list.d -name '*.sources' -exec \
-        sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+# Optionally switch to Azure apt mirror for faster package fetches in CI
+# Only rewrite if azure.archive.ubuntu.com is resolvable (BuildKit DNS can fail)
+# Falls back to default archive.ubuntu.com which is universally reachable
+RUN if getent hosts azure.archive.ubuntu.com >/dev/null 2>&1; then \
+      echo "Using Azure apt mirror (DNS resolved successfully)"; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
+        sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+    else \
+      echo "Azure apt mirror not reachable, using default archive.ubuntu.com"; \
     fi
 
 # Install required packages and Node.js 22
 # Note: Some packages may already exist in runner-like base images, apt handles this gracefully
-# apt_update_retry: retries up to 3 times with backoff to survive prolonged mirror syncs
+# apt_update_retry: retries up to 3 times with backoff; if all fail, reverts to archive.ubuntu.com
 RUN set -eux; \
     apt_update_retry() { \
       local i; for i in 1 2 3; do \
-        rm -rf /var/lib/apt/lists/* && apt-get update && return 0; \
-        echo "apt-get update attempt $i/3 failed, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
-      done; return 1; \
+        rm -rf /var/lib/apt/lists/* && apt-get update 2>&1 | tee /tmp/apt-update.log && \
+        if ! grep -q "Failed to fetch" /tmp/apt-update.log; then return 0; fi; \
+        echo "apt-get update attempt $i/3 had fetch failures, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
+      done; \
+      echo "All apt-get update retries failed, falling back to archive.ubuntu.com..." >&2; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' /etc/apt/sources.list; \
+        sed -i 's|http://security.ubuntu.com|http://archive.ubuntu.com|g' /etc/apt/sources.list 2>/dev/null || true; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+      rm -rf /var/lib/apt/lists/* && apt-get update; \
     }; \
     PKGS="iptables curl ca-certificates git gh gnupg dnsutils net-tools netcat-openbsd gosu libcap2-bin"; \
     apt_update_retry && \
@@ -60,9 +76,19 @@ RUN set -eux; \
 RUN set -eux; \
     apt_update_retry() { \
       local i; for i in 1 2 3; do \
-        rm -rf /var/lib/apt/lists/* && apt-get update && return 0; \
-        echo "apt-get update attempt $i/3 failed, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
-      done; return 1; \
+        rm -rf /var/lib/apt/lists/* && apt-get update 2>&1 | tee /tmp/apt-update.log && \
+        if ! grep -q "Failed to fetch" /tmp/apt-update.log; then return 0; fi; \
+        echo "apt-get update attempt $i/3 had fetch failures, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
+      done; \
+      echo "All apt-get update retries failed, falling back to archive.ubuntu.com..." >&2; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' /etc/apt/sources.list; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+      rm -rf /var/lib/apt/lists/* && apt-get update; \
     }; \
     PARITY_PKGS="libgdiplus libev-dev libssl-dev php-intl php-gd"; \
     apt_update_retry && \
@@ -77,9 +103,19 @@ RUN set -eux; \
 # Retry logic handles transient mirror sync failures during apt-get update
 RUN apt_update_retry() { \
       local i; for i in 1 2 3; do \
-        rm -rf /var/lib/apt/lists/* && apt-get update && return 0; \
-        echo "apt-get update attempt $i/3 failed, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
-      done; return 1; \
+        rm -rf /var/lib/apt/lists/* && apt-get update 2>&1 | tee /tmp/apt-update.log && \
+        if ! grep -q "Failed to fetch" /tmp/apt-update.log; then return 0; fi; \
+        echo "apt-get update attempt $i/3 had fetch failures, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
+      done; \
+      echo "All apt-get update retries failed, falling back to archive.ubuntu.com..." >&2; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' /etc/apt/sources.list; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+      rm -rf /var/lib/apt/lists/* && apt-get update; \
     }; \
     apt_update_retry && \
     apt-get upgrade -y && rm -rf /var/lib/apt/lists/* || \

containers/squid/Dockerfile

@@ -1,27 +1,42 @@
 FROM ubuntu/squid:latest
 
-# Switch to Azure apt mirror for faster, more reliable package fetches in CI
-# GitHub Actions runners are Azure-hosted; azure.archive.ubuntu.com is geographically closer
-# Handles both traditional sources.list (jammy) and DEB822 format (noble+)
-RUN if [ -f /etc/apt/sources.list ]; then \
-      sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
-      sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
-    fi && \
-    if [ -d /etc/apt/sources.list.d ]; then \
-      find /etc/apt/sources.list.d -name '*.sources' -exec \
-        sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
-      find /etc/apt/sources.list.d -name '*.sources' -exec \
-        sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+# Optionally switch to Azure apt mirror for faster package fetches in CI
+# Only rewrite if azure.archive.ubuntu.com is resolvable (BuildKit DNS can fail)
+# Falls back to default archive.ubuntu.com which is universally reachable
+RUN if getent hosts azure.archive.ubuntu.com >/dev/null 2>&1; then \
+      echo "Using Azure apt mirror (DNS resolved successfully)"; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
+        sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' /etc/apt/sources.list; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://archive.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://security.ubuntu.com|http://azure.archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+    else \
+      echo "Azure apt mirror not reachable, using default archive.ubuntu.com"; \
     fi
 
 # Install additional tools for debugging, healthcheck, and SSL Bump
-# apt_update_retry: retries up to 3 times with backoff to survive prolonged mirror syncs
+# apt_update_retry: retries up to 3 times with backoff; if all fail, reverts to archive.ubuntu.com
 RUN set -eux; \
     apt_update_retry() { \
       local i; for i in 1 2 3; do \
-        rm -rf /var/lib/apt/lists/* && apt-get update && return 0; \
-        echo "apt-get update attempt $i/3 failed, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
-      done; return 1; \
+        rm -rf /var/lib/apt/lists/* && apt-get update 2>&1 | tee /tmp/apt-update.log && \
+        if ! grep -q "Failed to fetch" /tmp/apt-update.log; then return 0; fi; \
+        echo "apt-get update attempt $i/3 had fetch failures, retrying in $((i*10))s..." >&2; sleep $((i*10)); \
+      done; \
+      echo "All apt-get update retries failed, falling back to archive.ubuntu.com..." >&2; \
+      if [ -f /etc/apt/sources.list ]; then \
+        sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' /etc/apt/sources.list; \
+      fi; \
+      if [ -d /etc/apt/sources.list.d ]; then \
+        find /etc/apt/sources.list.d -name '*.sources' -exec \
+          sed -i 's|http://azure.archive.ubuntu.com|http://archive.ubuntu.com|g' {} + 2>/dev/null || true; \
+      fi; \
+      rm -rf /var/lib/apt/lists/* && apt-get update; \
     }; \
     PKGS="curl dnsutils net-tools netcat-openbsd openssl squid-openssl"; \
     apt_update_retry && \

docs/awf-config.schema.json

@@ -2,6 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json",
   "title": "AWF Configuration",
+  "version": "1",
   "description": "JSON/YAML configuration for awf CLI. CLI flags override config file values. See https://github.com/github/gh-aw-firewall for documentation.",
   "type": "object",
   "additionalProperties": false,