AWS Security Blog

How to Simplify Security Assessment Setup Using Amazon EC2 Systems Manager and Amazon Inspector

August 15, 2021: This blog post is under construction. Please refer back to this post in a day or two for the most accurate and helpful information.

In a July 2016 AWS Blog post, I discussed how to integrate Amazon Inspector with third-party ticketing systems by using Amazon Simple Notification Service (SNS) and AWS Lambda.

This AWS Security Blog post continues in the same vein, describing how to use Amazon Inspector to automate various aspects of security management. In this post, I show you how to install the Amazon Inspector agent automatically through the Amazon EC2 Systems Manager when a new Amazon EC2 instance is launched. In a subsequent post, I will show you how to update EC2 instances automatically that run Linux when Amazon Inspector discovers a missing security patch.

An overview of EC2 Systems Manager and EC2 Simple Systems Manager (SSM)

Amazon EC2 Systems Manager is a set of services that makes it easy to manage your Windows or Linux hosts running on EC2 instances. EC2 Systems Manager does this through an agent called EC2 Simple Systems Manager (SSM), which is installed on your instances. With SSM on your EC2 instances, you can save yourself an SSH or RDP session to the instance to perform management tasks.

With EC2 Systems Manager, you can perform various tasks at scale through a simple API, CLI, or EC2 Run Command. The EC2 Run Command can execute a Unix shell script on Linux instances or a Windows PowerShell script on Windows instances. When you use EC2 Systems Manager to run a script on an EC2 instance, the output is piped to a text file in Amazon S3 for you automatically. Therefore, you can examine the output without visiting the system or inventing your own mechanism for capturing console output.

The solution

Step 1: Enable EC2 Systems Manager and install the EC2 SSM agent

Setting up EC2 Systems Manager is relatively straightforward, but you must set up EC2 Systems Manager at the time you launch the instance. This is because the SSM agent will use an instance role to communicate with the EC2 Systems Manager securely. When launched with the appropriately configured IAM role, the EC2 instance is provided with a set of credentials that allows the SSM agent to perform actions on behalf of the account owner. The policy on the IAM role determines the permissions associated with these credentials.

The easiest way I have found to do this is to create the role, and then each time you launch an instance, associate the role with the instance and provide the SSM agent installation script in the instance’s user data in the launch wizard or API. Here’s how:

  1. Create an instance role so that the on-instance SSM agent can communicate with EC2 Systems Manager. If you already need an instance role for some other purpose, use the IAM console to attach the AmazonEC2RoleforSSM managed policy to your existing role.
  2. When launching the instance with the EC2 launch wizard, associate the role you just created with the new instance.
  3. When launching the instance with the EC2 launch wizard, provide the appropriate script as user data for your operating system and architecture to install the SSM agent as the instance is launched. To see this process and scripts in full, see Installing the SSM Agent.

Note: You must change the scripts slightly when copying them from the instructions to the EC2 user data: the word region in the curl command must be replaced with the AWS region code (for example, us-east-1).

When your instance starts, the SSM agent is installed. Having the SSM agent on the instance is the key component to the automated installation of the Amazon Inspector agent on the instance.

Step 2: Automatically install the Amazon Inspector agent when new EC2 instances are launched

Let’s assume that you will install the SSM agent when you first launch your instances. With that assumption in mind, you have two methods for installing the Amazon Inspector agent.

Method 1: Install the Amazon Inspector agent with user data

Just as we did above with the SSM agent, we can use the user data feature of EC2 to execute the Amazon Inspector agent installation script during instance launch. This is useful if you have decided not to install the SSM agent, but it is more work than necessary if you are in the habit of deploying the SSM agent at the launch of an instance.

To install the Amazon Inspector agent with user data on Linux systems, simply add the following commands to the User data box in the instance launch wizard (as shown in the following screenshot). This script works without modification on any Linux distribution that Amazon Inspector supports.

#!/bin/bash
cd /tmp
curl -O https://d1wk0tztpsntt1.cloudfront.net/linux/latest/install
chmod +x /tmp/install
/tmp/install

Note: If you are adding these commands to existing user data, be sure that only the first line of user data is #!/bin/bash. You should not have multiple copies of this line.

Finish launching the EC2 instance and the Amazon Inspector agent is installed as the instance is starting for the first time. To read more about this process, see Working with AWS Agents on Linux-based Operating Systems.

Method 2: Install the Amazon Inspector agent whenever a new EC2 instance starts

In environments that launch new instances continually, installing the Amazon Inspector agent automatically when an instance starts prevents some additional work. As we discussed in the previous method, you need to modify your instance launch process to include the EC2 SSM agent. This means you need to configure your instances with an EC2 Systems Manager role, as well as run the EC2 SSM agent.

First, create an IAM role that gives your Lambda function the permissions it needs to deploy the Amazon Inspector agent. Then, create the Lambda job that uses the SSM RunShellScript to install the Amazon Inspector agent. Finally, set up Amazon CloudWatch Events to run the Lambda job whenever a new instance enters the Running state.

Here are the details of the three-step process:

Step 1 – Create an IAM role for the Lambda function to use to send commands to EC2 Systems Manager:

  1. Sign in to the AWS Management Console and navigate to the IAM console.
  2. Choose Roles in the navigation pane. Choose Create new role.
  3. Type a name for a role. You should (but are not required to) use a descriptive name such as Inspector-agent-autodeploy-Lambda. Remember the name you choose because you will need it in Step 2.
  4. Choose the AWS Lambda role type.
  5. Attach the policies AWSLambdaBasicExecutionRole and AmazonSSMFullAccess.
  6. Choose Create the role to finish.

Step 2 – Create the Lambda function that will run EC2 Systems Manager commands to install the Amazon Inspector agent:

  1. Sign in to the AWS Management Console in your chosen region and navigate to the Lambda console.
  2. Choose Create a Lambda function.
  3. Skip Select blueprint.
  4. On the Configure triggers page, choose Next. Type a Name and Description for the function. Choose Python 2.7 for Runtime.
  5. Download and save autodeploy.py. Unzip the file, and copy the entire contents of autodeploy.py.
  6. From the Code entry type drop-down list, choose Edit code inline, and replace all the existing text with the text that you just copied from autodeploy.py.
  7. From the Role drop-down list, choose Choose an existing role, and then from the Existing role drop-down list, choose the role that you created in Step 1.
  8. Choose Next and then Create function to finish creating the function.

Step 3 – Set up CloudWatch Events to trigger the function:

  1. In the AWS Management Console in the same region as you used in Step 2, navigate to the CloudWatch console and then choose Events in the navigation pane.
  2. Choose Create rule. From the Select event source drop-down list, choose Amazon EC2.
  3. Choose Specific state(s) and Running. This tells CloudWatch to generate an event when an instance enters the Running state.
  4. Under Targets, choose Add target and then Lambda function.
  5. Choose the function that you created in Step 2.
  6. Click Configure details. Type a name and description for the event, and choose Create rule.

Summary

You have completed the setup! Now, whenever an EC2 instance enters the Running state (either on initial creation or on reboot), CloudWatch Events triggers an event that invokes the Lambda function that you created. The Lambda function then uses EC2 System Manager to install the Amazon Inspector agent on the instance.

In a subsequent AWS Security Blog post, I will show you how to take your security assessment automation a step further by automatically performing remediations for Amazon Inspector findings by using EC2 System Manager and Lambda.

If you have comments about this blog post, submit them in the “Comments” section below. If you have implementation questions, start a new thread on the Amazon Inspector forum.

– Eric