# Scan an image

Read an image's vulnerability scan, and scan it again after the vulnerability database has moved or a scan failed.

Every pushed image is scanned on its own, and so is every image a pull-through cache brings in.
The scanner is Trivy: it pulls the image by digest, lists its operating-system and language
packages, and matches them against its vulnerability database. Replace repository-id and
manifest-id with the repository's id and the image's `manifest.id`, and scan-id
with a scan's `id`.

## Prerequisites

- To read results: `ecr:GetScanResults` on the repository. Without it the console's **Scans** tab
  says so, and a scan report answers 404.
- To scan again: `ecr:ScanImage` on the repository.
- In the console, also `ecr:DescribeRepositories` on the repository; without it its page answers 404.

## Scan again

**Console**
1. Open **Image repositories**, then open the repository.
2. On the **Images** tab, open the image row's action menu and choose
   **Scan for vulnerabilities**.

The **Vulnerabilities** column shows **Scanning** until the scan ends. A scan report also has
**Re-scan**.

**CLI**
```sh
dcloud ecr images scan repository-id manifest-id
```

**API**
```http
POST /ecr/api/repositories/repository-id/images/manifest-id/scan
```

The answer is `202` with `{ scanId }`; the scan runs in the background.

## Read the result

**Console**
1. Open the repository's **Scans** tab. It lists the latest scan of every image, with its
   **Status** and the counts per severity.
2. Choose **View report** to see every finding, grouped by what was scanned: the operating system
   or a file such as a lock file.

**CLI**
```sh
dcloud ecr images latest-scan repository-id manifest-id
dcloud ecr images list-scans repository-id manifest-id
dcloud ecr scan-results get scan-id
```

**API**
```http
GET /ecr/api/repositories/repository-id/images/manifest-id/scan
```

`…/scans` lists every scan of the image (newest first, 50 per page by default, at most 200), and
`GET /ecr/api/scan-results/{scanId}` returns one scan with its `findings`: a JSON text holding the
operating system found and, per scanned target, its vulnerabilities.

## Scan fields

| Field         | Values                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `status`      | `pending`, `running`, `completed`, `failed`                                                                              |
| `triggeredBy` | `auto` (a push, a pull-through fill, or a rescan the platform starts itself), `manual` (the console, the CLI or the API) |
| severities    | `summaryCritical`, `summaryHigh`, `summaryMedium`, `summaryLow`, `summaryUnknown`; `null` until completed                |

The images table shows the worst severity found, **Scanning** while a scan is `pending` or
`running`, **Scan failed** for `failed`, **Clean** when a completed scan found nothing, and
**Not scanned** before any scan.

A scan that finds no operating system and no packages is recorded as `failed` with "Nothing to
scan: no operating system or language packages were found in this image", never as clean. Helm
charts, signatures, SBOMs and multi-platform indexes are not scanned; each platform image of a
multi-platform push is. A scan that completes, or that the scanner answers with an error, emits
`ECR Image Scan` on your event bus.

## If it is refused

`404` `Not found` when the repository or the image does not exist. The latest-scan read answers
`404` too for an image that has never been scanned.

## Related

- [Monitoring Container registry](monitoring.md)
- `ecr.images.scan` · `dcloud ecr images scan`
