inspec 2.2.112 → 2.3.4

data/docs/resources/aws_ebs_volumes.md.erb

@@ -0,0 +1,86 @@
+---
+title: About the aws_ebs_volumes Resource
+platform: aws
+---
+
+# aws\_ebs\_volumes
+
+Use the `aws_ebs_volumes` InSpec audit resource to test properties of some or all AWS EBS volumes. To audit a single EBS volume, use `aws_ebs_volume` (singular).
+
+EBS volumes are persistent block storage volumes for use with Amazon EC2 instances in the AWS Cloud.
+
+Each EBS volume is uniquely identified by its ID.
+
+<br>
+
+## Availability
+
+### Installation
+
+This resource is distributed along with InSpec itself. You can use it automatically.
+
+## Syntax
+
+An `aws_ebs_volumes` resource block collects a group of EBS volumes and then tests that group.
+
+    # Ensure you have exactly 3 volumes
+    describe aws_ebs_volumes do
+      its('volume_ids.count') { should cmp 3 }
+    end
+
+    # Use the InSpec resource to enumerate IDs, then test in-depth using `aws_ebs_volume`.
+    aws_ebs_volumes.volume_ids.each do |volume_id|
+      describe aws_ebs_volume(volume_id) do
+        it { should exist }
+        it { should be_encrypted }
+        its('size') { should cmp 8 }
+        its('iops') { should cmp 100 }
+      end
+    end
+
+<br>
+
+## Examples
+
+As this is the initial release of `aws_ebs_volumes`, its limited functionality precludes examples.
+
+<br>
+
+## Filter Criteria
+
+This resource currently does not support any filter criteria; it will always fetch all volumes in the region.
+
+## Properties
+
+### entries
+
+Provides access to the raw results of the query, which can be treated as an array of hashes. This can be useful for checking counts and other advanced operations.
+
+    # Allow at most 100 EBS volumes on the account
+    describe aws_ebs_volumes do
+      its('entries.count') { should be <= 100 }
+    end
+
+### volume_ids
+
+Provides a list of the volume ids that were found in the query.
+
+    describe aws_ebs_volumes do
+      its('volume_ids') { should include 'vol-12345678' }
+      its('volume_ids.count') { should cmp 3 }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [Universal Matchers page](https://www.inspec.io/docs/reference/matchers/). 
+
+### exist
+
+The control will pass if the filter returns at least one result. Use `should_not` if you expect zero matches.
+
+    # Verify that at least one EBS volume exists
+    describe aws_ebs_volumes do
+      it { should exist }
+    end   

data/docs/style.md

@@ -0,0 +1,178 @@
+# InSpec profile style guide
+
+This is a set of recommended InSpec rules you should use when writing controls.
+
+## Control files
+
+### 1. All controls should be located in the "controls" directory and end in ".rb"
+
+Reason: Most syntax highlighters will render InSpec files correctly across a wide list of tools.
+
+Avoid: `controls/ssh_config`
+Use: `controls/ssh_config.rb`
+
+Avoid: `controls/ssh/config.rb`
+Use: `controls/ssh_config.rb`
+
+### 2. Avoid using "controls" or "control" in the name of your control files
+
+Reason: Using `controls` in the filename again duplicates it and creates unnecessary clutter when reading it. Keep the names short and concise.
+
+Avoid: `controls/ssh_controls.rb`
+Use: `controls/ssh.rb`
+
+
+## Code style
+
+### 3. Avoid unnecessary parentheses in matchers
+
+Adding additional parentheses is not required and provides more readability if it is not used:
+
+Avoid: `it { should eq(value) }`
+Use: `it { should eq value }`
+
+The exception are matchers that require additional arguments or named arguments.
+
+
+## Controls
+
+### 4. Do not wrap controls in conditional statements
+
+Reason: This will create dynamic profiles whose controls depend on the execution. The problem here is that we cannot render the profile or provide its information before scanning a system. We want to be able to inform users of the contents of their profiles before they run them. It is valid to skip controls that are not necessary for a system, as long as you do it via `only_if` conditions. Ruby's internal conditionals will hide parts of the profile to static analysis and should thus be avoided.
+
+Avoid:
+```ruby
+if package('..').installed?
+  control "package-test1" do
+    ..
+  end
+end
+```
+
+Use:
+```ruby
+control "package-test1" do
+  only_if { package('..').installed? }
+end
+```
+
+Avoid:
+```ruby
+case inspec.platform.name
+when /centos/
+  include_controls 'centos-profile'
+...
+```
+
+Use: The `supports` attribute in `inspec.yml` files of the profile you want to include:
+
+```ruby
+supports:
+- platform-name: centos
+```
+
+Now whenever you run the base profile you can just `include_controls 'centos-profile'`.
+It will only run the included profiles is the platform matches the supported platform.
+
+
+### 5. Do not include dynamic elements in the control IDs
+
+Reason: Control IDs are used to map test results to the tests and profiles. Dynamic control IDs make it impossible to map results back, since the identifier which connects tests and results may change in the process.
+
+Avoid:
+```ruby
+control "test-file-#{name}" do
+  ..
+end
+```
+
+Use:
+```ruby
+control "test-all-files" do
+  ..
+end
+```
+
+Sometimes you may create controls from a static list of elements. If this list stays the same no matter what system is scanned, it may be ok to do so and use it as a generator for static controls.
+
+
+### 6. Avoid Ruby system calls
+
+Reason: Ruby code is executed on the system that runs InSpec. This allows
+InSpec to work without Ruby and rubygems being required on remote
+targets (servers or containers). System calls are often used to interact with
+the local OS or remote endpoints from a local installation.
+InSpec tests, however, are designed to be universally executable on all
+types of runtimes, including local and remote execution. We want to give
+users the ability to take an OS profile and execute it remotely or locally.
+
+**Avoid shelling out**
+
+Avoid: `` `ls``\`
+Avoid: `system("ls")`
+Avoid: `IO.popen("ls")`
+Use: `command("ls")` or `powershell("..")`
+
+Ruby's command executors will only run localy. Imagine a test like this:
+
+```ruby
+describe `whoami` do
+  it { should eq "bob\n" }
+end
+```
+
+If you run this test on your local system and happen to be using Bob's account
+it will succeed. But if you were to run it against `--target alice@remote-host.com`
+it will still report that the user is bob instead of alice.
+
+Instead, do this:
+
+```ruby
+describe command('whoami') do
+  its('stdout') { should eq "bob\n" }
+end
+```
+
+If the profile is pointed to a remote endpoint using the `command` resource
+will run it on the remote OS.
+
+**Avoid Ruby IO on files**
+
+Avoid: `File.new("filename").read`
+Avoid: `File.read("filename")`
+Avoid: `IO.read("filename")`
+Use: `file("filename")`
+
+Similar to the command interactions these files will only be read localy
+with Ruby's internal calls. If you run this test against a remote target it won't
+read the file from the remote endpoint, but from the local OS instead.
+Use the `file` resource to read files on the target system.
+
+In general, try to avoid Ruby's IO calls from within InSpec controls and
+use InSpec resources instead.
+
+
+### 7. Avoid Ruby gem dependencies in controls
+
+In addition to avoiding system-level gems and modules you should also limit
+the use of external dependencies to resource packs or plugins. Gems need to be
+resolved, installed, vendored, and protected from conflicts. We aim to avoid
+exposing this complexity to users of InSpec, to make it a great tool even if
+you are not a developer.
+
+Developers may still use external gem dependencies but should vendor it
+with their plugins or resource packs.
+
+
+### 8. Avoid debugging calls (in production)
+
+Reason: One of the best way to develop and explore tests is the interactive debugging shell `pry` (see the section on "Interactive Debugging with Pry" at the end of this page). However, after you finish your profile make sure you have no interactive statements included anymore. Sometimes interactive calls are hidden behind conditionals (`if` statements) that are harder to reach. These calls can easily cause trouble when an automated profiles runs into an interactive `pry` call that stops the execution and waits for user input.
+
+Avoid: `binding.pry` in production profiles
+Use: Use debugging calls during development only
+
+Also you may find it helpful to use the inspec logging interface:
+
+```ruby
+Inspec::Log.info('Hi')
+```

data/examples/plugins/inspec-resource-lister/Gemfile

@@ -0,0 +1,12 @@
+# encoding: utf-8
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'bundler'
+  gem 'byebug'
+  gem 'minitest'
+  gem 'rake'
+  gem 'rubocop', '= 0.49.1' # Need to keep in sync with main InSpec project, so config files will work
+end

data/examples/plugins/inspec-resource-lister/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2018 Chef Software Inc.
+
+   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.

data/examples/plugins/inspec-resource-lister/README.md

@@ -0,0 +1,62 @@
+# InSpec Plugin Example - Resource Lister
+
+This plugin provides an example of building a plugin for use with [InSpec](https://inspec.io). Its functionality is simple, but useful: list resources included with InSpec.
+
+## To Install this as a User
+
+You will need InSpec v2.3 or later.
+
+If you want to just use this (not learn how to write a plugin), you can do so by simply running:
+
+```
+you@machine $ inspec plugin install inspec-resource-lister
+```
+
+You can then run:
+
+```
+you@machine $ inspec plugin help listresources
+# ... Usage info
+
+you@machine $ inspec plugin listresources core
+aide_conf
+apache
+apache_conf
+... snip ...
+yumrepo
+zfs_dataset
+zfs_pool
+------------------------------
+160 resources total
+```
+
+## Features of This Example Kit
+
+This example plugin is a full-fledged plugin example, with everything a real-world, industrial grade plugin would have, including:
+
+* an implementation of an InSpec CLI Command, using the InSpec PluginV2 API
+* documentation (you are reading it now)
+* tests, at the unit and functional level
+* a .gemspec, for packaging and publishing it as a gem
+* a Gemfile, for managing its dependencies
+* a Rakefile, for running development tasks
+* Rubocop linting support for using the base InSpec project rubocop.yml (See Rakefile)
+
+You are encouraged to use this plugin as a starting point for real plugins.
+
+## Development of a Plugin
+
+[Plugin Development](https://github.com/inspec/inspec/blob/master/docs/dev/plugins.md) is documented on the `inspec` project on GitHub.  Additionally, this example
+plugin has extensive comments explaining what is happening, and why.
+
+### A Tour of the Plugin
+
+One nice circuit of the plugin might be:
+ * look at the gemspec, to see what the plugin thinks it does
+ * look at the functional tests, to see the plugin proving it does what it says
+ * look at the unit tests, to see how the plugin claims it is internally structured
+ * look at the Rakefile, to see how to interact with the project
+ * look at lib/inspec-resource-lister.rb, the entry point which InSpec will always load if the plugin is installed
+ * look at lib/inspec-resource-lister/plugin.rb, the plugin definition which InSpec uses to understand what the plugin _can_ do.
+ * look at lib/inspec-resource-lister/cli_command.rb, the CLI Command implementation itself.
+

data/examples/plugins/inspec-resource-lister/Rakefile

@@ -0,0 +1,40 @@
+# A Rakefile defines tasks to help maintain your project.
+# Rake provides several task templates that are useful.
+
+#------------------------------------------------------------------#
+#                    Test Runner Tasks
+#------------------------------------------------------------------#
+
+# This task template will make a task named 'test', and run
+# the tests that it finds.
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList[
+    'test/unit/*_test.rb',
+    'test/functional/*_test.rb',
+  ]
+  t.verbose = true
+  # Ideally, we'd run tests with warnings enabled,
+  # but the dependent gems have many warnings. As this
+  # is an example, let's disable them so the testing
+  # experience is cleaner.
+  t.warning = false
+end
+
+#------------------------------------------------------------------#
+#                    Code Style Tasks
+#------------------------------------------------------------------#
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:lint) do |t|
+  # Choices of rubocop rules to enforce are deeply personal.
+  # Here, we set things up so that your plugin will use the Bundler-installed
+  # inspec gem's copy of the InSpec project's rubocop.yml file (which
+  # is indeed packaged with the inspec gem).
+  require 'inspec/globals'
+  inspec_rubocop_yml = File.join(Inspec.src_root, '.rubocop.yml')
+
+  t.options = ['--display-cop-names', '--config', inspec_rubocop_yml]
+end

data/examples/plugins/inspec-resource-lister/inspec-resource-lister.gemspec

@@ -0,0 +1,45 @@
+# coding: utf-8
+
+# As plugins are usually packaged and distributed as a RubyGem,
+# we have to provide a .gemspec file, which controls the gembuild
+# and publish process.  This is a fairly generic gemspec.
+
+# It is traditional in a gemspec to dynamically load the current version
+# from a file in the source tree.  The next three lines make that happen.
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'inspec-resource-lister/version'
+
+Gem::Specification.new do |spec|
+  # Importantly, all InSpec plugins must be prefixed with `inspec-` (most
+  # plugins) or `train-` (plugins which add new connectivity features).
+  spec.name          = 'inspec-resource-lister'
+
+  # It is polite to namespace your plugin under InspecPlugins::YourPluginInCamelCase
+  spec.version       = InspecPlugins::ResourceLister::VERSION
+  spec.authors       = ['Clinton Wolfe']
+  spec.email         = ['cwolfe@chef.io']
+  spec.summary       = 'InSpec Plugin example, lists available resources'
+  spec.description   = 'Example for implementing an InSpec Plugin.  This simply lists available resources.'
+  spec.homepage      = 'https://github.com/inspec/inspec/tree/master/examples/plugin'
+  spec.license       = 'Apache-2.0'
+
+  # Though complicated-looking, this is pretty standard for a gemspec.
+  # It just filters what will actually be packaged in the gem (leaving
+  # out tests, etc)
+  spec.files = %w{
+    README.md inspec-resource-lister.gemspec Gemfile
+  } + Dir.glob(
+    'lib/**/*', File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ['lib']
+
+  # If you rely on any other gems, list them here with any constraints.
+  # This is how `inspec plugin install` is able to manage your dependencies.
+  # For example, perhaps you are writing a thing that talks to AWS, and you
+  # want to ensure you have `aws-sdk` in a certain version.
+
+  # All plugins should mention inspec, > 2.2.78
+  # 2.2.78 included the v2 Plugin API
+  spec.add_dependency 'inspec', '>=2.2.78', '<4.0.0'
+end

data/examples/plugins/inspec-resource-lister/lib/inspec-resource-lister.rb

@@ -0,0 +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-resource-lister/plugin'