Container reachability

Determine if the packages inside a container image are actually used by your application at runtime.
Beta

Endor Labs allows you to determine whether the OS packages present in a container image are actually used by your application at runtime. Use container reachability to distinguish dependencies that are merely installed from those that are actively exercised during execution, helping security teams prioritize the most critical security issues for remediation.

Note
Run the container scan using the new endorctl container scan command. The endorctl scan --container command does not support container reachability.

To perform container reachability analysis, ensure you meet the following system requirements:

  • The container must have sufficient CPU and memory resources to run successfully.

  • The container must be runnable.

  • The container must have network access if its startup process requires external communication.

  • Docker daemon dockerd must be installed on the host, must be runnable and accessible to the current user without elevated privileges. For example, docker images should work without sudo.

  • The negotiated Docker API version between the client and server must be 1.48 or higher.

  • The scan must be run on either a Linux or macOS host machine. Container reachability is supported for both amd64 and arm64 architectures.

Endor Labs determines container reachability by extracting OS packages from the container image, profiling the container’s runtime behavior, and correlating the results to identify which dependencies are actually used during execution. The steps below describe how container reachability is determined.

  1. Dependency extraction - Endor Labs extracts all packages and dependencies present in the container image by analyzing its file system to identify installed OS packages and their file path locations within the image.

  2. Dynamic profiling - Endor Labs runs the container image in a controlled environment, monitoring which OS-level files and dependencies are accessed during execution. The profiling captures runtime behavior including system calls, process IDs, and file path access patterns. It also identifies the main process that starts the container as the entry point and uses it to determine which packages are reachable through their dependency relationships.

  3. Path matching and reachability determination - Endor Labs correlates the results from both steps by comparing the extracted dependency file paths against the file access patterns captured during profiling, then assigns each dependency a reachability status based on whether it was accessed during execution.

Run the following command with the --os-reachability flag to include container reachability analysis in the scan.

endorctl container scan \
  --namespace=<your-namespace> \
  --image=<image_name:tag> \
  --project-name=<endor_project_name> \
  --os-reachability

You can also run container scans with OS reachability using GitHub Actions. See Scan containers with OS reachability for details.

Before dynamic profiling begins, Endor Labs performs a series of image qualification checks to determine if the container image is suitable for profiling. These checks include:

  • Image size - Verifies that the uncompressed image size does not exceed the configured limit. The default limit is 10 GB. Use the --profiling-max-size flag to adjust this limit.

  • Runnability - Runs the container to check that it starts without errors. If the container exits with an error, the error details are shown in the CLI output and surfaced in the Endor Labs user interface.

If the image fails any of the qualification checks, dynamic profiling is skipped and the scan proceeds without reachability analysis.

You can run the endorctl container scan --os-reachability command with the following options.

Flag Environment Variable Type Description
--volume ENDOR_CONTAINER_SCAN_VOLUME string Bind mount a volume for the container during profiling, for example, --volume=/host/path:/container/path.
--publish ENDOR_CONTAINER_SCAN_PUBLISH string Publish a container’s port to the host for profiling in the format host_port:container_port, for example, --publish=8080:80.
--env ENDOR_CONTAINER_SCAN_ENV string Set environment variables for the container during profiling.
--entrypoint ENDOR_CONTAINER_SCAN_ENTRYPOINT string Override the container entry point for profiling, for example, --entrypoint=/app/start.sh.
--profiling-max-size ENDOR_CONTAINER_SCAN_PROFILING_MAX_SIZE integer Set the maximum allowed container image size in GB for dynamic profiling, for example, --profiling-max-size=15. The default is 10 GB and the minimum is 1 GB.

The container reachability status indicates whether a dependency was used during runtime profiling or whether its usage could not be determined.

  • Reachable - The dependency is observed in runtime signals or confidently inferred through correlation analysis.

  • Potentially reachable - The dependency has not been observed during profiling, and there is no correlation evidence of its usage. However, its usage cannot be definitively ruled out without additional analysis, such as extended runtime monitoring.

  • Unreachable - The dependency was not observed during profiling and has no path from the container image’s entry point to it.

Use reachability information to prioritize vulnerability remediation effectively. The following table provides recommended actions based on the combination of vulnerability severity and reachability status.

Severity Reachability Status Recommended Action
Critical Reachable Remediate immediately to mitigate active, high-risk vulnerabilities.
High Reachable Prioritize remediation as soon as possible.
Critical Potentially Reachable Review and verify reachability before scheduling remediation.
Medium or Low Reachable Plan remediation as part of regular maintenance activities.
Medium or Low Potentially Reachable Low priority, monitor and reassess as needed.

You can filter findings across all projects by their reachability status.

  1. Select Findings from the left sidebar.
  2. Select Attributes, and in the Reachable Dependency filter, select Yes, Potentially, or No to narrow down findings by reachability status.

Keep the following limitations in mind when using container reachability analysis:

  • Code coverage - The scan does not detect dependencies accessed after the profiling window ends.

  • OS packages - Container reachability analysis applies only to OS-level packages. It identifies which OS packages are used at runtime but does not analyze specific vulnerable functions within those packages. Use Software Composition Analysis reachability to assess the runtime relevance of application dependencies.

  • Windows not supported - Container scanning and reachability are not supported on Windows.

  • Tar image paths - Dynamic profiling is not supported for container images referenced with a tar path.

Container fails to start and crashes during profiling

  • Verify that the container image runs successfully by using the docker run command.

  • Check whether the container requires specific environment variables or mounted volumes to start correctly. Use the --env and --volume flags to provide them during the scan.

  • Ensure that the container does not depend on interactive input during startup or execution.

  • Use the --entrypoint flag to override the container entry point if the default entry point causes issues.

Container profiling times out due to slow container startup or execution

  • Check the container’s startup performance to ensure it initializes within the expected time frame.

  • Verify that the container has network connectivity if it depends on external services.

  • Review the container logs to identify any errors or issues that occur during startup.

Profiling is skipped because the image is too large

  • Check whether the uncompressed image size exceeds the configured limit. The default limit is 10 GB.

  • Use the --profiling-max-size flag to increase the limit if needed.

Known active dependencies are shown as potentially reachable

Possible Causes:

  • The dependency might only be accessed after the profiling window ends.

  • The dependency may require specific HTTP endpoints or actions that are not triggered during profiling.

  • The dependency might be loading slowly or initialized only under specific conditions.

  • Startup optimizations may delay the actual use of the dependency until after profiling completes.

  • The dependency may not have a direct path from the container image’s entry point.

Solutions:

  • Review the typical application startup time to determine whether dependencies are loaded later in the process.

  • Consider whether specific operations or workflows trigger the use of these dependencies.

  • Use the --env, --volume, or --publish flags to provide the container with the configuration it may require to exercise more code paths during profiling.

  • Use container reachability results together with threat modeling to better assess overall security risk.