@raishin/vanguard-frontier-agentic 1.4.0 → 1.5.0

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/least-privilege-rbac.yaml

@@ -0,0 +1,210 @@
+# =====================================================================
+# Least-privilege RBAC for kubernetes-live-network-architecture-mutation-guard-agent
+#
+# Apply BEFORE running the agent.
+# Authoring contract: docs/least-privilege-rbac.md
+# Pre-flight matrix:  references/rbac-pre-flight.md
+# Refusal list:       references/refusal-list.md (cluster-side enforcement of these omissions)
+#
+# Audit:
+#   SA="system:serviceaccount:vanguard-system:vanguard-network-arch-guard"
+#   kubectl auth can-i delete namespaces --as=$SA       # must return: no
+#   kubectl auth can-i patch services -A --as=$SA       # must return: yes
+#
+# Per upstream kubernetes.io/docs/concepts/security/rbac-good-practices:
+#   "Avoid wildcard permissions, especially to all resources, as this grants
+#    access to current and future object types."
+# =====================================================================
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: vanguard-system
+  labels:
+    pod-security.kubernetes.io/enforce: restricted
+    pod-security.kubernetes.io/enforce-version: latest
+    app.kubernetes.io/managed-by: vanguard-frontier
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: vanguard-network-arch-guard
+  namespace: vanguard-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/scope: "least-privilege-network-architecture"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+automountServiceAccountToken: true
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: vanguard-network-arch-guard
+rules:
+  # ---- READ across networking architecture surface ----
+  - apiGroups: [""]
+    resources: ["services", "endpoints", "nodes"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["discovery.k8s.io"]
+    resources: ["endpointslices"]
+    verbs: ["get", "list", "watch"]
+  - apiGroups: ["gateway.networking.k8s.io"]
+    resources:
+      - "gatewayclasses"
+      - "gateways"
+      - "httproutes"
+      - "grpcroutes"
+      - "tlsroutes"
+      - "tcproutes"
+      - "udproutes"
+      - "referencegrants"
+    verbs: ["get", "list", "watch"]
+  # ---- WRITE on Service spec (low blast radius, reversible) ----
+  - apiGroups: [""]
+    resources: ["services"]
+    verbs: ["patch"]
+    # NOTE: "delete" verb DELIBERATELY OMITTED. Rollback uses `kubectl apply -f baseline.yaml`.
+    # NOTE: "update" verb omitted in favor of "patch" for narrower change semantics.
+  # NOTE: CoreDNS ConfigMap read/write is intentionally ABSENT from this ClusterRole.
+  # resourceNames on a ClusterRole restricts only the object name, not the namespace;
+  # a ClusterRole rule would let the SA patch any ConfigMap named "coredns" in ANY
+  # namespace. A namespaced Role/RoleBinding in kube-system (below) provides the
+  # correct least-privilege scope. See docs/least-privilege-rbac.md §Threat model.
+  # ---- WRITE on Gateway API resources (user-owned, not control plane) ----
+  - apiGroups: ["gateway.networking.k8s.io"]
+    resources:
+      - "gateways"
+      - "httproutes"
+      - "grpcroutes"
+      - "tlsroutes"
+      - "tcproutes"
+      - "udproutes"
+      - "referencegrants"
+    verbs: ["create", "patch"]
+    # NOTE: "delete" verb DELIBERATELY OMITTED on Gateway API resources.
+    # Rollback to absent state is performed by a human-confirmed operation, not by this agent.
+    # NOTE: "gatewayclasses" is read-only; GatewayClass is installed by the controller's Helm chart.
+# =====================================================================
+# DELIBERATELY ABSENT — DO NOT add unless you accept the listed risk.
+# This list is exhaustive against the destructive operations enumerated
+# in references/refusal-list.md. The binding is deny-by-default: anything
+# not granted above is denied at the API server. New attack vectors that
+# emerge in future Kubernetes releases are denied automatically.
+#
+# === Namespaces & finalizers ===
+#   apiGroups: [""], resources: ["namespaces"]                              -> delete kube-system / cilium / istio-system
+#   patch with metadata.finalizers paths on any resource                    -> bypass namespace / PV / CRD finalizer protection
+#
+# === Workload writes in control-plane namespaces ===
+#   apiGroups: [""], resources: ["pods"]                                    -> exec / delete on control-plane pods
+#   apiGroups: [""], resources: ["pods/exec"]                               -> shell into cilium-agent / kube-proxy / coredns
+#   apiGroups: [""], resources: ["pods/portforward"]                        -> NetworkPolicy bypass to any reachable Service
+#   apiGroups: [""], resources: ["pods/proxy"]                              -> proxy traffic via apiserver to pod
+#   apiGroups: [""], resources: ["pods/binding"]                            -> manual Pod-to-Node binding, scheduler bypass
+#   apiGroups: [""], resources: ["pods/eviction"]                           -> bypass PodDisruptionBudgets in some configs
+#   apiGroups: ["apps"], resources: ["daemonsets"], verbs: write            -> remove cilium / kube-proxy / node-local-dns
+#   apiGroups: ["apps"], resources: ["deployments"], verbs: write           -> remove ingress controllers / mesh control planes
+#   apiGroups: ["apps"], resources: ["statefulsets"], verbs: write          -> remove etcd-replica / clustered controllers
+#
+# === Node lifecycle ===
+#   apiGroups: [""], resources: ["nodes"], verbs: ["patch", "update", "delete"]    -> drain / cordon / delete nodes
+#   apiGroups: [""], resources: ["nodes/proxy"]                             -> direct kubelet API, bypasses some RBAC
+#   apiGroups: ["coordination.k8s.io"], resources: ["leases"]               -> Lease in kube-node-lease, fake node liveness
+#
+# === Secrets & credentials ===
+#   apiGroups: [""], resources: ["secrets"]                                 -> cluster-wide credential exposure
+#   apiGroups: [""], resources: ["serviceaccounts/token"]                   -> mint tokens for arbitrary SAs (TokenRequest)
+#   apiGroups: ["certificates.k8s.io"], any verb                            -> approve CSRs, especially with system:masters group
+#   apiGroups: ["authentication.k8s.io"], any verb                          -> tokenreviews, impersonation primitives
+#
+# === Cluster-extension surface (admission, aggregation, scheduling) ===
+#   apiGroups: ["admissionregistration.k8s.io"]                             -> mutating/validating webhook configs (admission bypass)
+#   apiGroups: ["apiregistration.k8s.io"]                                   -> APIService aggregation hijack
+#   apiGroups: ["apiextensions.k8s.io"]                                     -> CRD install / uninstall
+#   apiGroups: ["scheduling.k8s.io"]                                        -> PriorityClass system-cluster-critical / system-node-critical
+#   apiGroups: ["policy"], resources: ["poddisruptionbudgets"], verbs: write -> remove eviction protection
+#
+# === Networking control plane ===
+#   apiGroups: [""], resources: ["endpoints"], verbs: write                 -> race with EndpointSlice controller, redirect Service traffic
+#   apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: write  -> same race
+#   apiGroups: ["networking.k8s.io"], resources: ["ingressclasses"], verbs: write -> break Ingress controller binding
+#   apiGroups: ["networking.k8s.io"], resources: ["networkpolicies"]        -> delegated to cilium-network-policy-review
+#   apiGroups: ["cilium.io"], resources: ["ciliumnetworkpolicies", "ciliumclusterwidenetworkpolicies"]  -> delegated
+#   apiGroups: ["security.istio.io"], resources: ["authorizationpolicies", "peerauthentications"]      -> delegated
+#
+# === Storage ===
+#   apiGroups: ["storage.k8s.io"], resources: ["storageclasses"], verbs: write    -> remove default StorageClass, break PVC provisioning
+#   apiGroups: [""], resources: ["persistentvolumes"], verbs: write               -> orphan cloud volumes
+#
+# === RBAC self-modification ===
+#   apiGroups: ["rbac.authorization.k8s.io"]                                -> binding self-modification, privilege escalation
+#
+# === Wildcards (always anti-pattern) ===
+#   any "*" verb or "*" resource                                            -> per upstream RBAC good practices, grants future objects
+#
+# === Cross-cutting verbs ===
+#   any "delete" verb on cluster-scoped or namespaced resources             -> rollback is `apply -f baseline.yaml`, never delete
+#
+# Add ClusterMesh peer Secret write access (resourceName-locked, narrow
+# namespace) only when the operator explicitly opts in for ClusterMesh
+# peering and accepts the additional review checklist in
+# references/permitted-mutations.md. The narrow scope must be expressed
+# both in the Role (resourceNames: [<peer-cluster-id>]) and in admission
+# policy (Kyverno rule limiting Secret data field shape).
+# =====================================================================
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: vanguard-network-arch-guard
+subjects:
+  - kind: ServiceAccount
+    name: vanguard-network-arch-guard
+    namespace: vanguard-system
+roleRef:
+  kind: ClusterRole
+  name: vanguard-network-arch-guard
+  apiGroup: rbac.authorization.k8s.io
+---
+# =====================================================================
+# Namespaced Role + RoleBinding for CoreDNS ConfigMap access.
+# A ClusterRole with resourceNames restricts only the object name, not
+# the namespace, so the SA would be able to patch any ConfigMap named
+# "coredns" cluster-wide. This Role is bound only in kube-system,
+# providing the correct least-privilege scope.
+# =====================================================================
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: vanguard-network-arch-guard-coredns
+  namespace: kube-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+rules:
+  # Broad read in kube-system — needed to inspect ConfigMap state before patching.
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    verbs: ["get", "list", "watch"]
+  # Patch locked to the single ConfigMap that holds the CoreDNS Corefile.
+  # NOTE: "delete" verb DELIBERATELY OMITTED. Rollback uses `kubectl apply -f baseline.yaml`.
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    resourceNames: ["coredns"]
+    verbs: ["patch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: vanguard-network-arch-guard-coredns
+  namespace: kube-system
+  annotations:
+    vanguard.frontier/agent: "kubernetes-live-network-architecture-mutation-guard-agent"
+    vanguard.frontier/contract: "docs/least-privilege-rbac.md"
+subjects:
+  - kind: ServiceAccount
+    name: vanguard-network-arch-guard
+    namespace: vanguard-system
+roleRef:
+  kind: Role
+  name: vanguard-network-arch-guard-coredns
+  apiGroup: rbac.authorization.k8s.io

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/official-sources.md

@@ -0,0 +1,41 @@
+# Official sources
+
+Authoritative upstream documentation for the surfaces this guard mutates.
+
+## RBAC and authorization
+
+- [RBAC Good Practices](https://kubernetes.io/docs/concepts/security/rbac-good-practices/) — the foundational guidance this guard implements: minimal privilege, no wildcards, no `cluster-admin` for routine work, no `system:masters` group membership.
+- [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) — the API reference for `Role` / `ClusterRole` / `RoleBinding` / `ClusterRoleBinding`.
+- [`kubectl auth can-i`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_auth/kubectl_auth_can-i/) — the pre-flight matrix syntax.
+- [User Impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) — the recommended pattern: low-privileged operator with `impersonate` rights on the agent's ServiceAccount.
+
+## Service traffic policy and topology-aware routing
+
+- [Service Internal Traffic Policy](https://kubernetes.io/docs/concepts/services-networking/service-traffic-policy/) — `internalTrafficPolicy` and `externalTrafficPolicy` semantics.
+- [Topology Aware Routing](https://kubernetes.io/docs/concepts/services-networking/topology-aware-routing/) — `service.kubernetes.io/topology-mode: Auto` annotation and `spec.trafficDistribution` field.
+
+## CoreDNS
+
+- [CoreDNS `kubernetes` plugin](https://coredns.io/plugins/kubernetes/) — the in-cluster DNS plugin reference.
+- [CoreDNS `reload` plugin](https://coredns.io/plugins/reload/) — Corefile change detection (default 30s poll).
+- [CoreDNS `loop` plugin](https://coredns.io/plugins/loop/) — recursion-loop detection (silent failure mode if absent).
+- [CoreDNS `health` plugin](https://coredns.io/plugins/health/) — liveness probe target.
+
+## NodeLocal DNSCache
+
+- [Using NodeLocal DNSCache in Kubernetes Clusters](https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/) — install manifest, the `__PILLAR__` token substitutions, and the kube-proxy / Cilium kube-proxy replacement preconditions.
+
+## Gateway API
+
+- [Gateway API](https://gateway-api.sigs.k8s.io/) — the SIG site (authoritative).
+- [`Gateway` resource](https://gateway-api.sigs.k8s.io/api-types/gateway/) — the listener model and `allowedRoutes` semantics.
+- [`HTTPRoute`](https://gateway-api.sigs.k8s.io/api-types/httproute/) — HTTP route reference.
+- [`GRPCRoute`](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) — gRPC route reference. **GA / Standard channel since Gateway API v1.1.0.**
+- [`ReferenceGrant`](https://gateway-api.sigs.k8s.io/api-types/referencegrant/) — cross-namespace reference authorization.
+- [Gateway API Versioning](https://gateway-api.sigs.k8s.io/concepts/versioning/) — Standard vs Experimental channel semantics.
+
+## Cilium ClusterMesh
+
+- [Setting up Cluster Mesh](https://docs.cilium.io/en/stable/network/clustermesh/clustermesh/) — peer Secret structure, namespace, and CA trust setup.
+- [ClusterMesh Troubleshooting](https://docs.cilium.io/en/stable/operations/troubleshooting/) — `cilium clustermesh status`, `cilium-dbg troubleshoot clustermesh`, and the KVStoreMesh `kvstoremesh-dbg troubleshoot` command.
+- [KVStoreMesh command reference](https://docs.cilium.io/en/stable/cmdref/clustermesh-apiserver_kvstoremesh/) — `--clustermesh-cache-ttl` (default `0s` means "never revoked"), `--global-ready-timeout` (default 10m).

package/skills/kubernetes/kubernetes-live-network-architecture-mutation-guard/references/permitted-mutations.md

@@ -0,0 +1,173 @@
+# Permitted mutations
+
+This is the explicit allowlist. Any mutation outside this list MUST be either rejected by the prompt rules OR refused by the cluster RBAC binding.
+
+## Service spec patches (low blast radius, reversible)
+
+### `internalTrafficPolicy` / `externalTrafficPolicy`
+
+Reversible field on `v1.Service`. Default is `Cluster`; `Local` constrains routing to node-local endpoints.
+
+```bash
+# Capture baseline
+kubectl get svc <name> -n <ns> -o yaml > /tmp/svc-<name>.before.yaml
+
+# Apply the patch
+kubectl patch svc <name> -n <ns> --type=merge \
+  -p '{"spec":{"externalTrafficPolicy":"Cluster"}}'
+
+# Verify EndpointSlices still serve the Service
+kubectl get endpointslice -n <ns> -l kubernetes.io/service-name=<name>
+
+# Rollback
+kubectl apply -f /tmp/svc-<name>.before.yaml
+```
+
+Refusal triggers inside this mutation type:
+- Setting `externalTrafficPolicy: Local` on a Service whose backend Pods are not present on every Node that the LoadBalancer health-check targets — blackhole risk.
+- Setting `internalTrafficPolicy: Local` on a Service consumed cluster-wide where backends are not co-located with consumers on every Node.
+
+### `service.kubernetes.io/topology-mode: Auto` annotation
+
+Annotation, additive. Only applies when `Service` is multi-zone with sufficient endpoints per zone.
+
+```bash
+kubectl annotate svc <name> -n <ns> \
+  service.kubernetes.io/topology-mode=Auto --overwrite
+```
+
+Rollback: `kubectl annotate svc <name> -n <ns> service.kubernetes.io/topology-mode-`
+
+### `spec.trafficDistribution` field (KEP-4444)
+
+Newer API; supersedes the annotation when both are set. Field-level patch on `v1.Service`.
+
+```bash
+kubectl patch svc <name> -n <ns> --type=merge \
+  -p '{"spec":{"trafficDistribution":"PreferClose"}}'
+```
+
+Rollback: `kubectl patch svc <name> -n <ns> --type=json -p='[{"op":"remove","path":"/spec/trafficDistribution"}]'`
+
+## CoreDNS Corefile patch (medium blast radius, reversible with backup)
+
+The CoreDNS `reload` plugin polls the Corefile every 30 seconds. If the new Corefile is invalid, CoreDNS rejects the reload and continues serving the previous config — but if the pod restarts for any other reason, it will fail to start. Always have a baseline.
+
+```bash
+# Capture baseline (CRITICAL — never skip)
+kubectl get cm coredns -n kube-system -o yaml > /tmp/coredns.before.yaml
+
+# Apply
+kubectl apply -f /tmp/coredns.new.yaml
+
+# Verify reload (look for "Reloading complete" in logs within 60 seconds)
+kubectl -n kube-system logs -l k8s-app=kube-dns --tail=50 --since=2m | grep -i "reload"
+
+# Verify no CrashLoopBackOff
+kubectl -n kube-system get pods -l k8s-app=kube-dns
+
+# If any pod is unhealthy — rollback
+kubectl apply -f /tmp/coredns.before.yaml
+```
+
+Refusal triggers:
+- New Corefile lacks the `reload` plugin (would prevent future zero-downtime updates).
+- New Corefile lacks the `loop` plugin (CoreDNS forward-loop detection).
+- New Corefile lacks the `health` plugin (liveness probe target removed).
+- New Corefile lacks the `kubernetes` plugin or its `pods insecure` mode set to anything other than the cluster's documented standard.
+- `forward .` target is changed to a private IP without confirming reachability from CoreDNS pod network.
+
+## NodeLocal DNSCache install / upgrade (medium blast radius, requires explicit human gate)
+
+Manifest from upstream `kubernetes/dns` repository (`nodelocaldns.yaml`). The install adds a `DaemonSet` and patches kube-proxy iptables / IPVS rules to redirect DNS traffic to the local cache. **This is a node-wide control-plane change**; refuse without an explicit human go-ahead even though the manifest itself is documented.
+
+```bash
+# Capture cluster DNS service IP for the manifest's __PILLAR__LOCAL__DNS__ token
+kubectl get svc -n kube-system kube-dns -o jsonpath='{.spec.clusterIP}'
+
+# Apply the upstream-rendered manifest (with values substituted)
+kubectl apply -f /tmp/nodelocaldns-rendered.yaml
+
+# Verify rollout — every Node must have a Ready node-local-dns pod within 5 minutes
+kubectl rollout status ds/node-local-dns -n kube-system --timeout=5m
+
+# Rollback (uninstall — high impact, plan before applying)
+kubectl delete -f /tmp/nodelocaldns-rendered.yaml
+```
+
+Refusal triggers:
+- Cluster does not run kube-proxy or Cilium kube-proxy replacement (NodeLocalDNS depends on a kube-proxy mode that supports the iptables / IPVS redirect).
+- The `DaemonSet` request lacks `resources.limits.memory` (NodeLocal DNSCache OOM is a known node-wide DNS outage).
+- The `DaemonSet` request lacks a `PodDisruptionBudget`.
+- Node selector excludes any node — partial DNS coverage is worse than none.
+
+## Gateway API resources (medium blast radius, reversible)
+
+### `Gateway` resource
+
+```bash
+# Pre-check: GatewayClass must reference a controller that is actually running
+GWC=$(yq '.spec.gatewayClassName' /tmp/gw.yaml)
+CONTROLLER=$(kubectl get gatewayclass $GWC -o jsonpath='{.spec.controllerName}')
+# Confirm controller pods are Ready before applying
+
+kubectl apply -f /tmp/gw.yaml
+kubectl wait --for=condition=Programmed gateway/<name> -n <ns> --timeout=2m
+
+# Status verification
+kubectl get gateway <name> -n <ns> -o jsonpath='{.status.conditions}'
+```
+
+Refusal triggers:
+- `GatewayClass` does not exist or its controller is not running.
+- `spec.allowedRoutes.namespaces.from: All` without an accompanying `ReferenceGrant` strategy — security boundary expansion.
+- `Listener` overlap on (port, protocol, hostname) with existing Gateway in same scope.
+
+### `HTTPRoute` / `GRPCRoute` / `TLSRoute`
+
+GA / Standard channel since Gateway API v1.1.0 (per `gateway-api.sigs.k8s.io/api-types/grpcroute`).
+
+```bash
+kubectl apply -f /tmp/route.yaml
+kubectl wait --for=condition=Accepted httproute/<name> -n <ns> --timeout=1m
+
+# Status verification — Accepted: True AND ResolvedRefs: True per parent
+kubectl get httproute <name> -n <ns> -o jsonpath='{.status.parents}'
+```
+
+Refusal triggers:
+- Route attaches to a Gateway that is not in `Programmed: True`.
+- `parentRefs` reference a Gateway in another namespace without a matching `ReferenceGrant`.
+
+### `ReferenceGrant`
+
+Cross-namespace authorization for routes. Always-additive; deletion can break in-flight routes.
+
+```bash
+kubectl apply -f /tmp/refgrant.yaml
+# No status conditions; verify by querying the route's ResolvedRefs.
+```
+
+## Cilium ClusterMesh peer Secret (medium blast radius, requires explicit human gate)
+
+Creates a `Secret` in the Cilium namespace whose data field carries the peer cluster's etcd client certificate, key, and CA. **Never log or print the data fields.**
+
+```bash
+# Capture baseline (confirm absence)
+kubectl get secret cilium-clustermesh -n kube-system 2>&1 | tee /tmp/clustermesh-pre.txt
+
+# Apply the peer secret — secret data is sensitive
+kubectl apply -f /tmp/clustermesh-peer.yaml
+
+# Verify ClusterMesh comes up
+kubectl exec -n kube-system ds/cilium -- cilium clustermesh status
+
+# Rollback
+kubectl delete secret cilium-clustermesh -n kube-system
+```
+
+Refusal triggers:
+- Secret destination namespace does not match the documented Cilium ClusterMesh namespace for this cluster.
+- Secret name does not exactly match the peer cluster identifier.
+- Secret data contains plaintext that looks like a CA or client key but is not properly base64-encoded for the `Secret` `data` field.
+- ClusterMesh peer `policy-default-local-cluster` flag has not been considered (delegate to `cilium-network-policy-review-agent`).