View a markdown version of this page

Amazon Inspector integration in Image Builder - EC2 Image Builder
Scan output AMIs with on-demand AMI scans
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Inspector integration in Image Builder

Image Builder integrates with Amazon Inspector to scan the images that you build for software vulnerabilities. Amazon Inspector is a paid service.

Image Builder supports the following scan types. An AMI image or AMI pipeline uses one scan type, and you can't combine the two AMI scan types.

  • Test instance scan (TEST_INSTANCE_CVE) – For AMI images. Amazon Inspector scans the test instance that Image Builder launches during the test stage, and Image Builder saves a copy of the findings with your image. You can view the findings on the Security findings pages of the Image Builder console, or with the ListImageScanFindings API action. This scan type requires that Amazon Inspector is activated for your account. It's the default scan type for AMI images.

  • On-demand AMI scan (ON_DEMAND_AMI_CVE) – For AMI images. Amazon Inspector scans the output AMI that the build creates. This scan type doesn't require Amazon Inspector activation. You can set a scan result condition that fails the image if the AMI has findings that are more severe than you allow. You can view the results for the AMI on the Amazon EC2 console. For more information, see Scan output AMIs with on-demand AMI scans.

  • Container image scan – For container images. Amazon Inspector scans a copy of your container image that Image Builder pushes to Amazon ECR, and Image Builder saves a copy of the findings with your image. The findings appear in the same places as test instance scan findings. This scan type requires that Amazon Inspector is activated for Amazon ECR in your account.

When Amazon Inspector discovers vulnerabilities in your software, it takes the following actions:

  • Sends an event to Amazon EventBridge for each finding.

  • Rates the severity of the finding. The severity rating categorizes vulnerabilities to help you prioritize your findings, and includes the following values:

    • Untriaged

    • Informational

    • Low

    • Medium

    • High

    • Critical

  • Provides information about the finding, and links to additional resources for more detail.

  • Offers remediation guidance to help you resolve the issues that generated the finding.

Configure security scans

For test instance scans and container image scans, Image Builder saves a copy of the findings with your image so that you can investigate and remediate them after the build. Amazon Inspector scans either the test instance or the copy of your container image that Image Builder pushes to Amazon ECR. Image Builder terminates the test instance after the test stage. For on-demand AMI scans, Amazon Inspector scans the output AMI, and Image Builder doesn't save a copy of the findings.

To choose the scan type for your pipeline in the console, see Configure security scans for Image Builder images in the Amazon Web Services Management Console.

Amazon Inspector activation required for test instance and container image scans

Test instance scans and container image scans require that Amazon Inspector is activated for your account in the Amazon Region where you build your image: for Amazon EC2 (ec2) resources for test instance scans of AMI images, or for Amazon ECR (ecr) resources for container images. When a CreateImage, CreateImagePipeline, or UpdateImagePipeline request enables one of these scans, Image Builder checks the activation before it accepts the request. The request fails with ResourceDependencyException if Amazon Inspector isn't activated for the required resource type, or with UnsupportedOperationException if Amazon Inspector isn't available in the Region. For more information, see Getting started tutorial: Activating Amazon Inspector in the Amazon Inspector User Guide.

Because Image Builder doesn't repeat the check when it runs an existing pipeline, later builds save no security findings if you deactivate Amazon Inspector for your account after you create a pipeline that has scanning enabled. For the scan status that Image Builder reports in this case, see Image scan status and failure reasons.

On-demand AMI scans don't require Amazon Inspector activation, and Image Builder doesn't check the activation for them.

Choose the scanning configuration for your recipe type

The ecrConfiguration field applies only to container images. For AMI images, set imageScanningEnabled to true and omit ecrConfiguration. To choose the scan type for an AMI image, set imageScanningTypes. For all scanning fields and the error that Image Builder returns if you specify ecrConfiguration for an AMI image, see Create custom images with Image Builder. For how Amazon Inspector scans Amazon EC2 instances, see Scanning Amazon EC2 instances with Amazon Inspector in the Amazon Inspector User Guide.

Prerequisites for container image scanning

For a container recipe, Image Builder checks the following before it accepts the request.

  • Amazon Inspector must be activated for Amazon ECR – For instructions, see Activating a scan type in the Amazon Inspector User Guide.

  • A repository that you name must already exist – If you set repositoryName, the Amazon ECR repository must already exist in the same account and Region, or the request fails with ResourceNotFoundException.

  • A repository that you name must not use MANUAL scan frequency – If the repository uses a MANUAL scan frequency, the request fails with ResourceDependencyException. Use scan on push or continuous scanning.

If you omit repositoryName, Image Builder uses the default repository image-builder-image-scanning-repository and creates it if it doesn't exist. To learn when Image Builder removes the image that it pushes, see Create custom images with Image Builder.

Review security findings

In the Image Builder console, you can view security findings for all of your Image Builder resources in one place. You can see all findings on the Security findings page in the Security Overview section, or you can group your findings by vulnerability, by image pipeline, or by image. The console defaults to display all security findings. The summary panel for the All security findings option shows the number of findings that you have for each severity level. For more information, see Manage security findings for Image Builder images in the Amazon Web Services Management Console.

These pages show findings from test instance scans and container image scans. They don't show the results of on-demand AMI scans. For where to find those results, see View on-demand AMI scan results.

To learn more about Amazon Inspector vulnerability findings, see Understanding Amazon Inspector findings in the Amazon Inspector User Guide.

Image Builder encrypts the findings snapshot for an image at rest with a KMS key that Image Builder owns.

Scan output AMIs with on-demand AMI scans

With an on-demand AMI scan, Amazon Inspector scans the output AMI that your build creates, instead of the test instance. You don't have to activate Amazon Inspector for your account. You can also set a scan result condition, so that the image fails if the AMI has findings that are more severe than you allow.

To request an on-demand AMI scan, set imageScanningEnabled to true and set imageScanningTypes to ON_DEMAND_AMI_CVE in the image scanning configuration. You can do this in CreateImage, CreateImagePipeline, and UpdateImagePipeline requests. For the fields, see Create custom images with Image Builder. To configure a pipeline in the console, see Configure security scans for Image Builder images in the Amazon Web Services Management Console. For a Amazon CLI example, see Create an AMI image pipeline from the Amazon CLI.

For more information about how Amazon Inspector scans machine images, see Running on-demand machine image scans with Amazon Inspector in the Amazon Inspector User Guide.

How on-demand AMI scans work

When you request ON_DEMAND_AMI_CVE, Image Builder adds the Amazon managed test-ami-scan workflow to the image, unless you already list it. Image Builder adds it when you create an image and on each pipeline run. The workflow starts an Amazon Inspector scan of the output AMI. For the workflow steps, parameters, and run order, see AMI scan managed workflow (test-ami-scan).

What happens after the scan starts depends on whether you set a scan result condition:

  • With a scan result condition – Image Builder waits for Amazon Inspector to finish the scan, and then checks the results against your condition. If the AMI has a finding that's more severe than the condition allows, the image fails.

  • Without a scan result condition – Image Builder starts the scan but doesn't wait for it. The build continues, and Image Builder can distribute the image. The scan results appear in Amazon EC2 later.

Pricing

Amazon Inspector charges for each successful on-demand scan. For more information, see Amazon Inspector pricing.

To troubleshoot an image that fails because of an on-demand AMI scan, see On-demand AMI scan fails the image.

Scan result conditions

Use a scan result condition to prevent Image Builder from distributing an AMI that doesn't meet your security criteria. The condition sets the highest finding severity that the output AMI can have. If the scan reports a finding with a higher severity, the image fails in the test stage, and Image Builder doesn't distribute the AMI. Specify the condition in the scanResultCondition field. You can use it only with ON_DEMAND_AMI_CVE. The condition has the following fields:

  • maximumSeverityLabel (string) – Required. The most severe finding that the image can have. Valid values are INFORMATIONAL, LOW, MEDIUM, and HIGH. If the AMI has a finding that's more severe, the image fails. A counted CRITICAL finding always fails the image.

  • fixAvailable (boolean) – Set to true to count only findings that have a fix available. Set to false to count every finding, including findings that have no fix available. The default is true.

View on-demand AMI scan results

Image Builder doesn't save on-demand AMI scan results with the image. To view the results, use the AMI ID from the output resources of the image, and do one of the following:

  • In the Amazon EC2 console, view the scan results for the AMI.

  • Call the Amazon EC2 GetImageFindings API action.

On-demand AMI scan results don't appear on the Security findings pages in the Image Builder console. The ListImageScanFindings and ListImageScanFindingAggregations API actions don't return them. Image Builder also doesn't set the scanState of the image, because scanState refers to test instance scans.

Amazon Inspector delivers on-demand scan findings through Amazon EventBridge, not in the Amazon Inspector console.

Permissions for on-demand AMI scans

On-demand AMI scans don't require an execution role. If you don't specify an execution role for the image (executionRole), Image Builder runs the test-ami-scan workflow with its service-linked role, AWSServiceRoleForImageBuilder. The service-linked role includes the permissions that the scan needs.

If you specify an execution role, Image Builder runs the workflow with that role. For example, you specify an execution role when you attach custom image workflows. The execution role must trust the Image Builder service principal and have the permissions for the scan. To grant the scan permissions, use one of the following options:

  • Amazon managed policy (recommended) – Attach the EC2ImageBuilderExecutionPolicy Amazon managed policy to the role. The policy includes the permissions for on-demand AMI scans. For more information, see EC2ImageBuilderExecutionPolicy policy.

  • Custom policy – Add the permissions in the following list to the role.

A custom execution role needs the following permissions for on-demand AMI scans:

  • inspector2:StartOnDemandScan, inspector2:GetOnDemandScanStatus, and inspector2:ListOnDemandScans, on the resource arn:aws:inspector2:*:*:*.

  • iam:CreateServiceLinkedRole on the resource arn:aws:iam::*:role/*, with the condition that iam:AWSServiceName is one of ami.inspector2.amazonaws.com, inspector2.amazonaws.com, or agentless.inspector2.amazonaws.com.

  • ec2:DescribeImages, which Image Builder uses to read the scan results when it checks a scan result condition.

The following example policy grants these permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "inspector2:StartOnDemandScan",
                "inspector2:GetOnDemandScanStatus",
                "inspector2:ListOnDemandScans"
            ],
            "Resource": "arn:aws:inspector2:*:*:*"
        },
        {
            "Effect": "Allow",
            "Action": "iam:CreateServiceLinkedRole",
            "Resource": "arn:aws:iam::*:role/*",
            "Condition": {
                "StringEquals": {
                    "iam:AWSServiceName": [
                        "agentless.inspector2.amazonaws.com",
                        "ami.inspector2.amazonaws.com",
                        "inspector2.amazonaws.com"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": "ec2:DescribeImages",
            "Resource": "*"
        }
    ]
}

This example covers only the permissions for the scan. The execution role also needs the permissions that Image Builder uses for the rest of the image build. For information about how to assign an execution role, see Specify the IAM service role that Image Builder uses to run workflow actions.

If your execution role doesn't have a required permission, the StartAmiScan workflow step fails with an access-denied error.

Requirements and limitations for on-demand AMI scans

On-demand AMI scans have the following requirements and limitations:

  • AMI image recipes only – The request must specify an imageRecipeArn. Image Builder rejects ON_DEMAND_AMI_CVE for a request that specifies a containerRecipeArn.

  • Scanning must be turned on – To use imageScanningTypes or scanResultCondition, you must set imageScanningEnabled to true.

  • Execution role permissions – If you specify an execution role, the role must have the permissions for the scan. If you don't specify one, Image Builder uses its service-linked role, which includes these permissions. For more information, see Permissions for on-demand AMI scans.

  • One scan type – imageScanningTypes takes exactly one value. You can't combine TEST_INSTANCE_CVE and ON_DEMAND_AMI_CVE.

  • Image tests must be turned on – If you set imageTestsEnabled to false, the request fails with an InvalidParameterCombinationException.

  • The scan targets the parent AMI if you skip the build – If you specify workflows without a build workflow, Image Builder doesn't create a new AMI, and the scan targets the parent AMI of the recipe. Amazon Inspector scans only AMIs that your account owns, so your account must own the parent AMI.

  • The scan workflow must stop on failure when you set a condition – If you list the test-ami-scan workflow with onFailure set to CONTINUE and also set a scanResultCondition, Image Builder rejects the request.

  • Supported operating systems – Amazon Inspector must support the operating system of the AMI. For supported operating systems, see Running on-demand machine image scans with Amazon Inspector in the Amazon Inspector User Guide.

  • Console restrictions – In the Image Builder console, you can't skip the test stage while On-demand AMI scan is selected. You also can't skip the build stage when your account doesn't own the parent image of the recipe, because Amazon Inspector can't scan it. For example, your account doesn't own an Amazon Web Services Marketplace image or an Amazon managed image.