container

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

This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

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.

Usage

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.

Run the endorctl scan

Endor Labs supports the following methods of scanning container images:

Scan container images in a Git repository: Use this approach to scan images built within your repository using a Dockerfile.
Scan container images as a standalone project: Use this approach to scan base or golden images that are shared across multiple repositories or applications.
Scan container image tarball: Use this to scan images saved as tar files, such as base images exported from Docker, to generate dependency, SBOM, and vulnerability reports.

Scan container images in a Git repository

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>

Scan container images as a standalone project

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.

Scan container image tarball

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.

Ensure that you have the container image available locally.
```
docker pull alpine:latest
```

Export the image to a tarball file.

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

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.

Options

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

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.

Collect container profiling data

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`.