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).

Configuring machine image scanning

Your scan configuration determines which of the machine images that your account owns are in scope. It has three parts, which Amazon Inspector applies in this order:

A machine image is in scope only if it satisfies all three parts. Amazon Inspector excludes a machine image if any exclusion condition applies.

You configure machine image scanning by using the UpdateConfiguration API operation, or from the machine image scanning settings under General settings in the Amazon Inspector console. To view your current configuration, use the GetConfiguration API operation. Amazon Inspector applies default values for every setting when you activate machine image scanning for an account. The default configuration is the following:

Setting scan eligibility windows

Scan eligibility windows determine how long Amazon Inspector continues to monitor a machine image. Amazon Inspector provides two independent windows:

A machine image is eligible if either window is satisfied. This means an older machine image stays in scope as long as you're still launching instances from it, and a newly created image is in scope even if you haven't launched an instance from it yet.

The following durations are available for each window:

When a machine image falls outside both windows, Amazon Inspector stops monitoring it and closes its findings. A deprecated image stays eligible for rescans as long as it satisfies either window. Amazon Inspector checks your images against the windows once a day. As a result, a change in scope can take up to 24 hours to take effect.

Excluding copied and backup machine images

You can exclude two categories of machine image from scanning. These exclusions apply in both scan modes. Amazon Inspector applies them before your scan mode tag filter. To exclude other individual images, add an exclusion tag to them and use exclusion (SCAN_ALL) mode. For more information, see Managing machine image scan mode.

Managing machine image scan mode

The scan mode determines which of your eligible machine images Amazon Inspector keeps in scope. It also sets whether the tag you configure adds images to that scope or removes them. Amazon Inspector scans continuously in both modes, and supports the following modes.

You choose the tag that Amazon Inspector matches on, so you can reuse a tag that's already part of your tagging strategy. Note the following about the tag:

For information about adding tags to a machine image, see Tag your Amazon EC2 resources in the Amazon Elastic Compute Cloud User Guide.

When you add or remove the configured tag on a machine image, Amazon Inspector re-evaluates that image. In exclusion (SCAN_ALL) mode, adding the tag removes the image from your scanning scope, and removing the tag brings it back in. In inclusion (TARGET_SCANNING) mode, adding the tag brings the image into scope, and removing the tag removes it. In both modes, the exclusion options still apply, so an image that you tag for inclusion stays out of scope if it's also a copied or backup image that you chose to exclude.

How Amazon Inspector applies a configuration change

When you change your scan configuration, Amazon Inspector re-evaluates every machine image in the account right away. Amazon Inspector then does the following:

Amazon Inspector processes one configuration change for an account at a time. If you call UpdateConfiguration while Amazon Inspector is still applying a previous change, Amazon Inspector returns a ValidationException. Retry the request after the previous change finishes. If you submit a configuration that matches your current configuration, Amazon Inspector treats the request as a no-op.

Separately from configuration changes, Amazon Inspector re-evaluates your machine images against your scan eligibility windows once a day. For more information, see Setting scan eligibility windows.

Configuring machine image scan settings

The following procedure describes how to configure machine image scanning. To complete this procedure for a multi-account environment, follow these steps while signed in as the Amazon Inspector delegated administrator.

Console

To configure machine image scanning

1. Sign in using your credentials, and then open the Amazon Inspector console at https://console.aws.amazon.com/inspector/v2/home.

2. Select the Amazon Web Services Region where you want to configure machine image scanning.

3. From the navigation pane, choose General settings, and then choose Machine image scanning settings.

4. Under Scan eligibility, choose a duration for Created within and a duration for Last launched within.

5. Under Scan mode, choose Exclusion mode or Inclusion mode, and then enter the tag key and optional tag value that Amazon Inspector matches on. A tag is required for Inclusion mode. (Optional) Select or clear Exclude copied machine images and Exclude backup machine images; both are selected by default.

6. Choose Save.

7. (Recommended) Repeat these steps in each Amazon Web Services Region where you activated machine image scanning.

API

Run the UpdateConfiguration API operation. In the request, provide an amiConfiguration object. Any field that you omit keeps its current value.

The following example continuously scans all eligible machine images except the ones tagged with InspectorExclude=true, and excludes copied machine images.

{
    "amiConfiguration": {
        "createdWithin": "180_DAYS",
        "lastLaunchedWithin": "90_DAYS",
        "scanModeConfiguration": {
            "scanMode": "SCAN_ALL",
            "tags": [
                {
                    "key": "InspectorExclude",
                    "value": "true"
                }
            ],
            "excludeCopiedAmis": true,
            "excludeBackupDlmAmis": false
        }
    }
}
                    

The following example continuously scans only the eligible machine images that have the InspectorScan tag key, regardless of the tag value, and excludes backup machine images.

{
    "amiConfiguration": {
        "scanModeConfiguration": {
            "scanMode": "TARGET_SCANNING",
            "tags": [
                {
                    "key": "InspectorScan"
                }
            ],
            "excludeCopiedAmis": false,
            "excludeBackupDlmAmis": true
        }
    }
}