Container Image Security Scanner¶

The Container Image Security Scanner (scanner-container) is a first-class VirtualSutra agent that scans container images for CVEs, OS compliance violations, and generates Software Bills of Materials (SBOMs). It is dispatched directly by the orchestrator - one task per ContainerImageConfig in the inspection scope - and runs in parallel with cloud and codebase scanner tasks.

Coordinator image: ghcr.io/virtual-sutra/scanner-container
Redis stream: vsutra:tasks:container_scanner
AgentType: CONTAINER_SCANNER

In Kubernetes, the coordinator spawns a multi-container Job using dedicated sub-images - each tool runs in its own container, sharing the pulled image layer via an emptyDir volume:

Capabilities¶

All image pulls use Skopeo for daemon-free operation - no Docker socket is required.

Prerequisites¶

The following tools must be present in the scanner container image. They are included in the official ghcr.io/virtual-sutra/scanner-container image.

N1 - CVE Scanning (required)¶

• Skopeo >= 1.13 - daemon-free image pull to OCI layout
• Trivy >= 0.50 - CVE and misconfiguration scanning

N2 - OS Compliance (opt-in, enable_openscap: true)¶

• OpenSCAP >= 1.3 (openscap-scanner package)
• SCAP Security Guide (SSG) - scap-security-guide package
• umoci >= 0.4 - extracts OCI image filesystem for oscap-chroot evaluation

N2 is disabled by default (enable_openscap: false) because image extraction is slow. Enable it per image via the ContainerImageConfig. See OS compliance findings for the operating systems it assesses and how to read its results.

N3 - SBOM Generation (required)¶

• Syft >= 1.0 - generates CycloneDX JSON SBOM

Configuration¶

Container images to scan are declared in InspectionConfig.scope.container_images as a list of ContainerImageConfig objects.

{
  "scope": {
    "container_images": [
      {
        "registry": "ghcr.io",
        "repository": "my-org/my-app",
        "tag": "v1.2.3",
        "platforms": ["linux/amd64", "linux/arm64"],
        "enable_trivy": true,
        "enable_openscap": false,
        "enable_sbom": true,
        "license_blocklist": ["GPL-3.0", "AGPL-3.0"],
        "credentials_ref": "env://REGISTRY_PASSWORD",
        "username_ref": "env://REGISTRY_USERNAME"
      }
    ]
  }
}

ContainerImageConfig fields¶

Registry Authentication¶

Public registries¶

No credentials needed. Leave credentials_ref and username_ref unset.

Private registries (generic)¶

Set REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables on the scanner container, or use per-image credentials_ref / username_ref secret references.

REGISTRY_USERNAME=myuser
REGISTRY_PASSWORD=mypassword

AWS ECR¶

Use standard AWS IAM credentials. Authenticate with the ECR auth helper or pre-authenticate:

aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

Or assign the AmazonEC2ContainerRegistryReadOnly IAM policy to the scanner's execution role.

Azure ACR¶

Create a service principal with the AcrPull role:

az ad sp create-for-rbac --name vsutra-scanner \
  --role AcrPull \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ContainerRegistry/registries/<acr>

Store the password in a secret and reference it via credentials_ref.

GCP Artifact Registry¶

Create a service account with roles/artifactregistry.reader and provide the JSON key:

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:vsutra-scanner@PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

Store the JSON key content in a secret and reference it via credentials_ref.

Findings¶

CVE findings (N1 - Trivy)¶

OS compliance findings (N2 - OpenSCAP)¶

The benchmark is chosen from the image's own /etc/os-release:

RHEL / UBI benchmarks read the image's RPM database. OpenSCAP does that only by chroot(), which the scanner (non-root, no capabilities) is not permitted. Such an image is therefore not evaluated in this release: it gets CKV_VSUTRA_IMG_OSCAP_2, and the OpenSCAP sub-scan fails as a coverage gap. Support for RHEL / UBI images is planned. Every other identified OS is not supported for OS compliance: Alpine, Debian 11, Ubuntu 20.04, Rocky, AlmaLinux, CentOS Stream, Amazon Linux, Oracle Linux, SLES, Fedora, and STIG on Debian. An image whose OS cannot be identified (no os-release, such as scratch or static images) fails the sub-scan.

An assessed image gets CKV_VSUTRA_IMG_OSCAP_1, plus CKV_VSUTRA_IMG_OSCAP_2 when some of its rules were not evaluated; an unsupported one gets CKV_VSUTRA_IMG_OSCAP_0; an image whose OS cannot be identified gets none. All are informational:

Every rule that failed and could be judged on an image is one finding:

A rule OpenSCAP could not decide is a finding titled "OS compliance check could not be evaluated: …", at medium severity for error and informational for unknown. It is not a failure of the rule.

These are results for an image, not for a host. The image is unpacked without root and nothing is running in it. Four classes of rule are therefore set aside: they are neither passes nor failures, are counted on the summary, and their controls are recorded as not evaluated:

• file_ownership: every unpacked file belongs to the scanner's own user.
• host_state: kernel parameters, services, mounts, the bootloader and similar.
• script_check: rules answered by a script that would run in the scanner, not in the image.
• not_checked: the benchmark ships no check for the rule.

0 failed on the summary never means "compliant": the set-aside rules have to be assessed on the host or cluster the image runs on.

OpenSCAP never downloads remote content, on any deployment profile. A rule whose check needs remote content is set aside as not checked, and its controls are recorded as not evaluated. In the shipped content (SSG 0.1.82), the only such rule is Debian's security-patch check, and no profile the scanner runs selects it.

License violation findings (N3 - Syft)¶

SBOM Artifacts¶

CycloneDX JSON SBOMs are written to SBOM_OUTPUT_DIR/{run_id}/{image_slug}.cdx.json (default: /tmp/vsutra-sboms/).

SBOMs are accessible via the API:

• GET /runs/{run_id}/sbom - list available SBOM files for a run
• GET /runs/{run_id}/sbom/{filename} - download a specific CycloneDX SBOM file

Environment Variables¶

Resource Types Summary¶