inspec 1.0.0 → 1.35.1

data/docs/matchers.md

@@ -8,6 +8,7 @@ Inspec uses matchers to help compare resource values to expectations.
 The following matchers are available:
 
 * `be`
+* `be_in`
 * `cmp`
 * `eq`
 * `include`
@@ -125,6 +126,16 @@ describe passwd do
 end
 ```
 
+## be_in
+
+Verifies that an item is included in a list.
+
+```ruby
+describe resource do
+  its('item') { should be_in LIST }
+end
+```
+
 ## match
 
 Check if a string matches a regular expression.

data/docs/migration.md

@@ -0,0 +1,293 @@
+---
+title: InSpec Migration Guide
+---
+
+# Migrate from Serverspec to InSpec
+
+## How is InSpec different from Serverspec
+
+We've written a complete blog post about that topic: [The Road to InSpec](https://blog.chef.io/2015/11/04/the-road-to-inspec/)
+
+## Is InSpec suitable for infrastructure testing?
+
+InSpec is a framework that allows you to run infrastructure testing as well as compliance testing. The compliance features are always optional and provide customers a way to use InSpec for both use-cases. To ensure we build the best infrastructure testing, we migrate our cookbooks [chef-cookbooks](https://github.com/chef-cookbooks) to InSpec.
+
+## Which Serverspec resources are available in InSpec?
+
+The following resources are available in InSpec:
+
+|                                         Serverspec                                         |                                        InSpec                                        |
+|:------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------:|
+| [`bond`](http://serverspec.org/resource_types.html#bond)                                     | [`bond`](https://www.inspec.io/docs/reference/resources/bond/)                         |
+| [`bridge`](http://serverspec.org/resource_types.html#bridge)                                 | [`bridge`](https://www.inspec.io/docs/reference/resources/bridge/)                     |
+| [`command`](http://serverspec.org/resource_types.html#command)                               | [`command`](https://www.inspec.io/docs/reference/resources/command/)                   |
+| [`cron`](http://serverspec.org/resource_types.html#cron)                                     | [`crontab`](https://www.inspec.io/docs/reference/resources/crontab/)                   |
+| [`docker_container`](http://serverspec.org/resource_types.html#docker_container)             | [`docker_container`](https://www.inspec.io/docs/reference/resources/docker_container/) |
+| [`docker_image`](http://serverspec.org/resource_types.html#docker_image)                     | [`docker_image`](https://www.inspec.io/docs/reference/resources/docker_image/)         |
+| [`file`](http://serverspec.org/resource_types.html#file)                                     | [`file`](https://www.inspec.io/docs/reference/resources/file/)                         |
+| [`group`](http://serverspec.org/resource_types.html#group)                                   | [`group`](https://www.inspec.io/docs/reference/resources/group/)                       |
+| [`host`](http://serverspec.org/resource_types.html#host)                                     | [`host`](https://www.inspec.io/docs/reference/resources/host/)                         |
+| [`interface`](http://serverspec.org/resource_types.html#interface)                           | [`interface`](https://www.inspec.io/docs/reference/resources/interface/)               |
+| [`iis_website`](http://serverspec.org/resource_types.html#iis_website)                       | [`iis_website`](https://www.inspec.io/docs/reference/resources/iis_website/)           |
+| [`iis_app_pool`](http://serverspec.org/resource_types.html#iis_app_pool)                     | [`iis_website`](https://www.inspec.io/docs/reference/resources/iis_website/)           |
+| [`iptables`](http://serverspec.org/resource_types.html#iptables)                             | [`iptables`](https://www.inspec.io/docs/reference/resources/iptables/)                 |
+| [`kernel_module`](http://serverspec.org/resource_types.html#kernel_module)                   | [`kernel_module`](https://www.inspec.io/docs/reference/resources/kernel_module/)       |
+| [`linux_kernel_parameter`](http://serverspec.org/resource_types.html#linux_kernel_parameter) | [`kernel_parameter`](https://www.inspec.io/docs/reference/resources/kernel_parameter/) |
+| [`mysql_config`](http://serverspec.org/resource_types.html#mysql_config)                     | [`mysql_conf`](https://www.inspec.io/docs/reference/resources/mysql_conf/)             |
+| [`package`](http://serverspec.org/resource_types.html#package)                               | [`package`](https://www.inspec.io/docs/reference/resources/package/)                   |
+| [`port`](http://serverspec.org/resource_types.html#port)                                     | [`port`](https://www.inspec.io/docs/reference/resources/port/)                         |
+| [`ppa`](http://serverspec.org/resource_types.html#ppa)                                       | [`apt`](https://www.inspec.io/docs/reference/resources/apt/)                           |
+| [`process`](http://serverspec.org/resource_types.html#process)                               | [`processes`](https://www.inspec.io/docs/reference/resources/processes/)               |
+| [`service`](http://serverspec.org/resource_types.html#service)                               | [`service`](https://www.inspec.io/docs/reference/resources/service/)                   |
+| [`user`](http://serverspec.org/resource_types.html#user)                                     | [`user`](https://www.inspec.io/docs/reference/resources/user/)                         |
+| [`windows_feature`](http://serverspec.org/resource_types.html#windows_feature)               | [`windows_feature`](https://www.inspec.io/docs/reference/resources/windows_feature/)   |
+| [`windows_registry_key`](http://serverspec.org/resource_types.html#windows_registry_key)     | [`registry_key`](https://www.inspec.io/docs/reference/resources/registry_key/)         |
+| [`x509_certificate`](http://serverspec.org/resource_types.html#x509_certificate)             | [`x509_certificate`](https://www.inspec.io/docs/reference/resources/x509_certificate/) |
+| [`yumrepo`](http://serverspec.org/resource_types.html#yumrepo)                               | [`yum`](https://www.inspec.io/docs/reference/resources/yum/)                           |
+| [`zfs`](http://serverspec.org/resource_types.html#zfs)                                       | [`zfs_pool`](https://www.inspec.io/docs/reference/resources/zfs_pool/)                 |
+
+Some Serverspec resources are not available yet. We will implement those resources based on user feedback. If you need a resource that is not available in InSpec, please open an [Github issue](https://github.com/chef/inspec/issues). The list of resources that are not available in InSpec:
+
+* [`cgroup`](http://serverspec.org/resource_types.html#cgroup)
+* [`default_gateway`](http://serverspec.org/resource_types.html#default_gateway)
+* [`ip6tables`](http://serverspec.org/resource_types.html#ip6tables)
+* [`ipfilter`](http://serverspec.org/resource_types.html#ipfilter)
+* [`ipnat`](http://serverspec.org/resource_types.html#ipnat)
+* [`linux_audit_system`](http://serverspec.org/resource_types.html#linux_audit_system)
+* [`lxc`](http://serverspec.org/resource_types.html#lxc)
+* [`mail_alias`](http://serverspec.org/resource_types.html#mail_alias)
+* [`php_config`](http://serverspec.org/resource_types.html#php_config)
+* [`routing_table`](http://serverspec.org/resource_types.html#routing_table)
+* [`selinux`](http://serverspec.org/resource_types.html#selinux)
+* [`selinux_module`](http://serverspec.org/resource_types.html#selinux_module)
+* [`x509_private_key`](http://serverspec.org/resource_types.html#x509_private_key)
+
+In addition InSpec provides additional [resources](https://www.inspec.io/docs/reference/resources/) that are not available in Serverspec:
+
+* [`apache_conf`](https://www.inspec.io/docs/reference/resources/apache_conf/)
+* [`apt`](https://www.inspec.io/docs/reference/resources/apt/)
+* [`audit_policy`](https://www.inspec.io/docs/reference/resources/audit_policy/)
+* [`auditd_conf`](https://www.inspec.io/docs/reference/resources/auditd_conf/)
+* [`bash`](https://www.inspec.io/docs/reference/resources/bash/)
+* [`csv`](https://www.inspec.io/docs/reference/resources/csv/)
+* [`etc_shadow`](https://www.inspec.io/docs/reference/resources/etc_shadow/)
+* [`gem`](https://www.inspec.io/docs/reference/resources/gem/)
+* [`grub_conf`](https://www.inspec.io/docs/reference/resources/grub_conf/)
+* [`inetd_conf`](https://www.inspec.io/docs/reference/resources/inetd_conf/)
+* [`ini`](https://www.inspec.io/docs/reference/resources/ini/)
+* [`json`](https://www.inspec.io/docs/reference/resources/json/)
+* [`npm`](https://www.inspec.io/docs/reference/resources/npm/)
+* [`ntp_conf`](https://www.inspec.io/docs/reference/resources/ntp_conf/)
+* [`oneget`](https://www.inspec.io/docs/reference/resources/oneget/)
+* [`pip`](https://www.inspec.io/docs/reference/resources/pip/)
+* [`powershell`](https://www.inspec.io/docs/reference/resources/powershell/)
+* [`security_policy`](https://www.inspec.io/docs/reference/resources/security_policy/)
+* [`ssh_config`](https://www.inspec.io/docs/reference/resources/ssh_config/)
+* [`sshd_config`](https://www.inspec.io/docs/reference/resources/sshd_config/)
+* [`sys_info`](https://www.inspec.io/docs/reference/resources/sys_info/)
+
+## How do I migrate my Serverspec tests to InSpec
+
+For most cases, the migration to InSpec is pretty straight forward. First, replace the current verifier in `kitchen.yml` configuration with:
+
+```
+verifier:
+  name: inspec
+```
+
+Second, rename the directory `test/integration/default/serverspec` to
+`test/integration/default/inspec`
+
+Third, remove the Serverspec-specific code from the test files.
+
+```
+require 'serverspec'
+
+# Required by serverspec
+set :backend, :exec
+```
+
+InSpec is now configured with Test-Kitchen:
+
+```
+kitchen verify package-install-centos-72
+-----> Starting Kitchen (v1.14.2)
+-----> Verifying <package-install-centos-72>...
+       Detected alternative framework tests for `inspec`
+       Loaded
+
+Target:  ssh://vagrant@127.0.0.1:2200
+
+
+  PHP has
+     ✔  php
+     ✔  the pear.php.net channel
+     ✔  the pecl.php.net channel
+
+Test Summary: 3 successful, 0 failures, 0 skipped
+       Finished verifying <package-install-centos-72> (0m0.40s).
+-----> Kitchen is finished. (0m3.31s)
+```
+
+Some real-world migrations are available:
+
+* [docker](https://github.com/chef-cookbooks/docker)
+* [nginx](https://github.com/chef-cookbooks/chef_nginx/pull/5/files)
+* [mysql](https://github.com/chef-cookbooks/mysql/pull/430/files)
+* [php](https://github.com/chef-cookbooks/php/pull/189/files)
+
+Some general recommendations:
+
+* use test-kitchen 1.14+
+* in case of errors, increase the log level `kitchen verify package-install-centos-72 -l debug`
+
+## Do I still need the backend configuration?
+
+InSpec does not attach backend information to test files. All tests are defined independently of any backend. Therefore a Serverspec test file:
+
+```
+require 'serverspec'
+
+# Required by serverspec
+set :backend, :exec
+
+describe 'PHP' do
+  it 'has php' do
+    expect(command('php -v').exit_status).to eq(0)
+  end
+
+  it 'has the pear.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pear.php.net')
+  end
+
+  it 'has the pecl.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pecl.php.net')
+  end
+end
+```
+
+will become the following InSpec test file:
+
+```
+describe 'PHP' do
+  it 'has php' do
+    expect(command('php -v').exit_status).to eq(0)
+  end
+
+  it 'has the pear.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pear.php.net')
+  end
+
+  it 'has the pecl.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pecl.php.net')
+  end
+end
+```
+
+As you can see, the InSpec test files just focuses on tests and tries to avoid all clutter.
+
+## Nested describe blocks
+
+Serverspec and RSpec allow you to define nested describe blocks. We did a survey and found out that most users use nested describe blocks only to improve their output report. We believe the code structure should not change to improve the output of a report. Nevertheless we understand that nested describe blocks help you to structure test code. A sample code block looks like:
+
+```
+describe 'chef-server-directories' do
+  describe file('/etc/opscode') do
+    it { should be_directory }
+    it { should be_owned_by 'root' }
+  end
+
+  describe file('/etc/opscode-analytics') do
+    it { should be_directory }
+    it { should be_owned_by 'opscode' }
+    it { should be_grouped_into 'opscode' }
+  end
+
+  describe file('/var/log/opscode') do
+    it { should be_directory }
+    it { should be_owned_by 'opscode' }
+    it { should be_grouped_into 'opscode' }
+  end
+
+  describe file('/var/opt/opscode') do
+    it { should be_directory }
+    it { should be_owned_by 'root' }
+  end
+end
+```
+
+In InSpec you would split up groups into files.
+
+```
+tests
+├── server-directories.rb
+├── other-tests.rb
+└── further-tests.rb
+```
+
+Each file can have a top-level description of its content:
+
+```
+title "Chef Server Directories"
+
+describe file('/etc/opscode') do
+  it { should be_directory }
+  it { should be_owned_by 'root' }
+end
+
+describe file('/etc/opscode-analytics') do
+  it { should be_directory }
+  it { should be_owned_by 'opscode' }
+  it { should be_grouped_into 'opscode' }
+end
+
+describe file('/var/log/opscode') do
+  it { should be_directory }
+  it { should be_owned_by 'opscode' }
+  it { should be_grouped_into 'opscode' }
+end
+
+describe file('/var/opt/opscode') do
+  it { should be_directory }
+  it { should be_owned_by 'root' }
+end
+
+```
+
+## Are you supporting the `expect` syntax?
+
+Of course. We still prefer the `should` syntax for UX reasons. We did surveys with various types of customers like devops engineers, auditors, managers. All participants who prefered the `expect` syntax have been Ruby experts. All non-Ruby developers found it easier to understand the `should` syntax.
+
+### `should` syntax with InSpec
+
+```
+describe command('php -v') do
+  its('exit_status') { should eq 0 }
+end
+
+describe command('pear list-channels') do
+  its('stdout') { should include('pear.php.net')}
+end
+
+describe command('pear list-channels') do
+  its('stdout') { should include('pecl.php.net')}
+end
+```
+
+### `expect` syntax with InSpec
+
+```
+describe 'PHP' do
+  it 'has php' do
+    expect(command('php -v').exit_status).to eq(0)
+  end
+
+  it 'has the pear.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pear.php.net')
+  end
+
+  it 'has the pecl.php.net channel' do
+    expect(command('pear list-channels').stdout).to include('pecl.php.net')
+  end
+end
+```

data/docs/profiles.md

@@ -17,6 +17,8 @@ A profile should have the following structure::
     │   └── control_etc.rb
     ├── libraries
     │   └── extension.rb
+    |── files
+    │   └── extras.conf
     └── inspec.yml
 
 where:
@@ -24,6 +26,7 @@ where:
 * `inspec.yml` includes the profile description (required)
 * `controls` is the directory in which all tests are located (required)
 * `libraries` is the directory in which all InSpec resource extensions are located (optional)
+* `files` is the directory with additional files that a profile can access (optional)
 * `README.md` should be used to explain the profile, its scope, and usage
 
 See a complete example profile in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile
@@ -98,24 +101,31 @@ and to target all of these examples in a single `inspec.yml` file:
     name: ssh
     supports:
       - os-name: debian
-    supports:
       - os-name: ubuntu
         release: 14.04
-    supports:
       - os-family: redhat
-    supports:
       - platform: aws
 
 
 # Profile 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.
+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.
 
-## Path
+## Defining the Dependencies
 
-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.
+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:
 
-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
+
+InSpec supports a number of dependency sources.
+
+### 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
@@ -123,19 +133,19 @@ For example:
     - 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, tar.gz format). If the download fails, the profile is inaccessible, or not in the correct format, an error is returned.
+### url
 
-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:
 
@@ -147,105 +157,98 @@ 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, 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 `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.
 
 For example:
 
     depends:
     - name: supermarket-profile
-      git: username/profile
-      branch:  desired_branch
-      tag:     desired_version
-      commit:  pinned_commit
-      version: semver_via_tags
+      supermarket: supermarket-username/supermarket-profile
+
+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, 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 `compliance` setting specifies a profile that is located on the Chef Automate or Chef Compliance server.
 
 For example:
 
     depends:
-    - name: gh-profile
-      git: username/project
-      branch:  desired_branch
-      tag:     desired_version
-      commit:  pinned_commit
-      version: semver_via_tags
+      - name: linux
+        compliance: base/linux
 
-## Chef Compliance
+## Vendoring Dependencies
 
-A `compliance` setting specifies a profile that is located on the Chef Compliance server.
+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.
 
-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: linux
-        compliance: base/linux
+## Using Controls from an Included Profile
 
+Once defined in the `inspec.yml`, controls from the included profiles can be used! Let’s look at some examples.
 
-## Define in inspec.yml
+### Including All Controls from a Profile
 
-Use the `depends` setting in the `inspec.yml` file to define any combination of profile dependencies. For example:
+With the `include_controls` command in a profile, all controls from the named profile will be executed every time the including profile is executed.
 
-    depends:
-      - name: ssh-hardening
-        supermarket: hardening/ssh-hardening
-      - 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
-      - name: windows-patch-benchmark
-        git: https://github.com/chris-rock/windows-patch-benchmark.git
-      - name: linux
-        compliance: base/linux
+![Include Controls](/images/profile_inheritance/include_controls.png)
 
-# Profile Inheritance
+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:
 
-When a profile is run, it may include controls that are defined in other profiles. Controls may also be required.
+ * 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:
@@ -262,15 +265,24 @@ Attributes may be used in profiles to define secrets, such as user names and pas
 
 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')
 
-    describe val_user do
-      it { should eq 'bob' }
-    end
+    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
 
-    describe val_password do
-      it { should eq 'secret' }
+      describe val_password do
+        it { should eq 'secret' }
+      end
     end
 
 And a Yaml file named `profile-attribute.yml`:
@@ -283,3 +295,39 @@ The following command runs the tests and applies the secrets specified in `profi
     $ inspec exec examples/profile-attribute --attrs examples/profile-attribute.yml
 
 See the full example in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile-attribute
+
+# Profile files
+
+An InSpec profile may contain additional files that can be accessed during tests. This covers use-cases where e.g. a list of ports is provided to be tested.
+
+To access these files, they must be stored in the `files` directory at the root of a profile. They are accessed by their name relative to this folder with `inspec.profile.file(...)`.
+
+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
+
+With `services.yml` containing:
+
+    - 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
+
+    my_services.each do |s|
+      describe service(s['name']) do
+        it { should be_running }
+      end
+
+      describe port(s['port']) do
+        it { should be_listening }
+      end
+    end