AWS imagebuilder: Document image scan status, failure reasons, and finding retention
Summary
Adds a new section explaining that Amazon Inspector (not Image Builder) runs scans, lists terminal scan failure reasons (ACCESS_DENIED, INTERNAL_ERROR, UNSUPPORTED_OS, UNKNOWN) with causes and resolutions, describes the 15-minute default wait and CloudWatch logging, notes that only package vulnerability findings are saved, and states findings are retained until the image build version is deleted. Also removes "or network settings" from the Inspector discovery sentence and adds nav entries.
Security assessment
The change documents the behavior of the vulnerability-scanning integration (scan status polling, failure reasons such as ACCESS_DENIED, retention of findings, and CloudWatch logging of incomplete scans). It is security-relevant operational/audit documentation but does not describe or remediate a specific vulnerability or incident.
Evidence
+Image Builder saves only package vulnerability findings from Amazon Inspector. For more information, see [Understanding Amazon Inspector findings](https://docs.aws.amazon.com/inspector/latest/user/findings-understanding.html) in the _Amazon Inspector User Guide_.
Diff
diff --git a/imagebuilder/latest/userguide/image-security-findings.md b/imagebuilder/latest/userguide/image-security-findings.md index 3fa98de..db52930 100644 --- a//imagebuilder/latest/userguide/image-security-findings.md +++ b//imagebuilder/latest/userguide/image-security-findings.md @@ -7 +7 @@ -Configure security scansManage security findings +Configure security scansManage security findingsScan status and failure reasons @@ -13 +13 @@ When you activate security scanning with Amazon Inspector, it continuously scans -When Amazon Inspector discovers vulnerabilities in your software or network settings, it takes the following actions: +When Amazon Inspector discovers vulnerabilities in your software, it takes the following actions: @@ -62,0 +63,4 @@ If you've activated scanning for your pipeline, Image Builder takes a snapshot o +###### Finding retention + +Image Builder keeps the findings snapshot until you delete the image build version. For more information, see [Delete an image](./delete-resources.html#delete-resources-image). + @@ -97,0 +102,4 @@ If you want to turn off the snapshots later, you can edit your pipeline to clear +###### Package vulnerability findings only + +Image Builder saves only package vulnerability findings from Amazon Inspector. For more information, see [Understanding Amazon Inspector findings](https://docs.aws.amazon.com/inspector/latest/user/findings-understanding.html) in the _Amazon Inspector User Guide_. + @@ -185,0 +194,42 @@ The date and time when this vulnerability was first added to the vendor's databa +## Image scan status and failure reasons + +Amazon Inspector, not Image Builder, runs the scan. When you enable scanning, the `CollectImageScanFindings` step in your test workflow polls Amazon Inspector for the scan status of the test instance for an AMI-based image, or of the Amazon ECR container that Image Builder pushes to the scanning repository for a container-based image. Polling continues until the scan reaches a terminal state or the wait time ends. If the scan succeeds, Image Builder saves a one-time snapshot of the findings. + +Image Builder treats the following Amazon Inspector reasons as terminal. When Amazon Inspector returns one, Image Builder stops polling, sets the image scan status to `FAILED`, and records the reason unchanged. For all reasons, see the [ScanStatus](https://docs.aws.amazon.com/inspector/v2/APIReference/API_ScanStatus.html) data type in the _Amazon Inspector API Reference_. + +`ACCESS_DENIED` + + +**Cause** – A resource access policy restricts Amazon Inspector (not Image Builder) access to the scanned resource. + +**Resolution** – Update the IAM or resource policy that denies Amazon Inspector access, then build a new image. + +`INTERNAL_ERROR` + + +**Cause** – Amazon Inspector encountered an internal error for the scanned resource. + +**Resolution** – Build a new image to scan again. + +`UNSUPPORTED_OS` + + +**Cause** – Amazon Inspector doesn't support the operating system, architecture, or image manifest type of the scanned resource. + +**Resolution** – Build from a parent image that Amazon Inspector supports. For the list of supported operating systems, see [Supported operating systems and programming languages for Amazon Inspector](https://docs.aws.amazon.com/inspector/latest/user/supported.html) in the _Amazon Inspector User Guide_. + +If the scan doesn't reach a terminal state in time, Image Builder sets the image scan status to `FAILED` with the reason `UNKNOWN`. By default, Image Builder waits 15 minutes for the scan. If the `CollectImageScanFindings` step sets `timeoutSeconds`, that value limits the whole step instead, including the wait for the scan. When the default wait ends, Image Builder also writes a message to the image's log group in CloudWatch Logs that says the image scan didn't finish. For the log group names, see [Monitor Image Builder logs with Amazon CloudWatch Logs](./monitor-cwlogs.html). + +The scan also ends this way in the following cases, because Amazon Inspector reports no coverage for the resource: + + * Amazon Inspector isn't activated for your account when the build runs. + + * The scanned resource is terminated before the scan completes. + + + + +###### Failed scans can't be repeated + +After a scan fails, Image Builder can't scan the same image again, even if the `CollectImageScanFindings` step has a `retry` attribute. To scan again, build a new image. +