AWS Management Tools Blog

Using AWS Systems Manager to run compliance scans using InSpec by Chef

As described in the Security Pillar of the AWS Well-Architected Framework, the careful management of the security configurations of the running systems within your environment forms the foundation of how you will maintain robust, secure, scalable systems.

InSpec by Chef, an open-source testing framework, provides teams the ability to define and assess system state and status across the entire application lifecycle. InSpec can already be used with AWS OpsWorks for Chef Automate to track the compliance of your infrastructure based on predefined policies. For example, you can describe compliance controls in InSpec and integrate these tests into any stage of your deployment pipeline or choose from a set of pre-packaged InSpec profiles. You can then use the Compliance pane as a unified dashboard to identify issues, remediate them, and track progress for various nodes and profiles.

“According to the Chef User Survey 2017, 55% of organizations do compliance assessments incompletely or not at all,” says James Casey, Vice President of Partner Engineering and Integration at Chef. “Amazon Web Services and Chef help customers identify and automate compliance by using InSpec, part of Chef’s integration with AWS OpsWorks for Chef Automate. Now, customers have more options to use InSpec’s framework with the addition of InSpec availability through AWS Systems Manager.”

In this blog post, I’ll focus on three features of AWS Systems Manager that can be used with InSpec:

  • Run Command—Provides a simple way of running an ad hoc scan of your infrastructure using InSpec.
  • State Manager—Allows you to execute InSpec tests on a schedule so that you can continuously assess the compliance of your systems.
  • Configuration Compliance –Collects and aggregates information about InSpec test results.

I’ll use the newly defined Systems Manager Document AWS-RunInSpecChecks to run InSpec profiles that check the configuration of both Windows and Linux servers against a security baseline.

Here’s an outline of the steps:

  1. Launch Systems Manager Managed Instances.
  2. Ensure you have an InSpec Profile. In this blog you will use predefined profiles from the DevSec Hardening Framework project on GitHub to check both Linux and Windows servers against a security baseline.
  3. Execute the InSpec tests using Run Command or State Manager. You don’t need InSpec installed your servers because the scripts will do that for you.
  4. View the results of your tests in Compliance.


Launch Managed Instances

You need at least one managed instance that can act as a target of InSpec test execution. You can skip this step if you already have one or more Systems Manager managed instances in your AWS Account.

Otherwise, you can launch an AWS CloudFormation stack that launches two Amazon EC2 instances, one Windows Server 2012 R2 Base and one Amazon Linux, to act as test managed instances. The stack also creates an IAM Role and Instance Profile with the AmazonEC2RoleforSSM managed policy.

The following link launches the stack in the us-east-1 (N. Virginia) Region:

The CloudFormation template requires the following parameters:

  • KeyPair: Choose an Amazon EC2 key pair from the list. Ensure that you have the private key corresponding to the key pair.
  • Subnet: Choose a subnet where the instances will be launched. Ensure that the subnet has outbound access to Internet addresses and to the Systems Manager API endpoints via an Internet Gateway, a NAT Gateway or a VPC Endpoint for Systems Manager.
  • VpcId: Choose the VPC for the subnet you chose in Subnet.

The CloudFormation stack provides the following outputs:

  • LinuxServer: The EC2 instance ID of the Linux server.
  • WindowsServer: The EC2 instance ID of the Windows server.

Create a Parameter to store your GitHub token

You need a GitHub personal token to download InSpec profiles from GitHub. Follow the steps in Join GitHub to create a GitHub account if you don’t already have one, create a token and save the token in a secure location.

You can use Parameter Store to store your GitHub personal access token using the AWS CLI:

aws ssm put-parameter --name 'github-personal-token' --description 'GitHub Personal Token' --type SecureString --value '<value>'

Or you can perform these steps using the Systems Manager console:

  1. In the AWS Management Console, navigate to the Systems Manager console. Choose Parameter Store from the left navigation pane. Then choose Create Parameter.
  2. For Name, type github-personal-token.
  3. For Description, type GitHub Personal Token.
  4. For Type, choose SecureString and accept the default KMS Key ID alias/aws/ssm.
  5. For Value, copy and paste the value of the GitHub personal token you saved earlier.
  6. Choose Create parameter to create the parameter.

Execute InSpec tests on Windows Servers

In this step, you’ll execute an InSpec Profile against a Windows server. An InSpec Profile organizes multiple controls to support dependency management and code reuse. Each profile is a standalone structure with its own distribution and execution flow.

  1. Log into the Systems Manager console and choose Run Command from the left navigation pane.
  2. Choose Run Command.
  3. In the search bar, choose to search by Document name prefix. Choose Equal as the condition and type AWS-Run as the prefix. From the list of Command documents, choose the document named AWS-RunInSpecChecks.
  4. Choose the Targets (either instances or tags). You can narrow the list to Windows servers in the search bar by choosing the filter Platform and choosing Windows.
  5. In the Command parameters section, choose Github as the Source Type. Type the following into the text area for Source Info to execute an InSpec profile that checks Windows servers against a security baseline defined by the DevSec Hardening Framework project on GitHub.
    "path": "",
    "getOptions" : "branch:master",

  6. Accept the default values for the remaining parameters and choose Run.
  7. Refresh the Command status page until the status for the instances shown in the Targets and outputs list changes from In Progress to Success.
  8. Choose an instance ID from the list to see the output of the command run. Expand the steps shown on the Output page to view the command output.
  9. Verify that the output of the runInSpecWindows step shows that the execution was successful and has a line showing the number of tests executed and the number that were compliant and non-compliant. Note that the scripts install the Chef Development Kit (chefdk), execute InSpec tests, and then uninstall chefdk. For example:
    Installing Chef Development Kit
    Installing chefdk from C:\Windows\TEMP\chefdk-2.4.22-1-x64.msi
    Executing InSpec tests
    Completed InSpec checks and put 27 compliant (27 critical, 0 high, 0 low) and 47 non-compliant (39 critical, 0 high, 8 low) items
    Uninstalling Chef Development Kit

View Compliance items

In this step, you’ll view the results of the tests in Systems Manager Compliance.

  1. Log into the Systems Manager console and choose Explore Built-in insights.
  2. Choose Compliance from the navigation pane on the left.
  3. A summary of compliance items is shown as a chart, and the list of managed instances is displayed.
  4. Choose a Managed Instance to view a list of compliance items of type Custom:InSpec that were created as a result of the InSpec tests executed. You can see that each item has a descriptive title, the compliance status: whether it is compliant (the test passed) or non-compliant (the test failed), and severity.

Execute InSpec tests on Linux servers

To execute InSpec tests on Linux servers, follow the steps in the previous section, but choose one or more Linux servers in Step 4. In Step 6, type the following for Source Info to execute an InSpec profile that checks Linux servers against the SSH baseline defined by the DevSec Hardening Framework project.

"path": "",
"getOptions" : "branch:master",

You can also choose to execute a sample cross-platform InSpec profile that checks for open SSH and RDP ports. Type the following for Source Info and chose a combination of Linux and Windows servers.

 "owner": "awslabs",
 "repository": "amazon-ssm",
 "path": "Compliance/InSpec/PortCheck",
 "getOptions": "branch:master",
 "tokenInfo": "{{ssm-secure:github-personal-token}}"


In this blog post, I have shown how Systems Manager now lets you run compliance scans using InSpec by Chef. The walk-throughs used Run Command to execute individual tests. You can also create State Manager Associations to execute these tests on a schedule so that you can continuously assess the compliance of your systems.

Visit the AWS Systems Manager landing page to learn more and get started.

Cleaning up

If you launched instances using the CloudFormation template described earlier, you can delete those resources to avoid being charged for them going forward.

  1. In the CloudFormation console, choose the stack named SSM-InSpec, and from Actions, choose Delete Stack.
  2. Refresh the Events tab of the stack until the stack disappears from the stack list.

About the Author


Maitreya Ranganath is a Solutions Architect with the Enterprise team. He has a focus in Security and Compliance and enjoys helping customers architect secure, scalable, and cost-effective solutions on AWS.