inspec-iggy 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3dc2db85eac33aa51e03baf7f0df30858a7f1815
-  data.tar.gz: e44f8c04a3998030335b6a2dcf2ff225c7b18d4f
+  metadata.gz: 77411a21b6c3a1f74cdc23ab20f48d96af93a985
+  data.tar.gz: 0b32db4421f119d92343a7cd834e2953989ee3b7
 SHA512:
-  metadata.gz: 9c8086684b141e0590b9a55f1b135922a4c9f4f7df3c3c32ec6422c890c7fe24a61443b16eac2e35bedb02f3a031a7efc7586a81d378addcd4c0d52d5d6de037
-  data.tar.gz: cda93559f8d2c47aaa4447d51d6f2151a006e3249e1297f379d041402c0f168f209acfda6003e42e30859ad901063e1aa0c5973127306ef7fdfec29ef7c058de
+  metadata.gz: eac8bdf420cb4951742c5e66038bfda33c7776d7c75b78fab08f8cff81c18883c956670991ea62a8c4822a290bb24981db267b93ca68a5aa0487db57ee0462ce
+  data.tar.gz: b01d470916ca825f4a30cc3376a3979815160efd76fe2ee6d1ecae8b98d6881b937b6fa139a050719b6b38dcd9c056e725a6984b4e389ad862be2d16af179279

data/Gemfile

@@ -1,15 +1,17 @@
 # encoding: utf-8
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 gemspec
 
 group :test do
-  gem "bundler"
-  gem "rake"
-  gem "chefstyle"
+  gem 'rake'              # Build task manager
+  gem 'chefstyle'
+  gem 'byebug'            # A debugger REPL
+  gem 'rubocop'           # Needed for style linting
+  gem 'm'
 end
 
 group :tools do
-  gem "github_changelog_generator"
-  gem "rb-readline"
+  gem 'github_changelog_generator'
+  gem 'rb-readline'
 end

data/README.md

@@ -1,53 +1,61 @@
 # Description #
 
-InSpec-Iggy (InSpec Generate -> "IG" -> "Iggy") is an [InSpec](https://inspec.io) plugin for generating compliance controls and profiles from [Terraform](https://terraform.io) ```tfstate``` files. Iggy generates InSpec AWS controls by mapping Terraform resources to InSpec resources. You may also use tags to annotate your Terraform scripts to specify which compliance profiles to be used and Iggy will create a profile including those dependencies.
+[![Build Status Master](https://travis-ci.org/inspec/inspec-iggy.svg?branch=master)](https://travis-ci.org/inspec/inspec-iggy)
 
-Iggy was originally a stand-alone CLI inspired by Christoph Hartmann's [inspec-verify-provision](https://github.com/chris-rock/inspec-verify-provision) and the blog post on testing [Terraform with InSpec](http://lollyrock.com/articles/inspec-terraform/).
+InSpec-Iggy (InSpec Generate -> "IG" -> "Iggy") is an [InSpec](https://inspec.io) plugin for generating compliance controls and profiles from [Terraform](https://terraform.io) `tfstate` files and [AWS CloudFormation](https://aws.amazon.com/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](https://automate.chef.io/).
 
-The [CHANGELOG.md](https://github.com/mattray/iggy/blob/master/CHANGELOG.md) covers current, previous and future development milestones and contains the features backlog.
+    inspec terraform generate -n myprofile
+    inspec exec myprofile -t aws://us-west-2
+    inspec compliance upload myprofile
 
-# Requirements #
+Iggy was originally a stand-alone CLI inspired by Christoph Hartmann's [inspec-verify-provision](https://github.com/chris-rock/inspec-verify-provision) and the blog post on testing [InSpec for provisioning testing: Verify Terraform setups with InSpec](http://lollyrock.com/articles/inspec-terraform/).
 
-Iggy generates compliance profiles for InSpec 2, 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.
+The [CHANGELOG.md](https://github.com/inspec/iggy/blob/master/CHANGELOG.md) covers current, previous and future development milestones and contains the features backlog.
 
-Written and tested with Ruby 2.4.4 (or whatever InSpec 2.0 supports).
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [InSpec Terraform Generate](#itg)
+4. [InSpec Terraform Extract](#ite)
+5. [InSpec Cloudformation Generate](#icg)
+6. [Testing](#testing)
 
-# Installation #
+# Requirements <a name="requirements"></a>
 
-`inspec-iggy` is a plugin for InSpec and may be installed as follows
+Iggy generates compliance profiles for InSpec 2.3 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.
 
-```bash
-# install InSpec
-gem install inspec
-gem install inspec-iggy
-inspec terraform version
-```
+Written and tested with Ruby 2.5.1.
+
+# Installation <a name="installation"></a>
 
-## * for development: ##
+`inspec-iggy` is a plugin for InSpec.  InSpec 2.3 or later is required.  To install, use:
 
-```bash
-# 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 version
+```
+$ inspec plugin install inspec-iggy
 ```
 
-## * or build a gem: ##
+# InSpec Terraform Generate<a name="itg"></a>
 
-```bash
-# 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 version
-```
+     inspec terraform generate --tfstate terraform.tfstate --name myprofile
 
-# InSpec Terraform Generate #
+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 generate --tfstate terraform.tfstate
+## Usage
 
-Iggy dynamically pulls the available AWS resources from InSpec and attempts to map them to the Terraform resources. Newer versions of InSpec may provide additional coverage.
+    inspec terraform generate [options] -n, --name=NAME
 
-# InSpec Terraform Extract (EXPERIMENTAL)#
+     -n, --name=NAME                  Name of profile to be generated (required)
+     -t, [--tfstate=TFSTATE]          Specify path to the input terraform.tfstate (default: .)
+     [--debug], [--no-debug]          Verbose debugging messages
+     [--copyright=COPYRIGHT]          Name of the copyright holder (default: The Authors)
+     [--email=EMAIL]                  Email address of the author (default: you@example.com)
+     [--license=LICENSE]              License for the profile (default: Apache-2.0)
+     [--maintainer=MAINTAINER]        Name of the copyright holder (default: The Authors)
+     [--summary=SUMMARY]              One line summary for the profile (default: An InSpec Compliance Profile)
+     [--title=TITLE]                  Human-readable name for the profile (default: InSpec Profile)
+     [--version=VERSION]              Specify the profile version (default: 0.1.0)
+     [--overwrite], [--no-overwrite]  Overwrites existing profile directory
+
+# InSpec Terraform Extract (EXPERIMENTAL)<a name="ite"></a>
 
     inspec terraform extract --tfstate terraform.tfstate
 
@@ -78,27 +86,70 @@ Currently it only supports URL-based compliance profiles. InSpec supports other
 
 inspec exec https://github.com/dev-sec/linux-baseline -t ssh://clckwrk@52.33.203.34 -i ~/.ssh/mattray-apac
 
-# CloudFormation Support #
+# InSpec CloudFormation Generate<a name="icg"></a>
+
+    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.
+
+## Usage
+
+     inspec cloudformation generate [options] -n, --name=NAME -s, --stack=STACK -t, --template=TEMPLATE
+
+     -n, --name=NAME                  Name of profile to be generated (required)
+     -s, --stack=STACK                Specify stack name or unique stack ID associated with the CloudFormation template
+     -t, --template=TEMPLATE          Specify path to the input CloudFormation template
+     [--debug], [--no-debug]          Verbose debugging messages
+     [--copyright=COPYRIGHT]          Name of the copyright holder (default: The Authors)
+     [--email=EMAIL]                  Email address of the author (default: you@example.com)
+     [--license=LICENSE]              License for the profile (default: Apache-2.0)
+     [--maintainer=MAINTAINER]        Name of the copyright holder (default: The Authors)
+     [--summary=SUMMARY]              One line summary for the profile (default: An InSpec Compliance Profile)
+     [--title=TITLE]                  Human-readable name for the profile (default: InSpec Profile)
+     [--version=VERSION]              Specify the profile version (default: 0.1.0)
+     [--overwrite], [--no-overwrite]  Overwrites existing profile directory
+
+# Development
+
+## Installation
+
+To point `inspec` at a local copy of `inspec-iggy` for development, use:
+
+```
+$ inspec plugin install path/to/your/inspec-iggy/lib/inspec-iggy.rb
+```
+
+# Testing Iggy<a name="testing"></a>
 
-**CloudFormation support has been started, but it is incomplete while focusing on Terraform.** Here is an example of the current output, note that it's not tied to an actual deployed CloudFormation Stack, so that will need to be provided for the entry point of testing.
-https://gist.github.com/c4d6eda82dfb25502ef381cc631a1edd
 
-# Testing #
+Unit, Functional, and Integration tests are provided, though more are welcome. Iggy uses the Minitest library for testing, using the classic `def test...` syntax. Because Iggy loads InSpec into memory, and InSpec uses RSpec internally, Spec-style testing breaks.
 
-Iggy uses [RSpec](http://rspec.info/) for testing. You should run the following before committing.
+To run all tests, run
+
+```
+$ bundle exec rake test
+```
 
-    $ rspec
+Linting is also provided via Rubocop.
 
-For style
+To check for code style issues, run:
 
-    $ chefstyle .
+```
+$ bundle exec rake lint
+```
+
+You can auto-correct many issues:
+
+```
+$ bundle exec rubocop -a
+```
 
 # License and Author #
 
 |                |                                           |
 |:---------------|:------------------------------------------|
 | **Author**     | Matt Ray (<matt@chef.io>)                 |
-| **Copyright:** | Copyright (c) 2017 Chef Software Inc.     |
+| **Copyright:** | Copyright (c) 2017-2018 Chef Software Inc.|
 | **License:**   | Apache License, Version 2.0               |
 
 Licensed under the Apache License, Version 2.0 (the "License");

data/inspec-iggy.gemspec

@@ -1,26 +1,26 @@
 # coding: utf-8
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-require "inspec-iggy/version"
+require 'inspec-iggy/version'
 
 Gem::Specification.new do |spec|
-  spec.name        = "inspec-iggy"
-  spec.version     = Iggy::VERSION
-  spec.authors     = ["Matt Ray"]
-  spec.email       = ["matt@chef.io"]
-  spec.summary     = "InSpec plugin to generate InSpec compliance profiles from Terraform."
-  spec.description = "Generate InSpec compliance profiles from Terraform by tagging instances and mapping Terraform to InSpec."
-  spec.homepage    = "https://github.com/inspec/inspec-iggy"
-  spec.license     = "Apache-2.0"
+  spec.name        = 'inspec-iggy'
+  spec.version     = InspecPlugins::Iggy::VERSION
+  spec.authors     = ['Matt Ray']
+  spec.email       = ['matt@chef.io']
+  spec.summary     = 'InSpec plugin to generate InSpec compliance profiles from Terraform.'
+  spec.description = 'Generate InSpec compliance profiles from Terraform by tagging instances and mapping Terraform to InSpec.'
+  spec.homepage    = 'https://github.com/inspec/inspec-iggy'
+  spec.license     = 'Apache-2.0'
 
   spec.files = %w{
     README.md inspec-iggy.gemspec Gemfile
   } + Dir.glob(
-    "{bin,docs,examples,lib,tasks,test}/**/*", File::FNM_DOTMATCH
+    '{bin,docs,examples,lib,tasks}/**/*', File::FNM_DOTMATCH
   ).reject { |f| File.directory?(f) }
 
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "inspec", ">=2.0", "<3.0.0"
+  spec.add_dependency 'inspec', '>=2.3', '<4.0.0'
 end

data/lib/inspec-iggy.rb

@@ -1,7 +1,16 @@
 # encoding: utf-8
 
+# This file is known as the "entry point."
+# This is the file InSpec will try to load if it
+# thinks your plugin is installed.
+
+# The *only* thing this file should do is setup the
+# load path, then load the plugin definition file.
+
+# Next two lines simply add the path of the gem to the load path.
+# This is not needed when being loaded as a gem; but when doing
+# plugin development, you may need it.  Either way, it's harmless.
 libdir = File.dirname(__FILE__)
 $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 
-require "inspec-iggy/cli"
-require "inspec-iggy/version"
+require 'inspec-iggy/plugin'

data/lib/inspec-iggy/cloudformation/cli_command.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+#
+# Author:: Matt Ray (<matt@chef.io>)
+#
+# Copyright:: 2018, Chef Software, Inc <legal@chef.io>
+#
+
+require 'inspec/plugin/v2'
+
+require 'inspec-iggy/version'
+require 'inspec-iggy/profile'
+require 'inspec-iggy/cloudformation/parser'
+
+module InspecPlugins::Iggy
+  module CloudFormation
+    class CliCommand < Inspec.plugin(2, :cli_command)
+      subcommand_desc 'cloudformation SUBCOMMAND ...', 'Generate InSpec from CloudFormation'
+
+      # Thor.map(Hash) allows you to make aliases for commands.
+      map('-v' => 'version')         # Treat `inspec terraform -v`` as `inspec terraform version`
+      map('--version' => 'version')  # Treat `inspec terraform -version`` as `inspec terraform version`
+
+      desc 'version', 'Display version information', hide: true
+      def version
+        say("Iggy v#{InspecPlugins::Iggy::VERSION}")
+      end
+
+      option :debug,
+             desc: 'Verbose debugging messages',
+             type: :boolean,
+             default: false
+
+      option :copyright,
+             desc: 'Name of the copyright holder',
+             default: 'The Authors'
+
+      option :email,
+             desc: 'Email address of the author',
+             default: 'you@example.com'
+
+      option :license,
+             desc: 'License for the profile',
+             default: 'Apache-2.0'
+
+      option :maintainer,
+             desc: 'Name of the copyright holder',
+             default: 'The Authors'
+
+      option :summary,
+             desc: 'One line summary for the profile',
+             default: 'An InSpec Compliance Profile'
+
+      option :title,
+             desc: 'Human-readable name for the profile',
+             default: 'InSpec Profile'
+
+      option :version,
+             desc: 'Specify the profile version',
+             default: '0.1.0'
+
+      option :overwrite,
+             desc: 'Overwrites existing profile directory',
+             type: :boolean,
+             default: false
+
+      option :name,
+             aliases: '-n',
+             required: true,
+             desc: 'Name of profile to be generated'
+
+      option :stack,
+             aliases: '-s',
+             required: true,
+             desc: 'Specify stack name or unique stack ID associated with the CloudFormation template'
+
+      option :template,
+             aliases: '-t',
+             required: true,
+             desc: 'Specify path to the input CloudFormation template'
+
+      desc 'generate [options]', 'Generate InSpec compliance controls from CloudFormation template'
+      def generate
+        Inspec::Log.level = :debug if options[:debug]
+        # hash of generated controls
+        generated_controls = InspecPlugins::Iggy::CloudFormation::Parser.parse_generate(options[:template])
+        printable_controls = InspecPlugins::Iggy::InspecHelper.cfn_controls(options[:title], generated_controls, options[:stack])
+        InspecPlugins::Iggy::Profile.render_profile(self, options, options[:template], printable_controls)
+        exit 0
+      end
+    end
+  end
+end

data/lib/inspec-iggy/cloudformation/parser.rb

@@ -0,0 +1,106 @@
+#
+# Author:: Matt Ray (<matt@chef.io>)
+#
+# Copyright:: 2018, Chef Software, Inc <legal@chef.io>
+#
+
+require 'json'
+require 'inspec/objects/control'
+require 'inspec/objects/ruby_helper'
+require 'inspec/objects/describe'
+
+require 'inspec-iggy/inspec_helper'
+
+module InspecPlugins::Iggy::CloudFormation
+  class Parser
+    def self.parse_generate(file) # rubocop:disable all
+      Inspec::Log.debug "CloudFormation.parse_generate file = #{file}"
+      begin
+        unless File.file?(file)
+          STDERR.puts "ERROR: #{file} is an invalid file, please check your path."
+          exit(-1)
+        end
+        template = JSON.parse(File.read(file))
+      rescue JSON::ParserError => e
+        STDERR.puts e.message
+        STDERR.puts "ERROR: Parsing error in #{file}."
+        exit(-1)
+      end
+      absolutename = File.absolute_path(file)
+
+      # InSpec controls generated
+      generated_controls = []
+      # iterate over the resources
+      cfn_resources = template['Resources']
+      cfn_resources.keys.each do |cfn_res|
+        # split out the last ::, these are all AWS
+        cfn_resource = cfn_resources[cfn_res]['Type'].split('::').last
+        # split camelcase and join with underscores
+        cfn_res_type = 'aws_' + cfn_resource.split(/(?=[A-Z])/).join('_').downcase
+
+        # add translation layer
+        if InspecPlugins::Iggy::InspecHelper::TRANSLATED_RESOURCES.key?(cfn_res_type)
+          Inspec::Log.debug "CloudFormation.parse_generate cfn_res_type = #{cfn_res_type} #{InspecPlugins::Iggy::InspecHelper::TRANSLATED_RESOURCES[cfn_res_type]} TRANSLATED"
+          cfn_res_type = InspecPlugins::Iggy::InspecHelper::TRANSLATED_RESOURCES[cfn_res_type]
+        end
+
+        # does this match an InSpec resource?
+        if InspecPlugins::Iggy::InspecHelper::RESOURCES.include?(cfn_res_type)
+          Inspec::Log.debug "CloudFormation.parse_generate cfn_res_type = #{cfn_res_type} MATCH"
+
+          # insert new control based off the resource's ID
+          ctrl = Inspec::Control.new
+          ctrl.id = "#{cfn_res_type}::#{cfn_res}"
+          ctrl.title = "InSpec-Iggy #{cfn_res_type}::#{cfn_res}"
+          ctrl.descriptions['default'] = "#{cfn_res_type}::#{cfn_res} from the source file #{absolutename}\nGenerated by InSpec-Iggy v#{InspecPlugins::Iggy::VERSION}"
+          ctrl.impact = '1.0'
+
+          describe = Inspec::Describe.new
+          # describes the resource with the logical_resource_id as argument, replaced at inspec exec
+          describe.qualifier.push([cfn_res_type, "resources[#{cfn_res}]"])
+
+          # ensure the resource exists
+          describe.add_test(nil, 'exist', nil)
+
+          # EC2 instances should be running
+          describe.add_test(nil, 'be_running', nil) if cfn_res_type.eql?('aws_ec2_instance')
+
+          # if there's a match, see if there are matching InSpec properties
+          inspec_properties = InspecPlugins::Iggy::InspecHelper.resource_properties(cfn_res_type)
+          cfn_resources[cfn_res]['Properties'].keys.each do |attr|
+            # insert '_' on the CamelCase to get camel_case
+            attr_split = attr.split(/(?=[A-Z])/)
+            property = attr_split.join('_').downcase
+            if inspec_properties.member?(property)
+              Inspec::Log.debug "CloudFormation.parse_generate #{cfn_res_type} inspec_property = #{property} MATCH"
+              value = cfn_resources[cfn_res]['Properties'][attr]
+              if (value.is_a? Hash) || (value.is_a? Array)
+                #  these get replaced at inspec exec
+                if property.eql?('vpc_id') # rubocop:disable Metrics/BlockNesting
+                  vpc = cfn_resources[cfn_res]['Properties'][attr].values.first
+                  # https://github.com/inspec/inspec/issues/3173
+                  describe.add_test(property, 'eq', "resources[#{vpc}]") unless cfn_res_type.eql?('aws_route_table') # rubocop:disable Metrics/BlockNesting
+                  # AMI is a Ref into Parameters
+                elsif property.eql?('image_id') # rubocop:disable Metrics/BlockNesting
+                  amiref = cfn_resources[cfn_res]['Properties'][attr].values.first
+                  ami = template['Parameters'][amiref]['Default']
+                  describe.add_test(property, 'eq', ami)
+                end
+              else
+                describe.add_test(property, 'eq', value)
+              end
+            else
+              Inspec::Log.debug "CloudFormation.parse_generate #{cfn_res_type} inspec_property = #{property} SKIP"
+            end
+          end
+          ctrl.add_test(describe)
+          generated_controls.push(ctrl)
+        else
+          Inspec::Log.debug "CloudFormation.parse_generate cfn_res_type = #{cfn_res_type} SKIP"
+        end
+      end
+      Inspec::Log.debug "CloudFormation.parse_generate generated_controls = #{generated_controls}"
+      generated_controls
+    end
+  end
+end