AWS imagebuilder: Document Amazon Inspector image scanning in Image Builder
Summary
Expands create-image documentation with Amazon Inspector scanning configuration, ECR scan repository/tags, test-stage requirements, and PowerShell examples.
Security assessment
The change documents how to enable Amazon Inspector vulnerability scanning during Image Builder image builds and how scan findings/configuration are handled. This is security-related documentation, but it does not reference a specific vulnerability, CVE, or incident.
Evidence
+ * **Image scanning** – To scan your image with Amazon Inspector during the test stage of the build, use the `--image-scanning-configuration` parameter. By default, image scanning is off. When scanning is on, Image Builder waits for Amazon Inspector to scan the test instance, or pushes a copy of your container image to Amazon ECR for Amazon Inspector to scan. Image Builder then saves a snapshot of the findings with your image, so the findings remain available after the scanned resource no longer exists. If you specify a scanning configuration, the **get-image** response includes it, but image list responses don't. For an image that a pipeline builds, **get-image** returns the scanning configuration that the pipeline had when the build started. The **get-image-pipeline** and **list-image-pipelines** responses include the current scanning configuration of the pipeline. The `--image-scanning-configuration` parameter accepts the following fields:
Diff
diff --git a/imagebuilder/latest/userguide/create-images.md b/imagebuilder/latest/userguide/create-images.md index 1d5027c..f6e0bf4 100644 --- a//imagebuilder/latest/userguide/create-images.md +++ b//imagebuilder/latest/userguide/create-images.md @@ -7 +7 @@ -Cancel image creation from the AWS CLI +Cancel image creation @@ -13 +13 @@ There are several different ways that you can create a new Image Builder image. -AWS Management Console +Console @@ -34 +34 @@ AWS CLI -Before you run the **[create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html)** command in the AWS CLI, you must create the following resources if they don't already exist: +Before you run the [create-image](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/imagebuilder/create-image.html) command in the AWS CLI, you must create the following resources if they don't already exist: @@ -61 +61 @@ You can also specify any of the following resources that your image requires: - * **Image scanning** – To configure snapshots for Amazon Inspector findings on your image or container test instance, use the `--image-scanning-configuration` parameter. For container images you also specify the ECR repository that Amazon Inspector uses for its scans. + * **Image scanning** – To scan your image with Amazon Inspector during the test stage of the build, use the `--image-scanning-configuration` parameter. By default, image scanning is off. When scanning is on, Image Builder waits for Amazon Inspector to scan the test instance, or pushes a copy of your container image to Amazon ECR for Amazon Inspector to scan. Image Builder then saves a snapshot of the findings with your image, so the findings remain available after the scanned resource no longer exists. If you specify a scanning configuration, the **get-image** response includes it, but image list responses don't. For an image that a pipeline builds, **get-image** returns the scanning configuration that the pipeline had when the build started. The **get-image-pipeline** and **list-image-pipelines** responses include the current scanning configuration of the pipeline. The `--image-scanning-configuration` parameter accepts the following fields: @@ -63 +63,15 @@ You can also specify any of the following resources that your image requires: - * **Image tests** – To suppress the Image Builder test stage, use the `--image-tests-configuration` parameter. Alternatively, you can set a timeout for how long it can run. + * imageScanningEnabled (boolean) – Set to `true` to scan your image with Amazon Inspector during the test stage of the build. Set to `false`, or omit the field, to turn off scanning. + + * ecrConfiguration (object) – Applies only to requests that specify a `containerRecipeArn`. Sets the Amazon ECR repository and tags for the copy of the container image that Image Builder pushes for Amazon Inspector to scan. If you turn on scanning and specify `repositoryName` or `containerTags` in `ecrConfiguration` for a request that specifies an `imageRecipeArn`, the request fails with an `InvalidParameterCombinationException`. + + * repositoryName (string) – The name of an existing Amazon ECR repository for the scanned image, 1–1024 characters. For repository requirements, see [Amazon Inspector integration in Image Builder](./integ-inspector.html). If you omit it, Image Builder uses `image-builder-image-scanning-repository`, creates it if it doesn't exist, and removes the image after it collects the findings. The image stays in the repository if Image Builder doesn't finish collecting the findings, or if you name your own repository. + + * containerTags (list of strings) – Additional tags that Image Builder applies to the container image that it pushes for scanning. Image Builder also applies its own version tags to that image. Each tag must be from 1–1024 characters in length. + +###### Test stage requirements + +If you turn on scanning and set `imageTestsEnabled` to `false` in the `--image-tests-configuration` parameter, the request fails with an `InvalidParameterCombinationException`. This requirement applies to the **create-image** , **create-image-pipeline** , and **update-image-pipeline** commands. + +If you use the `--workflows` parameter, include exactly one `CollectImageScanFindings` step across the test workflows for an image. Image Builder doesn't check for this step, and without it Image Builder saves no findings. The AWS managed `express-test-image` workflow doesn't include this step. + + * **Image tests** – To suppress the Image Builder test stage, use the `--image-tests-configuration` parameter. You can't set `imageTestsEnabled` to `false` when you enable image scanning. @@ -97 +111,14 @@ The following example shows how to create an image with the [create-image](https -## Cancel image creation from the AWS CLI +PowerShell + + +The following example shows how to use the [New-EC2IBImage](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2IBImage.html) cmdlet to create an image. This example uses default distribution settings: + + + New-EC2IBImage ` + -ImageRecipeArn arn:aws:imagebuilder:us-west-2:123456789012:image-recipe/simple-recipe-linux/1.0.0 ` + -InfrastructureConfigurationArn arn:aws:imagebuilder:us-west-2:123456789012:infrastructure-configuration/simple-infra-config-linux + +## Cancel image creation + +AWS CLI + @@ -103,0 +131,8 @@ To cancel an in-progress image build, use the **cancel-image-creation** command, +PowerShell + + +The following example shows how to use the [Stop-EC2IBImageCreation](https://docs.aws.amazon.com/powershell/latest/reference/items/Stop-EC2IBImageCreation.html) cmdlet to cancel an in-progress image build: + + + Stop-EC2IBImageCreation -ImageBuildVersionArn arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/2019.12.03/1 +