inspec 1.31.0 → 1.45.9

data/Gemfile

@@ -37,7 +37,6 @@ group :tools do
   gem 'pry', '~> 0.10'
   gem 'rb-readline'
   gem 'license_finder'
-  gem "github_changelog_generator", git: "https://github.com/chef/github-changelog-generator"
 end
 
 # gems for Maintainers.md generation

data/README.md

@@ -339,11 +339,10 @@ The InSpec community and maintainers are very active and helpful. This project b
 
 ## Testing InSpec
 
-We perform `unit`, `resource` and `integration` tests.
+We perform `unit` and `integration` tests.
 
-* `unit` tests ensure the intended behaviour of the implementation
-* `resource` tests run against docker containers
-* `integration` tests run against VMs via test-kitchen and [kitchen-inspec](https://github.com/chef/kitchen-inspec)
+- `unit` tests ensure the intended behaviour of the implementation
+- `integration` tests run against Docker-based VMs via test-kitchen and [kitchen-inspec](https://github.com/chef/kitchen-inspec)
 
 ### Unit tests
 
@@ -351,60 +350,51 @@ We perform `unit`, `resource` and `integration` tests.
 bundle exec rake test
 ```
 
-If you like to run only one test, use
+If you like to run only one test file:
 
 ```bash
-bundle exec ruby -W -Ilib:test test/unit/resources/user_test.rb
+bundle exec m test/unit/resources/user_test.rb
 ```
 
-### Resource tests
-
-Resource tests make sure the backend execution layer behaves as expected. These tests will take a while, as a lot of different operating systems and configurations are being tested.
-
-You will require:
-
-* docker
-
-Run `resource` tests with
+You may also run a single test within a file by line number:
 
 ```bash
-bundle exec rake test:resources config=test/test.yaml
-bundle exec rake test:resources config=test/test-extra.yaml
+bundle exec m test/unit/resources/user_test.rb -l 123
 ```
 
 ### Integration tests
 
 These tests download various virtual machines, to ensure InSpec is working as expected across different operating systems.
 
-You will require:
+These tests require the following gems:
+
+- test-kitchen
+- kitchen-dokken
+- kitchen-inspec
 
-* vagrant with virtualbox
-* test-kitchen
+These gems are provided via the `integration` group in the project's Gemfile.
 
-**Run `integration` tests with vagrant:**
+In addition, these test require Docker to be available on your machine or a remote Docker machine configured via the standard Docker environment variables.
+
+#### Running Integration tests
+
+List the various test instances available:
 
 ```bash
-KITCHEN_YAML=.kitchen.vagrant.yml bundle exec kitchen test
+bundle exec kitchen list`
 ```
 
-**Run `integration` tests with AWS EC2:**
+The platforms and test suites are configured in the `.kitchen.yml` file. Once you know which instance you wish to test, test that instance:
 
 ```bash
-export AWS_ACCESS_KEY_ID=enteryouryourkey
-export AWS_SECRET_ACCESS_KEY=enteryoursecreykey
-export AWS_KEYPAIR_NAME=enteryoursshkeyid
-export EC2_SSH_KEY_PATH=~/.ssh/id_aws.pem
-KITCHEN_YAML=.kitchen.ec2.yml bundle exec kitchen test
+bundle exec kitchen test <INSTANCE_NAME>
 ```
 
-In addition you may need to add your ssh key to `.kitchen.ec2.yml`
+You may test all instances in parallel with:
 
+```bash
+bundle exec kitchen test -c
 ```
-transport:
-  ssh_key: /Users/chartmann/aws/aws_chartmann.pem
-  username: ec2-user
-```
-
 
 ## License
 

data/Rakefile

@@ -4,7 +4,6 @@
 require 'bundler'
 require 'bundler/gem_tasks'
 require 'rake/testtask'
-require_relative 'tasks/changelog'
 require_relative 'tasks/maintainers'
 require_relative 'tasks/spdx'
 
@@ -138,19 +137,6 @@ task :version do
   inspec_version
 end
 
-# Update the version of this gem and create an updated
-# changelog. It covers everything short of actually releasing
-# the gem.
-desc 'Bump the version of this gem'
-task :bump_version, [:version] do |_, args|
-  v = args[:version] || ENV['to']
-  fail "You must specify a target version!  rake bump_version to=1.2.3" if v.empty?
-  check_update_requirements
-  inspec_version(v)
-  Rake::Task['changelog'].invoke
-  Rake::Task['docs:cli'].invoke
-end
-
 desc 'Release a new docker image'
 task :release_docker do
   version = Inspec::VERSION
@@ -164,23 +150,6 @@ task :release_docker do
   sh('sh', '-c', cmd)
 end
 
-desc 'Release a new Habitat package'
-task :release_habitat do
-    version = Inspec::VERSION
-    ENV['HAB_ORIGIN'] = "chef"
-    if Dir.exist?("./results") then
-        raise "Please remove the ./results directory"
-    end
-    if ! ENV.has_key?("HAB_AUTH_TOKEN") then
-        raise "Please set the HAB_AUTH_TOKEN environment variable"
-    end
-    cmd = "echo #{version} > ./habitat/VERSION && "\
-          "hab pkg build . && " \
-          "hab pkg upload ./results/*.hart"
-    puts "--> #{cmd}"
-    sh('sh', '-c', cmd)
-end
-
 desc 'Release the website [deprecated]'
 task :www do
   puts 'The Rake tasks for releasing the website are now in the www/ directory.'

data/docs/dsl_inspec.md

@@ -71,6 +71,16 @@ describe.one do
 end
 ```
 
+#### Sensitive resources
+
+In some scenarios, you may be writing checks involving resources with sensitive content (e.g. a file resource). In the case of failures, it may be desired to suppress output. This can be done by adding the `:sensitive` flag to the resource definition
+
+```ruby
+describe file('/tmp/mysecretfile'), :sensitive do
+  its('content') { should contain 'secret_info' }
+end
+```
+
 ## Examples
 
 The following examples show simple compliance tests using a single `control` block.

data/docs/matchers.md

@@ -8,11 +8,14 @@ Inspec uses matchers to help compare resource values to expectations.
 The following matchers are available:
 
 * `be`
+* `be_in`
 * `cmp`
 * `eq`
 * `include`
 * `match`
 
+<br>
+
 ## be
 
 This matcher can be followed by many different comparison operators.
@@ -25,6 +28,8 @@ describe file('/proc/cpuinfo') do
 end
 ```
 
+<br>
+
 ## cmp
 
 Unlike `eq`, cmp is a matcher for less-restrictive comparisons. It will
@@ -63,6 +68,13 @@ end
       its('log_format') { should cmp 'RAW' }
     end
     ```
+* Recognize versions embedded in strings
+
+    ```ruby
+    describe package(curl) do
+      its('version') { should cmp > '7.35.0-1ubuntu2.10' }
+    end
+    ```
 
 * Compare arrays with only one entry to a value
 
@@ -91,6 +103,7 @@ end
     expected: 0345
     got: 0444
     ```
+<br>
 
 ## eq
 
@@ -115,6 +128,8 @@ its('Port') { should eq 22 }
 
 For less restrictive comparisons, please use `cmp`.
 
+<br>
+
 ## include
 
 Verifies if a value is included in a list.
@@ -125,6 +140,20 @@ describe passwd do
 end
 ```
 
+<br>
+
+## be_in
+
+Verifies that an item is included in a list.
+
+```ruby
+describe resource do
+  its('item') { should be_in LIST }
+end
+```
+
+<br>
+
 ## match
 
 Check if a string matches a regular expression.

data/docs/plugin_kitchen_inspec.md

@@ -4,19 +4,19 @@ title: About kitchen-inspec
 
 # kitchen-inspec
 
-The `kitchen-inspec` driver enables InSpec to be used as a verifier within Kitchen.
+Use InSpec as a Kitchen verifier with `kitchen-inspec`.
 
-To use InSpec as a verifier, add it to the kitchen.yml file:
+Add the InSpec verifier to the `.kitchen.yml` file:
 
     verifier:
       name: inspec
 
-To define a suite that pulls its run-list from the Chef Compliance server:
+Use a compliance profile from the Chef Compliance server:
 
     suites:
       - name: compliance
         run_list:
-          - recipe[ssh-hardening]
+          - recipe[ssh-hardening::default]
         verifier:
           inspec_tests:
             - compliance://base/ssh
@@ -27,29 +27,23 @@ and then run the following command:
 
 where `--insecure` is required when using self-signed certificates.
 
-To define a suite that pulls its run-list from the Chef Supermarket:
+Use a compliance profile from the Chef Supermarket:
 
     suites:
       - name: supermarket
         run_list:
-          - recipe[ssh-hardening]
+          - recipe[ssh-hardening::default]
         verifier:
           inspec_tests:
-            - supermarket://hardening/ssh-hardening
-
-The `kitchen-inspec` driver expects tests to be located in the `test/integration` directory in a cookbook. For example::
-
-    .
-    ├── Berksfile
-    ├── Gemfile
-    ├── README.md
-    ├── metadata.rb
-    ├── recipes
-    │   ├── default.rb
-    │   └── nginx.rb
-    └── test
-        └── integration
-            └── default
-                ├── controls
-                ├── inspec.yml
-                └── libraries
+            - supermarket://dev-sec/ssh-baseline
+
+Use InSpec tests from the local file system:
+
+    suites:
+      - name: local
+        run_list:
+          - recipe[my_cookbook::default]
+        verifier:
+          inspec_tests:
+            - test/integration/default
+

data/docs/profiles.md

@@ -109,18 +109,23 @@ and to target all of these examples in a single `inspec.yml` file:
 
 # Profile Dependencies
 
-A profile dependency is needed when:
+An InSpec profile can bring in the controls and custom resources from another InSpec profile. Additionally, when inheriting the controls of another profile, a profile can skip or even modify those included controls.
 
- * using `include_controls` or `require_controls` in order to load controls defined in another profile
- * using a custom InSpec resource defined in another profile
+## Defining the Dependencies
 
-Use the `depends` setting in the `inspec.yml` file to specify one (or more) profiles on which this profile depends. A profile dependency may be sourced from a path, URL, a git repo, a cookbook located on Chef Supermarket or on GitHub, or a profile located on the Chef Compliance server.
+Before a profile can use controls from another profile, the to-be-included profile needs to be specified in the including profile’s `inspec.yml` file in the `depends` section. For each profile to be included, a location for the profile from where to be fetched and a name for the profile should be included. For example:
 
-## Path
+    depends:
+    - name: linux-baseline
+      url: https://github.com/dev-sec/linux-baseline/archive/master.tar.gz
+    - name: ssh-baseline
+      url: https://github.com/dev-sec/ssh-baseline/archive/master.tar.gz
 
-The `path` setting defines a profile that is located on disk. This setting is typically used during development of profiles and when debugging profiles. This setting does not support version constraints. If the location of the profile does not exist, an error is returned.
+InSpec supports a number of dependency sources.
 
-For example:
+### path
+
+The `path` setting defines a profile that is located on disk. This setting is typically used during development of profiles and when debugging profiles.
 
     depends:
     - name: my-profile
@@ -128,19 +133,19 @@ For example:
     - name: another
       path: ../relative/path
 
-## URL
+### url
 
-The `url` setting specifies a profile that is located at an HTTP- or HTTPS-based URL. The profile must be accessible via a HTTP GET operation and must be a valid profile archive (zip, tar, tar.gz format). If the download fails, the profile is inaccessible, or not in the correct format, an error is returned.
-
-For example:
+The `url` setting specifies a profile that is located at an HTTP- or HTTPS-based URL. The profile must be accessible via a HTTP GET operation and must be a valid profile archive (zip, tar, or tar.gz format).
 
     depends:
     - name: my-profile
       url: https://my.domain/path/to/profile.tgz
+    - name: profile-via-git
+      url: https://github.com/myusername/myprofile-repo/archive/master.tar.gz
 
-## git
+### git
 
-A `git` setting specifies a profile that is located in a git repository, with optional settings for branch, tag, commit, and version. The source location is translated into a URL upon resolution. This type of dependency supports version indexing via semantic versioning as git tags.
+A `git` setting specifies a profile that is located in a git repository, with optional settings for branch, tag, commit, and version. The source location is translated into a URL upon resolution. This type of dependency supports version constraints via semantic versioning as git tags.
 
 For example:
 
@@ -152,7 +157,7 @@ For example:
       commit:  pinned_commit
       version: semver_via_tags
 
-## Chef Supermarket
+### supermarket
 
 A `supermarket` setting specifies a profile that is located in a cookbook hosted on Chef Supermarket. The source location is translated into a URL upon resolution.
 
@@ -164,27 +169,9 @@ For example:
 
 Available Supermarket profiles can be listed with `inspec supermarket profiles`.
 
-## GitHub
+### compliance
 
-A `github` setting specifies a profile that is located in a repository hosted on GitHub. The source location is translated into a URL upon resolution.
-
-For example:
-
-    depends:
-    - name: gh-profile
-      github: username/project
-
-A path to a Git commit or tag on GitHub can also be used:
-
-    dev-sec/linux-baseline
-    dev-sec/linux-baseline/tree/2.0
-    dev-sec/linux-baseline/tree/48bd4388ddffde68badd83aefa654e7af3231876
-
-would all download profiles corresponding to the GitHub URL, https://github.com/dev-sec/linux-baseline/tree/48bd4388ddffde68badd83aefa654e7af3231876, for example.
-
-## Chef Compliance
-
-A `compliance` setting specifies a profile that is located on the Chef Compliance server.
+A `compliance` setting specifies a profile that is located on the Chef Automate or Chef Compliance server.
 
 For example:
 
@@ -192,80 +179,76 @@ For example:
       - name: linux
         compliance: base/linux
 
-You need to `inspec vendor` the profile before uploading it to Chef Compliance version 1.7.7 or newer. The vendor subcommand fetches all dependent profiles and stores them in the `vendor` directory.
+## Vendoring Dependencies
 
-## Define in inspec.yml
+When you execute a local profile, the `inspec.yml` file will be read in order to source any profile dependencies. It will then cache the dependencies locally and generate an `inspec.lock` file.
 
-Use the `depends` setting in the `inspec.yml` file to define any combination of profile dependencies. For example:
+If you add or update dependencies in `inspec.yml`, dependencies may be re-vendored and the lockfile updated with `inspec vendor --overwrite`
 
-    depends:
-      - name: ssh-hardening
-        supermarket: hardening/ssh-hardening
-        version: '= 2.0.0'
-      - name: os-hardening
-        url: https://github.com/dev-sec/tests-os-hardening/archive/master.zip
-      - name: ssl-benchmark
-        git: https://github.com/dev-sec/ssl-benchmark.git
-        version: '< 2.0'
-      - name: windows-patch-benchmark
-        git: https://github.com/chris-rock/windows-patch-benchmark.git
-        version: '~> 0.6'
-      - name: linux
-        compliance: base/linux
+## Using Controls from an Included Profile
 
-## Vendoring Dependencies
+Once defined in the `inspec.yml`, controls from the included profiles can be used! Let’s look at some examples.
 
-When you execute a local profile, the `inspec.yml` file will be read in order to source any profile dependencies. It will then cache the dependencies locally and generate an `inspec.lock` file. If you add or update dependencies in `inspec.yml`, please refresh the lock file by either:
+### Including All Controls from a Profile
 
- * running `inspec vendor` inside the profile directory; or
- * deleting `inspec.lock` before running `inspec exec`
+With the `include_controls` command in a profile, all controls from the named profile will be executed every time the including profile is executed.
 
-# Profile Inheritance
+![Include Controls](/images/profile_inheritance/include_controls.png)
 
-When a profile is run, it may include controls that are defined in other profiles. Controls may also be required.
+In the example above, every time `my-app-profile` is executed, all the controls from `my-baseline` are also executed. Therefore, the following controls would be executed:
 
-This requires an `inspec.yml` dependency to the profile you inherit from.
+ * myapp-1
+ * myapp-2
+ * myapp-3
+ * baseline-1
+ * baseline-2
 
-## include_controls
+This is a great reminder that having a good naming convention for your controls is helpful to avoid confusion when
+including controls from other profiles!
 
-The `include_controls` keyword may be used in a profile to import all rules from the named profile.
+### Skipping a Control from a Profile
 
-For example, to include controls from the `cis-level-1` profile when running the `cis-fs-2.7` profile:
+What if one of the controls from the included profile does not apply to your environment? Luckily, it is not necessary to maintain a slightly-modified copy of the included profile just to delete a control. The `skip_control` command tells InSpec to not run a particular control.
 
-    include_controls 'cis-level-1' do
+![Include Controls with Skip](/images/profile_inheritance/include_controls_with_skip.png)
 
-      control "cis-fs-2.7" do
-        impact 1.0
-      ...
+In the above example, all controls from `my-app-profile` and `my-baseline` profile will be executed every time `my-app-profile` is executed **except** for control `baseline-2` from the `my-baseline` profile.
 
-    end
+### Modifying a Control
 
-To include controls from the `cis-level-1` profile, but skipping two controls within that profile:
+Let's say a particular control from an included profile should still be run, but the impact isn't appropriate? Perhaps the test should still run, but if it fails, it should be treated as low severity instead of high severity?
 
-    include_controls 'cis-level-1' do
+When a control is included, it can also be modified!
 
-      skip_control "cis-fs-2.1"
-      skip_control "cis-fs-2.2"
+![Include Controls with Modification](/images/profile_inheritance/include_controls_with_mod.png)
 
-    end
+In the above example, all controls from `my-baseline` are executed along with all the controls from the including profile, `my-app-profile`. However, should control `baseline-1` fail, it will be raised with an impact of `0.5` instead of the originally-intended impact of `1.0`.
 
-## require_controls
+### Selectively Including Controls from a Profile
 
-The `require_controls` keyword may be used to load only specific controls from the named profile.
+If there are only a handful of controls that should be executed from an included profile, it's not necessarily to skip all the unneeded controls, or worse, copy/paste those controls bit-for-bit into your profile. Instead, use the `require_controls` command.
 
-For example, to require that controls `cis-fs-2.1` and `cis-fs-2.2` be loaded from the `cis-level-1` profile:
+![Require Controls](/images/profile_inheritance/require_controls.png)
 
-    require_controls 'cis-level-1' do
+Whenever `my-app-profile` is executed, in addition to its own controls, it will run only the controls specified in the `require_controls` block. In the case, the following controls would be executed:
 
-      control "cis-fs-2.1"
-      control "cis-fs-2.2"
+ * myapp-1
+ * myapp-2
+ * myapp-3
+ * baseline-2
+ * baseline-4
 
-    end
+Controls `baseline-1`, `baseline-3`, and `baseline-5` would not be run, just as if they were manually skipped. This method of including specific controls ensures only the controls specified are executed; if new controls are added to a later version of `my-baseline`, they would not be run.
+
+And, just the way its possible to modify controls when using `include_controls`, controls can be modified as well.
+
+![Require Controls with Modification](/images/profile_inheritance/require_controls_with_mod.png)
 
+As with the prior example, only `baseline-2` and `baseline-4` are executed, but if `baseline-2` fails, it will report with an impact of `0.5` instead of the originally-intended `1.0` impact.
 
-## require_resource
+## Using Resources from an Included Profile
 
-By default, all of the resources from a listed dependency are available
+By default, all of the custom resources from a listed dependency are available
 for use in your profile. If two of your dependencies provide a resource with
 the same name, you can use the `require_resource` DSL function to
 disambiguate the two:
@@ -340,7 +323,7 @@ The tests in `example.rb` can now access this file:
     my_services = yaml(content: inspec.profile.file('services.yml')).params
 
     my_services.each do |s|
-      describe service(s['name']) do
+      describe service(s['service_name']) do
         it { should be_running }
       end
 
@@ -348,3 +331,40 @@ The tests in `example.rb` can now access this file:
         it { should be_listening }
       end
     end
+
+# "should" vs. "expect" syntax
+
+Users familiar with the RSpec testing framework may know that there are two ways to write test statements: `should` and `expect`. The RSpec community decided that `expect` is the preferred syntax. However, InSpec recommends the `should` syntax as it tends to read more easily to those users who are not as technical.
+
+InSpec will continue to support both methods of writing tests. Consider this `file` test:
+
+    describe file('/tmp/test.txt') do
+      it { should be_file }
+    end
+
+This can be re-written with `expect` syntax
+
+    describe file('/tmp/test.txt') do
+      it 'should be a file' do
+        expect(subject).to(be_file)
+      end
+    end
+
+The output of both of the above examples looks like this:
+
+    File /tmp/test.txt
+       ✔  should be a file
+
+In addition, you can make use of the `subject` keyword to further control your output if you choose:
+
+    describe 'test file' do
+      subject { file('/tmp/test.txt') }
+      it 'should be a file' do
+        expect(subject).to(be_file)
+      end
+    end
+
+... which will render the following output:
+
+    test file
+      ✔  should be a file

data/docs/resources/aide_conf.md.erb

@@ -0,0 +1,71 @@
+---
+title: About the aide_conf Resource
+---
+
+# aide_conf
+
+Use the `aide_conf` InSpec audit resource to test the rules established for the file integrity tool AIDE. Controlled by the aide.conf file typically at /etc/aide.conf.
+
+<br>
+
+## Syntax
+
+An `aide_conf` resource block can be used to determine if the selection lines contain one (or more) directories whose files should be added to the aide database:
+
+    describe aide_conf('path') do
+      its('selection_lines') { should include '/sbin' }
+    end
+
+where
+
+* `'selection_lines'` refers to all selection lines found in the aide.conf file
+* `('path')` is the non-default path to the `aide.conf` file (optional)
+* `should include 'value'` is the value that is expected
+
+Use the where clause to match a selection_line to one rule or a particular set of rules found in the aide.conf file:
+
+    describe aide_conf.where { selection_line == '/bin' } do
+      its('rules.flatten') { should include 'r' }
+    end
+
+    describe aide_conf.where { selection_line == '/sbin' } do
+      its('rules') { should include ['p', 'i', 'l', 'n', 'u', 'g', 'sha512'] }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### Test if all selection lines contain the xattr rule
+
+    describe aide_conf.all_have_rule('xattr') do
+      it { should eq true }
+    end
+
+### Test whether selection line for /bin contains a particular rule
+
+    describe aide_conf.where { selection_line == '/bin' } do
+      its('rules.flatten') { should include 'r' }
+    end
+
+### Test whether selection line for /sbin consists of a particular set of rules
+
+    describe aide_conf.where { selection_line == '/sbin' } do
+      its('rules') { should include ['r', 'sha512'] }
+    end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### all_have_rule
+
+The usage of all_have_rule will return whether or not all selection lines in audit.conf contain a particular rule:
+
+    describe aide_conf.all_have_rule('sha512') do
+      it { should eq true }
+    end