From a6c694681a1d2bc0122090368f6e3097ec2a4fee Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 08:55:04 +0200 Subject: [PATCH 01/10] docs(rfc): clarify node-rescan-requested annotation behavior Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index 369ca350..a026db6a 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -56,10 +56,15 @@ are considered for scanning. If not specified, all the nodes are going to be sca The `NodeScanConfiguration` is primarily used to schedule periodic scans over time through the `scanInterval` attribute. -To trigger an immediate scan outside the regular interval, the user can annotate -the `NodeScanConfiguration` resource with `sbomscanner.kubewarden.io/node-rescan-requested: "true"`. -This will trigger a new scan immediately, and the annotation will be automatically -removed after the scan is completed. +To trigger an immediate scan outside the regular interval, +the user can annotate the `NodeScanConfiguration` resource with +`sbomscanner.kubewarden.io/node-rescan-requested: "true"`. +This bypasses the `scanInterval` timer and schedules a new `NodeScanJob` +for every node matched by the `nodeSelector` +(or every node in the cluster if no selector is set). +Nodes that already have a `NodeScanJob` in progress are skipped +so an in-flight scan is never duplicated. +The annotation is automatically removed once the corresponding `NodeScanJob` resources have been created. Please, note that `NodeScanConfiguration` is a singleton resource, meaning that there can be only one instance of it in the cluster. From 1b76845159140502b98256600d38f8091ad3e557 Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 08:55:22 +0200 Subject: [PATCH 02/10] docs(rfc): document NodeScanConfiguration enabled field Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index a026db6a..c417a053 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -74,6 +74,10 @@ meaning that there can be only one instance of it in the cluster. For this feature we are going to add the following CRDs: * `NodeScanConfiguration`: Defines the global scan settings. + * `enabled`: Controls whether node scanning is active. + Defaults to `true`. + When set to `false`, all node scan resources are cleaned up, + similarly to what happens when the `NodeScanConfiguration` is deleted. * `scanInterval`: Duration between automated scans. * `nodeSelector`: Filter which nodes are scanned. If not specified, all the nodes are scanned. From 110b71287ce850730136e3b67abcb1b45ababa32 Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 08:55:32 +0200 Subject: [PATCH 03/10] docs(rfc): document default skipPatterns for container-runtime state Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index c417a053..cba7b83c 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -83,7 +83,20 @@ For this feature we are going to add the following CRDs: If not specified, all the nodes are scanned. * `skipPatterns`: A list of file/directory paths to be ignored. This can be expressed as .gitignore-like patterns (eg. `**/tmp/**` to ignore all the `tmp` directories). - If not specified, no file is ignored. + If the field is left unset, a default list of container-runtime state directories is applied so that + OCI image content already covered by registry scanning is not rescanned as raw files on disk. + The defaults are: + * `/var/lib/containerd/` + * `/var/lib/docker/` + * `/var/lib/rancher/k3s/agent/containerd/` + * `/var/lib/rancher/rke2/agent/containerd/` + * `/var/lib/containers/` + * `/run/containerd/` + * `/run/k3s/containerd/` + + A user-supplied list replaces the defaults entirely; there is no merging. + To scan everything (including the paths above), set `skipPatterns: []` explicitly. + An empty list is preserved by the apiserver and disables the defaults. Here's an example of how to use the `skipPatterns` field: ```yaml # Gitignore-style patterns to exclude from filesystem scans. From 359088f47f54da86266b2a44dbaefd69d6eb166d Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 08:55:44 +0200 Subject: [PATCH 04/10] docs(rfc): expand nodescan drawbacks with capability and always-running notes Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index cba7b83c..acbad0aa 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -263,6 +263,15 @@ Garbage collection is crucial to prevent resource orphaning and to maintain a cl [drawbacks]: #drawbacks -Mounting the host filesystem into a container bridges the isolation boundary and -introduces significant risk. To mitigate potential host compromise, the `DaemonSet` +Mounting the host filesystem into a container bridges the isolation boundary and +introduces significant risk. To mitigate potential host compromise, the `DaemonSet` must mount the host root filesystem as `readOnly: true`. + +The worker container also needs the `CAP_DAC_READ_SEARCH` Linux capability +(all other capabilities are dropped). +This capability lets the scanner bypass discretionary access-control read and +directory-search checks so that Trivy can walk the entire host filesystem. + +A further drawback is that the `DaemonSet` runs continuously on every matching node, +even though the worker only performs actual work when it receives a scan job. +In future development we can consider a mechanism to run the pod only while a scan is in progress. From fe19082413a9fee0b502c424cdf6d6adaeb7aae2 Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 09:22:22 +0200 Subject: [PATCH 05/10] docs(rfc): format .gitignore consistently and use "e.g." Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index acbad0aa..2b15056b 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -82,7 +82,7 @@ For this feature we are going to add the following CRDs: * `nodeSelector`: Filter which nodes are scanned. If not specified, all the nodes are scanned. * `skipPatterns`: A list of file/directory paths to be ignored. - This can be expressed as .gitignore-like patterns (eg. `**/tmp/**` to ignore all the `tmp` directories). + This can be expressed as `.gitignore`-style patterns (e.g., `**/tmp/**` to ignore all `tmp` directories). If the field is left unset, a default list of container-runtime state directories is applied so that OCI image content already covered by registry scanning is not rescanned as raw files on disk. The defaults are: From 5005b1ed9f461fa887a50ca3152cc59ab1e49038 Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 09:34:06 +0200 Subject: [PATCH 06/10] docs(rfc): clarify rescan annotation is removed after attempted creation Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index 2b15056b..44454761 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -64,7 +64,7 @@ for every node matched by the `nodeSelector` (or every node in the cluster if no selector is set). Nodes that already have a `NodeScanJob` in progress are skipped so an in-flight scan is never duplicated. -The annotation is automatically removed once the corresponding `NodeScanJob` resources have been created. +The annotation is automatically removed once the runner has attempted to create the corresponding `NodeScanJob` resources. Please, note that `NodeScanConfiguration` is a singleton resource, meaning that there can be only one instance of it in the cluster. From 95b07cde04f2a48c96868a916b6836b99dc834fa Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 09:34:21 +0200 Subject: [PATCH 07/10] docs(rfc): use "API server" wording for consistency with kubernetes docs Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index 44454761..3ff1674e 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -96,7 +96,7 @@ For this feature we are going to add the following CRDs: A user-supplied list replaces the defaults entirely; there is no merging. To scan everything (including the paths above), set `skipPatterns: []` explicitly. - An empty list is preserved by the apiserver and disables the defaults. + An empty list is preserved by the API server and disables the defaults. Here's an example of how to use the `skipPatterns` field: ```yaml # Gitignore-style patterns to exclude from filesystem scans. From dc820e74a93d197ab049ccb53dd23ef2d5d9eee1 Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 09:34:28 +0200 Subject: [PATCH 08/10] docs(rfc): use kubernetes-style DAC_READ_SEARCH capability name Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index 3ff1674e..f3656bbf 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -267,7 +267,7 @@ Mounting the host filesystem into a container bridges the isolation boundary and introduces significant risk. To mitigate potential host compromise, the `DaemonSet` must mount the host root filesystem as `readOnly: true`. -The worker container also needs the `CAP_DAC_READ_SEARCH` Linux capability +The worker container also needs the `DAC_READ_SEARCH` Linux capability (all other capabilities are dropped). This capability lets the scanner bypass discretionary access-control read and directory-search checks so that Trivy can walk the entire host filesystem. From c26bf056bac783a866068eaee341c796cbe3eb2d Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 10:07:38 +0200 Subject: [PATCH 09/10] docs(rfc): note DAC_READ_SEARCH incompatibility with restricted/baseline PSA Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index f3656bbf..e22553f9 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -271,6 +271,8 @@ The worker container also needs the `DAC_READ_SEARCH` Linux capability (all other capabilities are dropped). This capability lets the scanner bypass discretionary access-control read and directory-search checks so that Trivy can walk the entire host filesystem. +Because of this requirement, the worker cannot run in a namespace enforcing the +`restricted` or `baseline` Pod Security Admission profiles. A further drawback is that the `DaemonSet` runs continuously on every matching node, even though the worker only performs actual work when it receives a scan job. From ef6a9473fe036464475ecbfcfeead21ff316663d Mon Sep 17 00:00:00 2001 From: Fabrizio Sestito Date: Fri, 3 Jul 2026 10:13:30 +0200 Subject: [PATCH 10/10] docs(rfc): suggest dedicated namespace for node worker as PSA future work Signed-off-by: Fabrizio Sestito --- docs/rfc/0008_node_scan.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/rfc/0008_node_scan.md b/docs/rfc/0008_node_scan.md index e22553f9..549e88a7 100644 --- a/docs/rfc/0008_node_scan.md +++ b/docs/rfc/0008_node_scan.md @@ -273,6 +273,9 @@ This capability lets the scanner bypass discretionary access-control read and directory-search checks so that Trivy can walk the entire host filesystem. Because of this requirement, the worker cannot run in a namespace enforcing the `restricted` or `baseline` Pod Security Admission profiles. +As a future improvement we might consider running the node worker pods in a +dedicated namespace so that the other components can still run under the +`restricted` PSA profile. A further drawback is that the `DaemonSet` runs continuously on every matching node, even though the worker only performs actual work when it receives a scan job.