Local Scanning

Local Scanning lets Sysdig analyze container images directly on your Kubernetes nodes, maximizing coverage in restricted or air-gapped environments without pulling images from registries at runtime.

What is Local Scanning?

Local Scanning lets Sysdig analyze container images directly on your Kubernetes nodes, instead of relying solely on Cluster Shield to pull them from registries for runtime scanning.

On each node, Sysdig:

Reads container images from the container runtime (Docker, containerd, CRI-O, etc.).
Builds a Software Bill of Materials (SBOM) locally.
Sends SBOMs and metadata to the backend for vulnerability matching. Image layers and source code never leave your environment.

This maximizes coverage in restricted, air-gapped, or complex environments while keeping images and proprietary code securely inside your own infrastructure.

Note: Cluster Shield also extracts SBOMs inside your environment and sends only SBOMs/metadata to the backend. The key difference with Local Scanning is where the image is read from (registry vs. node runtime) and which component does the SBOM extraction.

When to Use Local Scanning

Both Cluster Shield and Local Scanning generate SBOMs inside your environment and send only SBOMs and scan metadata to the Sysdig backend. Images are never uploaded to Sysdig.

The key difference is from where the image is read:

Cluster Shield pulls images from registries and extracts SBOMs from those registry images.
Local Scanning (Host Shield) reads images directly from node runtimes and extracts SBOMs from node images.

Local Scanning is particularly valuable when:

Registries are hard to use for runtime scanning. For example, they are private, behind firewalls, or require complex per-cluster credentials and networking.
You want to reduce operational friction around configuring registry access for every cluster and every environment.
You run air-gapped clusters or have embedded / locally built images (such as images built directly on nodes or stored only in internal OpenShift registries) that are not reliably available from a central registry.
Network egress between clusters and registries is constrained or expensive, and you want to avoid repeatedly pulling large images just to scan them at runtime.
You want stronger control over data residency, ensuring that image layers and source code never leave your infrastructure, regardless of how registries are deployed.
You need robust runtime coverage for short-lived Jobs, CronJobs, and init/sidecar/ephemeral containers in environments where registry-based runtime scanning is difficult to operate reliably.

Note: Local Scanning complements, but does not replace, pre-deployment scanning (Pipeline/CLI) or Admission Control. Admission Control still relies on being able to pull images from registries at admission time.

High-Level Architecture

Local Scanning is implemented by the Host Shield and Cluster Shield working together:

Host Shield (Node-level local image analysis):
- Runs on every Kubernetes node.
- Reads container images directly from the node’s runtime.
- Extracts SBOMs and reuses existing SBOMs when possible.
- Streams only metadata SBOMs and/or SBOM references to the backend.
Cluster Shield (Kubernetes metadata & control plane):
- Connects to the Kubernetes API and collects workload metadata.
- Maps scan results to Pods, Deployments, DaemonSets, StatefulSets, Jobs, CronJobs, and init/sidecar/ephemeral containers.
- Can still perform registry-based image scans for scenarios such as Admission Control and non-runtime workloads.
Sysdig Backend (Vulnerability matching & reporting):
- Matches SBOMs against vulnerability intelligence.
- Correlates with Kubernetes context from the Cluster Shield.
- Exposes unified findings in the Runtime Vulnerabilities views and APIs.

The image_source setting ensures Host Shield acts as the primary runtime scanner when Local Scanning is enabled, avoiding duplicate work with the Cluster Shield.

Coverage and Limitations

What Local Scanning Covers

With Local Scanning enabled, Sysdig is designed to cover:

Running Pods, including main application containers, sidecars, init containers, and ephemeral containers (subject to runtime/event support).
Short-lived workloads (Jobs): Images are scanned locally, and results are retained for a defined period.
CronJobs: Job-runs are scanned when they execute on nodes, and results are mapped back to CronJob definitions.
Multiple clusters: SBOMs are reused whenever the same image digest runs in more than one cluster.

What Local Scanning Does Not Cover

Zero-replica workloads: Workload definitions with zero replicas (e.g., a Deployment not yet scaled up). If there are no Pods, there is no image on your nodes, and thus no local SBOM.
Non-Kubernetes hosts: These are handled via standard host vulnerability scanning, not Local Scanning semantics.
Admission Control: Admission decisions still rely on registry access at admission time. Local Scanning is primarily a runtime enhancement.

Prerequisites

To use Local Scanning, you need:

A Sysdig Secure backend (SaaS or supported on-prem) with Vulnerability Management enabled.
At least one Kubernetes cluster with:
- Host Shield deployed (via the unified shield chart).
- Cluster Shield deployed for full Kubernetes context (required for Local Scanning).
Supported container runtimes enabled on nodes (containerd, docker, crio or podman).
Network connectivity from nodes to the Sysdig backend endpoint (API and collector) for sending metadata and scan results.

Enabling Local Scanning

Local Scanning is activated by configuring the shield Helm chart to use the node as the preferred image source for Kubernetes workloads.

1. Ensure Host Shield and Host Scanner are Available

Host Shield is installed as part of the unified shield chart. When you configure Local Scanning (see step 2), the host-scanner component is deployed and used to extract SBOMs from images on the node.

If you also want to enable host OS vulnerability scanning (in addition to Local Scanning), you can turn on host vulnerability management:

features:
  vulnerability_management:
    host_vulnerability_management:
      enabled: true

Note: Enabling Local Scanning does not require you to enable full host OS scanning. Host Shield will still be used for local image analysis when image_source: node is set.

2. Switch Workload Scanning to Use Local Images

Tell Sysdig to use the node as the image source instead of pulling from registries. Set image_source: node under the container_vulnerability_management block:

features:
  vulnerability_management:
    container_vulnerability_management:
      enabled: true
      target_workloads:
        kubernetes:
          enabled: true
          image_source: node   # Enables Local Scanning
      in_use:
        enabled: true

image_source: node: Host Shield is deployed and used to read images from node runtimes (Local Scanning).
image_source: registry (Default): Cluster Shield pulls images from registries for runtime scanning.

3. (Optional) Configure Container Runtimes

In most environments, you do not need to configure runtimes manually; the chart sets defaults that work for common runtimes. If you need to manually configure or prioritize runtimes, you can adjust the internals block:

internals:
  vulnerability_management:
    host_scanner:
      container_runtimes:
        priority:
          - containerd
          - docker
          - crio

Only runtimes listed under priority are enabled. Adjust the order to reflect the predominant runtime in your environment.

Verifying Local Scanning is Working

In the Sysdig Secure UI

Navigate to the Runtime vulnerabilities view (for example, Attack Surface > Vulnerability Findings > Vuln Runtime).
Filter by asset.type = "workload" and your cluster name (e.g., kubernetes.cluster.name = "my-cluster").
You should see workloads backed by node-scanned images appearing with normal scan results.

You can validate coverage for specific objects by filtering on:

kubernetes.pod.container.name to confirm init or sidecar containers are successfully mapped.
Specific Jobs/CronJobs to ensure short-lived workloads are being scanned and retained as expected.

Logs and Diagnostics

From the Host Shield / Host Scanner pod logs, you should see:

SBOM extraction events for containers on the node.
Periodic workload updates and keepalives sent to the backend.

Errors about local scanning not being available or the backend not supporting workload scanning usually indicate a configuration or version mismatch.

Troubleshooting Checklist

If you don’t see expected scan results for Kubernetes workloads:

Confirm Host Shield deployment: Verify pods are running on the nodes you expect to scan, and that Host Shield is correctly installed with the shield chart. If you enabled host OS scanning, confirm host_vulnerability_management.enabled is true.
Check container runtime configuration: Ensure the actual runtime used by your nodes (e.g., containerd, crio) is supported and listed in the container_runtimes.priority block if you customized it.
Verify Local Scanning is enabled: Check that image_source: node is correctly applied under features.vulnerability_management.container_vulnerability_management.target_workloads.k8s.
Confirm Cluster Shield is healthy: Cluster Shield is required for Local Scanning (kubernetes-metadata must be enabled). Ensure it can read the Kubernetes API and is actively sending workload metadata. Runtime views should show workloads for the relevant cluster even before scans complete.
Look at workload lifecycle: Zero-replica Deployments and never-run CronJobs won’t have runtime scans until Pods are actively scheduled to nodes (or until any pre-execution CronJob scanning feature is enabled in your environment).
Review logs: Check Host Shield / Host Scanner logs. Errors about “kubernetes container detection is enabled but it is not supported by the backend” or “backend does not support workload scanning” or “detected cluster name conflict: an existing Cluster Shield instance with Container Vulnerability Management enabled is already using <cluster_name>” usually indicate a version or configuration mismatch between Host Shield capabilities and the Sysdig backend.