Container registry scanning

A container registry is a centralized service that stores and distributes your container images. Endor Labs lets you scan images directly from your registry, giving you full visibility into the security posture of your containerized workloads at scale. You can discover images across repositories, control the scope of your scans, avoid redundant work by skipping images that are already scanned, and run consistent scans over time using saved scan plans.

A scan plan is a JSON file that defines the set of container images to scan, along with the registry and filters used to select them. It acts as a predefined template for selecting container images and can be verified and tested ahead of time before the actual registry scan runs. Once saved, the scan plan can be reused to scan the exact same set of images without querying the registry again, making recurring or batch scans consistent and easier to share across runs or environments.

With registry scanning, you can list all repositories and tags, or a filtered subset, in a registry without manually specifying each image. You can save an enumerated image list as a scan plan and reuse it later so the same set of images is scanned without re-querying the registry each time.

Endor Labs supports the following container registries:

• AWS ECR
• Azure ACR
• Docker Hub
• GitHub Container Registry (GHCR)
• JFrog Artifactory

Use the endorctl container registry commands to list and scan images stored in your registry.

• List images from a registry: Use endorctl container registry list to preview which images match your filters before scanning. This lets you verify the scope and adjust filtering parameters such as --include, --exclude, --recent, and --limit. You can also save the results as a scan plan for the scan step.

• Scan images from a registry: Use endorctl container registry scan to enumerate and scan container images from a registry in a single step. You can also provide a saved scan plan from the list command instead of enumerating the registry again.

Use a scan plan when you want to review the list of images before scanning. The scan plans make it easier to reuse these pre-qualified combinations of scanned parameters and ensure consistent results.

List command

The list command connects to your registry, enumerates container images based on your configured filters, and prints a summary with a table of image paths. You can also save the results as a scan plan to reuse with the scan command.

endorctl container registry list --registry-type=<type> [options]

You can apply filters such as include, exclude, recent, and limit to narrow down the images returned. If you provide a namespace and API credentials, the saved plan automatically excludes already scanned images, so it is ready to scan only new or updated images.

Filters are applied in the following order:

1. include
2. exclude
3. recent
4. limit

You can use the endorctl container registry list command with the following flags.

Scan command

The scan command runs Endor Labs container scans on a set of images. You can pass a saved scan plan from the list command or enumerate the registry with the same filter flags as list. The command pulls each image if needed, runs the scan, and by default removes pulled images after scanning. The --namespace and API credentials are required. Images that are already scanned are automatically skipped.

• Scan using a saved scan plan:

  endorctl container registry scan --namespace=<namespace> --scan-plan=<path> [options]
  

• Scan using a registry type. When you do not use --scan-plan, pass --registry-type.

  endorctl container registry scan --namespace=<namespace> --registry-type=<type> [options]
  

You can use the endorctl container registry scan command with the following flags.

Supported container registries

The endorctl container registry list and endorctl container registry scan commands support the following container registries. Use the Registry_type value for --registry-type and the Registry_host value for --registry.

Output format

The list and scan commands both produce output that includes summary lines and, when there are image rows, a table. The scan command shows this when --show-scan-plan is enabled.

If any image rows remain after filters, the command prints a table with the following columns:

Scan plan output

The scan plan is a JSON file written by the endorctl container registry list command with --save-as-plan and read by the scan command with --scan-plan. When list is run with --namespace and API credentials, the saved plan excludes images that are already scanned so that it is ready to scan only new or unscanned images. The structure is:

parameters:
  registry_type: string          # required
  server: string                 # optional
  namespace: string              # optional
  account: string                # optional. Used only for Docker Hub and GHCR.
  repo_key: string               # optional. Used only for JFrog.
  architecture: string           # optional
  include: string                # optional
  exclude: string                # optional
  recent: string                 # optional
  limit: integer                 # optional
  include_untagged: boolean      # optional
  include_untagged_only: boolean # optional
  validate_tag_digest: boolean   # optional
  timeout_seconds: integer      # required

counts:
  repositories: integer
  tags: integer
  untagged_manifests: integer    # optional
  matching_repositories: integer # optional
  matching_tags: integer         # optional
  matching_untagged: integer     # optional
  ignored_repositories: integer  # optional
  ignored_tags: integer          # optional
  ignored_untagged: integer      # optional
  digest_validated_tags: integer # optional
  digest_mismatch_tags: integer  # optional
  digest_lookup_errors: integer  # optional

images:                          # array
  - path: string                 # full image reference, tag or digest
    created: string
    updated: string
    multi_arch: boolean          # optional
    arch: string                 # optional
    multi_arch_digest: string    # optional

Container registry scanning with AWS ECR

The following commands use AWS ECR to show how to list images, apply filters, save a scan plan, and run scans. Use the appropriate --registry-type, --registry, and --registry-namespace values for other registries. See supported container registries to learn more.

• List all images in an AWS ECR registry.

endorctl container registry list --registry-type aws.ecr

• Filter images updated in the last 7 days, include only tags matching latest, and exclude release candidate tags.

endorctl container registry list --registry-type aws.ecr --recent 7d --include '.*:latest' --exclude '.*:-rc.*'

• Save the generated image list to a JSON scan plan file for use with the container registry scan command.

endorctl container registry list --registry-type aws.ecr --save-as-plan registry-scan-plan.json

• List images including untagged manifests.

endorctl container registry list --registry-type aws.ecr --include-untagged

• List only images that match a preferred architecture such as arm64 when the repository contains multi-architecture images.

endorctl container registry list --registry-type aws.ecr --architecture arm64

• Scan images defined in a previously saved scan plan file.

endorctl container registry scan --namespace demo --registry-type=aws.ecr --reauth --scan-plan aws_ecr_scan_plan.json

Troubleshooting

endorctl container registry list --registry-type artifactory --registry jfrog-host --registry-namespace repo-key --save-as-plan registry-scan-plan.json