AWS imagebuilder: Clarify Image Builder EventBridge state values and scan-findings event behavior
Summary
Updates the Image Builder EventBridge integration page: normalizes build-transition state values to uppercase (BUILDING/TESTING/DISTRIBUTING/FAILED/etc.), adds the state.reason field, expands the documented state.status list (CREATING, IMPORTING), notes best-effort delivery and GetImage as the source of truth, and rewrites the image-scan (CVE detection) event section to explain that the event is emitted from CollectImageScanFindings even with zero findings, that delivery is best effort, and that resource-id is the EC2 test instance ID for AMIs or the ECR container ARN for container builds.
Security assessment
The diff is primarily an accuracy/correctness update to event schema documentation (state value casing, added state.reason, expanded status list, best-effort delivery caveats). The only security-adjacent content is the clarification of the Amazon Inspector image-scan findings event (when it fires, that it fires even with no findings, and that finding-severity-counts should be checked), which documents vulnerability-scanning notification behavior rather than fixing or disclosing any specific vulnerability. No CVE or advisory identifier appears in the diff, and no auth/encryption/credential or exposure change is made.
Evidence
+Image Builder sends this event with the results after it collects the findings from a successful image scan, even if the scan finds no vulnerabilities.
Diff
diff --git a/imagebuilder/latest/userguide/integ-eventbridge.md b/imagebuilder/latest/userguide/integ-eventbridge.md index 3d898be..9c12e69 100644 --- a//imagebuilder/latest/userguide/integ-eventbridge.md +++ b//imagebuilder/latest/userguide/integ-eventbridge.md @@ -94 +94 @@ Image Builder sends this event when the state changes for an image resource duri - * From `building` to `testing` + * From `BUILDING` to `TESTING` @@ -96 +96 @@ Image Builder sends this event when the state changes for an image resource duri - * From `testing` to `distribution` + * From `TESTING` to `DISTRIBUTING` @@ -98 +98 @@ Image Builder sends this event when the state changes for an image resource duri - * From `testing` to `failed` + * From `TESTING` to `FAILED` @@ -100 +100 @@ Image Builder sends this event when the state changes for an image resource duri - * From `integrating` to `available` + * From `INTEGRATING` to `AVAILABLE` @@ -125 +125 @@ Image Builder sends this event when the state changes for an image resource duri -Image Builder sends this event each time an image resource changes state during image creation, across the build transitions shown above. +Image Builder sends this event when an image resource changes state during image creation. The build transitions in the preceding list are examples. @@ -132,0 +133 @@ Field | Description +`state.reason` | The reason for the new status. Image Builder includes this field when the new status is `FAILED`. @@ -134 +135,5 @@ Field | Description -The build-transition status values are `BUILDING`, `TESTING`, `DISTRIBUTING`, `INTEGRATING`, `AVAILABLE`, `CANCELLED`, and `FAILED`. +The `state.status` values that this event reports are `CREATING`, `IMPORTING`, `BUILDING`, `TESTING`, `DISTRIBUTING`, `INTEGRATING`, `AVAILABLE`, `CANCELLED`, and `FAILED`. Image Builder reports `IMPORTING` only for an image import operation, such as an image that you import from a VM, and reports `CREATING` only on the first attempt of a build. A build that converts a disk image reports `CREATING` and `BUILDING` instead. + +An image with no distribution configuration doesn't report `INTEGRATING`. + +Image Builder sends this event on a best-effort basis. To confirm the state of an image, call **GetImage**. @@ -140 +145 @@ The `resources` array contains the ARN of the image resource that changed state. -If you have CVE detection enabled for your image, Image Builder sends a message with the results whenever an image scan completes. +Image Builder sends this event with the results after it collects the findings from a successful image scan, even if the scan finds no vulnerabilities. @@ -166 +171,3 @@ If you have CVE detection enabled for your image, Image Builder sends a message -Image Builder sends this event when an image scan completes, and only when you enable image scanning (Amazon Inspector) for the image. If scanning is off, Image Builder doesn't send this event. To turn on scanning, see [Configure security scans for Image Builder images in the AWS Management Console](./image-security-findings.html#image-config-security-scans). +If scanning is off, the AWS managed test workflows skip the `CollectImageScanFindings` step, so Image Builder doesn't send this event. To turn on scanning, see [Configure security scans for Image Builder images in the AWS Management Console](./image-security-findings.html#image-config-security-scans). + +Image Builder sends this event only from a `CollectImageScanFindings` workflow step, and sends it even when the scan returns no findings, so check `finding-severity-counts` before you act on it. Delivery is best effort, so a delivery failure doesn't fail the build. After the first `CollectImageScanFindings` step for an image finishes, whether it succeeds or fails, any later `CollectImageScanFindings` step for the image fails and doesn't send an event. @@ -172 +179 @@ Field | Description -`resource-id` | The ID of the Amazon EC2 test instance that Image Builder scanned. +`resource-id` | The ID of the resource that Amazon Inspector scanned: the ID of the Amazon EC2 test instance for an AMI build, or for a container build, the ARN of the copy of the Amazon ECR container that Image Builder pushes for scanning.