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

# Container Image Scanning

> Container image scanning identifies known security vulnerabilities in the base images your project depends on, including operating system packages, system libraries, and other software installed within the image layers.

## Overview

* **What it Does**: Container image scanning identifies known security vulnerabilities in the container images your project uses. This includes vulnerabilities in base operating system packages, system libraries, and application packages installed within the image layers. By scanning images before deployment, you can catch security risks in containerized applications early.

* **Who it's For**: Security teams, developers, and DevOps engineers who ship containerized applications and want visibility into the vulnerabilities they inherit from base images.

## How It Works

Corgea automatically discovers the container images referenced in your project and scans each one against known vulnerability databases.

<Steps>
  <Step title="Image Discovery">
    Corgea scans your project for `Dockerfile` and Docker Compose files, then extracts the image references from them:

    * **Dockerfiles**: base images declared with `FROM` (for example, `FROM python:3.11-slim`)
    * **Docker Compose**: images declared under `image:` for each service (for example, `image: postgres:15`)

    Discovered images are de-duplicated and mapped back to the file that referenced them.
  </Step>

  <Step title="Image Analysis">
    Each image is pulled and its layers are analyzed to build an inventory of installed software — including OS/distribution packages (Debian, Ubuntu, Alpine, and others) and application packages installed inside the image.
  </Step>

  <Step title="Vulnerability Matching">
    The discovered packages are cross-referenced against known vulnerability databases, and any matches are reported alongside your other scan results.
  </Step>
</Steps>

## Scanning a Fully Built Image

The discovery flow above scans the base images your project references. To scan a **fully built** image instead — for example an image you just built in CI that has never been pushed to a registry — pass it to the CLI with `--include-image`:

```bash theme={null}
corgea scan --include-image myapp:1.2.3
```

Your local container engine (`docker` or `podman`) exports the image and the CLI uploads it with your project, so the image is scanned exactly as it ships. When you pass `--include-image`, Corgea scans the images you provide instead of discovering base images from your source tree. `--include-image` is supported only by the BLAST scanner. Container scanning must be enabled for your account.

See [Scan Container Images](/cli#scan-container-images) in the CLI reference for the full flag behavior.

## Tracking findings across scans

Corgea tracks a container finding by its image, package, and vulnerability advisory. Triage decisions persist when package versions change, while different packages affected by the same advisory remain separate findings.

## Supported Registries

Corgea scans images hosted on public registries:

* Docker Hub
* GitHub Container Registry (GHCR)
* Google Container Registry (GCR)
* Quay.io
* Microsoft Container Registry (MCR)
* Amazon ECR Public
* GitLab Container Registry

<Info>Automatic image discovery is enabled when Docker files are detected in your project, and requires no configuration. Scanning a fully built image with `--include-image` requires container scanning to be enabled for your account.</Info>

## Limitations

These limits apply to the images Corgea discovers and pulls itself:

* **Public registries only**: Images hosted on private registries are skipped. To scan a private image, pull or build it on your own runner and pass it with `--include-image`, which uploads the image from your container engine rather than having Corgea fetch it.
* **Maximum image size**: Images larger than 1000 MB (1 GB) are skipped.
* Only images referenced in `Dockerfile` and Docker Compose files are discovered. Use `--include-image` to scan an image that neither file references.

## Best Practices

<Tip>Use specific image tags (for example, `python:3.11.5-slim`) instead of `latest` for consistent, reproducible scan results.</Tip>

* **Use Specific Tags**: Avoid `latest` tags; pin exact versions so scans are reproducible.
* **Prefer Minimal Base Images**: Use slim, Alpine, or distroless variants to reduce the attack surface.
* **Regular Updates**: Keep base images updated to pick up security patches.
* **Multi-Stage Builds**: Minimize the final image size and the set of packages it includes.

## Related

* [Dependency Scanning (SCA)](/sca) — scan your application's third-party dependencies
* [Malicious Package Detection](/malware-scanning) — detect known malicious or compromised packages