feat(sandboxpolicy): drive the privilege gadget from the sandbox policy controller

cmd/main.go

@@ -577,6 +577,7 @@ func main() {
 			Kubernetes: k8sClient.GetKubernetesClient(), Dynamic: k8sClient.GetDynamicClient(),
 			Containers: mainHandler.GetContainerCollection(), Tracers: mainHandler.GetTracerCollection(),
 			NodeName: cfg.NodeName, AgentNamespace: cfg.NamespaceName, ImageName: cfg.SandboxPolicyImage, ImageArchive: "tracers.tar",
+			PrivilegeImageName: cfg.SandboxPolicyPrivilegeImage, QualifiedKernels: cfg.SandboxPolicyQualifiedKernels,
 			ContainerdSocket: cfg.SandboxPolicyContainerdSocket, ControlRoot: cfg.SandboxPolicyControlRoot, MaxOwners: cfg.SandboxPolicyMaxOwners,
 			Sources:   sandboxintegration.NewProfileResolver(storageClient.GetStorageClient()),
 			Receivers: thirdPartyTracers.ThirdPartyEventReceivers,

docs/features/sandbox-policy.md

@@ -68,6 +68,47 @@ This change does not grant chart RBAC, change a chart version or store policy in
 SQLite/files. Kubernetes owns the CRD objects. Per-policy/node status resources
 are output; the agent does not write parent aggregate status.
 
+Each report carries `appliedGeneration`, the oldest policy generation still
+installed on the node, counting container bindings and privilege pod cgroup
+bindings. It stays on the last-good generation while a newer revision is
+rejected, and is absent when no binding enforces the policy. `stale` is set only
+when an installed binding lags the desired generation or its protection cannot be
+confirmed: a failure that leaves the current generation enforced is `Ready=False`
+with `stale: false`. At
+startup the agent reads the host's active LSM list once. Every section enforces
+through BPF LSM, so when `bpf` is missing every report says `tier: none`, and
+every enabled policy reports `Ready=False` with reason `BPFLSMInactive`.
+
+A privilege pod cgroup binding counts only where the witness counters confirm
+it: the pod was bound before any of its containers existed, in the instance
+that enforces now, and its slot has no tracking fault. "Its containers exist"
+comes from the pod's API status and from the container collection (by pod UID
+and by cgroup path); a container created after that snapshot is seen at the
+next call. A pod whose containers already exist gets no pod binding; its
+containers rely on their own bindings. A bound pod whose plan changes later
+moves to its new slot, unconfirmed. While the instance is not ready, every pod
+binding is unconfirmed.
+A pod binding whose slot has a fault makes the policy report
+`ProtectionUnconfirmed`. For a Strict slot a node tracking fault (a lost child
+mark of a `CLONE_INTO_CGROUP` fork anywhere on the node) is a fault too; a new
+instance clears it; node faults alone start a new instance at most every 10
+minutes, because their cause may persist.
+
+The privilege section reports Ready only on a qualified kernel:
+`sandboxPolicyQualifiedKernels` lists kernel releases (`uname -r`); unset or empty uses
+the built-in list of kernels where the kernel tests passed, today the AL2023 amd64
+fleet kernel `6.12.113-138.209.amzn2023.x86_64` (`6.18.56-125.164.amzn2023.x86_64`
+joins after its run), and `["*"]` admits every kernel. On another
+kernel the section still enforces, but every privilege policy reports
+`Ready=False` with reason `PrivilegeKernelUnqualified`.
+
+A privilege change commits in two phases: the privilege slot is prepared first
+(this can replace the node instance and binds nothing), then exec commits, then
+the privilege bind is a live map write. A failed prepare leaves both sections on
+their last-good plan. Removing the privilege section withdraws it first: a
+withdraw on an instance that is not ready stays pending and is retried, and exec
+does not change meanwhile.
+
 ## Reconciliation and failure behavior
 
 Configuration watch events are **refresh hints**, not trusted queued payloads.

go.mod

@@ -39,7 +39,7 @@ require (
 	github.com/kubescape/backend v0.0.39
 	github.com/kubescape/go-logger v0.0.35
 	github.com/kubescape/k8s-interface v0.0.214
-	github.com/kubescape/storage v0.0.388-0.20261105083812-136b4c98606f
+	github.com/kubescape/storage v0.0.388-0.20261109155453-fa55b25a70a3
 	github.com/kubescape/workerpool v0.0.0-20250526074519-0e4a4e7f44cf
 	github.com/moby/sys/mountinfo v0.7.2
 	github.com/opcoder0/fanotify v0.4.2

go.sum

@@ -1459,6 +1459,8 @@ github.com/kubescape/storage v0.0.352-0.20261013133511-eb6406e01cb9 h1:pPFehIHOZ
 github.com/kubescape/storage v0.0.352-0.20261013133511-eb6406e01cb9/go.mod h1:OSYXj9TzVAuuz+Gn2bIzp3Vg8rofTPH7x5Asek0N7mE=
 github.com/kubescape/storage v0.0.388-0.20261105083812-136b4c98606f h1:KTA6ctZBLIi+XRZwKFtl8etQZOTPciSy/nfAtBizzlc=
 github.com/kubescape/storage v0.0.388-0.20261105083812-136b4c98606f/go.mod h1:z3uiLdH1O3+eNiKuEOOalJy9uqH7ggNepaUSSWWm5ps=
+github.com/kubescape/storage v0.0.388-0.20261109155453-fa55b25a70a3 h1:oSyi5Tiixb+25/HMG03DiKtmiQiyQbuXs0p1F/WKfik=
+github.com/kubescape/storage v0.0.388-0.20261109155453-fa55b25a70a3/go.mod h1:z3uiLdH1O3+eNiKuEOOalJy9uqH7ggNepaUSSWWm5ps=
 github.com/kubescape/syft v1.32.0-ks.2 h1:xdUksUmKEyyVKsTfJDYW8Z5HawVJtelsUolPOsWtDx0=
 github.com/kubescape/syft v1.32.0-ks.2/go.mod h1:E6Kd4iBM2ljUOUQvSt7hVK6vBwaHkMXwcvBZmGMSY5o=
 github.com/kubescape/workerpool v0.0.0-20250526074519-0e4a4e7f44cf h1:hI0jVwrB6fT4GJWvuUjzObfci1CUknrZdRHfnRVtKM0=
@@ -1863,6 +1865,7 @@ github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8r
 github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
 github.com/seccomp/libseccomp-golang v0.11.0 h1:SDkcBRqGLP+sezmMACkxO1EfgbghxIxnRKfd6mHUEis=
 github.com/seccomp/libseccomp-golang v0.11.0/go.mod h1:5m1Lk8E9OwgZTTVz4bBOer7JuazaBa+xTkM895tDiWc=
+github.com/seccomp/libseccomp-golang v0.11.1 h1:wuk4ZjSx6kyQII4rj6G6fvVzRHQaSiPvccJazDagu4g=
 github.com/seccomp/libseccomp-golang v0.11.1/go.mod h1:5m1Lk8E9OwgZTTVz4bBOer7JuazaBa+xTkM895tDiWc=
 github.com/secure-systems-lab/go-securesystemslib v0.10.0 h1:l+H5ErcW0PAehBNrBxoGv1jjNpGYdZ9RcheFkB2WI14=
 github.com/secure-systems-lab/go-securesystemslib v0.10.0/go.mod h1:MRKONWmRoFzPNQ9USRF9i1mc7MvAVvF1LlW8X5VWDvk=
@@ -2917,6 +2920,7 @@ k8s.io/klog/v2 v2.140.0/go.mod h1:o+/RWfJ6PwpnFn7OyAG3QnO47BFsymfEfrz6XyYSSp0=
 k8s.io/kms v0.35.0/go.mod h1:VT+4ekZAdrZDMgShK37vvlyHUVhwI9t/9tvh0AyCWmQ=
 k8s.io/kms v0.37.0 h1:WDW3pSc5yFB1Od4YXXL3i5oK+vXI2v++LAV82+Ks1Z0=
 k8s.io/kms v0.37.0/go.mod h1:0U6zfwLkfJr9O/jLgz2GARnKLh2uIhkq2EeaU66J5ow=
+k8s.io/kms v0.37.1 h1:MD1kA8AdFF/N5sGP8gnvL6vTo/oeaQXbmLjWmmJHLc8=
 k8s.io/kms v0.37.1/go.mod h1:0U6zfwLkfJr9O/jLgz2GARnKLh2uIhkq2EeaU66J5ow=
 k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 h1:Y3gxNAuB0OBLImH611+UDZcmKS3g6CthxToOb37KgwE=
 k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912/go.mod h1:kdmbQkyfwUagLfXIad1y2TdrjPFWp2Q89B3qkRwf/pQ=

pkg/config/config.go

@@ -122,6 +122,8 @@ type Config struct {
 	EnableMetricsExporter          bool                                 `mapstructure:"prometheusExporterEnabled"`
 	EnableSandboxPolicy            bool                                 `mapstructure:"sandboxPolicyEnabled"`
 	SandboxPolicyImage             string                               `mapstructure:"sandboxPolicyImage"`
+	SandboxPolicyPrivilegeImage    string                               `mapstructure:"sandboxPolicyPrivilegeImage"`
+	SandboxPolicyQualifiedKernels  []string                             `mapstructure:"sandboxPolicyQualifiedKernels"`
 	SandboxPolicyContainerdSocket  string                               `mapstructure:"sandboxPolicyContainerdSocket"`
 	SandboxPolicyControlRoot       string                               `mapstructure:"sandboxPolicyControlRoot"`
 	SandboxPolicyMaxOwners         uint64                               `mapstructure:"sandboxPolicyMaxOwners"`
@@ -226,6 +228,9 @@ func LoadConfigOptional(path string, errNotFound bool) (Config, error) {
 
 	viper.SetDefault("sandboxPolicyEnabled", false)
 	viper.SetDefault("sandboxPolicyImage", "")
+	viper.SetDefault("sandboxPolicyPrivilegeImage", "")
+	// Unset: the built-in qualified kernel list. ["*"] admits every kernel.
+	viper.SetDefault("sandboxPolicyQualifiedKernels", nil)
 	viper.SetDefault("sandboxPolicyContainerdSocket", "")
 	viper.SetDefault("sandboxPolicyControlRoot", "")
 	viper.SetDefault("sandboxPolicyMaxOwners", 4)

pkg/ebpf/gadgets/common/enforcement/bindings.go

@@ -33,6 +33,11 @@ type ContainerIdentity = execruntime.ContainerIdentity
 type Binding struct {
 	Container ContainerIdentity
 	Slot      uint32
+	// SkipArming binds without arming the tasks already in the cgroup. Use it
+	// for a parent cgroup bound before its containers start: a container
+	// runtime helper can be there between its namespace setup and its exec,
+	// and must not be judged. Tasks are still armed at their own exec.
+	SkipArming bool
 	// Subtree also covers the descendant cgroups. Scope is exact by default;
 	// set it only for a parent cgroup bound before its containers start, and
 	// report it in status.
@@ -302,8 +307,8 @@ func (b *Bindings) bind(c Binding) error {
 	}
 	// A slot move arms again too: a task that the old slot left unarmed (an
 	// audit slot allows a fork whose child mark failed) must not escape the
-	// new slot.
-	if b.armed != nil {
+	// new slot. A SkipArming binding never arms.
+	if b.armed != nil && !c.SkipArming {
 		if err := b.armExisting(b.armed, id.CgroupPath); err != nil {
 			if bound && !errors.Is(err, ErrContainerGone) {
 				// Undo the move, so a retry moves and arms again.

pkg/ebpf/gadgets/common/enforcement/bindings_test.go

@@ -247,6 +247,31 @@ func TestSlotFaults(t *testing.T) {
 	}
 }
 
+func TestSkipArmingBindsWithoutArming(t *testing.T) {
+	b, policy, members, _ := newFixture(t, func(Map) error { return nil })
+	var armedPaths []string
+	b.armExisting = func(_ Map, path string) error { armedPaths = append(armedPaths, path); return nil }
+	parent := ContainerIdentity{Runtime: "parent", ID: "p1", CgroupID: 7, CgroupPath: "/kubepods.slice/kubepods-pod1.slice"}
+	b.desired[selector(parent)] = Binding{Container: parent, SkipArming: true}
+	if err := b.start(policy, members, &fakeMap{typ: ebpf.TaskStorage}, nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	// Only the initial container binding arms; the replayed parent does not.
+	if len(armedPaths) != 1 || armedPaths[0] != identity.CgroupPath || members.data[uint64(7)] != (bindingValue{}) {
+		t.Fatalf("startup armed %v bindings %v", armedPaths, members.data)
+	}
+	if err := b.Unbind(parent); err != nil {
+		t.Fatal(err)
+	}
+	if err := b.Bind(Binding{Container: parent, Slot: 1, SkipArming: true}); err != nil || len(armedPaths) != 1 || members.data[uint64(7)] != (bindingValue{Slot: 1}) {
+		t.Fatalf("live bind: %v armed %v bindings %v", err, armedPaths, members.data)
+	}
+	// A slot move of a SkipArming binding does not arm either.
+	if err := b.Bind(Binding{Container: parent, Slot: 0, SkipArming: true}); err != nil || len(armedPaths) != 1 {
+		t.Fatalf("slot move: %v armed %v", err, armedPaths)
+	}
+}
+
 func TestBindingFlags(t *testing.T) {
 	log := &[]string{}
 	policy := &fakeMap{typ: ebpf.Hash, data: map[interface{}]interface{}{}, log: log, name: "policy"}

pkg/ebpf/gadgets/enforce_privilege/README.md

@@ -128,7 +128,10 @@ policy:
 - **Scope.** A binding covers its exact cgroup, as in enforce_exec. A binding
   with `Subtree` (`BINDING_SUBTREE`) also covers its descendant cgroups at any
   depth; the owner sets it only for a parent cgroup bound before its containers
-  start, and reports it. A subtree binding must be at cgroup level 31 or less
+  start, and reports it. With `SkipArming` a container is then judged from its
+  first exec; the tasks already in the parent are not armed, also not at a
+  slot move or in a new instance, because a runtime helper can be there during
+  its setup. A subtree binding must be at cgroup level 31 or less
   (the controller refuses a deeper one; levels are counted in the owner's
   cgroup namespace, the kernel counts from the host root). The task's own
   binding wins, then the nearest parent that is a subtree binding or a Strict
@@ -150,6 +153,12 @@ policy:
 
 ## Known limits
 
+- **Parent bindings.** A subtree parent binding also judges the armed tasks
+  of its child cgroups that have no binding of their own, for example an
+  infrastructure (pause) process. OCI hooks are not armed under
+  `RuntimeHelpers` (see the next item). A new instance does not arm the tasks
+  that run only under a parent binding; they are judged again when their own
+  cgroup is bound or at their next exec.
 - **Runtime helpers are trusted under `RuntimeHelpers`.** In a binding with the
   flag, a task forked by an unarmed task inside the container (an OCI hook, or
   a process a hook leaves behind) is not judged, and neither are its children.

pkg/sandboxpolicy/availability.go

@@ -0,0 +1,45 @@
+package sandboxpolicy
+
+import (
+	"errors"
+	"fmt"
+)
+
+// EnforcementUnavailableError means a policy section cannot be enforced on this
+// node. Reason becomes the Ready condition reason in the node status.
+type EnforcementUnavailableError struct {
+	Section, Reason, Detail string
+	// Enforcing: the section enforces, but must not report Ready (for
+	// example on a kernel that is not qualified).
+	Enforcing bool
+}
+
+func (e *EnforcementUnavailableError) Error() string {
+	if e.Enforcing {
+		return fmt.Sprintf("%s enforces on this node but is not qualified: %s", e.Section, e.Detail)
+	}
+	return fmt.Sprintf("%s enforcement is unavailable on this node: %s", e.Section, e.Detail)
+}
+
+// PrivilegeAvailability is implemented by a backend that knows whether the
+// privilege section can be enforced on this node.
+type PrivilegeAvailability interface {
+	PrivilegeUnavailable() error
+}
+
+// privilegeUnavailable returns why the privilege section cannot be enforced,
+// or nil. It is called with c.mu held.
+func (c *Controller) privilegeUnavailable() error {
+	if a, ok := c.backend.(PrivilegeAvailability); ok {
+		return a.PrivilegeUnavailable()
+	}
+	return nil
+}
+
+func unavailableReason(err error) (string, string, bool) {
+	var u *EnforcementUnavailableError
+	if !errors.As(err, &u) {
+		return "", "", false
+	}
+	return u.Reason, u.Error(), true
+}

pkg/sandboxpolicy/compiler.go

@@ -30,8 +30,8 @@ func Compile(ctx context.Context, identity PolicyIdentity, spec api.PolicySpec,
 	if spec.Mode != api.ModeAudit && spec.Mode != api.ModeEnforce {
 		return result, fmt.Errorf("policy is not active: %q", spec.Mode)
 	}
-	if spec.File != nil || spec.Network != nil || spec.Privilege != nil || spec.Identity != nil {
-		return result, fmt.Errorf("non-exec sections are unsupported")
+	if spec.File != nil || spec.Network != nil || spec.Identity != nil {
+		return result, fmt.Errorf("file, network and identity sections are unsupported")
 	}
 	// JSON cloning preserves all pointers and slice fields of the API vocabulary.
 	data, err := json.Marshal(spec)
@@ -52,6 +52,7 @@ func Compile(ctx context.Context, identity PolicyIdentity, spec api.PolicySpec,
 			return result, fmt.Errorf("exec defaultMode requires native IG ABI support")
 		}
 	}
+	result.Privilege = copy.Privilege
 	names := make(map[string]bool)
 	for _, r := range result.Exec.Rules {
 		names[r.Name] = true
@@ -127,7 +128,7 @@ func Compile(ctx context.Context, identity PolicyIdentity, spec api.PolicySpec,
 		}
 	}
 	// Validate imported rules as well as authored rules after class expansion.
-	validated := api.PolicySpec{Containers: copy.Containers, Mode: copy.Mode, RootRole: result.RootRole, Exec: &result.Exec}
+	validated := api.PolicySpec{Containers: copy.Containers, Mode: copy.Mode, RootRole: result.RootRole, Exec: &result.Exec, Privilege: result.Privilege}
 	if err := api.ValidatePolicySpec(validated); err != nil {
 		return result, err
 	}
@@ -173,8 +174,13 @@ func validateShape(spec api.PolicySpec) error {
 	if spec.Mode == api.ModeOff {
 		return nil
 	}
-	if spec.File != nil || spec.Network != nil || spec.Privilege != nil || spec.Identity != nil {
-		return fmt.Errorf("non-exec sections are unsupported")
+	if spec.File != nil || spec.Network != nil || spec.Identity != nil {
+		return fmt.Errorf("file, network and identity sections are unsupported")
+	}
+	if spec.Privilege != nil {
+		if _, err := PrivilegeDocument("", spec.Mode, *spec.Privilege); err != nil {
+			return fmt.Errorf("privilege: %w", err)
+		}
 	}
 	if spec.Exec != nil {
 		if spec.Exec.Default != api.ActionAllow && spec.Exec.Default != api.ActionDeny {