> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.endorlabs.com/feedback

```json
{
  "path": "/developers-api/cli/commands/container/index",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# container

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

export const YamlTable = ({children, data: propData, content}) => {
  const KV_RE = /^([A-Za-z][A-Za-z0-9_()/#\s-]+?):\s*(.+)$/;
  const INLINE_MD_RE = /(\[([^\]]+)\]\(([^)]+)\))|(`([^`]+)`)|(\*\*([^*]+)\*\*)|(\*([^*]+)\*)/g;
  const YES_RE = /^-yes-$/i;
  const NO_RE = /^-no-$/i;
  const LIMITED_RE = /^-(limited|partial)-$/i;
  const NA_RE = /^-(na|none)-$/i;
  const NA2_RE = /^-na2-$/i;
  const SIMPLE_TAG_RE = /(<br\s*\/?>)|(<p\s*\/?>)|(-note-)|(-warning-)/gi;
  const tryParseKV = trimmed => {
    const m = KV_RE.exec(trimmed);
    return m ? {
      key: m[1],
      value: m[2].trim()
    } : null;
  };
  const registerKey = (key, seenKeys, orderedKeys) => {
    if (!seenKeys.has(key)) {
      orderedKeys.push(key);
      seenKeys.add(key);
    }
  };
  const flushEntry = (currentEntry, entries) => {
    if (Object.keys(currentEntry).length > 0) entries.push(currentEntry);
  };
  const parseDashPrefixed = (lines, entries, orderedKeys, seenKeys) => {
    let currentEntry = {};
    let inEntry = false;
    for (const line of lines) {
      const trimmed = line.trim();
      if (trimmed.startsWith('- ')) {
        if (inEntry) entries.push(currentEntry);
        currentEntry = {};
        inEntry = true;
        const kv = tryParseKV(trimmed.substring(2).trim());
        if (kv) {
          registerKey(kv.key, seenKeys, orderedKeys);
          currentEntry[kv.key] = kv.value;
        }
      } else if (inEntry && trimmed !== '') {
        const kv = tryParseKV(trimmed);
        if (kv) {
          registerKey(kv.key, seenKeys, orderedKeys);
          currentEntry[kv.key] = kv.value;
        }
      }
    }
    flushEntry(currentEntry, entries);
  };
  const parseBlankSeparated = (lines, entries, orderedKeys, seenKeys) => {
    let currentEntry = {};
    let inEntry = false;
    for (const line of lines) {
      const trimmed = line.trim();
      if (trimmed === '') {
        if (inEntry) {
          flushEntry(currentEntry, entries);
          currentEntry = {};
          inEntry = false;
        }
        continue;
      }
      const kv = tryParseKV(trimmed);
      if (!kv) continue;
      const isNewEntry = !line.startsWith(' ') && !line.startsWith('\t');
      if (isNewEntry && inEntry && Object.keys(currentEntry).length > 0) {
        entries.push(currentEntry);
        currentEntry = {};
      }
      registerKey(kv.key, seenKeys, orderedKeys);
      currentEntry[kv.key] = kv.value;
      inEntry = true;
    }
    flushEntry(currentEntry, entries);
  };
  const normalizeEntries = (entries, orderedKeys) => entries.map(entry => {
    const filled = {};
    for (const key of orderedKeys) filled[key] = entry[key] || '';
    return filled;
  });
  const parseYamlTableContent = contentStr => {
    if (!contentStr) return [];
    const entries = [];
    const orderedKeys = [];
    const seenKeys = new Set();
    const lines = contentStr.split('\n');
    if (lines.some(line => line.trim().startsWith('- '))) {
      parseDashPrefixed(lines, entries, orderedKeys, seenKeys);
    } else {
      parseBlankSeparated(lines, entries, orderedKeys, seenKeys);
    }
    return normalizeEntries(entries, orderedKeys);
  };
  const processText = text => {
    if (!text) return text;
    const parts = [];
    let keyIndex = 0;
    let lastIndex = 0;
    let match;
    while ((match = INLINE_MD_RE.exec(text)) !== null) {
      if (match.index > lastIndex) parts.push(text.slice(lastIndex, match.index));
      if (match[1]) {
        parts.push(<a key={keyIndex++} href={match[3]}>{match[2]}</a>);
      } else if (match[4]) {
        parts.push(<code key={keyIndex++}>{match[5]}</code>);
      } else if (match[6]) {
        parts.push(<strong key={keyIndex++}>{match[7]}</strong>);
      } else if (match[8]) {
        parts.push(<em key={keyIndex++}>{match[9]}</em>);
      }
      lastIndex = match.index + match[0].length;
    }
    if (lastIndex < text.length) parts.push(text.slice(lastIndex));
    if (parts.length === 0) return text;
    const keyRef = {
      current: keyIndex
    };
    return expandHtmlTags(parts, keyRef);
  };
  const processBadges = text => {
    if (!text || typeof text !== 'string') return text;
    if (YES_RE.test(text)) return <span className="yt-badge-yes" role="img" aria-label="Supported" title="Supported">✓</span>;
    if (NO_RE.test(text)) return <span className="yt-badge-no" role="img" aria-label="Not supported" title="Not supported">✗</span>;
    if (LIMITED_RE.test(text)) return <span className="yt-badge-limited" role="img" aria-label="Partially supported" title="Partially supported">◐</span>;
    if (NA_RE.test(text) || NA2_RE.test(text)) return <span className="yt-sr-only" title="Not applicable">Not applicable</span>;
    return processText(text);
  };
  const cellClassName = text => {
    if (!text || typeof text !== 'string') return undefined;
    if (NA_RE.test(text)) return 'yt-cell-na';
    if (NA2_RE.test(text)) return 'yt-cell-na2';
    return undefined;
  };
  const expandSimpleTags = (str, keyRef) => {
    const result = [];
    let last = 0;
    SIMPLE_TAG_RE.lastIndex = 0;
    let m;
    while ((m = SIMPLE_TAG_RE.exec(str)) !== null) {
      if (m.index > last) result.push(str.slice(last, m.index));
      if (m[1]) {
        result.push(<br key={keyRef.current++} />);
      } else if (m[2]) {
        result.push(<br key={keyRef.current++} />, <br key={keyRef.current++} />);
      } else if (m[3]) {
        result.push(<span key={keyRef.current++} className="yt-badge-note" style={{
          fontWeight: 600
        }}>Note: </span>);
      } else if (m[4]) {
        result.push(<span key={keyRef.current++} className="yt-badge-warning" style={{
          fontWeight: 600
        }}>Warning: </span>);
      }
      last = m.index + m[0].length;
    }
    if (last < str.length) result.push(str.slice(last));
    return result;
  };
  const expandHtmlTags = (chunks, keyRef) => {
    const out = [];
    for (const chunk of chunks) {
      if (typeof chunk === 'string') {
        out.push(...expandSimpleTags(chunk, keyRef));
      } else {
        out.push(chunk);
      }
    }
    return out;
  };
  const extractText = node => {
    if (node === null || node === undefined) return '';
    if (typeof node === 'string') return node;
    if (typeof node === 'number') return String(node);
    if (typeof node === 'boolean') return '';
    if (Array.isArray(node)) return node.map(extractText).join('');
    if (node && typeof node === 'object' && node.type) {
      const props = node.props || ({});
      if (typeof props.children === 'string') return props.children;
      if (props.children) return extractText(props.children);
      return '';
    }
    return String(node || '');
  };
  const [mounted, setMounted] = useState(false);
  useEffect(() => {
    setMounted(true);
  }, []);
  const data = useMemo(() => {
    if (propData) return propData;
    if (content && typeof content === 'string') return parseYamlTableContent(content);
    if (!children) return [];
    if (typeof children === 'string') return parseYamlTableContent(children);
    const childrenArray = Array.isArray(children) ? children : [children];
    return parseYamlTableContent(childrenArray.map(extractText).join('').trim());
  }, [children, propData, content]);
  const columns = useMemo(() => {
    if (!data || data.length === 0) return [];
    const firstRow = data[0];
    if (!firstRow || typeof firstRow !== 'object') return [];
    return Object.keys(firstRow);
  }, [data]);
  if (!mounted) return null;
  if (!data || data.length === 0) return null;
  const rowKey = row => columns.map(c => row[c] || '').join('|');
  return <table>
      <thead>
        <tr>
          {columns.map(col => <th key={col}>{col.replaceAll('_', ' ')}</th>)}
        </tr>
      </thead>
      <tbody>
        {data.map(row => <tr key={rowKey(row)}>
            {columns.map(col => <td key={col} className={cellClassName(row[col])}>{processBadges(row[col])}</td>)}
          </tr>)}
      </tbody>
    </table>;
};

Run the `endorctl container` command 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:

```bash theme={null}
endorctl container [command] [flags]
```

The `endorctl container` command supports the following subcommands:

* `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](/scan/containers/container-migration) for more information.
</Note>

## Run the endorctl scan

Endor Labs supports the following methods of scanning container images:

* **[Scan container images in a Git repository](#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](#scan-container-images-as-a-standalone-project)**: Use this approach to scan base or golden images that you share across multiple repositories or applications.

* **[Scan container image tarball](#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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
endorctl container scan --project-name=<endor_project_name> --image=<image_name:tag> --as-ref --finding-tags=<image_name:tag>
```

<Note>
  **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.
</Note>

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

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

   ```bash theme={null}
   docker pull alpine:latest
   ```

2. Export the image to a tarball file.

   ```bash theme={null}
   docker save alpine:latest -o alpine-latest.tar
   ```

3. Perform the endorctl scan.

   ```bash theme={null}
   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.
   </Note>

### Options

The `endorctl container scan` command supports the following flags.

<YamlTable>
  {`


    - Flag: \`image\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_IMAGE\`
    Type: string
    Description: The container image name and tag to scan, for example, \`nginx:latest\`. Use this flag in combination with other scan-related parameters.

    - Flag: \`image-tar\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_IMAGE_TAR\`
    Type: string
    Description: 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.

    - Flag: \`p\`, \`path\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_REPOSITORY_PATH\`
    Type: string
    Description: Set the path to a valid git repository to associate the container scan with a Git repository. Default is \`.\`.

    - Flag: \`project-name\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_PROJECT_NAME\`
    Type: string
    Description: Set the project name for the container scan when scanning as a standalone project.

    - Flag: \`as-ref\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_AS_REF\`
    Type: boolean
    Description: Scan the container in a persistent context and keep the version. Use with \`--project-name\` to specify the name of the project.

    - Flag: \`project-tags\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_PROJECT_TAGS\`
    Type: strings
    Description: Specify a list of user-defined tags to add to this project.

    - Flag: \`r\`, \`os-reachability\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_OS_REACHABILITY\`
    Type: boolean
    Description: Enable OS reachability analysis to determine which OS packages in the container image are actually used at runtime.

    - Flag: \`o\`, \`output-type\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_SUMMARY_OUTPUT_TYPE\`
    Type: string
    Description: Set output format (\`json\`, \`yaml\`, \`table\`, \`summary\`, or \`table-verbose\`). Default is \`table\`.

    - Flag: \`volume\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_VOLUME\`
    Type: strings
    Description: Bind mount a volume for container profiling, for example, \`--volume=/host/path:/container/path\`. Requires \`--os-reachability\`.

    - Flag: \`publish\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_PUBLISH\`
    Type: strings
    Description: Publish a container's port to the host for profiling, for example, \`--publish=8080:80\`. Requires \`--os-reachability\`.

    - Flag: \`e\`, \`env\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_ENV\`
    Type: strings
    Description: Set environment variables that the image needs to run, for example, \`--env=KEY=value\`. Requires \`--os-reachability\`.

    - Flag: \`entrypoint\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_ENTRYPOINT\`
    Type: string
    Description: Override the default ENTRYPOINT of the image for profiling, for example, \`--entrypoint=/app/start.sh\`. Requires \`--os-reachability\`.

    - Flag: \`profiling-max-size\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_PROFILING_MAX_SIZE\`
    Type: integer
    Description: 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.

    - Flag: \`profiling-data-dir\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_PROFILING_DATA_DIR\`
    Type: strings
    Description: Add a directory containing profiling data to include in the scan.

    - Flag: \`app-scan-context\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_APP_SCAN_CONTEXT\`
    Type: string
    Description: Provide the context ID of the SCA app scan. Default is \`default\`.

    - Flag: \`app-scan-project\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_APP_SCAN_PROJECT\`
    Type: string
    Description: Provide the SCA project name for the app in the container image.

    - Flag: \`base-image-name\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_BASE_IMAGE_NAME\`
    Type: string
    Description: Specify the base image name of the image to scan. Incompatible with \`--dockerfile-path\`.

    - Flag: \`base-image-scan\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_BASE_IMAGE_SCAN\`
    Type: boolean
    Description: Scan the base image if identified and not previously scanned.

    - Flag: \`base-image-scan-project\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_BASE_IMAGE_SCAN_PROJECT\`
    Type: string
    Description: Specify the project name for the base image scan. If not provided, the project name will be the current project.

    - Flag: \`detached-ref-name\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_DETACHED_REF_NAME\`
    Type: string
    Description: Set the name of the git reference to a user-provided name, for example, \`--detached-ref-name=main\`. Requires \`--path\`.

    - Flag: \`dockerfile-path\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_DOCKERFILE_PATH\`
    Type: string
    Description: Specify the Dockerfile path for building the image to scan. Incompatible with \`--base-image-name\`.

    - Flag: \`finding-tags\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_FINDING_TAGS\`
    Type: strings
    Description: Specify a list of user-defined tags to add to findings generated for objects in this scan scope. Use finding tags to search and filter findings later.

    - Flag: \`image-type\`
    Environment_Variable: \`ENDOR_CONTAINER_SCAN_IMAGE_TYPE\`
    Type: string
    Description: Specify the type of image to scan (\`app\` or \`base\`).

    `}
</YamlTable>

## Instrumented container reachability

Instrumented container reachability records the OS packages your application uses at runtime through a sensor in your image. Use `endorctl container instrument` to create the instrumented image. See [Instrumented container reachability](/scan/containers/instrumented-reachability) for more information.

The `endorctl container instrument` command supports the following flags.

<YamlTable>
  {`


    - Flag: \`app-stop-signal\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_APP_STOP_SIGNAL\`
    Type: string
    Description: 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.

    - Flag: \`app-stop-grace-period\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_APP_STOP_GRACE_PERIOD\`
    Type: string
    Description: Grace period for app shutdown, for example \`10s\`, \`1m\`. Use when the app needs time to flush before exit.

    - Flag: \`app-stderr-to-file\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_APP_STDERR_TO_FILE\`
    Type: boolean
    Description: Redirect application error output to a file in the instrumented container.

    - Flag: \`app-stdout-to-file\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_APP_STDOUT_TO_FILE\`
    Type: boolean
    Description: Redirect application standard output to a file in the instrumented container.

    - Flag: \`entrypoint\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_ENTRYPOINT\`
    Type: string
    Description: Override the image entrypoint (JSON array or shell string). Use when the image has a custom entrypoint.

    - Flag: \`cmd\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_CMD\`
    Type: string
    Description: Override the image CMD (JSON array or shell string). Use when the image has a custom CMD.

    - Flag: \`debug-mode\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_DEBUG_MODE\`
    Type: boolean
    Description: Enable sensor debug logs for instrumented container.

    - Flag: \`load-instrumented-image\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_LOAD_INSTRUMENTED_IMAGE\`
    Type: boolean
    Description: Load the instrumented image into the local Docker daemon so Kubernetes or a registry can use it. Default \`false\`.

    - Flag: \`output-image-tar\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_OUTPUT_IMAGE_TAR\`
    Type: string
    Description: Output tar path for the instrumented image. Default \`instrumented-image.tar\`.

    - Flag: \`sensor-path\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_SENSOR_PATH\`
    Type: string
    Description: Path to sensor binary.

    - Flag: \`platform\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_PLATFORM\`
    Type: string
    Description: Target platform for the instrumented image, for example \`linux/amd64\` or \`linux/arm64\`, or a comma-separated list such as \`linux/arm64,linux/amd64\` for multi-arch. Use when instrumenting multi-arch images. Requires \`--image\`.

    - Flag: \`publish\`
    Environment_Variable: \`ENDOR_CONTAINER_INSTRUMENT_PUBLISH\`
    Type: boolean
    Description: Publish the instrumented image to the registry after instrumentation completes. Requires you to authenticate the Docker daemon with the target registry. Default \`false\`.


    `}
</YamlTable>

### 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](/scan/containers/instrumented-reachability#determine-instrumented-container-reachability) for the full workflow.

The `endorctl container collect` command supports the following flags:

<YamlTable>
  {`


    - Flag: \`dynamic-profiling-data\`
    Environment_Variable: \`ENDOR_CONTAINER_COLLECT_DYNAMIC_PROFILING_DATA\`
    Type: boolean
    Description: Collect dynamic profiling data from instrumented containers (default \`true\`).

    - Flag: \`kubeconfig-context\`
    Environment_Variable: \`ENDOR_CONTAINER_COLLECT_KUBECONFIG_CONTEXT\`
    Type: string
    Description: Provide the kubectl kubeconfig context to use to access the target (k8s) deployment environments.

    - Flag: \`kubeconfig-path\`
    Environment_Variable: \`ENDOR_CONTAINER_COLLECT_KUBECONFIG_PATH\`
    Type: string
    Description: Provide the kubectl kubeconfig path to use to access the target (k8s) deployment environments.

    - Flag: \`output-dir\`
    Environment_Variable: \`ENDOR_CONTAINER_COLLECT_OUTPUT_DIR\`
    Type: string
    Description: Set the directory to store collected data from the target deployment environment. The command creates a subdirectory \`cluster/pod/container\`. Use that path for \`--profiling-data-dir\` in the scan step.

    - Flag: \`runtime-type\`
    Environment_Variable: \`ENDOR_CONTAINER_COLLECT_RUNTIME_TYPE\`
    Type: string
    Description: Container runtime type. Supports \`k8s\` only.


    `}
</YamlTable>

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

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

* [**List images from a registry**](#list-command): 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**](#scan-command): 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.

<Note>
  **Prerequisites for AWS ECR and Azure ACR registry scans**

  Install and configure the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) for AWS ECR or the [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) for Azure ACR. These tools can authenticate and enumerate the container registries.
</Note>

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

```bash theme={null}
endorctl container registry list --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.

The command applies filters 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.

<YamlTable>
  {`


    - Flag: \`--type\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_TYPE\`
    Type: string
    Description: Container registry type. See [supported container registries](/scan/containers/container-registry-scan/#supported-container-registries) for the registries and their corresponding values.

    - Flag: \`--host\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_HOST\`
    Type: string
    Description: Registry server or host. See the supported container registries table for example formats. Required for Azure ACR and JFrog.

    -Flag: \`--insecure\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_INSECURE\`
    Type: boolean
    Description: Allow HTTPS connections to the registry without verifying the TLS certificate. Use only when connecting to registries with self-signed or otherwise untrusted certificates.

    - Flag: \`--registry-namespace\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_NAMESPACE\`
    Type: string
    Description: 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.

    - Flag: \`--include\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_INCLUDE\`
    Type: string
    Description: 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, the command includes all repositories and their tags.

    - Flag: \`--exclude\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_EXCLUDE\`
    Type: string
    Description: 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\`.

    - Flag: \`--recent\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_RECENT\`
    Type: string
    Description: 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.

    - Flag: \`--limit\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_LIMIT\`
    Type: integer
    Description: Limit the number of images in the result after the command applies all filters.

    - Flag: \`--include-untagged\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_INCLUDE_UNTAGGED\`
    Type: boolean
    Description: Include untagged manifests when the registry type supports them.

    - Flag: \`--include-untagged-only\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_INCLUDE_UNTAGGED_ONLY\`
    Type: boolean
    Description: Consider only untagged container images. Use this only when the registry type supports untagged container images.

    - Flag: \`--validate-tag-digest\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_VALIDATE_TAG_DIGEST\`
    Type: boolean
    Description: Resolve and confirm digest through a registry HEAD request for each tag.

    - Flag: \`--architecture\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_ARCHITECTURE\`
    Type: string
    Description: Preferred architecture for multi-architecture images, for example, \`amd64\`, \`arm64\`, or \`linux/arm64\`.

    - Flag: \`--timeout\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_TIMEOUT\`
    Type: string
    Description: Command timeout duration, such as \`30s\`, \`1m\`, or \`5m\`. Default is \`30s\`.

    - Flag: \`--project-prefix\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_PROJECT_PREFIX\`
    Type: string
    Description: Optional prefix for project names derived from repository path. Without a prefix, the project name uses the container image repository path.

    - Flag: \`--save-as-plan\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_SAVE_AS_PLAN\`
    Type: string
    Description: Write the list output as a scan plan JSON file to use with \`endorctl container registry scan --scan-plan\`.

    - Flag: \`--scanned-only\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_SCANNED_ONLY\`
    Type: boolean
    Description: Show only images that Endor Labs already scanned. Requires \`--namespace\` and API credentials. You cannot use this flag with \`--save-as-plan\`.

    - Flag: \`--exclude-scanned\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_EXCLUDE_SCANNED\`
    Type: boolean
    Description: 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.


    `}
</YamlTable>

### 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. You must provide `--namespace` and API credentials. Images that are already scanned are automatically skipped.

* Scan using a saved scan plan:

  ```bash theme={null}
  endorctl container registry scan --namespace=<namespace> --scan-plan=<path> [options]
  ```

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

  ```bash theme={null}
  endorctl container registry scan --namespace=<namespace> --type=<type> [options]
  ```

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

<YamlTable>
  {`


    - Flag: \`--namespace\`, \`-n\`
    Environment_Variable: \`ENDOR_NAMESPACE\`
    Type: string
    Description: Endor Labs namespace for the scan and for checking current scan status.

    - Flag: \`--scan-plan\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_SCAN_PLAN\`
    Type: string
    Description: Path to a scan plan JSON file produced by \`endorctl container registry list --save-as-plan\`. Provide either \`--type\` or \`--scan-plan\`.

    - Flag: \`--show-scan-plan\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_SHOW_SCAN_PLAN\`
    Type: boolean
    Description: 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.

    - Flag: \`--reauth\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_REAUTH\`
    Type: boolean
    Description: Try to refresh registry credentials if authentication fails. For ECR and ACR, this uses the AWS CLI or Azure CLI respectively to refresh credentials.

    - Flag: \`--keep-pulled-images\`
    Environment_Variable: \`ENDOR_CONTAINER_REGISTRY_KEEP_PULLED_IMAGES\`
    Type: boolean
    Description: Keep pulled images in the local daemon after scanning. By default, the command removes pulled images to free disk space.


    `}
</YamlTable>