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:GetScanResultson the repository. Without it the console's Scans tab says so, and a scan report answers 404. - To scan again:
ecr:ScanImageon the repository. - In the console, also
ecr:DescribeRepositorieson the repository; without it its page answers 404.
Scan again
- Open Image repositories, then open the repository.
- 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.
dcloud ecr images scan repository-id manifest-idPOST /ecr/api/repositories/repository-id/images/manifest-id/scanThe answer is 202 with { scanId }; the scan runs in the background.
Read the result
- Open the repository's Scans tab. It lists the latest scan of every image, with its Status and the counts per severity.
- Choose View report to see every finding, grouped by what was scanned: the operating system or a file such as a lock file.
dcloud ecr images latest-scan repository-id manifest-id
dcloud ecr images list-scans repository-id manifest-id
dcloud ecr scan-results get scan-idGET /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.