Kubescape

In-cluster security posture, image vulnerability, and SBOM scanning of running workloads.

Agentic Friendly

Component Category

Platform governance / security posture and vulnerability scanning

Component Description

Kubescape scans the workloads running in the cluster. It checks Kubernetes resources against security frameworks, scans container images for known vulnerabilities, and generates a software bill of materials (SBOM) for each image. Results are stored as Kubernetes resources inside the cluster.

Why It Is Used

In BullSequana AI Foundation, Kubescape shows the security state of what is actually running, including tenant and dynamically created workloads that never passed through the platform's own image pipeline. It also reports vulnerabilities disclosed after an image was published. Findings stay inside the cluster and follow Kubernetes access control.

Learn More

What is scanned

ScanWhat it checksSchedule
Configuration (posture)Kubernetes resources against the allcontrols, nsa, mitre, security, and cis-v1.12.0 frameworksDaily
VulnerabilityContainer images of running workloads, using the Grype vulnerability database, plus an SBOM per imageDaily

Both scans cover every namespace except Kubernetes system namespaces and the kubescape namespace itself, so platform and tenant namespaces are included.

By default, both scans start once a day at the same time, which the chart derives from the cluster name, so clusters do not scan at the same moment. kubectl get cronjobs -n kubescape shows the schedule in use. To set a fixed time, put a cron expression in configuration_scan and vulnerability_scan under [schedule], or in KUBESCAPE_SCHEDULE_CONFIGURATION_SCAN and KUBESCAPE_SCHEDULE_VULNERABILITY_SCAN. The defaults, 0 8 * * * and 0 0 * * *, are the values that select the derived time.

Kubescape reads registry credentials from the pull secrets of the scanned pods. Private images are therefore scanned only while a workload that uses them has a running pod.

Deployment notes

Optional component

Kubescape is not deployed by default. To deploy it, set [component] enabled = true in its variables.toml or KUBESCAPE_COMPONENT_ENABLED=true.

When deployed, Kubescape runs in the kubescape namespace at sync wave 10 in the common tier, after storage providers are available. The namespace enforces the Kubernetes restricted Pod Security Standard.

Four components run:

  • Operator, which schedules and dispatches scans.
  • Kubescape, which runs configuration scans.
  • Kubevuln, which runs vulnerability scans. Its sbom-scanner sidecar generates the SBOMs, sized separately under [resources.sbom_scanner] ([kubevuln] sbom_scanner). Kubevuln is sized for large AI images and unpacks images on a dedicated 100 Gi scratch volume ([kubevuln] tmp_dir_size).
  • Storage, an aggregated Kubernetes API that stores scan results on a 5 Gi persistent volume ([resources.storage] size).

Both volumes use the site's RWO storage class.

The node agent, runtime threat detection, and the Kubescape admission controller are not deployed. The platform's admission controls stay with Kyverno and Kubernetes ValidatingAdmissionPolicies. Kubescape has no vendor cloud backend: results never leave the cluster, and the scanners do not download policy updates or check for new versions.

Vulnerability scans need outbound HTTPS access to grype.anchore.io. Kubevuln downloads the Grype vulnerability database from there and checks it for updates, and vulnerability scanning depends on that database. Kubevuln also pulls each scanned image from its registry. Configuration scans need no outbound access. On a site that restricts egress, allow this traffic from the kubescape namespace.

On a site without outbound access, set [grype_offline_db] enabled = true (KUBESCAPE_GRYPE_OFFLINE_DB_ENABLED=true). Kubescape then runs an in-cluster Grype database mirror from the kubescape/grype-offline-db image in the platform registry, and Kubevuln reads the database from it instead of grype.anchore.io. The mirror serves the database built into the image, so vulnerability data is as current as the mirrored image tag ([image] grype_offline_db_tag, v6-latest by default). With the in-cluster mirror off, [grype_offline_db] listing_url points Kubevuln at another mirror that publishes a Grype listing.

Ingress network policies limit access to each component. Kubescape and Kubevuln accept traffic only from the operator, the operator accepts traffic only from the scan schedulers, and Kubevuln metrics accept traffic only from Prometheus. The storage API accepts connections on its API port from any source, so that the Kubernetes API server can reach it. The policies do not restrict egress. Enforcement depends on a network policy engine in the cluster.

Configuration and sizing are set in the component's variables.toml. See Configuration Model for environment overrides.

Reading findings

Findings are Kubernetes resources in the spdx.softwarecomposition.kubescape.io API group. There is no user interface for them. The Kubescape operator has no built-in one: its web view is part of the vendor's cloud service, which BullSequana AI does not connect to so that findings stay in the cluster, and the platform deploys no other viewer. Findings are not exported to Prometheus or Grafana. Platform operators with cluster access read them with kubectl:

ResourceScopeContent
vulnerabilitysummariesCluster, one per namespaceVulnerability counts by severity for the namespace
vulnerabilitymanifestsummariesWorkload namespaceVulnerability counts for one workload container, and the name of its image's manifest
vulnerabilitymanifestskubescape namespaceFull vulnerability matches for one image
sbomsyftskubescape namespaceSBOM for one image
configurationscansummariesCluster, one per namespaceFailed controls by severity, summed over the namespace's resources
workloadconfigurationscansummariesResource namespaceResult of each control for one resource, and its failed controls by severity

Configuration results for cluster-scoped resources, such as ClusterRoleBindings, namespaces, and admission webhooks, and for the role bindings of service accounts are stored in the kubescape namespace.

A list returns each resource without its findings, so severity counts read as zero in a list. Read one resource by name to see its findings.

Reading findings requires get and list on the spdx.softwarecomposition.kubescape.io API group. The built-in view, edit, and admin roles do not include these resources, so tenant users with namespace roles cannot read findings.

Vulnerability results

Show the vulnerability counts for a namespace, then list the workload containers in it that have results:

kubectl get vulnerabilitysummaries <namespace> \
  -o custom-columns='NAMESPACE:.metadata.name,CRITICAL:.spec.severities.critical.all,HIGH:.spec.severities.high.all,MEDIUM:.spec.severities.medium.all,LOW:.spec.severities.low.all'
kubectl get vulnerabilitymanifestsummaries -n <namespace>

Each name has the form <kind>-<workload>-<container>. Read the counts for one workload container and the name of its image's manifest, then list the critical vulnerabilities in that image:

kubectl get vulnerabilitymanifestsummaries -n <namespace> <name> \
  -o custom-columns='IMAGE:.metadata.annotations.kubescape\.io/image-tag,CRITICAL:.spec.severities.critical.all,HIGH:.spec.severities.high.all,MANIFEST:.spec.vulnerabilitiesRef.all.name'
kubectl get vulnerabilitymanifests -n kubescape <manifest> \
  -o jsonpath='{range .spec.payload.matches[?(@.vulnerability.severity=="Critical")]}{.vulnerability.id}{"\t"}{.artifact.name}{"\t"}{.artifact.version}{"\t"}{.vulnerability.fix.state}{"\n"}{end}'

The second command prints the vulnerability ID, the affected package and version, and whether a fix is available. Replace Critical with High, Medium, or Low for other severities.

Configuration results

Show the failed controls by severity for a namespace, then list the resources in it that have results:

kubectl get configurationscansummaries <namespace> \
  -o custom-columns='NAMESPACE:.metadata.name,CRITICAL:.spec.severities.critical,HIGH:.spec.severities.high,MEDIUM:.spec.severities.medium,LOW:.spec.severities.low'
kubectl get workloadconfigurationscansummaries -n <namespace>

Each name has the form <kind>-<name> in lowercase, such as deployment-<name>. Read the failed controls of one resource:

kubectl get workloadconfigurationscansummaries -n <namespace> <name> \
  -o go-template='{{range .spec.controls}}{{if eq .status.status "failed"}}{{.controlID}}{{"\t"}}{{.severity.severity}}{{"\n"}}{{end}}{{end}}'

The command prints the ID and severity of each failed control. The Kubescape control library describes each control and its remediation. Controls that need site-specific settings, such as a list of allowed registries, report skipped.

Monitoring

Kubescape exposes operational telemetry to the platform Prometheus. The Kubescape telemetry dashboard in Grafana shows image scans by outcome, scan duration and queue depth, the time since the last successful scheduled scan, storage API request rate and latency, and pod resource usage. The dashboard contains no vulnerability or compliance data.

Interacts With

  • Prometheus, which scrapes Kubevuln and storage API telemetry.
  • Grafana, which hosts the Kubescape telemetry dashboard.
  • Kyverno, which, with the platform's ValidatingAdmissionPolicies, handles admission control; Kubescape only reports.
  • ArgoCD, which reconciles Kubescape as part of the common parent application.

On this page