setup

Scan (Vulnerabilities, SBOM, AIBOM)

Purpose

Scans container images for vulnerabilities (Trivy), generates a software bill of materials (Syft) and Docker Scout data, and — when AI packages are present — emits an AI bill of materials (AIBOM).

It can also scan the root volumes of running Linux EC2 instances without an agent. It does so only in accounts whose scan role allows it; see Scan EC2 instances.

The scan module has no configuration of its own. It inherits registry access from the modules that expose images:

  • Amazon ECR — via the aws module's SubImageScanRole
  • GitLab Container Registry — via the gitlab module's PAT (requires the read_registry scope)

Prerequisites

  • At least one registry-providing module configured and synced:
    • aws for ECR images, and/or
    • gitlab with read_registry scope for GLCR images
  • Images must already appear in the graph as ContainerImage nodes from a sync. Scan runs per image.

Required Fields

None. Enable the module and save.

Setup Steps

  1. Ensure the source registry module (aws, gitlab, or both) is configured and has synced at least once.
  2. In Modules → Scan, toggle the module enabled and save.
  3. Trigger a sync from Run Sync, or wait for the scheduled run.

What Runs Per Image

  1. crane pulls the image once into a local OCI directory.
  2. Trivy, Syft, and Docker Scout read that directory in parallel.
  3. If Syft detects AI-related packages (openai, anthropic, langchain, transformers, …), AIBOM runs against the OCI layers.
  4. Results are ingested into Neo4j and surface in Vulnerabilities, Fixes, and inventory views.

AIBOM is non-fatal: a scan is considered successful even when AIBOM is skipped.

Scan EC2 Instances (optional)

Subimage scans an EC2 instance without logging in or installing anything on it. For each instance it snapshots the root EBS volume, reads the snapshot with Trivy through the EBS direct APIs, and deletes the snapshot. Findings attach to the instance in the graph.

Enable EC2 scanning

  1. In every account you want scanned, update SubImageScanRole with the EnableVMScanning parameter set to true. This is the only Subimage setting that grants write access, and it is limited to EBS snapshots tagged subimage:scan=true.
    • Organization StackSet (created with Deploy across the organization): in CloudFormation, update the SubImageScanRoleStackSet stack. Choose Replace existing template, enter https://subimage-onboarding-templates.s3.us-east-1.amazonaws.com/subimage_stackset.yaml, and set EnableVMScanning to true. Every account in the StackSet receives the change.
    • Standalone stack (one account, or the management account): update the stack that created SubImageScanRole. Choose Replace existing template, enter https://subimage-onboarding-templates.s3.us-east-1.amazonaws.com/subimage_cloudformation.yaml, and set EnableVMScanning to true.
    • Terraform: set enable_vm_scanning = true in the AWS setup Terraform and apply.
  2. If any root volumes use customer managed KMS keys, update those key policies as described in the next section. Volumes encrypted with the AWS managed aws/ebs key need no change.

There is no switch in Subimage. On each run, the Scan module checks every account with a dry-run snapshot request and scans instances only where the role allows it. Accounts without EnableVMScanning are skipped, not reported as failures. The AWS module must have synced at least once so the instances are in the graph.

Customer managed KMS keys

If a key policy lets IAM policies grant access (it allows arn:aws:iam::<account-id>:root to use kms:*), the updated role already has the permissions it needs. Otherwise, add this statement to the key policy, replacing <account-id> with the account that owns the volumes. It lets the role decrypt only through EC2, the same way EBS snapshot reads do:

{
  "Sid": "AllowSubImageVMScanning",
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::<account-id>:role/SubImageScanRole" },
  "Action": ["kms:Decrypt", "kms:DescribeKey"],
  "Resource": "*",
  "Condition": {
    "StringLike": { "kms:ViaService": "ec2.*.amazonaws.com" }
  }
}

What EC2 scanning does in your account

  • Which instances: running Linux instances with an EBS root volume. Windows, macOS, stopped instances, and EKS nodes are skipped; container image scanning already covers EKS workloads.
  • Which volume: the root volume only. Attached data volumes are not scanned yet.
  • Snapshots: each snapshot is tagged subimage:scan=true and subimage:scan-job=<job ID>, and is deleted when its scan finishes, including when the scan fails. You pay standard EBS snapshot rates for the minutes it exists.
  • Filesystems: ext2, ext3, ext4, and XFS. Volumes that use LVM or ZFS fail to scan, and so do volumes partitioned with an extended MBR partition table.
  • What is read: installed OS and language packages. Container image storage (/var/lib/docker, /var/lib/containerd, /var/lib/containers) and the Go module cache are skipped, because those images are scanned from their registries and clusters. When a volume is too large to scan in time, Subimage rescans it for OS packages only.

Troubleshooting

  • No images scanned — the source module has not synced yet, or it synced but produced no ContainerImage nodes. Check its latest run in Sync History.
  • GLCR pulls fail — the GitLab token is missing the read_registry scope, or does not cover the group the image lives in.
  • ECR pulls fail with AccessDenied — SubImageScanRole is missing the ECR read permissions. Redeploy the AWS setup template; it already includes them.
  • No EC2 instances scanned — SubImageScanRole in that account was deployed without EnableVMScanning, so the account is skipped. Update the stack as described in Enable EC2 scanning.
  • EC2 scans fail with UnauthorizedOperation or AccessDenied — the role allows creating scan snapshots but not reading or deleting them, usually because the stack was edited by hand. Redeploy it from the current template.
  • EC2 scans fail with a KMS error — the volume uses a customer managed key whose policy does not allow SubImageScanRole. Add the key policy statements.
  • A scan snapshot was left behind — list them with aws ec2 describe-snapshots --owner-ids self --filters Name=tag:subimage:scan,Values=true, then delete them with aws ec2 delete-snapshot.