Container Image Scanning¶

VirtualSutra AI can scan container images for CVEs, OS compliance violations, and generate Software Bills of Materials (SBOMs). Container scanning runs in parallel with cloud and codebase scanning as part of a regular inspection.

Before you start¶

Before scanning container images, ensure you have:

• Registry access - the VirtualSutra scanner can pull from your registry (see setup per registry type below)
• Image reference - registry hostname, repository path, and tag or digest for each image to scan
• License blocklist (optional) - a list of SPDX license IDs to flag (e.g. GPL-3.0, AGPL-3.0)

What gets scanned¶

For each container image you add to the inspection scope:

All image pulls use Skopeo for daemon-free operation - the scanner never requires a Docker socket. Signature and provenance checks run immediately after the pull, in the same step that already holds your registry credentials.

Adding images to an inspection¶

In the inspection wizard, expand Container Images under Step 1 - Targets and click Add Image.

Public images¶

For any publicly accessible image (Docker Hub, GHCR public repos, ECR Public):

Leave the username and password fields blank.

Private images - setup per registry¶

Private registries require the scanner to authenticate before pulling. Set up access once, then reference credentials in the wizard or inspection.json.

AWS ECR¶

The scanner uses the same IAM role as the cloud inspector. Attach the read-only ECR policy to the VirtualSutra inspection role:

# Attach managed policy
aws iam attach-role-policy \
  --role-name VirtualSutraInspection \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly

No separate username/password needed - ECR auth uses the IAM role automatically.

What to enter in the wizard: set Registry to your ECR endpoint (e.g. 123456789.dkr.ecr.us-east-1.amazonaws.com). Leave username and credentials blank.

Azure ACR¶

Grant the service principal the AcrPull role on the container registry resource:

# Find your ACR resource ID
ACR_ID=$(az acr show --name <acr-name> --resource-group <rg> --query id -o tsv)

# Assign AcrPull role to the VirtualSutra service principal
az role assignment create \
  --assignee "<client-id>" \
  --role "AcrPull" \
  --scope "$ACR_ID"

What to enter in the wizard: set Registry to your ACR login server (e.g. myacr.azurecr.io). Enter the service principal Client ID as username and Client Secret as credentials - or use env://ACR_PASSWORD if configured in the environment.

GCP Artifact Registry / GCR¶

Grant the service account roles/artifactregistry.reader on the project:

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

For legacy GCR (gcr.io), grant roles/storage.objectViewer on the GCR storage bucket instead.

What to enter in the wizard: set Registry to your Artifact Registry hostname (e.g. us-docker.pkg.dev). Use _json_key as username and paste the service account JSON key as credentials - or use env://GCR_SA_KEY if configured.

Docker Hub / GHCR / self-hosted¶

For any registry that uses username + password or token authentication:

For GitHub Container Registry (ghcr.io), create a Personal Access Token with read:packages scope and use it as the password with your GitHub username.

For Docker Hub, use your Docker Hub username and a Personal Access Token with Read-only access.

Step-by-step: adding a container image in the wizard¶

1. Navigate to Runs → New Inspection (or /runs/new)
2. Under Step 1 - Targets, scroll to Container images and click Add

3. Fill in the fields:

   Field	What to enter
   Registry	Registry hostname - e.g. ghcr.io, docker.io, 123456789.dkr.ecr.us-east-1.amazonaws.com, us-docker.pkg.dev
   Repository	Image path - e.g. my-org/my-app
   Tag	Tag or digest - e.g. v1.2.3, latest, sha256:abc...
   Credentials	Leave blank for public images. For private: enter password/token directly or use env://VAR_NAME secret reference
   Username	Leave blank for public or ECR. For ACR/GHCR/Docker Hub: enter username or env://VAR_NAME

4. Toggle scanners:

   • Trivy (CVE scanning) - enabled by default
   • Syft (SBOM) - enabled by default
   • OpenSCAP (OS compliance) - disabled by default; enable for CIS benchmark (and, on Ubuntu, STIG) checks

5. Optionally add a license blocklist - comma-separated SPDX IDs (e.g. GPL-3.0, AGPL-3.0)

6. Click Add - repeat for additional images

7. Proceed to Step 2 - Scope and Step 3 - Output, then submit

Each image is scanned as an independent task running in parallel with all other scanner tasks.

Timing and resource usage¶

OpenSCAP requires extracting the full image filesystem and is the main contributor to scan time. Only enable it when you need CIS benchmark (and, on Ubuntu, STIG) checks.

Troubleshooting¶

Findings¶

Container scanner findings appear alongside cloud and codebase findings in the Findings tab.

CVE findings¶

Each CVE found in the image produces a finding:

• Severity - mapped from the CVSS score: Critical (≥ 9.0), High (7.0–8.9), Medium (4.0–6.9), Low (< 4.0)
• Resource - the container image and the affected package, e.g. ghcr.io/my-org/my-app:v1.2.3 / openssl 3.0.2
• Title - CVE-2024-XXXXX in <package>
• Compliance - CIS Docker Benchmark and NIST SP 800-190 control mappings where applicable
• Remediation - click any CVE finding to see upgrade guidance. VirtualSutra includes Dockerfile-level remediation steps for 49 common packages including imagemagick, openssl, glibc, curl, libwebp, xz-utils, openssh, nginx, Python, Node.js, and more. Use the Has Fix toggle in the findings filter to show only findings with remediation guidance.

Filter by Agent: container-scanner in the Findings sidebar to see only container findings.

License violation findings¶

If you configured a license_blocklist, any package in the SBOM whose license matches the blocklist produces a medium finding:

• Resource - package:<ecosystem> (e.g. package:npm, package:pip)
• Title - Blocked license <SPDX-ID> in <package>

Useful for enforcing that production images do not ship GPL-licensed or AGPL-licensed dependencies.

OS compliance findings (opt-in)¶

When OS compliance is enabled for an image, each failing benchmark rule that can be judged on an image produces a finding:

• Resource - container:os
• Title - the rule's benchmark title, prefixed OS compliance: (e.g. OS compliance: Ensure the Default Umask is Set Correctly in /etc/profile)
• Evaluated against the benchmark that matches the image's OS

Rules about a running machine (partitions, mounts, kernel settings, services, file ownership) are set aside, not reported. See Enabling OS compliance scanning.

Signature and provenance¶

Every scanned image gets two status columns on the run's Resources tab, next to the image row: Signature and Provenance. The container image PDF report carries the same statuses in a Signature & Provenance table.

You name an image by tag. When the scanner can read the digest the tag points to, it reads it once before the pull and pulls and verifies that digest, so a tag that moves mid-scan cannot make the verdict describe a different image, and the digest is shown on each signing finding. If the digest cannot be read, the image is pulled and verified by tag and no digest is shown.

Signature¶

Signed · Verified (key only, no transparency log) is a different state from Signed · Verified, not a variant of it: the key matched, but whether the signature was recorded in a transparency log has not been checked. Hovering that badge reads: "The signature verified against the configured public key. The transparency log was not consulted." The same holds for Signed · Verified (SCT not checked): the signer matched, but whether its certificate was logged has not been checked.

Provenance¶

A — (shown as Not checked in the PDF) means the check did not apply to that row (it is not a container image), the check could not be made (see When a check cannot run), or the status is one the console does not recognise. The console never shows an unrecognised status as its raw text.

Provenance is only verified when you tell the scanner what to verify it against with source_uri. Without it the scanner reports only whether an attestation exists, never that it is genuine.

What you can configure per image¶

Leave both the key and the identity unset and the scanner still tells you whether a signature exists - it just cannot tell you it is valid.

The findings it produces¶

When a check cannot run¶

If a registry, a transparency log or a trust root cannot be reached, or a verifier cannot run, the image's signature or provenance is reported as not checked. That is a low finding (SIGN_4 / SLSA_3) that says plainly the image has not been checked - not that it is unsigned or invalid.

It is also recorded as a coverage gap for that image. Verification never fails a scan: the image's other findings are kept and the scan task completes, but the run ends partial and names the image and the check that was not made, so a not-checked image is never read as a verified one. Ask your operator to fix the cause (for example an unreachable transparency log) and resume the run.

Air-gapped installs¶

Keyless (Sigstore) verification normally reaches the public Rekor and Fulcio services. Under the air-gap profile the scanner refuses to contact the public Sigstore services at all, so what you can verify depends on what you provide:

Your operator supplies the Rekor URL and the trust root when installing (the Helm values global.imageSigning.rekorUrl and global.imageSigning.trustRoot). A trusted root is created with cosign trusted-root create from your own Fulcio, Rekor, certificate-transparency log and timestamp authority.

A private Fulcio without a certificate-transparency log¶

A Fulcio with no certificate-transparency log issues certificates without an SCT, so keyless verification of its signatures fails. Your operator can turn that one check off on a self-hosted or air-gapped install (global.imageSigning.insecureIgnoreSct: true; refused on the hosted SaaS profile, which is expected to verify against public Sigstore); such a signature is then shown as Signed · Verified (SCT not checked), never as Signed · Verified.

Downloading SBOM artifacts¶

After a run completes, CycloneDX JSON SBOMs are available for download:

1. Open the completed run
2. Click the SBOMs tab (or navigate to Reports → SBOMs)
3. Click Download next to the image you want

Each SBOM file is named <image-slug>.cdx.json (e.g. ghcr.io_my-org_my-app_v1.2.3_linux-amd64.cdx.json).

SBOMs can also be fetched via the API:

# List available SBOMs for a run
curl -H "X-API-Key: $API_KEY" https://your-vsutra/api/runs/<run_id>/sbom

# Download a specific SBOM
curl -H "X-API-Key: $API_KEY" \
  https://your-vsutra/api/runs/<run_id>/sbom/<filename> \
  -o my-app.cdx.json

Enabling OS compliance scanning¶

OS compliance scanning (OpenSCAP) is disabled by default because it requires extracting the full image filesystem. Enable it per image in the inspection.json config:

{
  "scope": {
    "container_images": [
      {
        "registry": "ghcr.io",
        "repository": "my-org/my-app",
        "tag": "v1.2.3",
        "enable_openscap": true
      }
    ]
  }
}

OS compliance scanning adds roughly 5–10 minutes per image depending on image size.

OpenSCAP itself contacts no host: it never downloads remote content, on any install, so it works the same when air-gapped (the image is still pulled from its registry as usual).

Which images are assessed is decided from the image's own /etc/os-release:

An assessed image always gets one summary finding, CKV_VSUTRA_IMG_OSCAP_1, with the number of rules evaluated, failed and set aside, and one finding per failed rule, named by its XCCDF rule id. An image is not a running machine, so rules about file ownership, kernel settings, services and mounts are set aside rather than reported as passed or failed. 0 failed is therefore not a compliance verdict; see OS compliance findings.

Example inspection.json snippet¶

{
  "scope": {
    "container_images": [
      {
        "registry": "ghcr.io",
        "repository": "my-org/api",
        "tag": "v2.1.0",
        "platforms": ["linux/amd64"],
        "enable_trivy": true,
        "enable_openscap": false,
        "enable_sbom": true,
        "license_blocklist": ["GPL-3.0", "AGPL-3.0"]
      },
      {
        "registry": "123456789.dkr.ecr.us-east-1.amazonaws.com",
        "repository": "my-service",
        "tag": "latest",
        "platforms": ["linux/amd64"],
        "enable_trivy": true,
        "enable_sbom": true
      }
    ]
  }
}

For a full list of ContainerImageConfig fields, see the Container Image Security Scanner agent reference.