inspec 2.2.35 → 2.2.41

data/docs/inspec_and_friends.md

@@ -42,10 +42,10 @@ end
 
 That said, InSpec is not RSpec. Some key differences:
 
- * In InSpec, `describe` blocks should not be nested; instead use `control` blocks to describe a higher-level grouping of tests.
- * The RSpec `shared_example` construct is not supported.  Instead, create a simple custom resource that executes repetitious tasks.
- * InSpec is aimed at compliance practitioners and infrastructure testers, so our focus is providing a few, well-supported, easy-to-use [universal matchers](https://www.inspec.io/docs/reference/matchers/), such as `cmp`. In contrast, RSpec is a tool designed for software engineers. It thus supports a very large range of matchers, to enable testing of software engineering constructs such as exceptions, Object Oriented Programming relationships, and so on. 
- * While InSpec uses parts of the RSpec project and codebase, it is a separate project from InSpec. Rspec's release schedule and feature set are beyond the control of the InSpec team. While it is possible to use many of the RSpec core features within InSpec profiles, InSpec can only guarantee that the features described at [docs.inspec.io](https://docs.inspec.io) will function correctly. Some RSpec core functionality may be removed in future versions of InSpec as needed to ensure stability in the InSpec project.
+* In InSpec, `describe` blocks should not be nested; instead use `control` blocks to describe a higher-level grouping of tests.
+* The RSpec `shared_example` construct is not supported.  Instead, create a simple custom resource that executes repetitious tasks.
+* InSpec is aimed at compliance practitioners and infrastructure testers, so our focus is providing a few, well-supported, easy-to-use [universal matchers](https://www.inspec.io/docs/reference/matchers/), such as `cmp`. In contrast, RSpec is a tool designed for software engineers. It thus supports a very large range of matchers, to enable testing of software engineering constructs such as exceptions, Object Oriented Programming relationships, and so on.
+* While InSpec uses parts of the RSpec project and codebase, it is a separate project from InSpec. Rspec's release schedule and feature set are beyond the control of the InSpec team. While it is possible to use many of the RSpec core features within InSpec profiles, InSpec can only guarantee that the features described at [docs.inspec.io](https://docs.inspec.io) will function correctly. Some RSpec core functionality may be removed in future versions of InSpec as needed to ensure stability in the InSpec project.
 
 ## Serverspec
 

data/docs/matchers.md

@@ -32,8 +32,6 @@ describe file('/proc/cpuinfo') do
 end
 ```
 
-<br>
-
 ## cmp
 
 Unlike `eq`, `cmp` is a matcher for less-restrictive comparisons. It will
@@ -72,6 +70,7 @@ describe auditd_conf do
   its('log_format') { should cmp 'RAW' }
 end
 ```
+
 * Recognize versions embedded in strings
 
 ```ruby
@@ -107,7 +106,6 @@ end
 expected: 0345
 got: 0444
 ```
-<br>
 
 ## eq
 
@@ -132,8 +130,6 @@ its('Port') { should eq 22 }
 
 For less restrictive comparisons, please use `cmp`.
 
-<br>
-
 ## include
 
 Verifies if a value is included in a list.
@@ -144,8 +140,6 @@ describe passwd do
 end
 ```
 
-<br>
-
 ## be_in
 
 Verifies that an item is included in a list.
@@ -156,8 +150,6 @@ describe resource do
 end
 ```
 
-<br>
-
 ## match
 
 Check if a string matches a regular expression.

data/docs/plugin_kitchen_inspec.md

@@ -8,43 +8,53 @@ Use InSpec as a Kitchen verifier with `kitchen-inspec`.
 
 Add the InSpec verifier to the `.kitchen.yml` file:
 
-    verifier:
-      name: inspec
+```YML
+  verifier:
+    name: inspec
+```
 
 Use a compliance profile from the Chef Compliance server:
 
-    suites:
-      - name: compliance
-        run_list:
-          - recipe[ssh-hardening::default]
-        verifier:
-          inspec_tests:
-            - compliance://base/ssh
+```YML
+  suites:
+    - name: compliance
+      run_list:
+        - recipe[ssh-hardening::default]
+      verifier:
+        inspec_tests:
+          - compliance://base/ssh
+```
 
 and then run the following command:
 
-    $ inspec compliance login https://compliance.test --user admin --insecure --token ''
+```bash
+  $ inspec compliance login https://compliance.test --user admin --insecure --token ''
+```
 
 where `--insecure` is required when using self-signed certificates.
 
 Use a compliance profile from the Chef Supermarket:
 
-    suites:
-      - name: supermarket
-        run_list:
-          - recipe[ssh-hardening::default]
-        verifier:
-          inspec_tests:
-            - supermarket://dev-sec/ssh-baseline
+```YML
+  suites:
+    - name: supermarket
+      run_list:
+        - recipe[ssh-hardening::default]
+      verifier:
+        inspec_tests:
+          - 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
+```YML
+  suites:
+    - name: local
+      run_list:
+        - recipe[my_cookbook::default]
+      verifier:
+        inspec_tests:
+          - test/integration/default
+```
 
 Check out [Detect and correct with Test Kitchen](https://learn.chef.io/modules/detect-correct-kitchen#/) on Learn Chef Rally for a hands-on look at how to use Test Kitchen to run InSpec profiles.

data/docs/profiles.md

@@ -10,16 +10,18 @@ InSpec supports the creation of complex test and compliance profiles, which orga
 
 A profile should have the following structure::
 
-    examples/profile
-    ├── README.md
-    ├── controls
-    │   ├── example.rb
-    │   └── control_etc.rb
-    ├── libraries
-    │   └── extension.rb
-    |── files
-    │   └── extras.conf
-    └── inspec.yml
+```YAML
+examples/profile
+├── README.md
+├── controls
+│   ├── example.rb
+│   └── control_etc.rb
+├── libraries
+│   └── extension.rb
+|── files
+│   └── extras.conf
+└── inspec.yml
+```
 
 where:
 
@@ -37,79 +39,92 @@ Also check out [Explore InSpec resources](https://learn.chef.io/modules/explore-
 
 Each profile must have an `inspec.yml` file that defines the following information:
 
- * Use `name` to specify a unique name for the profile. Required.
- * Use `title` to specify a human-readable name for the profile.
- * Use `maintainer` to specify the profile maintainer.
- * Use `copyright` to specify the copyright holder.
- * Use `copyright_email` to specify support contact information for the profile, typically an email address.
- * Use `license` to specify the license for the profile.
- * Use `summary` to specify a one line summary for the profile.
- * Use `description` to specify a multiple line description of the profile.
- * Use `version` to specify the profile version.
- * Use `inspec_version` to place SemVer constraints on the version of InSpec that the profile can run under.
- * Use `supports` to specify a list of supported platform targets.
- * Use `depends` to define a list of profiles on which this profile depends.
+* Use `name` to specify a unique name for the profile. Required.
+* Use `title` to specify a human-readable name for the profile.
+* Use `maintainer` to specify the profile maintainer.
+* Use `copyright` to specify the copyright holder.
+* Use `copyright_email` to specify support contact information for the profile, typically an email address.
+* Use `license` to specify the license for the profile.
+* Use `summary` to specify a one line summary for the profile.
+* Use `description` to specify a multiple line description of the profile.
+* Use `version` to specify the profile version.
+* Use `inspec_version` to place SemVer constraints on the version of InSpec that the profile can run under.
+* Use `supports` to specify a list of supported platform targets.
+* Use `depends` to define a list of profiles on which this profile depends.
 
 `name` is required; all other profile settings are optional. For example:
 
-    name: ssh
-    title: Basic SSH
-    maintainer: Chef Software, Inc.
-    copyright: Chef Software, Inc.
-    copyright_email: support@chef.io
-    license: Proprietary, All rights reserved
-    summary: Verify that SSH Server and SSH Client are configured securely
-    version: 1.0.0
-    supports:
-      - os-family: linux
-    depends:
-      - name: profile
-        path: ../path/to/profile
-    inspec_version: "~> 2.1"
+```YAML
+name: ssh
+title: Basic SSH
+maintainer: Chef Software, Inc.
+copyright: Chef Software, Inc.
+copyright_email: support@chef.io
+license: Proprietary, All rights reserved
+summary: Verify that SSH Server and SSH Client are configured securely
+version: 1.0.0
+supports:
+  - os-family: linux
+depends:
+  - name: profile
+    path: ../path/to/profile
+inspec_version: "~> 2.1"
+```
 
 ## Verify Profiles
 
 Use the `inspec check` command to verify the implementation of a profile:
 
-    $ inspec check examples/profile
+```bash
+$ inspec check examples/profile
+```
 
 # Platform Support
 
 Use the `supports` setting in the `inspec.yml` file to specify one (or more) platforms for which a profile is targeting. The list of supported platforms may contain simple names, names and versions, or detailed flags, and may be combined arbitrarily. For example, to target anything running Debian Linux:
 
-    name: ssh
-    supports:
-      - os-name: debian
+```YAML
+name: ssh
+supports:
+  - os-name: debian
+```
 
 and to target only Ubuntu version 14.04
 
-    name: ssh
-    supports:
-      - os-name: ubuntu
-        release: 14.04
+```YAML
+name: ssh
+supports:
+  - os-name: ubuntu
+    release: 14.04
+```
 
 and to target the entire RedHat platform (including CentOS and Oracle Linux):
 
-    name: ssh
-    supports:
-      - os-family: redhat
+```YAML
+name: ssh
+supports:
+  - os-family: redhat
+```
 
 and to target anything running on Amazon AWS:
 
-    name: ssh
-    supports:
-      - platform: aws
+```YAML
+name: ssh
+supports:
+  - platform: aws
+```
 
 and to target all of these examples in a single `inspec.yml` file:
 
-    name: ssh
-    supports:
-      - os-name: debian
-      - os-name: ubuntu
-        release: 14.04
-      - os-family: redhat
-      - platform: aws
-
+```YAML
+name: ssh
+supports:
+  - os-name: debian
+  - os-name: ubuntu
+    release: 14.04
+  - os-family: redhat
+  - platform: aws
+```
 
 # Profile Dependencies
 
@@ -121,11 +136,13 @@ For hands-on examples, check out [Create a custom InSpec profile](https://learn.
 
 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:
 
-    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
+```YAML
+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
+```
 
 InSpec supports a number of dependency sources.
 
@@ -133,21 +150,25 @@ InSpec supports a number of dependency sources.
 
 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
-      path: /absolute/path
-    - name: another
-      path: ../relative/path
+```YAML
+depends:
+- name: my-profile
+  path: /absolute/path
+- name: another
+  path: ../relative/path
+```
 
 ### 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, 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
+```YAML
+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
 
@@ -155,13 +176,15 @@ A `git` setting specifies a profile that is located in a git repository, with op
 
 For example:
 
-    depends:
-    - name: git-profile
-      git: http://url/to/repo
-      branch:  desired_branch
-      tag:     desired_version
-      commit:  pinned_commit
-      version: semver_via_tags
+```YAML
+depends:
+- name: git-profile
+  git: http://url/to/repo
+  branch:  desired_branch
+  tag:     desired_version
+  commit:  pinned_commit
+  version: semver_via_tags
+```
 
 ### supermarket
 
@@ -169,9 +192,11 @@ A `supermarket` setting specifies a profile that is located in a cookbook hosted
 
 For example:
 
-    depends:
-    - name: supermarket-profile
-      supermarket: supermarket-username/supermarket-profile
+```YAML
+depends:
+- name: supermarket-profile
+  supermarket: supermarket-username/supermarket-profile
+```
 
 Available Supermarket profiles can be listed with `inspec supermarket profiles`.
 
@@ -181,9 +206,11 @@ A `compliance` setting specifies a profile that is located on the Chef Automate
 
 For example:
 
-    depends:
-      - name: linux
-        compliance: base/linux
+```YAML
+depends:
+- name: linux
+  compliance: base/linux
+```
 
 ## Vendoring Dependencies
 
@@ -199,15 +226,17 @@ Once defined in the `inspec.yml`, controls from the included profiles can be use
 
 With the `include_controls` command in a profile, all controls from the named profile will be executed every time the including profile is executed.
 
+```YAML
 ![Include Controls](/images/profile_inheritance/include_controls.png)
+```
 
 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:
 
- * myapp-1
- * myapp-2
- * myapp-3
- * baseline-1
- * baseline-2
+* myapp-1
+* myapp-2
+* myapp-3
+* baseline-1
+* baseline-2
 
 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!
@@ -216,7 +245,9 @@ including controls from other profiles!
 
 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.
 
+```YAML
 ![Include Controls with Skip](/images/profile_inheritance/include_controls_with_skip.png)
+```
 
 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.
 
@@ -226,7 +257,9 @@ Let's say a particular control from an included profile should still be run, but
 
 When a control is included, it can also be modified!
 
+```YAML
 ![Include Controls with Modification](/images/profile_inheritance/include_controls_with_mod.png)
+```
 
 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`.
 
@@ -234,21 +267,25 @@ In the above example, all controls from `my-baseline` are executed along with al
 
 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.
 
+```YAML
 ![Require Controls](/images/profile_inheritance/require_controls.png)
+```
 
 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:
 
- * myapp-1
- * myapp-2
- * myapp-3
- * baseline-2
- * baseline-4
+* myapp-1
+* myapp-2
+* myapp-3
+* baseline-2
+* baseline-4
 
 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.
 
+```YAML
 ![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.
 
@@ -259,46 +296,54 @@ 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:
 
-    require_resource(profile: 'my_dep', resource: 'my_res',
-                     as: 'my_res2')
+```YAML
+require_resource(profile: 'my_dep', resource: 'my_res',
+                  as: 'my_res2')
+  ```
 
 This will allow you to reference the resource `my_res` from the
 profile `my_dep` using the name `my_res2`.
 
 # Profile Attributes
 
-Attributes may be used in profiles to define secrets, such as user names and passwords, that should not otherwise be stored in plain-text in a cookbook. First specify a variable in the control for each secret, then add the secret to a Yaml file located on the local machine, and then run `inspec exec` and specify the path to that Yaml file using the `--attrs` attribute.
+Attributes may be used in profiles to define secrets, such as user names and passwords, that should not otherwise be stored in plain-text in a cookbook. First specify a variable in the control for each secret, then add the secret to a YAML file located on the local machine, and then run `inspec exec` and specify the path to that Yaml file using the `--attrs` attribute.
 
 For example, a control:
 
-    # define these attributes on the top-level of your file and re-use them across all tests!
-    val_user = attribute('user', default: 'alice', description: 'An identification for the user')
-    val_password = attribute('password', description: 'A value for the password')
+```Ruby
+# define these attributes on the top-level of your file and re-use them across all tests!
+val_user = attribute('user', default: 'alice', description: 'An identification for the user')
+val_password = attribute('password', description: 'A value for the password')
 
-    control 'system-users' do
-      impact 0.8
-      desc '
-        This test assures that the user "Bob" has a user installed on the system, along with a
-        specified password.
-      '
+control 'system-users' do
+  impact 0.8
+  desc '
+    This test assures that the user "Bob" has a user installed on the system, along with a
+    specified password.
+  '
 
-      describe val_user do
-        it { should eq 'bob' }
-      end
+   val_user do
+    it { should eq 'bob' }
+  end
 
-      describe val_password do
-        it { should eq 'secret' }
-      end
-    end
+  describe val_password do
+    it { should eq 'secret' }
+  end
+end
+```
 
-And a Yaml file named `profile-attribute.yml`:
+And a YAML file named `profile-attribute.yml`:
 
-    user: bob
-    password: secret
+```YAML
+user: bob
+password: secret
+```
 
 The following command runs the tests and applies the secrets specified in `profile-attribute.yml`:
 
-    $ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
+```bash
+$ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
+```
 
 See the full example in the InSpec open source repository: [Example InSpec Profile with Attributes](https://github.com/chef/inspec/tree/master/examples/profile-attribute)
 
@@ -310,33 +355,39 @@ To access these files, they must be stored in the `files` directory at the root
 
 Here is an example for reading and testing a list of ports. The folder structure is:
 
-    examples/profile
-    ├── controls
-    │   ├── example.rb
-    |── files
-    │   └── services.yml
-    └── inspec.yml
+```YAML
+examples/profile
+├── controls
+│   ├── example.rb
+│── files
+│   └── services.yml
+└── inspec.yml
+```
 
 With `services.yml` containing:
 
-    - service_name: httpd-alpha
-      port: 80
-    - service_name: httpd-beta
-      port: 8080
+```YAML
+- service_name: httpd-alpha
+  port: 80
+- service_name: httpd-beta
+  port: 8080
+```
 
 The tests in `example.rb` can now access this file:
 
-    my_services = yaml(content: inspec.profile.file('services.yml')).params
+```Ruby
+my_services = yaml(content: inspec.profile.file('services.yml')).params
 
-    my_services.each do |s|
-      describe service(s['service_name']) do
-        it { should be_running }
-      end
+my_services.each do |s|
+  describe service(s['service_name']) do
+    it { should be_running }
+end
 
-      describe port(s['port']) do
-        it { should be_listening }
-      end
-    end
+describe port(s['port']) do
+  it { should be_listening }
+  end
+end
+```
 
 For a more complete example that uses a profile file, see [Explore InSpec resources](https://learn.chef.io/modules/explore-inspec-resources#/) on Learn Chef Rally.
 
@@ -346,33 +397,43 @@ Users familiar with the RSpec testing framework may know that there are two ways
 
 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
+```Ruby
+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
+```Ruby
+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
+```text
+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
+```Ruby
+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
+```text
+test file
+  ✔  should be a file
+```