container

Use the container command to scan and operate on container images.

The endorctl container command allows you to scan container images, instrument them for reachability analysis, collect data from deployment environments, and perform registry operations.

The syntax of the endorctl container command is:

endorctl container [command] [flags]

The following subcommands are supported:

  • scan: Scans a container image for vulnerabilities and security risks.
  • instrument: Instruments a container image with the dynamic profiling sensor.
  • collect: Collects data from the target deployment environment.
Note
Use the endorctl container scan command instead of the deprecated endorctl scan --container command. See Container scan commands migration guide for more information.

Endor Labs supports the following methods of scanning container images:

Run the following command to scan a container image built in a specific repository. Specify the project path using the --path argument and the container image name using the --image argument. This associates the container with the Git repository and branch of the project.

endorctl container scan --image=<image_name:tag> --path=users/janedoe/endorlabs/npm/exampleproject

You can also scan multiple container images as part of a single repository.

endorctl container scan --image=<image_name1:tag> --path=users/janedoe/endorlabs/npm/exampleproject
endorctl container scan --image=<image_name2:tag> --path=users/janedoe/endorlabs/npm/exampleproject
endorctl container scan --image=<image_name3:tag> --path=users/janedoe/endorlabs/npm/exampleproject

You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API.

endorctl container scan --image=<image_name:tag> --path=users/janedoe/endorlabs/npm/exampleproject --finding-tags=<image_name:tag>

Run the following command to scan a container image from a registry. Specify the project name using the --project-name argument, and the container image name and tag using the --image argument.

endorctl container scan --image=<image_name:tag> --project-name=<endor_project_name>

To keep multiple versions of a container image in a container-only project, include the --as-ref flag.

endorctl container scan --image=<image_name:tag> --project-name=<endor_project_name> --as-ref

You can tag findings with the corresponding container image name and tag. This lets you filter container-related findings in the user interface or through the API.

endorctl container scan --project-name=<endor_project_name> --image=<image_name:tag> --as-ref --finding-tags=<image_name:tag>
Important
To associate a container scan with an existing SCA scan for a project, you must use the --path argument specifying the same project path used for the SCA scan. You cannot associate a container scan with an SCA scan for a project using the --project-name parameter.

You can save a container image as a tarball and scan it with endorctl to generate a report containing dependencies, SBOM details, and security findings.

  1. Ensure that you have the container image available locally.

    docker pull alpine:latest

  2. Export the image to a tarball file.

    docker save alpine:latest -o alpine-latest.tar

  3. Perform the endorctl scan.

    endorctl container scan --image=alpine:latest --project-name=<endor_project_name> --image-tar=/absolute/path/to/alpine-latest.tar
Note
  • --image-tar must point to the absolute path of the tarball file.
  • --image=<name:tag> is optional but recommended. It explicitly identifies the container image inside the tarball.

The following flags are supported for the endorctl container scan command.

Flag Environment Variable Type Description
image ENDOR_CONTAINER_SCAN_IMAGE string The container image name and tag to scan, for example, nginx:latest. Use this flag in combination with other scan-related parameters.
image-tar ENDOR_CONTAINER_SCAN_IMAGE_TAR string The absolute path to a container image tarball file to scan, for example, /path/to/image.tar. Use this flag in combination with other scan-related parameters.
p, path ENDOR_CONTAINER_SCAN_REPOSITORY_PATH string Set the path to a valid git repository to associate the container scan with a Git repository. Default is ..
project-name ENDOR_CONTAINER_SCAN_PROJECT_NAME string Set the project name for the container scan when scanning as a standalone project.
as-ref ENDOR_CONTAINER_SCAN_AS_REF boolean Scan the container in a persistent context and keep the version. Use with --project-name to specify the name of the project.
project-tags ENDOR_CONTAINER_SCAN_PROJECT_TAGS strings Specify a list of user-defined tags to add to this project.
r, os-reachability ENDOR_CONTAINER_SCAN_OS_REACHABILITY boolean Enable OS reachability analysis to determine which OS packages in the container image are actually used at runtime.
o, output-type ENDOR_CONTAINER_SCAN_SUMMARY_OUTPUT_TYPE string Set output format (json, yaml, table, summary, or table-verbose). Default is table.
volume ENDOR_CONTAINER_SCAN_VOLUME strings Bind mount a volume for container profiling, for example, --volume=/host/path:/container/path. Requires --os-reachability.
publish ENDOR_CONTAINER_SCAN_PUBLISH strings Publish a container’s port to the host for profiling, for example, --publish=8080:80. Requires --os-reachability.
e, env ENDOR_CONTAINER_SCAN_ENV strings Set environment variables that the image needs to run, for example, --env=KEY=value. Requires --os-reachability.
entrypoint ENDOR_CONTAINER_SCAN_ENTRYPOINT string Override the default ENTRYPOINT of the image for profiling, for example, --entrypoint=/app/start.sh. Requires --os-reachability.
profiling-max-size ENDOR_CONTAINER_SCAN_PROFILING_MAX_SIZE integer Set the maximum allowed container image size in GB for dynamic profiling. The default value is 10 GB and the minimum value is 1 GB.
profiling-data-dir ENDOR_CONTAINER_SCAN_PROFILING_DATA_DIR strings Add a directory containing profiling data to include in the scan.
app-scan-context ENDOR_CONTAINER_SCAN_APP_SCAN_CONTEXT string Provide the context ID of the SCA app scan. Default is default.
app-scan-project ENDOR_CONTAINER_SCAN_APP_SCAN_PROJECT string Provide the SCA project name for the app in the container image.
base-image-name ENDOR_CONTAINER_SCAN_BASE_IMAGE_NAME string Specify the base image name of the image being scanned. Cannot be used with --dockerfile-path.
base-image-scan ENDOR_CONTAINER_SCAN_BASE_IMAGE_SCAN boolean Scan the base image if identified and not previously scanned.
base-image-scan-project ENDOR_CONTAINER_SCAN_BASE_IMAGE_SCAN_PROJECT string Specify the project name for the base image scan. If not provided, the project name will be the current project.
detached-ref-name ENDOR_CONTAINER_SCAN_DETACHED_REF_NAME string Set the name of the git reference to a user-provided name, for example, --detached-ref-name=main. Requires --path.
dockerfile-path ENDOR_CONTAINER_SCAN_DOCKERFILE_PATH string Specify the Dockerfile path used to build the image being scanned. Cannot be used with --base-image-name.
finding-tags ENDOR_CONTAINER_SCAN_FINDING_TAGS strings Specify a list of user-defined tags to add to findings generated for objects in this scan scope. Finding tags can be used to search and filter findings later.
image-type ENDOR_CONTAINER_SCAN_IMAGE_TYPE string Specify the type of image being scanned (app or base).

Instrumented container reachability records which OS packages are used at runtime through a sensor in your image. Use endorctl container instrument to create the instrumented image. See Instrumented container reachability for more information.

The following flags are supported for the endorctl container instrument command.

Flag Environment Variable Type Description
app-stop-signal ENDOR_CONTAINER_INSTRUMENT_APP_STOP_SIGNAL string Signal sent to the app so the sensor can flush profiling data before the container exits, for example, QUIT or TERM. Ensure the signal is compatible with your application.
app-stop-grace-period ENDOR_CONTAINER_INSTRUMENT_APP_STOP_GRACE_PERIOD string Grace period for app shutdown, for example 10s, 1m. Use when the app needs time to flush before exit.
app-stderr-to-file ENDOR_CONTAINER_INSTRUMENT_APP_STDERR_TO_FILE boolean Redirect application error output to a file in the instrumented container.
app-stdout-to-file ENDOR_CONTAINER_INSTRUMENT_APP_STDOUT_TO_FILE boolean Redirect application standard output to a file in the instrumented container.
cmd ENDOR_CONTAINER_INSTRUMENT_CMD string Override the image CMD (JSON array or shell string). Use when the image has a custom CMD.
debug-mode ENDOR_CONTAINER_INSTRUMENT_DEBUG_MODE boolean Enable sensor debug logs for instrumented container.
entrypoint ENDOR_CONTAINER_INSTRUMENT_ENTRYPOINT string Override the image entrypoint (JSON array or shell string). Use when the image has a custom entrypoint.
load-instrumented-image ENDOR_CONTAINER_INSTRUMENT_LOAD_INSTRUMENTED_IMAGE boolean Load the instrumented image into the local Docker daemon so Kubernetes or a registry can use it.
output-image-tar ENDOR_CONTAINER_INSTRUMENT_OUTPUT_IMAGE_TAR string Output tar file for the instrumented image (default instrumented-image.tar).
sensor-path ENDOR_CONTAINER_INSTRUMENT_SENSOR_PATH string Path to sensor binary.

The endorctl container collect command collects data from the target deployment environment, including profiling data from instrumented containers. See Instrumented container reachability for the full workflow.

The following flags are supported for the endorctl container collect command:

Flag Environment Variable Type Description
dynamic-profiling-data ENDOR_CONTAINER_COLLECT_DYNAMIC_PROFILING_DATA boolean Collect dynamic profiling data from instrumented containers (default true).
kubeconfig-context ENDOR_CONTAINER_COLLECT_KUBECONFIG_CONTEXT string Provide the kubectl kubeconfig context to use to access the target (k8s) deployment environments.
kubeconfig-path ENDOR_CONTAINER_COLLECT_KUBECONFIG_PATH string Provide the kubectl kubeconfig path to use to access the target (k8s) deployment environments.
output-dir ENDOR_CONTAINER_COLLECT_OUTPUT_DIR string Set the directory to store collected data from the target deployment environment. A subdirectory cluster/pod/container is created. Use that path for --profiling-data-dir in the scan step.
runtime-type ENDOR_CONTAINER_COLLECT_RUNTIME_TYPE string Container runtime type (k8s or docker). Default is k8s.

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.

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.

Prerequisites for AWS ECR and Azure ACR registry scans
Install and configure the AWS CLI to use AWS ECR and the Azure CLI to use Azure ACR to authenticate and enumerate their corresponding container registries.

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.

Flag Environment Variable Type Description
--registry-type ENDOR_CONTAINER_REGISTRY_REGISTRY_TYPE string Container registry type. See supported container registries for the registries and their corresponding values.
--registry ENDOR_CONTAINER_REGISTRY_REGISTRY string Registry server or host. See the supported container registries table for example formats. Required for Azure ACR and JFrog.
--registry-namespace ENDOR_CONTAINER_REGISTRY_REGISTRY_NAMESPACE string The namespace or scope to list within. This flag is optional and is commonly used for the Docker Hub, GHCR, and JFrog Artifactory registries. For Docker Hub or GHCR, it is the organization or user name and for JFrog, it is the repository key.
--include ENDOR_CONTAINER_REGISTRY_INCLUDE string Regex to include repositories or tags. Matches the repository name without the registry server or domain, the full repository and tag, or the digest. If not set, all repositories and their tags are included.
--exclude ENDOR_CONTAINER_REGISTRY_EXCLUDE string Regex to exclude a subset of container image names by repository or by repository and tag. For example, --exclude='test-repo' excludes all tags in repositories matching test-repo, and --exclude='myapp:latest' excludes only the latest tag in repositories matching myapp.
--recent ENDOR_CONTAINER_REGISTRY_RECENT string Include only images updated within the given recent time window. Use a duration string such as 24h, 7d, or 2d7h. Applied after include and exclude.
--limit ENDOR_CONTAINER_REGISTRY_LIMIT integer Limit the number of images in the result after all filters are applied.
--include-untagged ENDOR_CONTAINER_REGISTRY_INCLUDE_UNTAGGED boolean Include untagged manifests when the registry type supports them.
--include-untagged-only ENDOR_CONTAINER_REGISTRY_INCLUDE_UNTAGGED_ONLY boolean Consider only untagged container images. Use this only when the registry type supports untagged container images.
--validate-tag-digest ENDOR_CONTAINER_REGISTRY_VALIDATE_TAG_DIGEST boolean Resolve and confirm digest through a registry HEAD request for each tag.
--architecture ENDOR_CONTAINER_REGISTRY_ARCHITECTURE string Preferred architecture for multi-architecture images, for example, amd64, arm64, or linux/arm64.
--timeout ENDOR_CONTAINER_REGISTRY_TIMEOUT string Command timeout duration, such as 30s, 1m, or 5m. Default is 30s.
--project-prefix ENDOR_CONTAINER_REGISTRY_PROJECT_PREFIX string Optional prefix for project names derived from repository path. Without a prefix, the project name uses the container image repository path.
--save-as-plan ENDOR_CONTAINER_REGISTRY_SAVE_AS_PLAN string Write the list output as a scan plan JSON file to use with endorctl container registry scan --scan-plan.
--scanned-only ENDOR_CONTAINER_REGISTRY_SCANNED_ONLY boolean Show only images that have already been scanned in Endor Labs. Requires --namespace and API credentials. Cannot be used with --save-as-plan.
--exclude-scanned ENDOR_CONTAINER_REGISTRY_EXCLUDE_SCANNED boolean Exclude images that are already scanned from the output. Without this flag, already-scanned images are still skipped during scanning. The flag only affects what appears in the list output. If a tag points to a new digest, Endor Labs treats it as a new image and scans it. When saving with --save-as-plan, the saved plan always excludes scanned images regardless of this flag. Requires --namespace and API credentials.

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.

Flag Environment Variable Type Description
--namespace, -n ENDOR_NAMESPACE string Endor Labs namespace for the scan and for checking current scan status.
--scan-plan ENDOR_CONTAINER_REGISTRY_SCAN_PLAN string Path to a scan plan JSON file produced by endorctl container registry list --save-as-plan. Either --registry-type or --scan-plan is required.
--show-scan-plan ENDOR_CONTAINER_REGISTRY_SHOW_SCAN_PLAN boolean Print the scan plan including registry, filters, counts, and image list before starting scans. Set to false to skip this output and start scanning immediately.
--reauth ENDOR_CONTAINER_REGISTRY_REAUTH boolean Try to refresh registry credentials if authentication fails. For ECR and ACR, this uses the AWS CLI or Azure CLI respectively to refresh credentials.
--keep-pulled-images ENDOR_CONTAINER_REGISTRY_KEEP_PULLED_IMAGES boolean Keep pulled images in the local daemon after scanning. By default, pulled images are removed to free disk space.