# Kubescape (/docs/foundation/components/kubescape)



## Component Category [#component-category]

Platform governance / security posture and vulnerability scanning

## Component Description [#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 [#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 [#learn-more]

* [Kubescape documentation](https://kubescape.io/docs/)
* [kubescape/kubescape on GitHub](https://github.com/kubescape/kubescape)

## What is scanned [#what-is-scanned]

| Scan                    | What it checks                                                                                           | Schedule |
| ----------------------- | -------------------------------------------------------------------------------------------------------- | -------- |
| Configuration (posture) | Kubernetes resources against the `allcontrols`, `nsa`, `mitre`, `security`, and `cis-v1.12.0` frameworks | Daily    |
| Vulnerability           | Container images of running workloads, using the Grype vulnerability database, plus an SBOM per image    | Daily    |

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 [#deployment-notes]

<Callout type="info" title="Optional component">
  Kubescape is not deployed by default. To deploy it, set `[component] enabled = true` in its `variables.toml` or `KUBESCAPE_COMPONENT_ENABLED=true`.
</Callout>

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](/docs/deployment/configuration-model) for environment overrides.

## Reading findings [#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`:

| Resource                             | Scope                      | Content                                                                               |
| ------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------- |
| `vulnerabilitysummaries`             | Cluster, one per namespace | Vulnerability counts by severity for the namespace                                    |
| `vulnerabilitymanifestsummaries`     | Workload namespace         | Vulnerability counts for one workload container, and the name of its image's manifest |
| `vulnerabilitymanifests`             | `kubescape` namespace      | Full vulnerability matches for one image                                              |
| `sbomsyfts`                          | `kubescape` namespace      | SBOM for one image                                                                    |
| `configurationscansummaries`         | Cluster, one per namespace | Failed controls by severity, summed over the namespace's resources                    |
| `workloadconfigurationscansummaries` | Resource namespace         | Result 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 [#vulnerability-results]

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

```bash
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:

```bash
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 [#configuration-results]

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

```bash
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:

```bash
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](https://kubescape.io/docs/controls/) describes each control and its remediation. Controls that need site-specific settings, such as a list of allowed registries, report `skipped`.

## Monitoring [#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 [#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.

## Related Pages [#related-pages]

* [Security Model](/docs/foundation/security-model)
* [Observability and Audit](/docs/foundation/observability-and-audit)
* [Configuration Model](/docs/deployment/configuration-model)
