@raishin/vanguard-frontier-agentic 1.9.0 → 2.0.0

package/tests/integration/rbac-pre-flight/guards/network-arch.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# guards/network-arch.sh — RBAC pre-flight for kubernetes-live-network-architecture-mutation-guard
+# Source lib/common.sh before running this file.
+
+run_guard_network_arch() {
+  begin_guard "network-architecture-mutation"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-network-arch-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/rbac-pre-flight.md)
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Namespace destruction
+  assert_cannot delete namespaces/kube-system "--as=$SA"
+  assert_cannot delete namespaces/cilium "--as=$SA"
+  assert_cannot delete namespaces/istio-system "--as=$SA"
+
+  # kube-system daemonset patches
+  assert_cannot patch daemonsets/cilium -n kube-system "--as=$SA"
+  assert_cannot patch daemonsets/kube-proxy -n kube-system "--as=$SA"
+
+  # Broad secret access
+  assert_cannot list secrets --all-namespaces "--as=$SA"
+
+  # Privilege escalation
+  assert_cannot create clusterroles "--as=$SA"
+  assert_cannot escalate roles "--as=$SA"
+  assert_cannot bind roles "--as=$SA"
+  assert_cannot impersonate users "--as=$SA"
+  assert_cannot impersonate groups "--as=$SA"
+  assert_cannot impersonate serviceaccounts "--as=$SA"
+
+  # Node lifecycle
+  assert_cannot delete nodes "--as=$SA"
+  assert_cannot patch nodes "--as=$SA"
+  assert_cannot update nodes "--as=$SA"
+  assert_cannot create pods/eviction "--as=$SA"
+  assert_cannot get nodes/proxy "--as=$SA"
+  assert_cannot create nodes/proxy "--as=$SA"
+
+  # Lease objects
+  assert_cannot patch leases.coordination.k8s.io -n kube-node-lease "--as=$SA"
+
+  # Admission webhook configs (additional verbs beyond universal)
+  assert_cannot patch mutatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot patch validatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot delete validatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+
+  # APIService aggregation
+  assert_cannot patch apiservices.apiregistration.k8s.io "--as=$SA"
+  assert_cannot delete apiservices.apiregistration.k8s.io "--as=$SA"
+
+  # Pod subresources
+  assert_cannot create pods/proxy --all-namespaces "--as=$SA"
+  assert_cannot create pods/binding --all-namespaces "--as=$SA"
+
+  # CSR / token minting
+  assert_cannot create certificatesigningrequests.certificates.k8s.io "--as=$SA"
+
+  # Manual Endpoints / EndpointSlices writes
+  assert_cannot create endpoints --all-namespaces "--as=$SA"
+  assert_cannot patch endpoints --all-namespaces "--as=$SA"
+  assert_cannot create endpointslices.discovery.k8s.io --all-namespaces "--as=$SA"
+  assert_cannot patch endpointslices.discovery.k8s.io --all-namespaces "--as=$SA"
+
+  # kube-system ConfigMap writes outside the resourceName-locked allowlist
+  assert_cannot patch configmaps/cilium-config -n kube-system "--as=$SA"
+  assert_cannot patch configmaps/kube-proxy -n kube-system "--as=$SA"
+  assert_cannot patch configmaps/kubelet-config -n kube-system "--as=$SA"
+  assert_cannot patch configmaps/cluster-info -n kube-public "--as=$SA"
+
+  # PriorityClass / IngressClass / StorageClass
+  assert_cannot patch priorityclasses.scheduling.k8s.io "--as=$SA"
+  assert_cannot delete ingressclasses.networking.k8s.io "--as=$SA"
+  assert_cannot patch ingressclasses.networking.k8s.io "--as=$SA"
+  assert_cannot patch storageclasses.storage.k8s.io "--as=$SA"
+
+  # Finalizer-stripping paths
+  assert_cannot update customresourcedefinitions/finalize "--as=$SA"
+
+  # resourceName negative tests — same configmap name in wrong namespace
+  assert_cannot patch configmaps/coredns -n default "--as=$SA"
+  assert_cannot patch configmaps/coredns -n kube-public "--as=$SA"
+  assert_cannot patch configmaps/extension-apiserver-authentication -n kube-system "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  assert_can get services --all-namespaces "--as=$SA"
+  assert_can list services --all-namespaces "--as=$SA"
+  assert_can patch services --all-namespaces "--as=$SA"
+  assert_can get endpointslices --all-namespaces "--as=$SA"
+  assert_can get nodes "--as=$SA"
+  assert_can get configmaps -n kube-system "--as=$SA"
+
+  # CoreDNS Corefile (resourceName-locked — positive side of resourceName test)
+  assert_can patch configmaps/coredns -n kube-system "--as=$SA"
+  assert_can get configmaps/coredns -n kube-system "--as=$SA"
+
+  # Gateway API resources — CRDs not present in vanilla kind; skip not fail
+  printf '%b  -- Gateway API checks (SKIP if CRDs absent) --%b\n' "$_CYAN" "$_RESET"
+  assert_can_or_skip create gateways.gateway.networking.k8s.io --all-namespaces "--as=$SA"
+  assert_can_or_skip patch gateways.gateway.networking.k8s.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create httproutes.gateway.networking.k8s.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create grpcroutes.gateway.networking.k8s.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create referencegrants.gateway.networking.k8s.io --all-namespaces "--as=$SA"
+
+  report_guard "network-architecture-mutation"
+}

package/tests/integration/rbac-pre-flight/guards/network-policy.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# guards/network-policy.sh — RBAC pre-flight for kubernetes-live-network-policy-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_network_policy() {
+  begin_guard "network-policy"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-network-policy-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-network-policy-guard-agent/references/rbac-pre-flight.md)
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Cluster-wide policy writes — opt-in only; Cilium CRDs may not exist in kind
+  assert_cannot_or_skip create ciliumclusterwidenetworkpolicies.cilium.io "--as=$SA"
+  assert_cannot_or_skip patch ciliumclusterwidenetworkpolicies.cilium.io "--as=$SA"
+  assert_cannot_or_skip delete ciliumclusterwidenetworkpolicies.cilium.io "--as=$SA"
+
+  # Delete on namespaced policies — rollback is via apply -f baseline, not delete
+  assert_cannot_or_skip delete ciliumnetworkpolicies.cilium.io --all-namespaces "--as=$SA"
+  assert_cannot delete networkpolicies.networking.k8s.io --all-namespaces "--as=$SA"
+
+  # Cilium agent ConfigMap
+  assert_cannot patch configmaps/cilium-config -n kube-system "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Cilium CRDs — skip not fail if CRDs absent
+  assert_can_or_skip create ciliumnetworkpolicies.cilium.io --all-namespaces "--as=$SA"
+  assert_can_or_skip patch ciliumnetworkpolicies.cilium.io --all-namespaces "--as=$SA"
+  assert_can_or_skip create ciliumegressgatewaypolicies.cilium.io --all-namespaces "--as=$SA"
+  assert_can_or_skip list ciliumnetworkpolicies.cilium.io --all-namespaces "--as=$SA"
+  assert_can_or_skip list ciliumendpoints.cilium.io --all-namespaces "--as=$SA"
+
+  # Core NetworkPolicy (always present)
+  assert_can create networkpolicies.networking.k8s.io --all-namespaces "--as=$SA"
+
+  report_guard "network-policy"
+}

package/tests/integration/rbac-pre-flight/guards/rbac-mutation.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# guards/rbac-mutation.sh — RBAC pre-flight for kubernetes-live-rbac-mutation-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_rbac_mutation() {
+  begin_guard "rbac-mutation"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-rbac-mutation-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-rbac-mutation-guard-agent/references/rbac-pre-flight.md)
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  # Cluster-scoped RBAC writes — opt-in only; default refusal
+  assert_cannot create clusterroles.rbac.authorization.k8s.io "--as=$SA"
+  assert_cannot create clusterrolebindings.rbac.authorization.k8s.io "--as=$SA"
+  assert_cannot patch clusterroles.rbac.authorization.k8s.io "--as=$SA"
+  assert_cannot patch clusterrolebindings.rbac.authorization.k8s.io "--as=$SA"
+
+  # Privilege-escalation primitives
+  assert_cannot escalate roles.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_cannot bind roles.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_cannot escalate clusterroles.rbac.authorization.k8s.io "--as=$SA"
+  assert_cannot bind clusterroles.rbac.authorization.k8s.io "--as=$SA"
+  assert_cannot impersonate users "--as=$SA"
+  assert_cannot impersonate groups "--as=$SA"
+  assert_cannot impersonate serviceaccounts --all-namespaces "--as=$SA"
+
+  # Delete — rollback is via apply -f baseline
+  assert_cannot delete roles.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_cannot delete rolebindings.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+
+  # ServiceAccount creation (separate from RBAC; could be used to create a privileged SA)
+  assert_cannot create serviceaccounts --all-namespaces "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  assert_can create roles.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_can patch roles.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_can create rolebindings.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_can patch rolebindings.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_can list rolebindings.rbac.authorization.k8s.io --all-namespaces "--as=$SA"
+  assert_can list serviceaccounts --all-namespaces "--as=$SA"
+
+  report_guard "rbac-mutation"
+}

package/tests/integration/rbac-pre-flight/guards/velero-restore.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# guards/velero-restore.sh — RBAC pre-flight for kubernetes-live-velero-restore-guard-agent
+# Source lib/common.sh before running this file.
+
+run_guard_velero_restore() {
+  begin_guard "velero-restore"
+
+  local SA="system:serviceaccount:vanguard-system:vanguard-velero-restore-guard"
+
+  # -------------------------------------------------------------------------
+  # Universal must-not-be-yes
+  # -------------------------------------------------------------------------
+  run_universal_must_not "$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-not-be-yes
+  # (from agents/kubernetes/kubernetes-live-velero-restore-guard-agent/references/rbac-pre-flight.md)
+  # All Velero CRDs are absent in vanilla kind — use assert_cannot_or_skip.
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-not-be-yes (Velero CRDs, SKIP if absent) --%b\n' "$_CYAN" "$_RESET"
+
+  # Schedule writes — operator install only
+  assert_cannot_or_skip create schedules.velero.io -n velero "--as=$SA"
+  assert_cannot_or_skip patch schedules.velero.io -n velero "--as=$SA"
+  assert_cannot_or_skip delete schedules.velero.io -n velero "--as=$SA"
+
+  # BackupStorageLocation writes — security-critical (s3 credentials)
+  assert_cannot_or_skip patch backupstoragelocations.velero.io -n velero "--as=$SA"
+  assert_cannot_or_skip delete backupstoragelocations.velero.io -n velero "--as=$SA"
+
+  # Backup deletion — rollback option loss
+  assert_cannot_or_skip delete backups.velero.io -n velero "--as=$SA"
+  assert_cannot_or_skip patch backups.velero.io -n velero "--as=$SA"
+
+  # Velero control plane (standard resources — not CRD-dependent)
+  assert_cannot patch deployments -n velero "--as=$SA"
+  assert_cannot get secrets -n velero "--as=$SA"
+
+  # -------------------------------------------------------------------------
+  # Domain-specific must-be-yes
+  # Velero CRDs — skip not fail if absent
+  # -------------------------------------------------------------------------
+  printf '%b  -- domain-specific must-be-yes (Velero CRDs, SKIP if absent) --%b\n' "$_CYAN" "$_RESET"
+
+  assert_can_or_skip create restores.velero.io -n velero "--as=$SA"
+  assert_can_or_skip create backups.velero.io -n velero "--as=$SA"
+  assert_can_or_skip list backups.velero.io -n velero "--as=$SA"
+  assert_can_or_skip list backupstoragelocations.velero.io -n velero "--as=$SA"
+  assert_can_or_skip list restores.velero.io -n velero "--as=$SA"
+
+  report_guard "velero-restore"
+}

package/tests/integration/rbac-pre-flight/lib/common.sh

@@ -0,0 +1,252 @@
+#!/usr/bin/env bash
+# lib/common.sh — shared helpers for RBAC pre-flight integration tests.
+# Guard scripts source this file; do NOT set -e here since denied checks
+# intentionally return exit code 1 from kubectl.
+
+# ---------------------------------------------------------------------------
+# Color output (suppressed when not a TTY)
+# ---------------------------------------------------------------------------
+if [ -t 1 ]; then
+  _GREEN='\033[0;32m'
+  _RED='\033[0;31m'
+  _YELLOW='\033[0;33m'
+  _CYAN='\033[0;36m'
+  _RESET='\033[0m'
+else
+  _GREEN=''
+  _RED=''
+  _YELLOW=''
+  _CYAN=''
+  _RESET=''
+fi
+
+# ---------------------------------------------------------------------------
+# Global counters (reset per guard via report_guard)
+# ---------------------------------------------------------------------------
+GUARD_PASS=0
+GUARD_FAIL=0
+GUARD_SKIP=0
+
+TOTAL_PASS=0
+TOTAL_FAIL=0
+TOTAL_SKIP=0
+
+# ---------------------------------------------------------------------------
+# require_kubectl — abort early if kubectl is not on PATH
+# ---------------------------------------------------------------------------
+require_kubectl() {
+  if ! command -v kubectl &>/dev/null; then
+    printf '%bFATAL: kubectl not found in PATH. Install kubectl >= 1.28 and retry.%b\n' \
+      "$_RED" "$_RESET" >&2
+    exit 1
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# _run_can_i — internal helper
+#   Usage: _run_can_i <verb> <resource> [extra kubectl flags...] --as=<SA>
+#   Returns the raw output of kubectl auth can-i (yes/no) in CANI_OUTPUT.
+#   Returns 0 on success, non-zero on kubectl error (distinct from denied).
+# ---------------------------------------------------------------------------
+_run_can_i() {
+  # kubectl auth can-i exits 0 for "yes" and 1 for "no".
+  # We capture output regardless of exit code.
+  CANI_OUTPUT=$(kubectl auth can-i "$@" 2>&1)
+  CANI_EXIT=$?
+  # Propagate real errors (not the normal denied exit) to the caller.
+  # kubectl prints "yes\n" or "no\n"; anything else is an error.
+  case "$CANI_OUTPUT" in
+    yes*|no*) return 0 ;;
+    *) return 2 ;;   # unexpected output / server error
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# assert_cannot — check that an SA does NOT have a permission
+#   Usage: assert_cannot <verb> <resource> [kubectl-flags...] (SA must be in flags)
+# ---------------------------------------------------------------------------
+assert_cannot() {
+  local description="$*"
+  _run_can_i "$@"
+  local rc=$?
+
+  if [ $rc -eq 2 ]; then
+    printf '  %b[SKIP]%b cannot %-60s  (kubectl error: %s)\n' \
+      "$_YELLOW" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_SKIP++ )) || true
+    return
+  fi
+
+  if [ "$CANI_OUTPUT" = "no" ]; then
+    printf '  %b[PASS]%b cannot %s\n' "$_GREEN" "$_RESET" "$description"
+    (( GUARD_PASS++ )) || true
+  else
+    printf '  %b[FAIL]%b cannot %-60s  (got: %s — binding is over-scoped)\n' \
+      "$_RED" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_FAIL++ )) || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# assert_can — check that an SA DOES have a permission
+#   Usage: assert_can <verb> <resource> [kubectl-flags...] (SA must be in flags)
+# ---------------------------------------------------------------------------
+assert_can() {
+  local description="$*"
+  _run_can_i "$@"
+  local rc=$?
+
+  if [ $rc -eq 2 ]; then
+    printf '  %b[SKIP]%b can    %-60s  (kubectl error: %s)\n' \
+      "$_YELLOW" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_SKIP++ )) || true
+    return
+  fi
+
+  if [ "$CANI_OUTPUT" = "yes" ]; then
+    printf '  %b[PASS]%b can    %s\n' "$_GREEN" "$_RESET" "$description"
+    (( GUARD_PASS++ )) || true
+  else
+    printf '  %b[FAIL]%b can    %-60s  (got: %s — binding is under-scoped)\n' \
+      "$_RED" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_FAIL++ )) || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# assert_can_or_skip — like assert_can but treats "NotFound" CRD errors as SKIP
+#   Use for Gateway API / Cilium / Istio / Argo CD / Velero / Kyverno CRDs that
+#   may not exist in a vanilla kind cluster.
+# ---------------------------------------------------------------------------
+assert_can_or_skip() {
+  local description="$*"
+  _run_can_i "$@"
+  local rc=$?
+
+  if [ $rc -eq 2 ]; then
+    # CRD not installed — skip rather than fail
+    printf '  %b[SKIP]%b can    %-60s  (CRD not found — install CRDs to test)\n' \
+      "$_YELLOW" "$_RESET" "$description"
+    (( GUARD_SKIP++ )) || true
+    return
+  fi
+
+  if [ "$CANI_OUTPUT" = "yes" ]; then
+    printf '  %b[PASS]%b can    %s\n' "$_GREEN" "$_RESET" "$description"
+    (( GUARD_PASS++ )) || true
+  else
+    printf '  %b[FAIL]%b can    %-60s  (got: %s — binding is under-scoped)\n' \
+      "$_RED" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_FAIL++ )) || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# assert_cannot_or_skip — like assert_cannot but treats "NotFound" as SKIP
+#   Use for domain-specific must-not checks on CRDs that may not be installed.
+# ---------------------------------------------------------------------------
+assert_cannot_or_skip() {
+  local description="$*"
+  _run_can_i "$@"
+  local rc=$?
+
+  if [ $rc -eq 2 ]; then
+    printf '  %b[SKIP]%b cannot %-60s  (CRD not found — install CRDs to test)\n' \
+      "$_YELLOW" "$_RESET" "$description"
+    (( GUARD_SKIP++ )) || true
+    return
+  fi
+
+  if [ "$CANI_OUTPUT" = "no" ]; then
+    printf '  %b[PASS]%b cannot %s\n' "$_GREEN" "$_RESET" "$description"
+    (( GUARD_PASS++ )) || true
+  else
+    printf '  %b[FAIL]%b cannot %-60s  (got: %s — binding is over-scoped)\n' \
+      "$_RED" "$_RESET" "$description" "$CANI_OUTPUT"
+    (( GUARD_FAIL++ )) || true
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# run_universal_must_not — runs the 21 universal must-not-be-yes checks
+#   Usage: run_universal_must_not <SA>
+# ---------------------------------------------------------------------------
+run_universal_must_not() {
+  local SA="$1"
+  printf '%b  -- universal must-not-be-yes --%b\n' "$_CYAN" "$_RESET"
+
+  assert_cannot '*' '*' --all-namespaces "--as=$SA"
+  assert_cannot delete namespaces "--as=$SA"
+  assert_cannot delete pods -n kube-system "--as=$SA"
+  assert_cannot create pods/exec -n kube-system "--as=$SA"
+  assert_cannot create pods/portforward --all-namespaces "--as=$SA"
+  assert_cannot delete daemonsets -n kube-system "--as=$SA"
+  assert_cannot delete deployments -n kube-system "--as=$SA"
+  assert_cannot create customresourcedefinitions "--as=$SA"
+  assert_cannot delete customresourcedefinitions "--as=$SA"
+  assert_cannot get secrets --all-namespaces "--as=$SA"
+  assert_cannot create clusterrolebindings "--as=$SA"
+  assert_cannot create mutatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot delete mutatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot create validatingwebhookconfigurations.admissionregistration.k8s.io "--as=$SA"
+  assert_cannot create apiservices.apiregistration.k8s.io "--as=$SA"
+  assert_cannot update certificatesigningrequests.certificates.k8s.io --subresource=approval "--as=$SA"
+  assert_cannot create serviceaccounts/token --all-namespaces "--as=$SA"
+  assert_cannot delete priorityclasses.scheduling.k8s.io "--as=$SA"
+  assert_cannot delete ingressclasses.networking.k8s.io "--as=$SA"
+  assert_cannot delete leases.coordination.k8s.io -n kube-node-lease "--as=$SA"
+  assert_cannot update namespaces/finalize "--as=$SA"
+}
+
+# ---------------------------------------------------------------------------
+# begin_guard — print guard header and reset per-guard counters
+# ---------------------------------------------------------------------------
+begin_guard() {
+  local guard_name="$1"
+  GUARD_PASS=0
+  GUARD_FAIL=0
+  GUARD_SKIP=0
+  printf '\n%b=== Guard: %s ===%b\n' "$_CYAN" "$guard_name" "$_RESET"
+}
+
+# ---------------------------------------------------------------------------
+# report_guard — print per-guard summary and accumulate totals
+#   Returns 1 if this guard had any failures (for run-all.sh to track).
+# ---------------------------------------------------------------------------
+report_guard() {
+  local guard_name="$1"
+  local status_color="$_GREEN"
+  local status_word="PASS"
+
+  if [ "$GUARD_FAIL" -gt 0 ]; then
+    status_color="$_RED"
+    status_word="FAIL"
+  fi
+
+  printf '%b  %s: %d passed, %d failed, %d skipped%b\n' \
+    "$status_color" "$status_word" \
+    "$GUARD_PASS" "$GUARD_FAIL" "$GUARD_SKIP" \
+    "$_RESET"
+
+  (( TOTAL_PASS += GUARD_PASS )) || true
+  (( TOTAL_FAIL += GUARD_FAIL )) || true
+  (( TOTAL_SKIP += GUARD_SKIP )) || true
+
+  [ "$GUARD_FAIL" -eq 0 ]  # returns 1 when there are failures
+}
+
+# ---------------------------------------------------------------------------
+# report_total — print final summary across all guards
+# ---------------------------------------------------------------------------
+report_total() {
+  printf '\n%b========================================%b\n' "$_CYAN" "$_RESET"
+  if [ "$TOTAL_FAIL" -eq 0 ]; then
+    printf '%bALL GUARDS PASSED%b  (%d passed, %d skipped)\n' \
+      "$_GREEN" "$_RESET" "$TOTAL_PASS" "$TOTAL_SKIP"
+  else
+    printf '%bFAILURES DETECTED%b  (%d passed, %d failed, %d skipped)\n' \
+      "$_RED" "$_RESET" "$TOTAL_PASS" "$TOTAL_FAIL" "$TOTAL_SKIP"
+  fi
+  printf '%b========================================%b\n' "$_CYAN" "$_RESET"
+  [ "$TOTAL_FAIL" -eq 0 ]
+}