fix(kubescape): require a cluster-wide posture exception to declare itself (#3010)

* fix(kubescape): require a cluster-wide posture exception to declare itself

An omitted spec.match makes a ClusterSecurityException suppress its controls
for every workload in the cluster. That is the widest scope the repository can
express and it is reached by typing nothing, so a forgotten scope and a
deliberate one produce byte-identical CRs and review has no signal to tell them
apart. Nine of the twenty committed exceptions were in that state.

Require an explicit platform.devantler.tech/cluster-wide: declared annotation
for it, failing closed on a missing marker, a malformed value, and on a CR that
both declares cluster-wide scope and sets spec.match. Each committed cluster-wide
exception now carries the marker with its actual justification -- including
pod-security-mutations and vpa-managed-resources, whose scopes are recorded as
knowingly wider than their own rationale.

Generated output is unchanged: the marker is source-side only.

* test(kubescape): assert which error each malformed cluster-wide marker returns

Every fixture in TestClusterWideAnnotationFailsClosed also omits spec.match, so
a regression that ignored the annotation entirely would still be rejected -- by
the undeclared-scope guard -- and the bare err != nil check stayed green while
the marker did nothing. Proven by ablation: with resolveClusterWideDeclaration
stubbed to always return false, the old assertion passes and the new one reports
the undeclared-scope error where it wanted the type error.

Author: devantler

k8s/bases/infrastructure/cluster-security-exceptions/admission-controllers.yaml

@@ -6,6 +6,12 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: admission-controllers
+  annotations:
+    # Cluster-wide on purpose: the webhook configurations these controls scan
+    # are installed by upstream charts across every controller namespace, and
+    # the platform sets none of them, so there is no narrower scope that is
+    # also complete.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     Admission webhook timeouts are configured by upstream Helm charts

k8s/bases/infrastructure/cluster-security-exceptions/cilium-network-policies.yaml

@@ -7,6 +7,12 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: cilium-network-policies
+  annotations:
+    # Cluster-wide on purpose: Cilium is the CNI for the whole cluster, so
+    # every namespace is segmented by CiliumNetworkPolicy rather than by the
+    # NetworkPolicy objects these controls look for. Scoping this would only
+    # make the controls fail somewhere Cilium is still the enforcement point.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     Platform uses CiliumNetworkPolicies for all network segmentation.

k8s/bases/infrastructure/cluster-security-exceptions/helm-chart-metadata.yaml

@@ -7,6 +7,11 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: helm-chart-metadata
+  annotations:
+    # Cluster-wide on purpose: the recommended-label conventions these controls
+    # check are set by whichever upstream chart rendered the object, in every
+    # namespace that runs one. The platform authors none of them.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     Third-party Helm charts use their own label conventions. Adding all

k8s/bases/infrastructure/cluster-security-exceptions/image-verification.yaml

@@ -11,6 +11,12 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: image-verification
+  annotations:
+    # Cluster-wide on purpose: C-0237 scans every workload image reference, and
+    # unsigned third-party chart images are spread across every namespace. The
+    # narrower posture is tracked as first-party pull enforcement (#2856), not
+    # as a scope on this exception.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     First-party images (ghcr.io/devantler-tech/*) are cosign-signed and

k8s/bases/infrastructure/cluster-security-exceptions/pod-security-mutations.yaml

@@ -15,6 +15,19 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: pod-security-mutations
+  annotations:
+    # Cluster-wide, and KNOWN to be wider than its own rationale (#2824). The
+    # compensating mutation named below excludes twelve namespaces —
+    # kube-system, kube-public, kube-node-lease, flux-system, longhorn-system,
+    # local-path-storage, kubescape, kubevirt, cdi, observability, velero,
+    # chaos-mesh — so in exactly those namespaces this exception suppresses
+    # C-0013/C-0016/C-0055/C-0211 with nothing injecting them. Six of the twelve
+    # are separately and deliberately excepted for C-0013/C-0016/C-0055 in
+    # infrastructure-privileged.yaml; C-0211 and the other six are not covered
+    # anywhere. Narrowing it needs a scope the CSE designators cannot yet spell
+    # (an In-list would fail every newly-onboarded namespace), which is why this
+    # is declared rather than fixed here.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     Kyverno mutate policy "add-security-context" injects these controls

k8s/bases/infrastructure/cluster-security-exceptions/talos-cis-control-plane-false-positives.yaml

@@ -37,6 +37,10 @@ metadata:
     # cluster-wide `kind: ".*"` designator for it, which the plugin would apply
     # to every workload in the cluster.
     platform.devantler.tech/headlamp-mirror: exclude
+    # Cluster-wide on purpose: every control here is a host-scanner finding on
+    # the control-plane node, which has no workload, namespace or kind to scope
+    # against. See the NO-`match:` note above.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     CIS control-plane checks that are false positives on Talos Linux, matching

k8s/bases/infrastructure/cluster-security-exceptions/talos-cis-worker-false-positives.yaml

@@ -40,6 +40,10 @@ metadata:
     # emit a cluster-wide `kind: ".*"` designator for it, which the plugin would
     # apply to every workload in the cluster.
     platform.devantler.tech/headlamp-mirror: exclude
+    # Cluster-wide on purpose: every control here is a host-scanner finding on
+    # the worker node, which has no workload, namespace or kind to scope
+    # against. See the NO-`match:` note above.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     CIS worker-node checks that are false positives on Talos Linux, matching Sidero's

k8s/bases/infrastructure/cluster-security-exceptions/upstream-chart-defaults.yaml

@@ -9,6 +9,12 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: upstream-chart-defaults
+  annotations:
+    # Cluster-wide on purpose: C-0258 is an etcd-level property of the Talos
+    # control plane with no workload scope at all, and the remaining three are
+    # properties of upstream chart images and operator hostPath usage that
+    # appear wherever those charts are installed.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     These controls flag behaviors defined by upstream Helm charts or the

k8s/bases/infrastructure/cluster-security-exceptions/vpa-managed-resources.yaml

@@ -9,6 +9,13 @@ apiVersion: kubescape.io/v1beta1
 kind: ClusterSecurityException
 metadata:
   name: vpa-managed-resources
+  annotations:
+    # Cluster-wide, and KNOWN to be wider than its own rationale: the reason
+    # below holds only where a VPA object actually right-sizes the workload,
+    # which is not every namespace. Narrowing it to the workloads VPA manages
+    # is tracked in #2824 alongside the same defect in pod-security-mutations.
+    # Declared here so the scope is a recorded decision rather than an omission.
+    platform.devantler.tech/cluster-wide: declared
 spec:
   reason: >-
     VPA manages resource requests and limits at pod admission time.

scripts/generate-kubescape-exceptions/main.go

@@ -60,6 +60,20 @@ const (
 	// cluster-wide designator would except that control for every workload.
 	mirrorExclude = "exclude"
 
+	// clusterWideAnnotation declares that an exception is MEANT to suppress its
+	// controls for every workload in the cluster. An omitted `spec.match` is
+	// what produces that scope, so without this marker the widest exception the
+	// repository can express is also the one written by typing the least, and a
+	// forgotten scope is indistinguishable from a deliberate one. Suppression is
+	// silent — an excepted workload that genuinely violates a control reads
+	// exactly like a compliant one — so the scope has to be stated, not inferred
+	// from an absence.
+	clusterWideAnnotation = "platform.devantler.tech/cluster-wide"
+	// clusterWideDeclared is the only accepted clusterWideAnnotation value. As
+	// with mirrorExclude, any other value fails closed rather than being read as
+	// a declaration: a typo must not grant cluster-wide suppression.
+	clusterWideDeclared = "declared"
+
 	formatKubescape = "kubescape"
 	formatConfigMap = "headlamp-configmap"
 
@@ -362,6 +376,42 @@ func resolveMirrorExclusion(metadata map[string]any, path, name string) (bool, e
 	return true, nil
 }
 
+// resolveClusterWideDeclaration reads the CR's cluster-wide scope marker.
+//
+// Absent annotation => not declared, which is the safe default: an exception
+// that forgot to scope itself then fails closed at conversion instead of
+// silently excepting its controls for every workload in the cluster.
+func resolveClusterWideDeclaration(metadata map[string]any, path, name string) (bool, error) {
+	rawAnnotations, present := metadata["annotations"]
+	if !present || rawAnnotations == nil {
+		return false, nil
+	}
+
+	// Same fail-closed reasoning as resolveMirrorExclusion: a malformed
+	// annotations block must not be read as "no marker", because here that
+	// reading is the permissive one.
+	annotations, ok := rawAnnotations.(map[string]any)
+	if !ok {
+		return false, cseErrorf(path, name, "metadata.annotations must be a mapping, got %v", rawAnnotations)
+	}
+
+	raw, ok := annotations[clusterWideAnnotation]
+	if !ok {
+		return false, nil
+	}
+
+	value, ok := raw.(string)
+	if !ok {
+		return false, cseErrorf(path, name, "%s must be a string, got %v", clusterWideAnnotation, raw)
+	}
+
+	if value != clusterWideDeclared {
+		return false, cseErrorf(path, name, "unsupported %s value %q (only %q is recognised)", clusterWideAnnotation, value, clusterWideDeclared)
+	}
+
+	return true, nil
+}
+
 // convertDocument converts one ClusterSecurityException document; nil for other kinds.
 func convertDocument(doc any, path string) (*policy, error) {
 	document, ok := doc.(map[string]any)
@@ -438,6 +488,22 @@ func convertDocument(doc any, path string) (*policy, error) {
 		match = parsed
 	}
 
+	clusterWide, err := resolveClusterWideDeclaration(metadata, path, name)
+	if err != nil {
+		return nil, err
+	}
+
+	switch {
+	case len(match) == 0 && !clusterWide:
+		return nil, cseErrorf(path, name,
+			"no spec.match, which excepts these controls for EVERY workload; scope it, or declare the scope with the %s: %s annotation",
+			clusterWideAnnotation, clusterWideDeclared)
+	case len(match) > 0 && clusterWide:
+		return nil, cseErrorf(path, name,
+			"declares %s: %s but also sets spec.match; the marker would claim a scope the exception does not have",
+			clusterWideAnnotation, clusterWideDeclared)
+	}
+
 	resources, err := resolveMatch(match, path, name)
 	if err != nil {
 		return nil, err