Kubewarden SBOM Scanner use cases

These are example use cases for Kubewarden SBOM Scanner. Each case names a persona and a goal. Then it explains how SBOM Scanner meets that goal.

Case A: As a cluster operator, I want to know which vulnerabilities are in my registries.

I create a Registry resource for each registry that I want to scan. SBOM Scanner discovers the images in the registry. If the SBOM resource of an image does not exist, it generates a Software Bill of Materials (SBOM) for that image. Then it scans each SBOM for vulnerabilities and stores a VulnerabilityReport.

I set spec.scanInterval on the Registry to scan on a schedule. I create a ScanJob to scan on demand. A ScanJob works like a Kubernetes Job. I can watch its status with kubectl.

A registry can contain many images that I do not run. I limit the scan with filters:

  • spec.platforms selects the operating systems and architectures that I run.

  • spec.repositories selects the repositories to scan.

  • matchConditions selects tags with CEL expressions. For example, only tags that are semantic versions, or only tags that end in -prod.

SBOM Scanner uses the SBOM as the source of truth. When the vulnerability database changes, the scanner reads the stored SBOM again. It does not pull the image again. Images with the same digest share one SBOM.

My registries can require credentials or a private certificate authority. I set spec.authSecret and spec.caBundle on the Registry. In an air-gapped cluster, I mirror the vulnerability databases and the VEX repositories to internal servers.

See Scanning Registries, Private Registries, and Air Gap Support.

Case B: As a platform team, I want to know which vulnerabilities affect the workloads that run in my cluster.

A registry scan tells me what exists. It does not tell me what runs. I enable the WorkloadScanConfiguration resource. SBOM Scanner watches Pods, Deployments, StatefulSets, DaemonSets, Jobs, and CronJobs. It finds the images that they use. It creates and manages the Registry resources for those images.

For each workload, SBOM Scanner creates a WorkloadScanReport. The report lists the containers of the workload and their vulnerabilities. It gives one summary for the whole workload. I use it to answer one question: what must I fix in this Deployment?

I roll out workload scanning in phases. I set spec.namespaceSelector to select the namespaces to scan. I add namespaces when I am ready.

Each WorkloadScanReport lives in the namespace of its workload. Teams read the reports for their namespaces with the usual Kubernetes RBAC. I can set spec.artifactsNamespace to keep the managed Registry resources and their images, SBOMs, and vulnerability reports in one central namespace.

The Image resource lists the workloads that use the image. I use this list when one image has a critical vulnerability. I find the affected workloads without a manual search.

See Scanning Workloads.

Case C: As a cluster operator, I want to know that the nodes under my workloads are safe.

Nodes are the base of the cluster. I enable the NodeScanConfiguration resource. A worker runs on each node as a DaemonSet. It reads the host file system, generates a NodeSBOM, and scans it. The result is a NodeVulnerabilityReport for each node.

I set spec.scanInterval to scan the nodes on a schedule. I set spec.nodeSelector to select the nodes to scan. I set spec.skipPatterns to exclude paths from the scan. The default patterns skip the image store of the container runtime. The registry scan already covers that content. I add an annotation to the NodeScanConfiguration to request an immediate scan of all matching nodes.

The node worker mounts the host root file system as read-only. It also needs the DAC_READ_SEARCH Linux capability. As a result, it cannot run in a namespace that enforces the restricted or baseline Pod Security Admission profiles.

See Scanning Nodes.

Case D: As a security engineer, I want fewer false positives, so that I can focus on remediation.

A vulnerability report often lists CVEs that do not affect the image. A vendor can publish a Vulnerability Exploitability eXchange (VEX) statement for such a CVE. I create a VEXHub resource for each VEX Hub repository that I trust. SBOM Scanner installs repositories from Rancher and Aqua Security by default. In an air-gapped cluster, I point a VEXHub at an internal mirror.

The scanner applies the VEX statements during the scan. It marks the matched vulnerabilities as suppressed and records the VEX status. The summary of the report does not count the suppressed vulnerabilities.

For each vulnerability that remains, the report gives me the data that I need to act:

  • The package name, the package URL (PURL), and the installed version.

  • The fixed versions, if a fix exists.

  • The image layer that added the package.

  • The severity and the CVSS scores from each vendor.

I query the reports with kubectl and field selectors. For example, I list all the reports for one repository or one tag.

See VEX Support and Querying SBOM and VulnerabilityReport Resources.

Case E: As an integrator, I want to consume scan results with my own tools.

All the scan results are Kubernetes resources. I do not need a separate API or database client.

  • I read VulnerabilityReport, WorkloadScanReport, and NodeVulnerabilityReport resources with kubectl, with a Kubernetes client library, or through the Kubernetes REST API.

  • I create Registry and ScanJob resources from a GitOps repository. The status conditions tell my pipeline when a scan completes or fails.

  • I export traces and metrics to an OpenTelemetry collector. A CI pipeline can set the traceparent annotation on a ScanJob. Then the whole scan becomes part of the pipeline trace.

  • I connect an AI assistant to the experimental MCP server. The assistant finds the most vulnerable images, workloads, or nodes with natural language.

  • I view the results in the Rancher UI.

The reports are standard resources. As a result, context-aware policies of the Kubewarden Admission Controller can read them and act on them.

See Querying SBOM and VulnerabilityReport Resources, OpenTelemetry, and MCP Server (Experimental).

Non-goals

SBOM Scanner does not intend to:

  • Enforce policies or block deployments. This is the role of the Kubewarden Admission Controller.

  • Detect malicious behavior at runtime. This is the role of the Kubewarden Runtime Enforcer.

  • Patch or rebuild images.

  • Run compliance benchmarks for the cluster.

  • Scan OCI artifacts that are not container images, for example signatures, attestations, and Helm charts.