README.md

Description

InSpec-Iggy (InSpec Generate -> "IG" -> "Iggy") is an InSpec plugin for generating compliance controls and profiles from Terraform tfstate files and AWS CloudFormation templates. Iggy generates InSpec controls by mapping Terraform and CloudFormation resources to InSpec resources and exports a profile that may be used from the inspec CLI or uploaded to Chef Automate.

inspec terraform generate -n myprofile
inspec exec myprofile -t aws://us-west-2
inspec compliance upload myprofile

Iggy was originally a stand-alone CLI inspired by Christoph Hartmann's inspec-verify-provision and the blog post on testing Terraform with InSpec.

The CHANGELOG.md covers current, previous and future development milestones and contains the features backlog.

1. Requirements
2. Installation
3. InSpec Terraform Generate
4. InSpec Terraform Extract
5. InSpec Cloudformation Generate
6. Testing

Requirements

Iggy generates compliance profiles for InSpec 2.2.64 and later, which includes the AWS and Azure resources. Because resources are continuing to be added to InSpec, you may want the latest version to support as many resource coverage as possible. It has currently been tested primarily with AWS but other InSpec-supported platforms should work as well.

Written and tested with Ruby 2.5.1.

Installation

inspec-iggy is a plugin for InSpec and may be installed as follows

* ChefDK 3.x/InSpec 2.2 Omnibus installer

Download your ChefDK or InSpec installer package from Chef Downloads.

Linux

# chef gem install inspec-iggy-0.3.0.gem
# mkdir /root/.inspec/plugins
# ln -s /root/.chefdk/gem/ruby/2.5.0/gems/inspec-iggy-0.3.0/ /root/.inspec/plugins/
# ls -l /root/.inspec/plugins/
total 0
lrwxrwxrwx. 1 root root 52 Sep 12 09:13 inspec-iggy-0.3.0 -> /root/.chefdk/gem/ruby/2.5.0/gems/inspec-iggy-0.3.0/
# inspec terraform help

Windows

# chef gem install inspec-iggy-0.3.0.gem
# mkdir /root/.inspec/plugins
# ln -s /root/.chefdk/gem/ruby/2.5.0/gems/inspec-iggy-0.3.0/ /root/.inspec/plugins/

* as a gem

# install InSpec
gem install inspec
gem install inspec-iggy
inspec terraform --help

* for development:

# Install `inspec-iggy` via a symlink:
git clone git@github.com:inspec/inspec-iggy ~/inspec-iggy
mkdir -p ~/.inspec/plugins
ln -s ~/inspec-iggy/ ~/.inspec/plugins/inspec-iggy
inspec terraform --help

* or build a gem:

# Build the `inspec-iggy` then install:
git clone https://github.com/inspec/inspec-iggy && cd inspec-iggy && gem build *gemspec && gem install *gem
inspec terraform --help

InSpec Terraform Generate

 inspec terraform generate --tfstate terraform.tfstate --name myprofile

Iggy dynamically pulls the available AWS resources from InSpec and attempts to map them to Terraform resources, producing an InSpec profile. inspec terraform generate --help will show all available options.

InSpec Terraform Extract (EXPERIMENTAL)

inspec terraform extract --tfstate terraform.tfstate

Tagging Profiles for Extract

Compliance profiles are added to the Terraform Resource to be tested. The current 2 options are the aws_vpc or the aws_instance. By tagging the aws_vpc you are specifying that the test is against the AWS API rather than individual machines. AWS instances tagged with compliance profiles will attempt to form command lines for inspec exec against them.

Tagging Format

Given there is not support for lists within AWS tags, we use the convention of starting our tag names with inspec_name_ and inspec_url_. These are extracted and split to identify the relevant compliance profiles to run.

tags {
    iggy_name_apache_baseline = "apache-baseline",
    iggy_url_apache_baseline = "https://github.com/dev-sec/apache-baseline",
    iggy_name_linux_baseline = "linux-baseline",
    iggy_url_linux_baseline = "https://github.com/dev-sec/linux-baseline"
}

Potential Enhancements

The current tagging for extraction implementation is directly tied to AWS. Other platforms such as Azure undoubtedly behave differently. Longterm this functionality should probably be turned into a Terraform Provider with predefined outputs.

Subnet might be a better choice for tagging than VPCs, given they list the AZ.

Currently it only supports URL-based compliance profiles. InSpec supports other formats (git, path, supermarket, compliance).

inspec exec https://github.com/dev-sec/linux-baseline -t ssh://clckwrk@52.33.203.34 -i ~/.ssh/mattray-apac

InSpec CloudFormation Generate

inspec cloudformation generate --template mytemplate.json --stack mystack-20180909T052147Z --profile myprofile

Iggy supports AWS CloudFormation templates by mapping the AWS resources to InSpec resources and using the stack name or unique stack ID associated with the CloudFormation template as an entry point to check those resources in the generated profile. inspec cloudformation generate --help will show all available options.

Testing

Iggy uses RSpec for testing. You should run the following before committing.

$ rspec

For style Iggy uses InSpec's .rubocop.yml

$ rubocop .

License and Author

Author	Matt Ray (matt@chef.io)
Copyright:	Copyright (c) 2017-2018 Chef Software Inc.
License:	Apache License, Version 2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.