Inspector is an AWS Service that allows us to perform security analysis on AWS resources like EC2 instances and identify potential security issues. It not only identifies the security issues with severity but also provides the needed recommendations to fix these issues. This helps keep the AWS Cloud resources secure and protect from security vulnerabilities.

This blog covers the steps involved in working with AWS inspector right from “configuring the pre-requisites” to “addressing the findings”. The steps involved are explained to work with the AWS console or through APIs. This blog can be used as a “Getting Started guide to AWS Inspector”

Terminology

How It Works

Inspector is an agent-based security assessment service that runs on AWS resources like EC2 instances. When an assessment is initiated on a target, these agents are notified of the same. The data related to network traffic, file system, process activity etc., are monitored and collected. The collected data are then consolidated and grouped under the rules within the assessment template. The vulnerabilities and security issues are then filtered to generate the findings for assessment run.

Each finding has the severity (Low, Medium, High, and Informational), description of the finding and recommendations to fix these issues.

The Steps

The diagram below explains the steps involved in configuring and using AWS Inspector

Prerequisites

Following the pre-requisites configuration to start with AWS inspector

Create a Role

In the getting started page, assign an IAM role for Inspector to allow access to other AWS services like EC2, SNS etc., By default, no role will be assigned. The following picture shows the Inspector prerequisites page

By clicking on the “Choose or create role” button, we can create or choose an IAM role and assign it to Inspector. The following picture shows the “Choose or create role” page.

Tag EC2 Instances

To include EC2 resources in an assessment run, we need to create a tag for each EC2 instance. These tags are key-value pairs, and each EC2 instance can have multiple tags. For example, if we have multiple EC2 instances, the tag name “Environment” can be used to differentiate which EC2 instances can be used for assessment run.

The following picture shows the tags for an EC2 instance

Install AWS Agent on EC2 Instances

In the target EC2 instance, we need to install the AWS agent. Commands/Steps involved in installing the AWS agent are available in the table below

Define Assessment Target

The assessment target is the EC2 instance to be inspected. In the “Define Assessment Target” window, provide a custom name for the “Assessment Target” and specify the “Tag” to be used for picking up the instances.

In this example, we are using the EC2 instances with the tag name “Environment” and whose value is “QA”. When multiple tags are specified, EC2 instances with any of these tags will be picked for assessment.

API Details

Action: CreateResourceGroup 

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_CreateResourceGroup.html 
POST { 
    "resourceGroupTags": [ 
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Sample Response:
{
    "resourceGroupArn": "arn:aws:inspector:us-west-2:123456789012:resourcegroup/0-AB6DMKnv"
}


Action: CreateAssessmentTarget

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_CreateAssessmentTarget.html
Request:
POST {
    "assessmentTargetName": "string",
    "resourceGroupArn": "string"
}

Sample response:
{
    "assessmentTargetArn": "string"
}

Action: DefineAssessmentTargets
API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_DescribeAssessmentTargets.html
POST {
    "assessmentTargetArn": "string"
}

Sample Response:
{
    "assessmentTargets": [
        {
            "arn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq",
            "createdAt": 1458074191.459,
            "name": "ExampleAssessmentTarget",
            "resourceGroupArn": "arn:aws:inspector:us-west-2:123456789012:resourcegroup/0-PyGXopAI",
            "updatedAt": 1458074191.459
        }
    ],
    "failedItems": {}
}

Define Assessment Template

The assessment template is where we specify the rules packages and duration of the assessment run. Multiple rules packages can be selected and there are currently four packages provided as part of Inspector. There is no option to import new packages, and these packages are defined and owned by AWS.

Duration specifies how long the assessment is expected to run. It's defaulted to an hour. There are five duration options available for us to select – 15 minutes, 1 hour (recommended), 8 hours, 12 hours, and 24 hours. With a longer duration, more findings can be expected.

SNS topic is an optional input that can added even after the template is created. By subscribing to an SNS topic, users can get notified when the assessment is completed

Note: Currently, there is no option to edit an assessment template, so please make to sure you verify the template before creating it.

Rules Packages

As mentioned, there are currently four rules packages. All these packages are defined and owned by AWS. Users do not have the option to include new rules packages

API Details

Action: ListRulesPackages

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_ListRulesPackages.html

POST {} 

Sample Response:
{
    "rulesPackageArns": [
        "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-9hgA516p",
        "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-H5hpSawc",
        "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-JJOtZiqQ",
        "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-vg5GGHSD"
    ]
}

Action: DescribeResourceGroups

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_DescribeResourceGroups.html

POST {
    "locale": "string",
    "rulesPackageArns": [ "string" ]
}

Sample response:
{
    "failedItems": {},
    "rulesPackages": [
        {
        "arn": "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-9hgA516p",
        "description": "The rules in this package help verify whether the EC2 instances in your application are exposed to Common Vulnerabilities and Exposures (CVEs). Attacks can exploit unpatched vulnerabilities to compromise the confidentiality, integrity, or availability of your service or data. The CVE system provides a reference for publicly known information security vulnerabilities and exposures. For more information, see
            [https://cve.mitre.org/](https://cve.mitre.org/). If a particular CVE appears in one of the produced Findings at the end of a completed
            Inspector assessment, you can search [https://cve.mitre.org/](https://cve.mitre.org/) using the CVE's ID (for example, \"CVE-2009-0021\")
            to find detailed information about this CVE, its severity, and how to mitigate it. ",
            "name": "Common Vulnerabilities and Exposures",
            "provider": "Amazon Web Services, Inc.",
            "version": "1.1"
        }
    ]
}

Action: CreateAssessmentTemplate

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_CreateAssessmentTemplate.html

POST {
    "assessmentTargetArn": "string",
    "assessmentTemplateName": "string",
    "durationInSeconds": number,
    "rulesPackageArns": [ "string" ],
    "userAttributesForFindings": [
        {
            "key": "string",
            "value": "string"
        }
    ]
}

Sample Response:
{
    "assessmentTemplateArn": "string"
}

Action: DescribeAssessmentTemplates

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_DescribeAssessmentTemplates.html

POST {
    "assessmentTemplateArns": [ "string" ]
}

Sample Response:
{
    "assessmentTemplates": [
        {
            "arn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw",
            "assessmentTargetArn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq",
            "createdAt": 1458074191.844,
            "durationInSeconds": 3600,
            "name": "ExampleAssessmentTemplate",
            "rulesPackageArns": [
                "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-X1KXtawP"
            ], 
            "userAttributesForFindings": []
        }
    ],
    "failedItems": {}
}

Run Assessment Templates

After the above are defined, navigate to the “Assessment Templates” page in the AWS console. Select the template and click “Run”. This will run the assessment template on the target for the duration specified. When the assessment run is complete, the number of findings at the template level will be available in the “Assessment Templates” page.

Assessment Runs

This page lists the history of assessment runs. In this page, we have options to view the:

• Assessment template used in the inspection.

• Assessment targets on which the inspection is done.

• Start and end time of the assessment.

• Status of the assessment run,

• Number of Findings.

API Details

Action: StartAssessmentRun

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_StartAssessmentRun.html

POST {
    "assessmentRunName": "string",
    "assessmentTemplateArn": "string"
}

Sample response:
{
    "assessmentRunArn": "arn:aws:inspector:us-west-2:123456789012:target/0-nvgVhaxX/template/0-it5r2S4T/run/0-jOoroxyY"
}

Action: DescribeAssessmentRuns

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_DescribeAssessmentRuns.html

POST {
    "assessmentRunArns": [ "string" ]
}

Sample Response:
{
    "assessmentRuns": [
        {
            "arn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE",
            "assessmentTemplateArn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw",
            "completedAt": 1458680301.4,
            "createdAt": 1458680170.035,
            "dataCollected": true,
            "durationInSeconds": 3600,
            "name": "Run 1 for ExampleAssessmentTemplate",
            "notifications": [],
            "rulesPackageArns": [
                "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-X1KXtawP"
            ],
            "startedAt": 1458680170.161,
            "state": "COMPLETED",
            "stateChangedAt": 1458680301.4,
            "stateChanges": [
                {
                    "state": "CREATED",
                    "stateChangedAt": 1458680170.035
                },
                {
                    "state": "START_DATA_COLLECTION_PENDING",
                    "stateChangedAt": 1458680170.065
                },
                {
                    "state": "START_DATA_COLLECTION_IN_PROGRESS",
                    "stateChangedAt": 1458680170.096
                },
                {
                    "state": "COLLECTING_DATA",
                    "stateChangedAt": 1458680170.161
                },
                {
                    "state": "STOP_DATA_COLLECTION_PENDING",
                    "stateChangedAt": 1458680239.883
                },
                {
                    "state": "DATA_COLLECTED",
                    "stateChangedAt": 1458680299.847
                },
                {
                    "state": "EVALUATING_RULES",
                    "stateChangedAt": 1458680300.099
                },
                {
                    "state": "COMPLETED",
                    "stateChangedAt": 1458680301.4
                }
            ],
            "userAttributesForFindings": []
        }
    ],
    "failedItems": {}
}

View Findings

There is a page in the AWS console for viewing the “Findings” of assessment runs. Each finding will have a rules package reference, description, and recommendations to fix the security issue.

Follow the recommendations to fix the issues and keep the system secured.

API Details

Action: ListFindings 

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_ListFindings.html

POST {
    "assessmentRunArns": [ "string" ],
    "filter": {
        "agentIds": [ "string" ],
        "attributes": [
            {
                "key": "string",
                "value": "string"
            }
        ],
        "autoScalingGroups": [ "string" ],
        "creationTimeRange": {
            "beginDate": number,
            "endDate": number
        },
        "ruleNames": [ "string" ],
        "rulesPackageArns": [ "string" ],
        "severities": [ "string" ],
        "userAttributes": [
            {
                "key": "string",
                "value": "string"
            }
        ]
    },
    "maxResults": number,
    "nextToken": "string"
}

Sample Response:
{
    "findingArns": [
        "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE/finding/0-HwPnsDm4",
        "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-v5D6fI3v/finding/0-tyvmqBLy"
    ]
}

Action: DescribeFindings

API Reference: http://docs.aws.amazon.com/inspector/latest/APIReference/API_DescribeFindings.html

POST {
    "findingArns": [ "string" ],
    "locale": "string"
}

Sample Response:
{
    "failedItems": {},
    "findings": [
        {
            "arn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE/finding/0-HwPnsDm4",
            "assetAttributes": {
                "ipv4Addresses": [],
                "schemaVersion": 1
            },
            "assetType": "ec2-instance",
            "attributes": [],
            "confidence": 10,
            "createdAt": 1458680301.37,
            "description": "Amazon Inspector did not find any potential security issues during this assessment.",
            "indicatorOfCompromise": false,
            "numericSeverity": 0,
            "recommendation": "No remediation needed.",
            "schemaVersion": 1,
            "service": "Inspector",
            "serviceAttributes": {
                "assessmentRunArn": "arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq/template/0-4r1V2mAw/run/0-MKkpXXPE",
                "rulesPackageArn": "arn:aws:inspector:us-west-2:758058086616:rulespackage/0-X1KXtawP",
                "schemaVersion": 1
            },
            "severity": "Informational",
            "title": "No potential security issues found",
            "updatedAt": 1458680301.37,
            "userAttributes": []
        }
    ]
}

Fix Security Issues

By following the recommendations in each Finding, you'll fix the security issues and vulnerabilities that Inspector pointed out. Note, however, that this is a manual activity. After fixing the issues, re-run the assessment template to confirm they don’t appear in the findings again.