Mirrors/inspec
2
0
Fork 0
mirror of https://github.com/inspec/inspec synced 2024-11-23 13:13:22 +00:00
Code Issues Projects Releases Packages Wiki Activity

merged latest master

Browse source
This commit is contained in:
anniehedgpeth 2016-11-01 15:00:03 -05:00
commit a98dfc93e9
509 changed files with 34203 additions and 9711 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
.delivery/build-cookbook/.kitchen.yml
View file

@ -1,25 +0,0 @@
---
driver:
name: vagrant
synced_folders:
- [<%= File.join(ENV['PWD'], '..', '..')%>, '/tmp/repo-data']
provisioner:
name: chef_zero
encrypted_data_bag_secret_key_path: 'secrets/fakey-mcfakerton'
data_bags_path: './data_bags'
platforms:
- name: ubuntu-14.04
- name: centos-7.1
suites:
- name: default
run_list:
- recipe[delivery_build::default]
- recipe[test]
attributes:
delivery_build:
delivery-cli:
artifact: 'https://delivery-packages.s3.amazonaws.com/cli/delivery-cli-20150706022129-1.x86_64.rpm'
checksum: '96ac99ed01466b8deb8d1c7366f4468dabf2282ad6b2ce7da8bd7edbc6ad673f'

16
.delivery/build-cookbook/Berksfile
View file

@ -1,16 +0,0 @@
# encoding: utf-8
source 'https://supermarket.chef.io'
metadata
cookbook 'delivery-truck',
git: 'https://github.com/chef-cookbooks/delivery-truck.git',
branch: 'master'
cookbook 'delivery-sugar',
git: 'https://github.com/chef-cookbooks/delivery-sugar.git',
branch: 'master'
cookbook 'delivery-sugar-extras',
git: 'https://github.com/chef-cookbooks/delivery-sugar-extras.git',
branch: 'master'

3
.delivery/build-cookbook/LICENSE
View file

@ -1,3 +0,0 @@
Copyright 2015 The Authors
All rights reserved, do not redistribute.

146
.delivery/build-cookbook/README.md
View file

@ -1,146 +0,0 @@
# build-cookbook
A build cookbook for running the parent project through Chef Delivery
This build cookbook should be customized to suit the needs of the parent project. Using this cookbook can be done outside of Chef Delivery, too. If the parent project is a Chef cookbook, we've detected that and "wrapped" [delivery-truck](https://github.com/chef-cookbooks/delivery-truck). That means it is a dependency, and each of its pipeline phase recipes is included in the appropriate phase recipes in this cookbook. If the parent project is not a cookbook, it's left as an exercise to the reader to customize the recipes as needed for each phase in the pipeline.
## .delivery/config.json
In the parent directory to this build-cookbook, the `config.json` can be modified as necessary. For example, phases can be skipped, publishing information can be added, and so on. Refer to customer support or the Chef Delivery documentation for assistance on what options are available for this configuration.
## Test Kitchen - Local Verify Testing
This cookbook also has a `.kitchen.yml` which can be used to create local build nodes with Test Kitchen to perform the verification phases, `unit`, `syntax`, and `lint`. When running `kitchen converge`, the instances will be set up like Chef Delivery "build nodes" with the [delivery_build cookbook](https://github.com/chef-cookbooks/delivery_build). The reason for this is to make sure that the same exact kind of nodes are used by this build cookbook are run on the local workstation as would run Delivery. It will run `delivery job verify PHASE` for the parent project.
Modify the `.kitchen.yml` if necessary to change the platforms or other configuration to run the verify phases. After making changes in the parent project, `cd` into this directory (`.delivery/build-cookbook`), and run:
```
kitchen test
```
## Recipes
Each of the recipes in this build-cookbook are run in the named phase during the Chef Delivery pipeline. The `unit`, `syntax`, and `lint` recipes are additionally run when using Test Kitchen for local testing as noted in the above section.
## Making Changes - Cookbook Example
When making changes in the parent project (that which lives in `../..` from this directory), or in the recipes in this build cookbook, there is a bespoke workflow for Chef Delivery. As an example, we'll discuss a Chef Cookbook as the parent.
First, create a new branch for the changes.
```
git checkout -b testing-build-cookbook
```
Next, increment the version in the metadata.rb. This should be in the *parent*, not in this, the build-cookbook. If this is not done, the verify phase will fail.
```
% git diff
<SNIP>
-version '0.1.0'
+version '0.1.1'
```
The change we'll use for an example is to install the `zsh` package. Write a failing ChefSpec in the cookbook project's `spec/unit/recipes/default_spec.rb`.
```ruby
require 'spec_helper'
describe 'godzilla::default' do
context 'When all attributes are default, on an unspecified platform' do
let(:chef_run) do
runner = ChefSpec::ServerRunner.new
runner.converge(described_recipe)
end
it 'installs zsh' do
expect(chef_run).to install_package('zsh')
end
end
end
```
Commit the local changes as work in progress. The `delivery job` expects to use a clean git repository.
```
git add ../..
git commit -m 'WIP: Testing changes'
```
From *this* directory (`.delivery/build-cookbook`, relative to the parent cookbook project), run
```
cd .delivery/build-cookbook
kitchen converge
```
This will take some time at first, because the VMs need to be created, Chef installed, the Delivery CLI installed, etc. Later runs will be faster until they are destroyed. It will also fail on the first VM, as expected, because we wrote the test first. Now edit the parent cookbook project's default recipe to install `zsh`.
```
cd ../../
$EDITOR/recipes/default.rb
```
It should look like this:
```
package 'zsh'
```
Create another commit.
```
git add .
git commit -m 'WIP: Install zsh in default recipe'
```
Now rerun kitchen from the build-cookbook.
```
cd .delivery/build-cookbook
kitchen converge
```
This will take awhile because it will now pass on the first VM, and then create the second VM. We should have warned you this was a good time for a coffee break.
```
Recipe: test::default
- execute HOME=/home/vagrant delivery job verify unit --server localhost --ent test --org kitchen
* execute[HOME=/home/vagrant delivery job verify lint --server localhost --ent test --org kitchen] action run
- execute HOME=/home/vagrant delivery job verify lint --server localhost --ent test --org kitchen
- execute HOME=/home/vagrant delivery job verify syntax --server localhost --ent test --org kitchen
Running handlers:
Running handlers complete
Chef Client finished, 3/32 resources updated in 54.665445968 seconds
Finished converging <default-centos-71> (1m26.83s).
```
Victory is ours! Our verify phase passed on the build nodes.
We are ready to run this through our Delivery pipeline. Simply run `delivery review` on the local system from the parent project, and it will open a browser window up to the change we just added.
```
cd ../..
delivery review
```
## FAQ
### Why don't I just run rspec, foodcritic/rubocop, knife cookbook test on my local system?
An objection to the Test Kitchen approach is that it is much faster to run the unit, lint, and syntax commands for the project on the local system. That is totally true, and also totally valid. Do that for the really fast feedback loop. However, the dance we do with Test Kitchen brings a much higher degree of confidence in the changes we're making, that everything will run on the build nodes in Chef Delivery. We strongly encourage this approach before actually pushing the changes to Delivery.
### Why do I have to make a commit every time?
When running `delivery job`, it expects to merge the commit for the changeset against the clean master branch. If we don't save our progress by making a commit, our local changes aren't run through `delivery job` in the Test Kitchen build instances. We can always perform an interactive rebase, and modify the original changeset message in Delivery with `delivery review --edit`. The latter won't modify the git commits, only the changeset in Delivery.
### What do I do next?
Make changes in the cookbook project as required for organizational goals and needs. Modify the `build-cookbook` as necessary for the pipeline phases that the cookbook should go through.
### What if I get stuck?
Contact Chef Support, or your Chef Customer Success team and they will help you get unstuck.

97
.delivery/build-cookbook/chefignore
View file

@ -1,97 +0,0 @@
# Put files/directories that should be ignored in this file when uploading
# or sharing to the community site.
# Lines that start with '# ' are comments.
# OS generated files #
######################
.DS_Store
Icon?
nohup.out
ehthumbs.db
Thumbs.db
# SASS #
########
.sass-cache
# EDITORS #
###########
\#*
.#*
*~
*.sw[a-z]
*.bak
REVISION
TAGS*
tmtags
*_flymake.*
*_flymake
*.tmproj
.project
.settings
mkmf.log
## COMPILED ##
##############
a.out
*.o
*.pyc
*.so
*.com
*.class
*.dll
*.exe
*/rdoc/
# Testing #
###########
.watchr
.rspec
spec/*
spec/fixtures/*
test/*
features/*
Guardfile
Procfile
.kitchen/
.kitchen.local.yml
# SCM #
#######
.git
*/.git
.gitignore
.gitmodules
.gitconfig
.gitattributes
.svn
*/.bzr/*
*/.hg/*
*/.svn/*
# Berkshelf #
#############
Berksfile
Berksfile.lock
cookbooks/*
tmp
# Cookbooks #
#############
CONTRIBUTING
# Strainer #
############
Colanderfile
Strainerfile
.colander
.strainer
# Vagrant #
###########
.vagrant
Vagrantfile
# Travis #
##########
.travis.yml

1
.delivery/build-cookbook/data_bags/keys/delivery_builder_keys.json
View file

@ -1 +0,0 @@
{"id": "delivery_builder_keys"}

12
.delivery/build-cookbook/metadata.rb
View file

@ -1,12 +0,0 @@
name 'build-cookbook'
maintainer 'Dominik Richter'
maintainer_email 'drichter@chef.io'
license 'all_rights'
version '0.1.0'
depends 'docker', '~> 1.0'
depends 'fancy_execute'
depends 'chef-sugar'
depends 'delivery-truck'
depends 'delivery-sugar'
depends 'delivery-sugar-extras'

37
.delivery/build-cookbook/recipes/default.rb
View file

@ -1,37 +0,0 @@
# encoding: utf-8
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 Chef Software Inc., All Rights Reserved.
include_recipe 'delivery-truck::default'
# create a persistant gem cache per builder for the entire project
gem_cache = File.join(node['delivery']['workspace']['root'], "../../../project_gem_cache")
directory gem_cache do
# set the owner to the dbuild so that the other recipes can write to here
owner node['delivery_builder']['build_user']
mode "0755"
recursive true
action :create
end
# ensure we always have a docker group with the build user as a member
group 'docker' do
members [node['delivery_builder']['build_user']]
end
package 'build-essential'
# get docker
docker_service 'dockerd' do
action [:create, :start]
host 'unix:///var/run/docker.sock'
group 'docker'
provider Chef::Provider::DockerService::Execute
end
log 'system info' do
message `uname -a; docker --version; ls -lha /var/run/docker.sock`
level :warn
end

5
.delivery/build-cookbook/recipes/deploy.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/functional.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

14
.delivery/build-cookbook/recipes/lint.rb
View file

@ -1,14 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: lint
#
# Copyright (c) 2015 Chef Software Inc., All Rights Reserved.
# Author:: Dominik Richter
include_recipe 'build-cookbook::prepare'
execute 'rubocop' do
command 'bundle exec rake lint'
cwd node['delivery_builder']['repo']
user node['delivery_builder']['build_user']
end

20
.delivery/build-cookbook/recipes/prepare.rb
View file

@ -1,20 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: prepare
#
# Copyright (c) 2015 Chef Software Inc., All Rights Reserved.
# Author:: Dominik Richter
repo_dir = node['delivery_builder']['repo']
cache_dir = File.join(repo_dir, '.cache')
directory cache_dir do
owner node['delivery_builder']['build_user']
mode '0755'
end
execute 'bundle install' do
command "bundle install --path #{cache_dir} --without integration tools maintenance"
cwd repo_dir
user node['delivery_builder']['build_user']
end

5
.delivery/build-cookbook/recipes/provision.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/publish.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/quality.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/security.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/smoke.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

5
.delivery/build-cookbook/recipes/syntax.rb
View file

@ -1,5 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: default
#
# Copyright (c) 2015 The Authors, All Rights Reserved.

22
.delivery/build-cookbook/recipes/unit.rb
View file

@ -1,22 +0,0 @@
#
# Cookbook Name:: build-cookbook
# Recipe:: unit
#
# Copyright (c) 2015 Chef Software Inc., All Rights Reserved.
# Author:: Dominik Richter
include_recipe 'build-cookbook::prepare'
home = node['delivery_builder']['repo']
{
'mock test resources' => 'rake test',
'test resources, main docker images' => 'rake test:resources config=test/test.yaml',
'test resources, extra docker images' => 'rake test:resources config=test/test-extra.yaml',
}.each do |title, test|
execute title do
command 'bundle exec '+test
cwd home
user node['delivery_builder']['build_user']
end
end

2
.delivery/build-cookbook/test/fixtures/cookbooks/test/metadata.rb vendored
View file

@ -1,2 +0,0 @@
name 'test'
version '0.1.0'

7
.delivery/build-cookbook/test/fixtures/cookbooks/test/recipes/default.rb vendored
View file

@ -1,7 +0,0 @@
%w(unit lint syntax).each do |phase|
# TODO: This works on Linux/Unix. Not Windows.
execute "HOME=/home/vagrant delivery job verify #{phase} --server localhost --ent test --org kitchen" do
cwd '/tmp/repo-data'
user 'vagrant'
end
end

22
.delivery/config.json
View file

@ -1,22 +0,0 @@
{
"version": "2",
"build_cookbook": {
"name": "build-cookbook",
"path": ".delivery/build-cookbook"
},
"delivery-truck": {
"publish": {
"github": "chef/vulcanosec"
}
},
"skip_phases": [
"syntax",
"security",
"quality",
"smoke",
"deploy"
],
"build_nodes": {
"unit": ["name:builder-*-7.delivery.chef.co"]
}
}

6
.gitignore vendored
View file

@ -12,3 +12,9 @@ Puppetfile.lock
profile.tar.gz profile.tar.gz
omnibus/.cache omnibus/.cache
omnibus/pkg omnibus/pkg
test/**/*.lock
examples/**/*.lock
habitat/VERSION
habitat/results
/.ruby-gemset
/.ruby-version

7
.kitchen.chef.yml
View file

@ -61,7 +61,14 @@ platforms:
box: chef/solaris-<%= solaris_version %> box: chef/solaris-<%= solaris_version %>
<% end %> <% end %>
<% [ '11-sp2-x86_64' ].each do |sles_version| %>
- name: sles-<%= sles_version %>
driver:
box: chef/sles-<%= sles_version %>
<% end %>
suites: suites:
- name: default - name: default
run_list: run_list:
- recipe[ssh-hardening]
- recipe[os_prepare] - recipe[os_prepare]

34
.travis.yml
View file

@ -7,7 +7,7 @@ cache: bundler
dist: trusty dist: trusty
services: services:
- docker - docker
bundler_args: "--without integration tools maintenance" bundler_args: "--without integration tools maintenance deploy"
before_install: before_install:
- gem install bundler - gem install bundler
- gem update --system 2.4.5 - gem update --system 2.4.5
@ -15,44 +15,48 @@ before_install:
matrix: matrix:
include: include:
- rvm: 1.9.3 - rvm: 1.9.3
- rvm: 2.0 - rvm: 2.1.8
- rvm: 2.2 - rvm: 2.2.5
- rvm: 2.3.1
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE="lint test test:resources config=test/test.yaml" N=2 env: SUITE="lint test test:functional"
- rvm: 2.2 - rvm: 2.3.1
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE="test:functional test:resources config=test/test-extra.yaml" N=2 env: SUITE="test:resources config=test/test.yaml" N=2
- rvm: 2.2 - rvm: 2.3.1
script: bundle exec rake $SUITE
env: SUITE="test:resources config=test/test-extra.yaml" N=2
- rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS=default-ubuntu-1204 DOCKER=true env: SUITE=test:integration OS=default-ubuntu-1204 DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-ubuntu-1604' DOCKER=true env: SUITE=test:integration OS='default-ubuntu-1604' DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-centos-68' DOCKER=true env: SUITE=test:integration OS='default-centos-68' DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-centos-7' DOCKER=true env: SUITE=test:integration OS='default-centos-7' DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-debian-8' DOCKER=true env: SUITE=test:integration OS='default-debian-8' DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-oracle-72' DOCKER=true env: SUITE=test:integration OS='default-oracle-72' DOCKER=true
- rvm: 2.2 - rvm: 2.3.1
bundler_args: "--without guard tools" bundler_args: "--without guard tools"
script: bundle exec rake $SUITE script: bundle exec rake $SUITE
env: SUITE=test:integration OS='default-fedora-24' DOCKER=true env: SUITE=test:integration OS='default-fedora-24' DOCKER=true
allow_failures: allow_failures:
- env: SUITE="lint test test:resources config=test/test.yaml" N=2 - env: SUITE="test:resources config=test/test.yaml" N=2
- env: SUITE="test:functional test:resources config=test/test-extra.yaml" N=2 - env: SUITE="test:resources config=test/test-extra.yaml" N=2
deploy: deploy:
provider: rubygems provider: rubygems

542
CHANGELOG.md
View file

@ -1,7 +1,541 @@
# Change Log # Change Log
## [0.30.0](https://github.com/chef/inspec/tree/0.30.0) (2016-08-12) ## [1.3.0](https://github.com/chef/inspec/tree/1.3.0) (2016-10-28)
[Full Changelog](https://github.com/chef/inspec/compare/v0.29.0...0.30.0) [Full Changelog](https://github.com/chef/inspec/compare/v1.2.1...1.3.0)
**Implemented enhancements:**
- extend the attributes object with helper methods [\#1220](https://github.com/chef/inspec/pull/1220) ([chris-rock](https://github.com/chris-rock))
**Fixed bugs:**
- inetd\_conf resource error [\#1253](https://github.com/chef/inspec/issues/1253)
- Process user should eq \["longusername"\]: usernames get truncated with a '+' at the end [\#995](https://github.com/chef/inspec/issues/995)
- Remove wildcard from windows package detection [\#1259](https://github.com/chef/inspec/pull/1259) ([chris-rock](https://github.com/chris-rock))
- Fix nil timeout and retries [\#1256](https://github.com/chef/inspec/pull/1256) ([alexpop](https://github.com/alexpop))
- Supermarket tools get and filter by tool\_type [\#1254](https://github.com/chef/inspec/pull/1254) ([alexpop](https://github.com/alexpop))
- Fix processes resource user and command truncation [\#1225](https://github.com/chef/inspec/pull/1225) ([alexpop](https://github.com/alexpop))
**Closed issues:**
- inetd and xinetd resources inconsistencies [\#1252](https://github.com/chef/inspec/issues/1252)
- TestKitchen - Duplicate testing when verifier specified in suite definition [\#1240](https://github.com/chef/inspec/issues/1240)
- Document new DCO process in contributing.md [\#1223](https://github.com/chef/inspec/issues/1223)
- Move InSpec Community to https://community-slack.chef.io/ [\#1222](https://github.com/chef/inspec/issues/1222)
- Export Docker package for InSpec from Habitat [\#1212](https://github.com/chef/inspec/issues/1212)
- Test verify action on Windows 2012 fails - \[no implicit conversion of nil into Array\] on default-windows-2012r2 [\#1193](https://github.com/chef/inspec/issues/1193)
- Add InSpec habitat plan [\#843](https://github.com/chef/inspec/issues/843)
**Merged pull requests:**
- Use Slack Badge instead of Gitter badge [\#1262](https://github.com/chef/inspec/pull/1262) ([chris-rock](https://github.com/chris-rock))
- remove accidentally added file [\#1260](https://github.com/chef/inspec/pull/1260) ([chris-rock](https://github.com/chris-rock))
- overwrite exec for inetd because respec its is executing `exec` [\#1257](https://github.com/chef/inspec/pull/1257) ([chris-rock](https://github.com/chris-rock))
- Use include instead of match in the error message [\#1248](https://github.com/chef/inspec/pull/1248) ([artem-sidorenko](https://github.com/artem-sidorenko))
- Code-block directive is not needed here [\#1247](https://github.com/chef/inspec/pull/1247) ([artem-sidorenko](https://github.com/artem-sidorenko))
- Set the global message to display again [\#1246](https://github.com/chef/inspec/pull/1246) ([ryankeairns](https://github.com/ryankeairns))
- Ignore RVM files [\#1245](https://github.com/chef/inspec/pull/1245) ([artem-sidorenko](https://github.com/artem-sidorenko))
- Change global message regarding 10/25 webinar [\#1244](https://github.com/chef/inspec/pull/1244) ([ryankeairns](https://github.com/ryankeairns))
- Fix issue with registry\_key example [\#1243](https://github.com/chef/inspec/pull/1243) ([seththoenen](https://github.com/seththoenen))
- Accessing nested mappings in a yam file [\#1242](https://github.com/chef/inspec/pull/1242) ([chriswessells](https://github.com/chriswessells))
- Fix broken link in README.md [\#1233](https://github.com/chef/inspec/pull/1233) ([swalberg](https://github.com/swalberg))
- DOCS: fix commit amend dash [\#1232](https://github.com/chef/inspec/pull/1232) ([alexpop](https://github.com/alexpop))
- Headers and list elements that include more than one `\_` character we… [\#1231](https://github.com/chef/inspec/pull/1231) ([nathenharvey](https://github.com/nathenharvey))
- Implements profile signing and verification \[Experimental\] [\#1228](https://github.com/chef/inspec/pull/1228) ([metadave](https://github.com/metadave))
- Document new DCO process [\#1224](https://github.com/chef/inspec/pull/1224) ([chris-rock](https://github.com/chris-rock))
- adding by\_user permissions support for windows [\#1215](https://github.com/chef/inspec/pull/1215) ([jeremymv2](https://github.com/jeremymv2))
## [v1.2.1](https://github.com/chef/inspec/tree/v1.2.1) (2016-10-15)
[Full Changelog](https://github.com/chef/inspec/compare/v1.2.0...v1.2.1)
**Implemented enhancements:**
- Show actual value for cmp octal comparisons in string to match expected [\#1211](https://github.com/chef/inspec/pull/1211) ([alexpop](https://github.com/alexpop))
**Fixed bugs:**
- Using "cmp" Against File Mode Fails [\#1188](https://github.com/chef/inspec/issues/1188)
- Unexpected failures with kitchen-inspec and inspec 1.0.0 [\#1187](https://github.com/chef/inspec/issues/1187)
- Rspec deprecation warnings added to test summary creating invalid json file [\#952](https://github.com/chef/inspec/issues/952)
- update train to fix empty target URIs [\#1221](https://github.com/chef/inspec/pull/1221) ([arlimus](https://github.com/arlimus))
**Closed issues:**
- www: typo on inspec.io [\#1197](https://github.com/chef/inspec/issues/1197)
**Merged pull requests:**
- move Inspec Habitat package to chef/inspec. [\#1216](https://github.com/chef/inspec/pull/1216) ([metadave](https://github.com/metadave))
- fix kitchen-inspec integration-1187 [\#1213](https://github.com/chef/inspec/pull/1213) ([vjeffrey](https://github.com/vjeffrey))
- Website: Fix typo in homepage code image [\#1210](https://github.com/chef/inspec/pull/1210) ([magwalk](https://github.com/magwalk))
## [v1.2.0](https://github.com/chef/inspec/tree/v1.2.0) (2016-10-10)
[Full Changelog](https://github.com/chef/inspec/compare/v1.1.0...v1.2.0)
**Implemented enhancements:**
- Support of linux mint or OS detection via distro families [\#280](https://github.com/chef/inspec/issues/280)
- Support of Linux Mint [\#1209](https://github.com/chef/inspec/pull/1209) ([artem-sidorenko](https://github.com/artem-sidorenko))
**Fixed bugs:**
- Online tutorial: weird behavior with backspace, invalid commands [\#1184](https://github.com/chef/inspec/issues/1184)
- parse\_config and parse\_config\_file does not show fully info when test fails \(or even if it succedes\) [\#1147](https://github.com/chef/inspec/issues/1147)
- www: Online tutorial: safari inspec online demo bug! [\#1086](https://github.com/chef/inspec/issues/1086)
- cmp code\_desc missing operation and expected valid [\#1204](https://github.com/chef/inspec/pull/1204) ([alexpop](https://github.com/alexpop))
**Closed issues:**
- Resources on `http://inspec.io/docs/reference/resources/` are not in alphabetical order [\#1195](https://github.com/chef/inspec/issues/1195)
- www: Online tutorial: update inspec tutorial to 1.0.0 version [\#1169](https://github.com/chef/inspec/issues/1169)
**Merged pull requests:**
- fix backspace bug [\#1206](https://github.com/chef/inspec/pull/1206) ([vjeffrey](https://github.com/vjeffrey))
- es5. that is a thing. [\#1191](https://github.com/chef/inspec/pull/1191) ([vjeffrey](https://github.com/vjeffrey))
- tutorial response filename length [\#1159](https://github.com/chef/inspec/pull/1159) ([chris-rock](https://github.com/chris-rock))
## [v1.1.0](https://github.com/chef/inspec/tree/v1.1.0) (2016-10-05)
[Full Changelog](https://github.com/chef/inspec/compare/v1.0.0...v1.1.0)
**Fixed bugs:**
- InSpec in Visibility [\#1117](https://github.com/chef/inspec/issues/1117)
- inspec exec on tar.gz with local library requirements doesn't work [\#779](https://github.com/chef/inspec/issues/779)
- parse\_config\_file fails when it encounters a '\[' [\#687](https://github.com/chef/inspec/issues/687)
- use mock backend for inspec vendor/check/json [\#1202](https://github.com/chef/inspec/pull/1202) ([arlimus](https://github.com/arlimus))
- bugfix: support nil entries in filter table [\#1201](https://github.com/chef/inspec/pull/1201) ([arlimus](https://github.com/arlimus))
- bugfix: always use the mock backend for inspec archive [\#1200](https://github.com/chef/inspec/pull/1200) ([arlimus](https://github.com/arlimus))
- Missing registry keys should not exist [\#1199](https://github.com/chef/inspec/pull/1199) ([alexpop](https://github.com/alexpop))
- bugfix: use correct logger in cli [\#1198](https://github.com/chef/inspec/pull/1198) ([arlimus](https://github.com/arlimus))
**Closed issues:**
- registry\_key ignores failed Get-Item, always "exists" [\#1196](https://github.com/chef/inspec/issues/1196)
- www: Online tutorial doesn't load \(not building\) [\#1182](https://github.com/chef/inspec/issues/1182)
- Issue locally running an inspec check on a service resource [\#1176](https://github.com/chef/inspec/issues/1176)
- Demo at `http://inspec.io/` stuck on `Loading` [\#1165](https://github.com/chef/inspec/issues/1165)
- Confusing reporter output with inherited profiles [\#1071](https://github.com/chef/inspec/issues/1071)
- Provide clear error message if dependency is not available [\#1069](https://github.com/chef/inspec/issues/1069)
- Dependencies: Design UX for scoping of attributes and resources [\#1057](https://github.com/chef/inspec/issues/1057)
- RFC Dependencies [\#888](https://github.com/chef/inspec/issues/888)
**Merged pull requests:**
- Remove pre-1.0 warning from meta-profile [\#1194](https://github.com/chef/inspec/pull/1194) ([chris-rock](https://github.com/chris-rock))
- Add shell options [\#1192](https://github.com/chef/inspec/pull/1192) ([jonathanmorley](https://github.com/jonathanmorley))
- Website: Fix buggy behavior in nav and add global message [\#1190](https://github.com/chef/inspec/pull/1190) ([magwalk](https://github.com/magwalk))
- add example for yumconf-like structured files [\#1185](https://github.com/chef/inspec/pull/1185) ([vjeffrey](https://github.com/vjeffrey))
- add sanity checks and fail build process if requirements aren't met [\#1183](https://github.com/chef/inspec/pull/1183) ([arlimus](https://github.com/arlimus))
- tp/learn links [\#1181](https://github.com/chef/inspec/pull/1181) ([tpetchel](https://github.com/tpetchel))
- include control section in instructions [\#1180](https://github.com/chef/inspec/pull/1180) ([vjeffrey](https://github.com/vjeffrey))
- Changing headings to align with SEO best practices [\#1179](https://github.com/chef/inspec/pull/1179) ([davidwrede](https://github.com/davidwrede))
- move inquirer to deploy [\#1178](https://github.com/chef/inspec/pull/1178) ([vjeffrey](https://github.com/vjeffrey))
- Ignore lockfiles in example profiles [\#1177](https://github.com/chef/inspec/pull/1177) ([stevendanna](https://github.com/stevendanna))
- Remove default parameter in `updateInstructions\(\)` [\#1175](https://github.com/chef/inspec/pull/1175) ([jerryaldrichiii](https://github.com/jerryaldrichiii))
- Website: Fix docs nav functionality and optimize for mobile [\#1174](https://github.com/chef/inspec/pull/1174) ([magwalk](https://github.com/magwalk))
- Adds segment [\#1172](https://github.com/chef/inspec/pull/1172) ([cwebberOps](https://github.com/cwebberOps))
- print profile info before test results \(inherited profiles\) [\#1170](https://github.com/chef/inspec/pull/1170) ([vjeffrey](https://github.com/vjeffrey))
- www: fix wording [\#1168](https://github.com/chef/inspec/pull/1168) ([arlimus](https://github.com/arlimus))
- Update dependency documentation and mention the lockfile [\#1167](https://github.com/chef/inspec/pull/1167) ([alexpop](https://github.com/alexpop))
## [v1.0.0](https://github.com/chef/inspec/tree/v1.0.0) (2016-09-26)
[Full Changelog](https://github.com/chef/inspec/compare/v1.0.0.beta3...v1.0.0)
**Implemented enhancements:**
- InSpec OS package [\#646](https://github.com/chef/inspec/issues/646)
- replace wmi win32\_useraccount with adsi users [\#1149](https://github.com/chef/inspec/pull/1149) ([chris-rock](https://github.com/chris-rock))
**Fixed bugs:**
- README.md has broken link to non-existent file [\#1136](https://github.com/chef/inspec/issues/1136)
**Merged pull requests:**
- update omnibus images [\#1164](https://github.com/chef/inspec/pull/1164) ([chris-rock](https://github.com/chris-rock))
- website / tutorial interaction [\#1163](https://github.com/chef/inspec/pull/1163) ([chris-rock](https://github.com/chris-rock))
- fix buttons on community page [\#1162](https://github.com/chef/inspec/pull/1162) ([arlimus](https://github.com/arlimus))
- fix alignment of community buttons [\#1161](https://github.com/chef/inspec/pull/1161) ([arlimus](https://github.com/arlimus))
- Fix require\_controls DSL method [\#1160](https://github.com/chef/inspec/pull/1160) ([stevendanna](https://github.com/stevendanna))
- Document the require\_resource function [\#1158](https://github.com/chef/inspec/pull/1158) ([stevendanna](https://github.com/stevendanna))
- fix css in docs search [\#1157](https://github.com/chef/inspec/pull/1157) ([arlimus](https://github.com/arlimus))
- update www readme for releasing the site [\#1156](https://github.com/chef/inspec/pull/1156) ([arlimus](https://github.com/arlimus))
- Fix minor typo in sys\_info documentation [\#1155](https://github.com/chef/inspec/pull/1155) ([stevendanna](https://github.com/stevendanna))
- fix outdated link in readme [\#1154](https://github.com/chef/inspec/pull/1154) ([arlimus](https://github.com/arlimus))
- fix minor website bugs [\#1153](https://github.com/chef/inspec/pull/1153) ([arlimus](https://github.com/arlimus))
- clean www before releasing [\#1152](https://github.com/chef/inspec/pull/1152) ([arlimus](https://github.com/arlimus))
- add docs to the website [\#1151](https://github.com/chef/inspec/pull/1151) ([arlimus](https://github.com/arlimus))
- return empty array for known privileges [\#1150](https://github.com/chef/inspec/pull/1150) ([chris-rock](https://github.com/chris-rock))
- Extend example for parse\_config.rb [\#1148](https://github.com/chef/inspec/pull/1148) ([nvtkaszpir](https://github.com/nvtkaszpir))
- Bump lockfile version to 1.0 [\#1141](https://github.com/chef/inspec/pull/1141) ([stevendanna](https://github.com/stevendanna))
- Improve error messages from compliance fetcher [\#1126](https://github.com/chef/inspec/pull/1126) ([stevendanna](https://github.com/stevendanna))
## [v1.0.0.beta3](https://github.com/chef/inspec/tree/v1.0.0.beta3) (2016-09-25)
[Full Changelog](https://github.com/chef/inspec/compare/v1.0.0.beta2...v1.0.0.beta3)
**Implemented enhancements:**
- Improve lockfile handling [\#1070](https://github.com/chef/inspec/issues/1070)
- Show skip\_message and correct title [\#1109](https://github.com/chef/inspec/pull/1109) ([alexpop](https://github.com/alexpop))
**Fixed bugs:**
- InSpec CLI output not showing skip message when control title is defined [\#1097](https://github.com/chef/inspec/issues/1097)
- bugfix: there is one more button to start the online demo [\#1140](https://github.com/chef/inspec/pull/1140) ([arlimus](https://github.com/arlimus))
**Closed issues:**
- add docs to inspec.io [\#1119](https://github.com/chef/inspec/issues/1119)
- Cache key for dependencies needs to be based on content hash for urls [\#1066](https://github.com/chef/inspec/issues/1066)
**Merged pull requests:**
- Enable builds on both Windows and \*nix [\#1145](https://github.com/chef/inspec/pull/1145) ([scotthain](https://github.com/scotthain))
- Website: Minor edits in preparation for launch [\#1144](https://github.com/chef/inspec/pull/1144) ([magwalk](https://github.com/magwalk))
- Truncate long filename. Temporary fix [\#1143](https://github.com/chef/inspec/pull/1143) ([stevendanna](https://github.com/stevendanna))
- add variables to each loops [\#1142](https://github.com/chef/inspec/pull/1142) ([chris-rock](https://github.com/chris-rock))
- embed tutorial in website [\#1139](https://github.com/chef/inspec/pull/1139) ([arlimus](https://github.com/arlimus))
- scope all tutorial assets [\#1138](https://github.com/chef/inspec/pull/1138) ([arlimus](https://github.com/arlimus))
- add build task for online tutorial with all assets [\#1137](https://github.com/chef/inspec/pull/1137) ([arlimus](https://github.com/arlimus))
- implement filter table for group/groups resource [\#1135](https://github.com/chef/inspec/pull/1135) ([chris-rock](https://github.com/chris-rock))
- fix minor typos in user resource [\#1134](https://github.com/chef/inspec/pull/1134) ([chris-rock](https://github.com/chris-rock))
- Website Copy Edits [\#1133](https://github.com/chef/inspec/pull/1133) ([magwalk](https://github.com/magwalk))
- add build tasks for www [\#1132](https://github.com/chef/inspec/pull/1132) ([arlimus](https://github.com/arlimus))
- add resources.md doc generation [\#1130](https://github.com/chef/inspec/pull/1130) ([arlimus](https://github.com/arlimus))
- add all resources to docs [\#1129](https://github.com/chef/inspec/pull/1129) ([arlimus](https://github.com/arlimus))
- reorder and fix sidebar contents for docs [\#1128](https://github.com/chef/inspec/pull/1128) ([arlimus](https://github.com/arlimus))
- add ruby usage in inspec as markdown [\#1127](https://github.com/chef/inspec/pull/1127) ([arlimus](https://github.com/arlimus))
- Add markdown docs [\#1125](https://github.com/chef/inspec/pull/1125) ([arlimus](https://github.com/arlimus))
- Avoid spurious downloads during dependency management [\#1124](https://github.com/chef/inspec/pull/1124) ([stevendanna](https://github.com/stevendanna))
- Website Design Fixes [\#1123](https://github.com/chef/inspec/pull/1123) ([magwalk](https://github.com/magwalk))
## [v1.0.0.beta2](https://github.com/chef/inspec/tree/v1.0.0.beta2) (2016-09-22)
[Full Changelog](https://github.com/chef/inspec/compare/v1.0.0.pre.beta1...v1.0.0.beta2)
**Implemented enhancements:**
- kernel\_parameter does not show fully info when test fails [\#1093](https://github.com/chef/inspec/issues/1093)
- InSpec html demo [\#851](https://github.com/chef/inspec/issues/851)
- Counting and status of controls without tests [\#849](https://github.com/chef/inspec/issues/849)
- supports does not mark resources as skipped [\#354](https://github.com/chef/inspec/issues/354)
- `include Inspec::DSL` anywhere [\#271](https://github.com/chef/inspec/issues/271)
- Suse Support [\#113](https://github.com/chef/inspec/issues/113)
- Update the username and password login method [\#1095](https://github.com/chef/inspec/pull/1095) ([alexpop](https://github.com/alexpop))
**Fixed bugs:**
- InSpec in Workflow [\#1115](https://github.com/chef/inspec/issues/1115)
- uninstalled package shows as installed [\#1092](https://github.com/chef/inspec/issues/1092)
- undefined method `send\_request' for Compliance::API:Class [\#1088](https://github.com/chef/inspec/issues/1088)
- \[package\] Regression on Windows 2008R2 [\#998](https://github.com/chef/inspec/issues/998)
- \[script\] Is there a limit on the number of char's within a script block [\#539](https://github.com/chef/inspec/issues/539)
- Use parenthesis when passing regular expressions [\#1106](https://github.com/chef/inspec/pull/1106) ([alexpop](https://github.com/alexpop))
- Include code description in the output of failed controls [\#1096](https://github.com/chef/inspec/pull/1096) ([alexpop](https://github.com/alexpop))
- Update the username and password login method [\#1095](https://github.com/chef/inspec/pull/1095) ([alexpop](https://github.com/alexpop))
**Closed issues:**
- Package Resource isn't searching 64-bit Registry Hives [\#1100](https://github.com/chef/inspec/issues/1100)
- demo improvements [\#1089](https://github.com/chef/inspec/issues/1089)
- Dependencies: All resources are scoped [\#1058](https://github.com/chef/inspec/issues/1058)
- Improve InSpec tutorial [\#1045](https://github.com/chef/inspec/issues/1045)
- 1.10.2 has an extra space in pip package output [\#1043](https://github.com/chef/inspec/issues/1043)
- Follow up to 1013: find\_files\(\) errors still occurring for apache\_conf resource after 0.33.0 upgrade [\#1030](https://github.com/chef/inspec/issues/1030)
- MVP in-browser inspec demo [\#957](https://github.com/chef/inspec/issues/957)
- Failing tests in inherited tests are not displayed [\#899](https://github.com/chef/inspec/issues/899)
**Merged pull requests:**
- Use the gem version for the omnibus package version [\#1122](https://github.com/chef/inspec/pull/1122) ([yzl](https://github.com/yzl))
- Add legal pages [\#1121](https://github.com/chef/inspec/pull/1121) ([magwalk](https://github.com/magwalk))
- update docs to markdown [\#1120](https://github.com/chef/inspec/pull/1120) ([arlimus](https://github.com/arlimus))
- add readme to www-build [\#1118](https://github.com/chef/inspec/pull/1118) ([arlimus](https://github.com/arlimus))
- Always write lockfiles for local top-level profiles [\#1116](https://github.com/chef/inspec/pull/1116) ([stevendanna](https://github.com/stevendanna))
- Add `--cache` option to `inspec exec` [\#1113](https://github.com/chef/inspec/pull/1113) ([stevendanna](https://github.com/stevendanna))
- fix double-space in pip to\_s resource [\#1112](https://github.com/chef/inspec/pull/1112) ([chris-rock](https://github.com/chris-rock))
- fixes debian package manager and some of the code examples [\#1111](https://github.com/chef/inspec/pull/1111) ([Anirudh-Gupta](https://github.com/Anirudh-Gupta))
- Add main site footer [\#1110](https://github.com/chef/inspec/pull/1110) ([magwalk](https://github.com/magwalk))
- Add community and tutorials pages [\#1108](https://github.com/chef/inspec/pull/1108) ([magwalk](https://github.com/magwalk))
- Add homepage content and styles [\#1107](https://github.com/chef/inspec/pull/1107) ([magwalk](https://github.com/magwalk))
- Styling setup and main navigation [\#1105](https://github.com/chef/inspec/pull/1105) ([magwalk](https://github.com/magwalk))
- docs task and rst/md formatter separation [\#1104](https://github.com/chef/inspec/pull/1104) ([arlimus](https://github.com/arlimus))
- Fail if a remote source content doesn't match lockfile [\#1103](https://github.com/chef/inspec/pull/1103) ([stevendanna](https://github.com/stevendanna))
- Optimize tutorial [\#1101](https://github.com/chef/inspec/pull/1101) ([chris-rock](https://github.com/chris-rock))
- Build with master of omnibus [\#1099](https://github.com/chef/inspec/pull/1099) ([yzl](https://github.com/yzl))
- use Gem::Version instead of a regular expression for a test version bump [\#1098](https://github.com/chef/inspec/pull/1098) ([chris-rock](https://github.com/chris-rock))
- fix demo instructions [\#1094](https://github.com/chef/inspec/pull/1094) ([vjeffrey](https://github.com/vjeffrey))
- Allow users to reference resources from dependencies [\#1080](https://github.com/chef/inspec/pull/1080) ([stevendanna](https://github.com/stevendanna))
- In ApacheConf\#include\_files, check for abs paths [\#1042](https://github.com/chef/inspec/pull/1042) ([davidcpell](https://github.com/davidcpell))
## [v1.0.0.pre.beta1](https://github.com/chef/inspec/tree/v1.0.0.pre.beta1) (2016-09-19)
[Full Changelog](https://github.com/chef/inspec/compare/v0.35.0...v1.0.0.pre.beta1)
**Implemented enhancements:**
- InSpec output for summary needs to count controls [\#852](https://github.com/chef/inspec/issues/852)
- ssl resource to use inspec.backend.hostname and require train 0.19.1 [\#1084](https://github.com/chef/inspec/pull/1084) ([alexpop](https://github.com/alexpop))
- optimize command simulator auto-generation [\#1078](https://github.com/chef/inspec/pull/1078) ([chris-rock](https://github.com/chris-rock))
**Closed issues:**
- proper scrolling of terminal [\#1053](https://github.com/chef/inspec/issues/1053)
**Merged pull requests:**
- fix inspec shell handling [\#1090](https://github.com/chef/inspec/pull/1090) ([vjeffrey](https://github.com/vjeffrey))
- update responses [\#1087](https://github.com/chef/inspec/pull/1087) ([vjeffrey](https://github.com/vjeffrey))
- print profile summary and test summary [\#1083](https://github.com/chef/inspec/pull/1083) ([vjeffrey](https://github.com/vjeffrey))
- Fix minor typo in documentation [\#1082](https://github.com/chef/inspec/pull/1082) ([Dispader](https://github.com/Dispader))
- uglify wepack content, kudos @chris-rock [\#1081](https://github.com/chef/inspec/pull/1081) ([arlimus](https://github.com/arlimus))
- Static keys in all json [\#811](https://github.com/chef/inspec/pull/811) ([arlimus](https://github.com/arlimus))
## [v0.35.0](https://github.com/chef/inspec/tree/v0.35.0) (2016-09-16)
[Full Changelog](https://github.com/chef/inspec/compare/v0.34.1...v0.35.0)
**Fixed bugs:**
- resource dsl not loded properly inside describe blocks [\#1074](https://github.com/chef/inspec/issues/1074)
**Closed issues:**
- online demo: check style of tutorial text [\#1054](https://github.com/chef/inspec/issues/1054)
- online demo: clear \(linux\) and cls \(windows\) command to clear the terminal [\#1052](https://github.com/chef/inspec/issues/1052)
- respect inspec.yml supports with include\_controls [\#1049](https://github.com/chef/inspec/issues/1049)
- Simplify dependency in inspec.yml [\#1048](https://github.com/chef/inspec/issues/1048)
**Merged pull requests:**
- Process transitive dependencies from lock file [\#1079](https://github.com/chef/inspec/pull/1079) ([stevendanna](https://github.com/stevendanna))
- Don't gpg-sign commits during tests [\#1077](https://github.com/chef/inspec/pull/1077) ([stevendanna](https://github.com/stevendanna))
- Ensure resources are visible inside its blocks [\#1076](https://github.com/chef/inspec/pull/1076) ([stevendanna](https://github.com/stevendanna))
- add gulp build pipeline to online demo [\#1075](https://github.com/chef/inspec/pull/1075) ([arlimus](https://github.com/arlimus))
- inspec simulator [\#1073](https://github.com/chef/inspec/pull/1073) ([chris-rock](https://github.com/chris-rock))
- Skip controls from profiles that don't support the current platform [\#1072](https://github.com/chef/inspec/pull/1072) ([stevendanna](https://github.com/stevendanna))
- add tutorials \(references\) to the site skeleton [\#1068](https://github.com/chef/inspec/pull/1068) ([arlimus](https://github.com/arlimus))
- Vj/improve demo [\#1065](https://github.com/chef/inspec/pull/1065) ([vjeffrey](https://github.com/vjeffrey))
- Provide inspec.yml shortcut syntax [\#1064](https://github.com/chef/inspec/pull/1064) ([stevendanna](https://github.com/stevendanna))
## [v0.34.1](https://github.com/chef/inspec/tree/v0.34.1) (2016-09-13)
[Full Changelog](https://github.com/chef/inspec/compare/v0.34.0...v0.34.1)
**Fixed bugs:**
- Force encoding in bin only [\#1062](https://github.com/chef/inspec/pull/1062) ([chris-rock](https://github.com/chris-rock))
**Merged pull requests:**
- Fixup rubocop violation in www/ [\#1067](https://github.com/chef/inspec/pull/1067) ([stevendanna](https://github.com/stevendanna))
- add homepage skeleton [\#1063](https://github.com/chef/inspec/pull/1063) ([arlimus](https://github.com/arlimus))
## [v0.34.0](https://github.com/chef/inspec/tree/v0.34.0) (2016-09-12)
[Full Changelog](https://github.com/chef/inspec/compare/v0.33.2...v0.34.0)
**Implemented enhancements:**
- Vendor Github and Supermarket dependencies [\#959](https://github.com/chef/inspec/issues/959)
- use simple config for security policy resource [\#1044](https://github.com/chef/inspec/pull/1044) ([chris-rock](https://github.com/chris-rock))
- identify enabled/disabled accounts for windows [\#1039](https://github.com/chef/inspec/pull/1039) ([chris-rock](https://github.com/chris-rock))
**Closed issues:**
- Compliance should allow the ability to upload the unconverted SCAP profiles from the agencies. [\#1055](https://github.com/chef/inspec/issues/1055)
- Multiple matchers in a describe block display only a single line [\#1025](https://github.com/chef/inspec/issues/1025)
- Create all content for inspec homepage demo [\#1021](https://github.com/chef/inspec/issues/1021)
- User resource should use Filtertable [\#948](https://github.com/chef/inspec/issues/948)
**Merged pull requests:**
- rename example to meta-profile [\#1051](https://github.com/chef/inspec/pull/1051) ([chris-rock](https://github.com/chris-rock))
- fix webpack start script for tutorial [\#1050](https://github.com/chef/inspec/pull/1050) ([vjeffrey](https://github.com/vjeffrey))
- Add Inspec::Fetcher\#relative\_target for compatibility [\#1046](https://github.com/chef/inspec/pull/1046) ([stevendanna](https://github.com/stevendanna))
- Typo supermarket -\> compliance [\#1041](https://github.com/chef/inspec/pull/1041) ([stevendanna](https://github.com/stevendanna))
- Improve duplicate and cycle detection in resolver [\#1038](https://github.com/chef/inspec/pull/1038) ([stevendanna](https://github.com/stevendanna))
- Add example of corporate profile [\#1037](https://github.com/chef/inspec/pull/1037) ([stevendanna](https://github.com/stevendanna))
- Ensure simplecov starts before everything else [\#1036](https://github.com/chef/inspec/pull/1036) ([stevendanna](https://github.com/stevendanna))
- add sys\_info resource to get information about the hostname [\#1035](https://github.com/chef/inspec/pull/1035) ([chris-rock](https://github.com/chris-rock))
- Add GitFetcher and rework Fetchers+SourceReaders [\#1034](https://github.com/chef/inspec/pull/1034) ([stevendanna](https://github.com/stevendanna))
- add demo content [\#1033](https://github.com/chef/inspec/pull/1033) ([vjeffrey](https://github.com/vjeffrey))
- add health graphs [\#1032](https://github.com/chef/inspec/pull/1032) ([arlimus](https://github.com/arlimus))
- fix table formatting in readme [\#1031](https://github.com/chef/inspec/pull/1031) ([arlimus](https://github.com/arlimus))
- remove old delivery tests [\#1029](https://github.com/chef/inspec/pull/1029) ([arlimus](https://github.com/arlimus))
- make demo better [\#1015](https://github.com/chef/inspec/pull/1015) ([vjeffrey](https://github.com/vjeffrey))
- user resource should support filtertable [\#990](https://github.com/chef/inspec/pull/990) ([ksubrama](https://github.com/ksubrama))
## [v0.33.2](https://github.com/chef/inspec/tree/v0.33.2) (2016-09-07)
[Full Changelog](https://github.com/chef/inspec/compare/v0.33.1...v0.33.2)
**Implemented enhancements:**
- ssl resource fix and speed improvement [\#1027](https://github.com/chef/inspec/pull/1027) ([alexpop](https://github.com/alexpop))
- allow direct access to iis configuration parameters [\#1020](https://github.com/chef/inspec/pull/1020) ([chris-rock](https://github.com/chris-rock))
**Fixed bugs:**
- ssl resource fix and speed improvement [\#1027](https://github.com/chef/inspec/pull/1027) ([alexpop](https://github.com/alexpop))
## [v0.33.1](https://github.com/chef/inspec/tree/v0.33.1) (2016-09-07)
[Full Changelog](https://github.com/chef/inspec/compare/v0.33.0...v0.33.1)
**Closed issues:**
- Research: determine mechanism for recording + playing back inspec [\#955](https://github.com/chef/inspec/issues/955)
- Create content for interactive inspec online demo [\#954](https://github.com/chef/inspec/issues/954)
**Merged pull requests:**
- Pass attributes from command line into profile context [\#1026](https://github.com/chef/inspec/pull/1026) ([stevendanna](https://github.com/stevendanna))
- Remove SourceReader::Inspec\#prepare\_load\_path [\#1023](https://github.com/chef/inspec/pull/1023) ([stevendanna](https://github.com/stevendanna))
- add demo yml contents [\#1022](https://github.com/chef/inspec/pull/1022) ([arlimus](https://github.com/arlimus))
## [v0.33.0](https://github.com/chef/inspec/tree/v0.33.0) (2016-09-05)
[Full Changelog](https://github.com/chef/inspec/compare/v0.32.0...v0.33.0)
**Implemented enhancements:**
- Introduce scoping to the ProfileContext which has a view of all of its dependencies [\#958](https://github.com/chef/inspec/issues/958)
- Create Help for Subcommands [\#305](https://github.com/chef/inspec/issues/305)
- Allow service resource to accept Windows service name with spaces [\#1003](https://github.com/chef/inspec/pull/1003) ([martinheg](https://github.com/martinheg))
**Fixed bugs:**
- Error output not informative [\#1016](https://github.com/chef/inspec/issues/1016)
- Suse Linux Enterprise Server 11 SPX is failing for describe service resource. [\#997](https://github.com/chef/inspec/issues/997)
- Inspec Docker directory test fails [\#996](https://github.com/chef/inspec/issues/996)
- package\(\) 'version' {should match\(pattern\)} does not return failed control, but shows as failed test [\#898](https://github.com/chef/inspec/issues/898)
- Raise error when an invalid URI is received [\#1019](https://github.com/chef/inspec/pull/1019) ([alexpop](https://github.com/alexpop))
- Fix os exception in mysql resource [\#1012](https://github.com/chef/inspec/pull/1012) ([alexpop](https://github.com/alexpop))
- cmp not treating 0 as integer only as string [\#991](https://github.com/chef/inspec/pull/991) ([jeremymv2](https://github.com/jeremymv2))
**Closed issues:**
- apache\_conf resource seems to be using incorrect paths to amalgamate apache config \(only Centos/RHEL?\) [\#1013](https://github.com/chef/inspec/issues/1013)
- More options link in Readme.md doesn't work \(404\) - need updating? [\#1001](https://github.com/chef/inspec/issues/1001)
- Chef compliance breaks after updating inspec gem 0.32 [\#992](https://github.com/chef/inspec/issues/992)
- Improve CLI report [\#984](https://github.com/chef/inspec/issues/984)
- record inspec + in-browser playback for online demo [\#956](https://github.com/chef/inspec/issues/956)
- UX & UI design for the interactive HTML demo [\#953](https://github.com/chef/inspec/issues/953)
**Merged pull requests:**
- use winrm v2 [\#1018](https://github.com/chef/inspec/pull/1018) ([chris-rock](https://github.com/chris-rock))
- always display error message [\#1017](https://github.com/chef/inspec/pull/1017) ([chris-rock](https://github.com/chris-rock))
- Fix apache conf [\#1014](https://github.com/chef/inspec/pull/1014) ([jeremymv2](https://github.com/jeremymv2))
- fix cli inherited profiles [\#1008](https://github.com/chef/inspec/pull/1008) ([vjeffrey](https://github.com/vjeffrey))
- improve suse 11 support for service resource [\#1007](https://github.com/chef/inspec/pull/1007) ([chris-rock](https://github.com/chris-rock))
- Extend Inspec DSL docs [\#1006](https://github.com/chef/inspec/pull/1006) ([nvtkaszpir](https://github.com/nvtkaszpir))
- vj/fix cli report [\#1004](https://github.com/chef/inspec/pull/1004) ([vjeffrey](https://github.com/vjeffrey))
- fix cli link to docs [\#1002](https://github.com/chef/inspec/pull/1002) ([chris-rock](https://github.com/chris-rock))
- Promote cmp usage as it provides results with octal mode [\#999](https://github.com/chef/inspec/pull/999) ([alexpop](https://github.com/alexpop))
- Initial attempt at isolating resources between dependencies [\#994](https://github.com/chef/inspec/pull/994) ([stevendanna](https://github.com/stevendanna))
- inspec demo [\#989](https://github.com/chef/inspec/pull/989) ([vjeffrey](https://github.com/vjeffrey))
- Allow functional tests to pass on OSX [\#988](https://github.com/chef/inspec/pull/988) ([stevendanna](https://github.com/stevendanna))
- Minor refactor and explanatory comments [\#987](https://github.com/chef/inspec/pull/987) ([stevendanna](https://github.com/stevendanna))
## [v0.32.0](https://github.com/chef/inspec/tree/v0.32.0) (2016-08-26)
[Full Changelog](https://github.com/chef/inspec/compare/v0.31.0...v0.32.0)
**Implemented enhancements:**
- Provide SSL InSpec with full demo [\#903](https://github.com/chef/inspec/issues/903)
- improve package resource on windows [\#86](https://github.com/chef/inspec/issues/86)
- can check windows service startup mode now [\#968](https://github.com/chef/inspec/pull/968) ([Anirudh-Gupta](https://github.com/Anirudh-Gupta))
- Resolved an issue checking ports on windows [\#962](https://github.com/chef/inspec/pull/962) ([chris-rock](https://github.com/chris-rock))
**Fixed bugs:**
- Grouping multiple `it` blocks in one `describe` blocks ruins console output during test runs [\#918](https://github.com/chef/inspec/issues/918)
- Windows default path format causes errors with inspec check [\#672](https://github.com/chef/inspec/issues/672)
- bugfix windows forward slashes handling [\#963](https://github.com/chef/inspec/pull/963) ([chris-rock](https://github.com/chris-rock))
- Fix command evaluation for inspec shell -c [\#943](https://github.com/chef/inspec/pull/943) ([ksubrama](https://github.com/ksubrama))
**Closed issues:**
- Support sid for user resource [\#960](https://github.com/chef/inspec/issues/960)
- Create and load Lockfiles for dependencies [\#950](https://github.com/chef/inspec/issues/950)
- Implement test cases for inspec shell [\#942](https://github.com/chef/inspec/issues/942)
- Transitive dependency loading [\#915](https://github.com/chef/inspec/issues/915)
- Document InSpec OR features [\#853](https://github.com/chef/inspec/issues/853)
- Document ini resource [\#848](https://github.com/chef/inspec/issues/848)
- Document special service resources [\#495](https://github.com/chef/inspec/issues/495)
**Merged pull requests:**
- Reformat service resource docs for discoverability [\#986](https://github.com/chef/inspec/pull/986) ([stevendanna](https://github.com/stevendanna))
- Generate documentation for the `vendor` command [\#985](https://github.com/chef/inspec/pull/985) ([stevendanna](https://github.com/stevendanna))
- suport for ruby 2.2.2 [\#983](https://github.com/chef/inspec/pull/983) ([chris-rock](https://github.com/chris-rock))
- Add windows user SID as 'UID' in user resource. Fix \#960 [\#982](https://github.com/chef/inspec/pull/982) ([ksubrama](https://github.com/ksubrama))
- document ini resource [\#981](https://github.com/chef/inspec/pull/981) ([vjeffrey](https://github.com/vjeffrey))
- Upgrade FFI to Ruby 2.3 issues on windows [\#980](https://github.com/chef/inspec/pull/980) ([ksubrama](https://github.com/ksubrama))
- move train connection out of loop for command\_simulator [\#979](https://github.com/chef/inspec/pull/979) ([vjeffrey](https://github.com/vjeffrey))
- Update port.rb Documentation [\#978](https://github.com/chef/inspec/pull/978) ([nvtkaszpir](https://github.com/nvtkaszpir))
- first pass at collecting command output for demo [\#977](https://github.com/chef/inspec/pull/977) ([vjeffrey](https://github.com/vjeffrey))
- Fix `rake` to work again [\#976](https://github.com/chef/inspec/pull/976) ([jkeiser](https://github.com/jkeiser))
- Fix `bundle install` on Ruby 2.1.9 [\#975](https://github.com/chef/inspec/pull/975) ([jkeiser](https://github.com/jkeiser))
- Initial control isolation support [\#973](https://github.com/chef/inspec/pull/973) ([stevendanna](https://github.com/stevendanna))
- Allow JSON 2.x [\#972](https://github.com/chef/inspec/pull/972) ([chris-rock](https://github.com/chris-rock))
- Add Ruby 2.3 to the test matrix, make it the primary test for most suites [\#971](https://github.com/chef/inspec/pull/971) ([jkeiser](https://github.com/jkeiser))
- Speed up windows package lookup [\#970](https://github.com/chef/inspec/pull/970) ([ksubrama](https://github.com/ksubrama))
- Expand relative paths based on profile location [\#965](https://github.com/chef/inspec/pull/965) ([stevendanna](https://github.com/stevendanna))
- restructure test suites in travis [\#964](https://github.com/chef/inspec/pull/964) ([chris-rock](https://github.com/chris-rock))
- Replace Molinillo-based resolver [\#961](https://github.com/chef/inspec/pull/961) ([stevendanna](https://github.com/stevendanna))
- Add prototype of inspec.lock [\#949](https://github.com/chef/inspec/pull/949) ([stevendanna](https://github.com/stevendanna))
- document OR feature [\#947](https://github.com/chef/inspec/pull/947) ([vjeffrey](https://github.com/vjeffrey))
- print controls, then tests; print header of describe, then individual test results [\#946](https://github.com/chef/inspec/pull/946) ([vjeffrey](https://github.com/vjeffrey))
- Add darwin helper [\#945](https://github.com/chef/inspec/pull/945) ([tas50](https://github.com/tas50))
- Update platforms in the docs to match the code [\#944](https://github.com/chef/inspec/pull/944) ([tas50](https://github.com/tas50))
- Add integration tests for file owner on windows [\#923](https://github.com/chef/inspec/pull/923) ([chris-rock](https://github.com/chris-rock))
## [v0.31.0](https://github.com/chef/inspec/tree/v0.31.0) (2016-08-19)
[Full Changelog](https://github.com/chef/inspec/compare/v0.30.0...v0.31.0)
**Implemented enhancements:**
- Support writing full tests in inspec shell [\#240](https://github.com/chef/inspec/issues/240)
- inspec shell documentation - Fix \#805 [\#925](https://github.com/chef/inspec/pull/925) ([ksubrama](https://github.com/ksubrama))
- Windows ports with pid and process name [\#912](https://github.com/chef/inspec/pull/912) ([alexpop](https://github.com/alexpop))
- Improve inspec shell by having it evaluate describe/control blocks. [\#909](https://github.com/chef/inspec/pull/909) ([ksubrama](https://github.com/ksubrama))
**Fixed bugs:**
- `inspec login help` help text inconsistent with `inspec` CLI usage [\#905](https://github.com/chef/inspec/issues/905)
- Subcommand help outputs incorrect usage line [\#895](https://github.com/chef/inspec/issues/895)
- `inspec compliance version` fails with stacktrace if no compliance URL is configured [\#894](https://github.com/chef/inspec/issues/894)
- `inspec` binary occasionally exits zero on SSH failures [\#840](https://github.com/chef/inspec/issues/840)
- inspec login fails [\#793](https://github.com/chef/inspec/issues/793)
- ssh\_config and sshd\_config matchers should be case-insensitive [\#759](https://github.com/chef/inspec/issues/759)
- Login succeeds but later commands fail [\#731](https://github.com/chef/inspec/issues/731)
- passwd resource does not ignore comments [\#725](https://github.com/chef/inspec/issues/725)
- remove tests and dev dependencies from released gem [\#924](https://github.com/chef/inspec/pull/924) ([arlimus](https://github.com/arlimus))
- update dependencies and loosen molinillo [\#917](https://github.com/chef/inspec/pull/917) ([arlimus](https://github.com/arlimus))
- Handle xinetd config with only one entry [\#846](https://github.com/chef/inspec/pull/846) ([chris-rock](https://github.com/chris-rock))
**Closed issues:**
- Document InSpec Shell [\#805](https://github.com/chef/inspec/issues/805)
**Merged pull requests:**
- fix functional test for compliance plugin [\#941](https://github.com/chef/inspec/pull/941) ([chris-rock](https://github.com/chris-rock))
- give accurate information for inspec compliance login --help [\#938](https://github.com/chef/inspec/pull/938) ([vjeffrey](https://github.com/vjeffrey))
- Document awesome where syntax for port [\#937](https://github.com/chef/inspec/pull/937) ([pburkholder](https://github.com/pburkholder))
- Fetch deps based on urls [\#935](https://github.com/chef/inspec/pull/935) ([stevendanna](https://github.com/stevendanna))
- Ease testing of compliance integration tests [\#934](https://github.com/chef/inspec/pull/934) ([chris-rock](https://github.com/chris-rock))
- restructure unit tests [\#933](https://github.com/chef/inspec/pull/933) ([chris-rock](https://github.com/chris-rock))
- return token stored message on login [\#932](https://github.com/chef/inspec/pull/932) ([vjeffrey](https://github.com/vjeffrey))
- fail gracefully on inspec compliance profiles when bad token is provided [\#930](https://github.com/chef/inspec/pull/930) ([vjeffrey](https://github.com/vjeffrey))
- Fix recursive deps for path-based deps [\#929](https://github.com/chef/inspec/pull/929) ([stevendanna](https://github.com/stevendanna))
- fix integration tests for Chef Compliance [\#928](https://github.com/chef/inspec/pull/928) ([chris-rock](https://github.com/chris-rock))
- Remove false username/passwd msg from inspec compliance login [\#927](https://github.com/chef/inspec/pull/927) ([vjeffrey](https://github.com/vjeffrey))
- inspec compliance version fails gracefully when no server config [\#926](https://github.com/chef/inspec/pull/926) ([vjeffrey](https://github.com/vjeffrey))
- add kitchen.yml for non-public kitchen boxes [\#922](https://github.com/chef/inspec/pull/922) ([chris-rock](https://github.com/chris-rock))
- Ignore comment lines in /etc/passwd [\#920](https://github.com/chef/inspec/pull/920) ([stevendanna](https://github.com/stevendanna))
- ssh\_config parse should be case insensitive [\#919](https://github.com/chef/inspec/pull/919) ([vjeffrey](https://github.com/vjeffrey))
- add ssl resource \(early access\) [\#914](https://github.com/chef/inspec/pull/914) ([arlimus](https://github.com/arlimus))
- Add iis\_site resource [\#907](https://github.com/chef/inspec/pull/907) ([chrisevett](https://github.com/chrisevett))
## [v0.30.0](https://github.com/chef/inspec/tree/v0.30.0) (2016-08-12)
[Full Changelog](https://github.com/chef/inspec/compare/v0.29.0...v0.30.0)
**Implemented enhancements:** **Implemented enhancements:**
@ -73,10 +607,6 @@
## [v0.28.1](https://github.com/chef/inspec/tree/v0.28.1) (2016-08-03) ## [v0.28.1](https://github.com/chef/inspec/tree/v0.28.1) (2016-08-03)
[Full Changelog](https://github.com/chef/inspec/compare/v0.28.0...v0.28.1) [Full Changelog](https://github.com/chef/inspec/compare/v0.28.0...v0.28.1)
**Implemented enhancements:**
- InSpec output for summary needs to count controls [\#852](https://github.com/chef/inspec/issues/852)
**Fixed bugs:** **Fixed bugs:**
- Read Chef attributes within the tests ? [\#813](https://github.com/chef/inspec/issues/813) - Read Chef attributes within the tests ? [\#813](https://github.com/chef/inspec/issues/813)

167
CONTRIBUTING.md
View file

@ -1,74 +1,155 @@
# Contributing to InSpec # Contributing to InSpec
We are glad you want to contribute to InSpec! We are glad you want to contribute to InSpec! This document will help answer common questions you may have during your first contribution.
## Submitting Issues
We utilize **Github Issues** for issue tracking and contributions. You can contribute in two ways: We utilize **Github Issues** for issue tracking and contributions. You can contribute in two ways:
1. Reporting an issue or making a feature request [here](#issues). 1. Reporting an issue or making a feature request [here](#issues).
2. Adding features or fixing bugs yourself and contributing your code to InSpec. 2. Adding features or fixing bugs yourself and contributing your code to InSpec.
We ask you not to submit security concerns via Github. For details on submitting potential security issues please see <https://www.chef.io/security/>
## Contribution Process ## Contribution Process
We have a 3 step process that utilizes **Github Issues**: We have a 3 step process for contributions:
1. Sign or be added to an existing [Contributor License Agreement (CLA)](https://supermarket.chef.io/become-a-contributor). 1. Commit changes to a git branch, making sure to sign-off those changes for the [Developer Certificate of Origin](#developer-certification-of-origin-dco).
2. Create a Github Pull Request. 2. Create a Github Pull Request for your change, following the instructions in the pull request template.
3. Do [Code Review](#cr) with the **InSpec Team** on the pull request. 3. Perform a [Code Review](#code-review-process) with the project maintainers on the pull request.
### <a name="pulls"></a> Chef Pull Requests ### Pull Request Requirements
We strive to ensure high quality throughout the InSpec experience. In order to ensure Chef Projects are built to last. We strive to ensure high quality throughout the experience. In order to ensure this, we require that all pull requests to Chef projects meet these specifications:
this, we require a couple of things for all pull requests to InSpec:
1. **Tests:** To ensure high quality code and protect against future regressions, we require all the 1. **Tests:** To ensure high quality code and protect against future regressions, we require all the code in Chef Projects to have at least unit test coverage. See the [test/unit](https://github.com/chef/inspec/tree/master/test/unit)
code in InSpec to have at least unit test coverage. See the [test/unit](https://github.com/chef/inspec/tree/master/test/unit) directory for the existing tests and use ```bundle exec rake test``` to run them.
directory for the existing tests and use ```bundle exec rake test``` to run them. 2. **Green CI Tests:** We use [Travis CI](https://travis-ci.org/) and/or [AppVeyor](https://www.appveyor.com/) CI systems to test all pull requests. We require these test runs to succeed on every pull request before being merged.
2. **Green Travis Run:** We use [Travis CI](https://travis-ci.org/) in order to run our tests
continuously on all the pull requests. We require the Travis runs to succeed on every pull
request before being merged.
3. **Up-to-date Documentation:** Every code change should be reflected in an update for our [documentation](https://github.com/chef/inspec/tree/master/docs). We expect PRs to update the documentation with the code change. 3. **Up-to-date Documentation:** Every code change should be reflected in an update for our [documentation](https://github.com/chef/inspec/tree/master/docs). We expect PRs to update the documentation with the code change.
In addition to this it would be nice to include the description of the problem you are solving In addition to this it would be nice to include the description of the problem you are solving
with your change. You can use [Chef Issue Template](#issuetemplate) in the description section with your change. You can use [Issue Template](#issuetemplate) in the description section
of the pull request. of the pull request.
### <a name="cr"></a> Chef Code Review Process ### Code Review Process
The Chef Code Review process happens on Github pull requests. See Code review takes place in Github pull requests. See [this article](https://help.github.com/articles/about-pull-requests/) if you're not familiar with Github Pull Requests.
[this article](https://help.github.com/articles/using-pull-requests) if you're not
familiar with Github Pull Requests.
Once you a pull request, the **InSpec Team** will review your code Once you open a pull request, project maintainers will review your code and respond to your pull request with any feedback they might have. The process at this point is as follows:
and respond to you with any feedback they might have. The process at this point is as follows:
1. thumbs-ups are required from the **InSpec Team** for all merges. 1. Two thumbs-up (:+1:) are required from project maintainers. See the master maintainers document for InSpec projects at <https://github.com/chef/inspec/blob/master/MAINTAINERS.md>.
2. When ready, your pull request will be merged into `master`, we may require you to rebase your PR to the latest `master`. 2. When ready, your pull request will be merged into `master`, we may require you to rebase your PR to the latest `master`.
3. Once the PR is merged, you will be included in `CHANGELOG.md`. 3. Once the PR is merged, you will be included in `CHANGELOG.md`.
If you would like to learn about when your code will be available in a release of Chef, read more about [Chef Release Cycles](#release-cycles).
### Contributor License Agreement (CLA)
Licensing is very important to open source projects. It helps ensure the
software continues to be available under the terms that the author desired.
Chef uses [the Apache 2.0 license](https://github.com/chef/chef/blob/master/LICENSE) ### Developer Certification of Origin (DCO)
to strike a balance between open contribution and allowing you to use the
software however you would like to.
The license tells you what rights you have that are provided by the copyright holder. Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired.
It is important that the contributor fully understands what rights they are
licensing and agrees to them. Sometimes the copyright holder isn't the contributor,
such as when the contributor is doing work for a company.
To make a good faith effort to ensure these criteria are met, Chef requires an Individual CLA Chef uses [the Apache 2.0 license](https://github.com/chef/chef/blob/master/LICENSE) to strike a balance between open contribution and allowing you to use the software however you would like to.
or a Corporate CLA for contributions. This agreement helps ensure you are aware of the
terms of the license you are contributing your copyrighted works under, which helps to
prevent the inclusion of works in the projects that the contributor does not hold the rights
to share.
It only takes a few minutes to complete a CLA, and you retain the copyright to your contribution. The license tells you what rights you have that are provided by the copyright holder. It is important that the contributor fully understands what rights they are licensing and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company.
You can complete our To make a good faith effort to ensure these criteria are met, Chef requires the Developer Certificate of Origin (DCO) process to be followed.
[Individual CLA](https://supermarket.chef.io/icla-signatures/new) online.
If you're contributing on behalf of your employer and they retain the copyright for your works, The DCO is an attestation attached to every contribution made by every developer. In the commit message of the contribution, the developer simply adds a Signed-off-by statement and thereby agrees to the DCO, which you can find below or at <http://developercertificate.org/>.
have your employer fill out our
[Corporate CLA](https://supermarket.chef.io/ccla-signatures/new) instead. ```
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the
best of my knowledge, is covered under an appropriate open
source license and I have the right under that license to
submit that work with modifications, whether created in whole
or in part by me, under the same open source license (unless
I am permitted to submit under a different license), as
Indicated in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including
all personal information I submit with it, including my
sign-off) is maintained indefinitely and may be redistributed
consistent with this project or the open source license(s)
involved.
```
For more information on the change see the Chef Blog post [Introducing Developer Certificate of Origin](https://blog.chef.io/2016/09/19/introducing-developer-certificate-of-origin/)
#### DCO Sign-Off Methods
The DCO requires a sign-off message in the following format appear on each commit in the pull request:
```
Signed-off-by: Julia Child <juliachild@chef.io>
```
The DCO text can either be manually added to your commit body, or you can add either **-s** or **--signoff** to your usual git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running **git commit --amend -s**. If you've pushed your changes to Github already you'll need to force push your branch after this with **git push -f**.
### Obvious Fix Policy
Small contributions, such as fixing spelling errors, where the content is small enough to not be considered intellectual property, can be submitted without signing the contribution for the DCO.
As a rule of thumb, changes are obvious fixes if they do not introduce any new functionality or creative thinking. Assuming the change does not affect functionality, some common obvious fix examples include the following:
- Spelling / grammar fixes
- Typo correction, white space and formatting changes
- Comment clean up
- Bug fixes that change default return values or error codes stored in constants
- Adding logging messages or debugging output
- Changes to 'metadata' files like Gemfile, .gitignore, build scripts, etc.
- Moving source files from one directory or package to another
**Whenever you invoke the "obvious fix" rule, please say so in your commit message:**
```
------------------------------------------------------------------------
commit 370adb3f82d55d912b0cf9c1d1e99b132a8ed3b5
Author: Julia Child <juliachild@chef.io>
Date: Wed Sep 18 11:44:40 2015 -0700
Fix typo in the README.
Obvious fix.
------------------------------------------------------------------------
```
## Release Cycles
Our primary shipping vehicle is operating system specific packages that includes all the requirements of InSpec. We call these [Omnibus packages](https://github.com/chef/omnibus)
We also release our software as gems to [Rubygems](https://rubygems.org/) but we strongly recommend using InSpec or ChefDK packages.
Our version numbering roughly follows [Semantic Versioning](http://semver.org/) standard. Our standard version numbers look like X.Y.Z which mean:
- X is a major release, which may not be fully compatible with prior major releases
- Y is a minor release, which adds both new features and bug fixes
- Z is a patch release, which adds just bug fixes
After shipping a release of InSpec we bump at least the `Minor` version by one to start development of the next minor release. We do a release approximately every week. Announcements of releases are made to the [InSpec mailing list](https://discourse.chef.io/c/chef-release) when they are available.
## InSpec Community
InSpec is made possible by a strong community of developers, system administrators, auditor and security experts. If you have any questions or if you would like to get involved in the InSpec community you can check out:
- [InSpec Mailing List](https://discourse.chef.io/c/inspec)
- [Chef Community Slack](https://community-slack.chef.io/)
Also here are some additional pointers to some awesome Chef content:
- [InSpec Docs](http://inspec.io/docs/)
- [Learn Chef](https://learn.chef.io/)
- [Chef Website](https://www.chef.io/)

24
Gemfile
View file

@ -6,10 +6,15 @@ gemspec
# detecting that net-ssh 3 does not work with 1.9.3 # detecting that net-ssh 3 does not work with 1.9.3
if Gem::Version.new(RUBY_VERSION) <= Gem::Version.new('1.9.3') if Gem::Version.new(RUBY_VERSION) <= Gem::Version.new('1.9.3')
gem 'net-ssh', '~> 2.9' gem 'net-ssh', '~> 2.9'
gem 'tins', '~> 1.6.0'
end end
# TODO: ffi 1.9.11 is currently erroneous on windows tests if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.2.2')
gem 'ffi', '= 1.9.10' gem 'json', '~> 1.8'
gem 'rack', '< 2.0'
end
gem 'ffi', '>= 1.9.14'
group :test do group :test do
gem 'bundler', '~> 1.5' gem 'bundler', '~> 1.5'
@ -19,17 +24,26 @@ group :test do
gem 'simplecov', '~> 0.10' gem 'simplecov', '~> 0.10'
gem 'concurrent-ruby', '~> 0.9' gem 'concurrent-ruby', '~> 0.9'
gem 'mocha', '~> 1.1' gem 'mocha', '~> 1.1'
gem 'ruby-progressbar', '~> 1.8'
gem 'nokogiri', '~> 1.6'
end end
group :integration do group :integration do
gem 'berkshelf', '~> 4.3' gem 'berkshelf', '~> 4.3'
gem 'test-kitchen', '~> 1.6' gem 'test-kitchen', '~> 1.6'
gem 'kitchen-vagrant' gem 'kitchen-vagrant'
gem 'kitchen-inspec', '0.12.5' # we need winrm v2 support >= 0.15.1
gem 'kitchen-inspec', '>= 0.15.1'
gem 'kitchen-ec2' gem 'kitchen-ec2'
gem 'kitchen-dokken' gem 'kitchen-dokken'
end end
group :simulator do
gem 'github-markup'
gem 'redcarpet'
gem 'docker-api'
end
group :tools do group :tools do
gem 'pry', '~> 0.10' gem 'pry', '~> 0.10'
gem 'rb-readline' gem 'rb-readline'
@ -45,3 +59,7 @@ group :maintenance do
gem 'octokit' gem 'octokit'
gem 'netrc' gem 'netrc'
end end
group :deploy do
gem 'inquirer'
end

4
MAINTAINERS.md
View file

@ -8,7 +8,7 @@ This file lists how the InSpec project is maintained. When making changes to the
system, this file tells you who needs to review your patch - you need at least system, this file tells you who needs to review your patch - you need at least
two maintainers to provide a :+1: on your pull request. Additionally, you need two maintainers to provide a :+1: on your pull request. Additionally, you need
to not receive a veto from a Lieutenant or the Project Lead. to not receive a veto from a Lieutenant or the Project Lead.
Check out [How Chef is Maintained](https://github.com/opscode/chef-rfc/blob/master/rfc030-maintenance-policy.md#how-the-project-is-maintained) Check out [How Chef is Maintained](https://github.com/chef/chef-rfc/blob/master/rfc030-maintenance-policy.md#how-the-project-is-maintained)
for details on the process, how to become a maintainer, lieutenant, or the for details on the process, how to become a maintainer, lieutenant, or the
project lead. project lead.
@ -18,6 +18,8 @@ project lead.
Handles the [InSpec](https://github.com/chef/inspec) toolset. Handles the [InSpec](https://github.com/chef/inspec) toolset.
To mention the team, use @chef/inspec-maintainers
### Lieutenant ### Lieutenant
* [Dominik Richter](https://github.com/arlimus) * [Dominik Richter](https://github.com/arlimus)

2
MAINTAINERS.toml
View file

@ -5,7 +5,7 @@ This file lists how the InSpec project is maintained. When making changes to the
system, this file tells you who needs to review your patch - you need at least system, this file tells you who needs to review your patch - you need at least
two maintainers to provide a :+1: on your pull request. Additionally, you need two maintainers to provide a :+1: on your pull request. Additionally, you need
to not receive a veto from a Lieutenant or the Project Lead. to not receive a veto from a Lieutenant or the Project Lead.
Check out [How Chef is Maintained](https://github.com/opscode/chef-rfc/blob/master/rfc030-maintenance-policy.md#how-the-project-is-maintained) Check out [How Chef is Maintained](https://github.com/chef/chef-rfc/blob/master/rfc030-maintenance-policy.md#how-the-project-is-maintained)
for details on the process, how to become a maintainer, lieutenant, or the for details on the process, how to become a maintainer, lieutenant, or the
project lead. project lead.
""" """

100
README.md
View file

@ -1,6 +1,6 @@
# InSpec: Inspect Your Infrastructure # InSpec: Inspect Your Infrastructure
[![Join the chat at https://gitter.im/chef/inspec](https://badges.gitter.im/chef/inspec.svg)](https://gitter.im/chef/inspec?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Slack](https://community-slack.chef.io/badge.svg)](https://community-slack.chef.io/)
[![Build Status Master](https://travis-ci.org/chef/inspec.svg?branch=master)](https://travis-ci.org/chef/inspec) [![Build Status Master](https://travis-ci.org/chef/inspec.svg?branch=master)](https://travis-ci.org/chef/inspec)
[![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/inspec?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/inspec/branch/master) [![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/inspec?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/inspec/branch/master)
@ -18,7 +18,7 @@ describe inetd_conf do
end end
``` ```
InSpec makes it easy to run your tests wherever you need. More options listed here: https://github.com/chef/inspec/blob/master/docs/ctl_inspec.rst InSpec makes it easy to run your tests wherever you need. More options are found in our [CLI docs](http://inspec.io/docs/reference/cli/).
```bash ```bash
# run test locally # run test locally
@ -45,6 +45,10 @@ inspec exec test.rb -t docker://container_id
InSpec requires Ruby ( >1.9 ). InSpec requires Ruby ( >1.9 ).
### Install as package
The InSpec package is available for MacOS, RedHat, Ubuntu and Windows. Download the latest package at [InSpec Downloads](https://downloads.chef.io/inspec).
### Install it via rubygems.org ### Install it via rubygems.org
When installing from source, gem dependencies may require ruby build tools to be installed. When installing from source, gem dependencies may require ruby build tools to be installed.
@ -110,6 +114,19 @@ gem install inspec-*.gem
On Windows, you need to install [Ruby](http://rubyinstaller.org/downloads/) with [Ruby Development Kit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit) to build dependencies with its native extensions. On Windows, you need to install [Ruby](http://rubyinstaller.org/downloads/) with [Ruby Development Kit](https://github.com/oneclick/rubyinstaller/wiki/Development-Kit) to build dependencies with its native extensions.
### Install via Habitat
Currently, this method of installation only supports Linux. See the [Habitat site](https://www.habitat.sh/) for more information.
Download the `hab` binary from the [Habitat](https://www.habitat.sh/docs/get-habitat/) site.
```bash
hab pkg install chef/inspec
export PATH="$(hab pkg path core/ruby)/bin:$(hab pkg path chef/inspec)/bin:$PATH"
inspec
```
### Run InSpec ### Run InSpec
You should now be able to run: You should now be able to run:
@ -156,11 +173,12 @@ describe sshd_config do
end end
``` ```
* Test your `kitchen.yml` file to verify that only Vagrant is configured as the driver. * Test your `kitchen.yml` file to verify that only Vagrant is configured as the driver. The %w() formatting will
pass rubocop lintng and allow you to access nested mappings.
```ruby ```ruby
describe yaml('.kitchen.yml') do describe yaml('.kitchen.yml') do
its('driver.name') { should eq('vagrant') } its(%w(driver name)) { should eq('vagrant') }
end end
``` ```
@ -170,6 +188,25 @@ Also have a look at our examples for:
- [Using InSpec with Test Kitchen & Ansible](https://github.com/chef/inspec/tree/master/examples/kitchen-ansible) - [Using InSpec with Test Kitchen & Ansible](https://github.com/chef/inspec/tree/master/examples/kitchen-ansible)
- [Implementing an InSpec profile](https://github.com/chef/inspec/tree/master/examples/profile) - [Implementing an InSpec profile](https://github.com/chef/inspec/tree/master/examples/profile)
## Or tests: Testing for a OR b
* Using describe.one, you can test for a or b. The control will be marked as passing if EITHER condition is met.
```ruby
control 'or-test' do
impact 1.0
title 'This is a OR test'
describe.one do
describe ssh_config do
its('Protocol') { should eq('3') }
end
describe ssh_config do
its('Protocol') { should eq('2') }
end
end
end
```
## Command Line Usage ## Command Line Usage
### exec ### exec
@ -191,6 +228,9 @@ inspec exec test.rb -t docker://container_id
# run with sudo # run with sudo
inspec exec test.rb --sudo [--sudo-password ...] [--sudo-options ...] [--sudo_command ...] inspec exec test.rb --sudo [--sudo-password ...] [--sudo-options ...] [--sudo_command ...]
# run in a subshell
inspec exec test.rb --shell [--shell-options ...] [--shell-command ...]
``` ```
### detect ### detect
@ -231,7 +271,7 @@ OpenSUSE | 13.1/13.2/42.1 | x86_64
OmniOS | | x86_64 OmniOS | | x86_64
Gentoo Linux | | x86_64 Gentoo Linux | | x86_64
Arch Linux | | x86_64 Arch Linux | | x86_64
HP-UX | 11.31 | ia64 HP-UX | 11.31 | ia64
* For Windows 2008 and 2008 R2 an updated Powershell (Windows Management Framework 5.0) is required. * For Windows 2008 and 2008 R2 an updated Powershell (Windows Management Framework 5.0) is required.
@ -249,30 +289,13 @@ Windows | 2012+
Documentation Documentation
* http://inspec.io/docs/
* http://inspec.io/docs/reference/resources/
* https://github.com/chef/inspec/tree/master/docs * https://github.com/chef/inspec/tree/master/docs
Blogs: Tutorials/Blogs/Podcasts:
* [The Road to InSpec](https://www.chef.io/blog/2015/11/04/the-road-to-inspec/) * http://inspec.io/tutorials/
* [Introduction to InSpec](http://tfitch.com/automation-tools-bootcamp/inspec.html)
* [InSpec Tutorial: Day 1 - Hello World](http://www.anniehedgie.com/inspec-basics-1)
* [InSpec Tutorial: Day 2 - Command Resource Blog Logo](http://www.anniehedgie.com/inspec-basics-2)
* [InSpec Tutorial: Day 3 - File Resource](http://www.anniehedgie.com/inspec-basics-3)
* [InSpec Tutorial: Day 4 - Custom Matchers](http://www.anniehedgie.com/inspec-basics-4)
* [InSpec Tutorial: Day 5 - Creating a Profile](http://www.anniehedgie.com/inspec-basics-5)
* [InSpec Tutorial: Day 6 - Ways to Run It and Places to Store It](http://www.anniehedgie.com/inspec-basics-6)
* [InSpec Tutorial: Day 7 - How to Inherit a Profile from Chef Compliance Server](http://www.anniehedgie.com/inspec-basics-7)
* [InSpec Tutorial: Day 8 - Regular Expressions](http://www.anniehedgie.com/inspec-basics-8)
* [InSpec Tutorial: Day 9 - Attributes](http://www.anniehedgie.com/inspec-basics-9)
* [Windows infrastructure testing using InSpec – Part I](http://datatomix.com/?p=236)
* [Windows infrastructure testing using InSpec and Profiles – Part II](http://datatomix.com/?p=238)
* [Testing Ansible with Inspec](http://scienceofficersblog.blogspot.de/2016/02/testing-ansible-with-inspec.html)
* [Operating Chef/InSpec in an air gapped environment](https://github.com/jeremymv2/chef-intranet-scaffolding/blob/master/README.md)
Podcasts:
* [InSpec Foodfight](http://foodfightshow.org/2016/02/inspec.html)
* [Test Driven Infrastructure With Arthur Maltson And Michael Goetz](https://www.arresteddevops.com/tdi/)
## Share your Profiles ## Share your Profiles
@ -294,6 +317,11 @@ InSpec is inspired by the wonderful [Serverspec](http://serverspec.org) project.
1. Create new Pull Request 1. Create new Pull Request
The InSpec community and maintainers are very active and helpful. This project benefits greatly from this activity.
[![InSpec health](https://graphs.waffle.io/chef/inspec/throughput.svg)](https://waffle.io/chef/inspec/metrics/throughput)
## Testing InSpec ## Testing InSpec
We perform `unit`, `resource` and `integration` tests. We perform `unit`, `resource` and `integration` tests.
@ -363,21 +391,15 @@ transport:
``` ```
### Chef Delivery Tests
It may be informative to look at what [tests Chef Delivery](https://github.com/chef/inspec/blob/master/.delivery/build-cookbook/recipes/unit.rb) is running for CI.
## License ## License
| **Author:** | Dominik Richter (<drichter@chef.io>) | | |
| ------ | --- |
| **Author:** | Christoph Hartmann (<chartmann@chef.io>) | **Author:** | Dominik Richter (<drichter@chef.io>) |
| **Author:** | Christoph Hartmann (<chartmann@chef.io>) |
| **Copyright:** | Copyright (c) 2015 Chef Software Inc. | **Copyright:** | Copyright (c) 2015 Chef Software Inc. |
| **Copyright:** | Copyright (c) 2015 Vulcano Security GmbH. |
| **Copyright:** | Copyright (c) 2015 Vulcano Security GmbH. | **License:** | Apache License, Version 2.0 |
| **License:** | Apache License, Version 2.0
Licensed under the Apache License, Version 2.0 (the "License"); Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. you may not use this file except in compliance with the License.

74
Rakefile
View file

@ -5,7 +5,9 @@ require 'bundler'
require 'bundler/gem_tasks' require 'bundler/gem_tasks'
require 'rake/testtask' require 'rake/testtask'
require 'rubocop/rake_task' require 'rubocop/rake_task'
require_relative 'tasks/docs'
require_relative 'tasks/maintainers' require_relative 'tasks/maintainers'
require_relative 'tasks/www'
# Rubocop # Rubocop
desc 'Run Rubocop lint checks' desc 'Run Rubocop lint checks'
@ -17,6 +19,13 @@ end
desc 'Run robocop linter' desc 'Run robocop linter'
task lint: [:rubocop] task lint: [:rubocop]
# update command output for demo
desc 'Run inspec commands and save results to www/app/responses'
task :update_demo do
ruby 'www/tutorial/scripts/build_simulator_runtime.rb'
ruby 'www/tutorial/scripts/run_simulator_recording.rb'
end
# run tests # run tests
task default: [:test, :lint] task default: [:test, :lint]
@ -145,6 +154,7 @@ task :bump_version, [:version] do |_, args|
check_update_requirements check_update_requirements
inspec_version(v) inspec_version(v)
Rake::Task['changelog'].invoke Rake::Task['changelog'].invoke
Rake::Task['docs:cli'].invoke
end end
desc 'Release a new docker image' desc 'Release a new docker image'
@ -158,55 +168,19 @@ task :release_docker do
sh('sh', '-c', cmd) sh('sh', '-c', cmd)
end end
namespace :docs do desc 'Release a new Habitat package'
desc 'Create cli docs' task :release_habitat do
task :cli do version = Inspec::VERSION
res = "=====================================================\n"\ ENV['HAB_ORIGIN'] = "chef"
"InSpec CLI\n"\ if Dir.exist?("./results") then
"=====================================================\n\n"\ raise "Please remove the ./results directory"
"Use the InSpec CLI to run tests and audits against targets "\
"using local, SSH, WinRM, or Docker connections.\n\n"
require 'inspec/cli'
cmds = Inspec::InspecCLI.all_commands
cmds.keys.sort.each do |key|
cmd = cmds[key]
res << "#{cmd.usage.split.first}\n"\
"=====================================================\n\n"
res << cmd.description.capitalize
res << "\n\n"
res << "Syntax\n"\
"-----------------------------------------------------\n\n"
res << "This subcommand has the following syntax:\n\n"\
".. code-block:: bash\n\n"\
" $ inspec #{cmd.usage}\n\n"
opts = cmd.options.select { |_, o| !o.hide }
unless opts.empty?
res << "Options\n"\
"-----------------------------------------------------\n\n"\
"This subcommand has additional options:\n\n"
opts.keys.sort.each do |option|
opt = cmd.options[option]
# TODO: remove when UX of help is reworked 1.0
usage = opt.usage.split(', ')
.map { |x| x.tr('[]', '') }
.map { |x| x.start_with?('-') ? x : '-'+x }
.map { |x| '``' + x + '``' }
res << "#{usage.join(', ')}\n #{opt.description}\n\n"
end
end
res << "\n\n"
end end
if ! ENV.has_key?("HAB_AUTH_TOKEN") then
dst = 'docs/cli.rst' raise "Please set the HAB_AUTH_TOKEN environment variable"
File.write(dst, res) end
puts "Documentation generated in #{dst.inspect}" cmd = "echo #{version} > ./habitat/VERSION && "\
end "hab studio build ./habitat && " \
"hab pkg upload ./results/*.hart"
puts "--> #{cmd}"
sh('sh', '-c', cmd)
end end

3
appveyor.yml
View file

@ -8,6 +8,7 @@ environment:
matrix: matrix:
- ruby_version: "193" - ruby_version: "193"
- ruby_version: "22" - ruby_version: "22"
- ruby_version: "23"
clone_folder: c:\projects\inspec clone_folder: c:\projects\inspec
clone_depth: 1 clone_depth: 1
@ -32,7 +33,7 @@ install:
- ruby -r rubygems -e "p Gem.path" - ruby -r rubygems -e "p Gem.path"
build_script: build_script:
- bundle install --path=vendor/bundle --without integration tools maintenance - bundle install --path=vendor/bundle --without integration tools maintenance deploy
test_script: test_script:
- SET SPEC_OPTS=--format progress - SET SPEC_OPTS=--format progress

3
bin/inspec
View file

@ -4,6 +4,9 @@
# author: Dominik Richter # author: Dominik Richter
# author: Christoph Hartmann # author: Christoph Hartmann
Encoding.default_external = Encoding::UTF_8
Encoding.default_internal = Encoding::UTF_8
require_relative '../lib/inspec' require_relative '../lib/inspec'
require_relative '../lib/inspec/cli' require_relative '../lib/inspec/cli'
Inspec::InspecCLI.start(ARGV) Inspec::InspecCLI.start(ARGV)

2
docs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
resources.md
cli.md

40
docs/README.md Normal file
View file

@ -0,0 +1,40 @@
# InSpec documentation
This is the home of the InSpec documentation. This documentation provides an introduction to this mechanism and shows how to write custom tests.
The goal of this folder is for any community member to clone these docs, make the changes, check if they are valid, and contribute to the project.
## How to build docs
We build docs by:
1. Auto-generating docs from code
2. Transforming markdown+snippets in this folder into pure markdown in `www/source/docs`
3. Rendering them to the website via instructions in `www/`
For development, you **only need step 1**!
**1 Generate docs**
To generate all docs run:
```
bundle exec rake docs
```
You can run tasks individually. For a list of tasks run:
```
bundle exec rake --tasks docs
```
## Stability Index
Every available InSpec resource will indicate its stability. As InSpec matures, certain parts are more reliable than others. Brand new features are likely to be redesigned and marked as such.
The stability indices are as follows:
* `Stability: Deprecated` - This features will be removed in future versions, because its known for being problematic. Do not rely on it.
* `Stability: Experimental` - New features may change or are removed in future versions
* `Stability: Stable` - API is well established and proofed. Maintaining compatibility is a high priority
* `Stability: Locked` - Only security and performance fixes are allowed

442
docs/cli.rst
View file

@ -1,442 +0,0 @@
=====================================================
InSpec CLI
=====================================================
Use the InSpec CLI to run tests and audits against targets using local, SSH, WinRM, or Docker connections.
archive
=====================================================
Archive a profile to tar.gz (default) or zip
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec archive PATH
Options
-----------------------------------------------------
This subcommand has additional options:
``--ignore-errors``, ``--no-ignore-errors``
Ignore profile warnings.
``-o``, ``--output=OUTPUT``
Save the archive to a path
``--overwrite``, ``--no-overwrite``
Overwrite existing archive.
``--profiles-path=PROFILES_PATH``
Folder which contains referenced profiles.
``--tar``, ``--no-tar``
Generates a tar.gz archive.
``--zip``, ``--no-zip``
Generates a zip archive.
check
=====================================================
Verify all tests at the specified path
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec check PATH
Options
-----------------------------------------------------
This subcommand has additional options:
``--format=FORMAT``
``--profiles-path=PROFILES_PATH``
Folder which contains referenced profiles.
compliance
=====================================================
Chef compliance commands
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec compliance SUBCOMMAND ...
detect
=====================================================
Detect the target os
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec detect
Options
-----------------------------------------------------
This subcommand has additional options:
``-b``, ``--backend=BACKEND``
Choose a backend: local, ssh, winrm, docker.
``--format=FORMAT``
``--host=HOST``
Specify a remote host which is tested.
``--json-config=JSON_CONFIG``
Read configuration from JSON file (`-` reads from stdin).
``-i``, ``--key-files=one two three``
Login key or certificate file for a remote scan.
``-l``, ``--log-level=LOG_LEVEL``
Set the log level: info (default), debug, warn, error
``--password=PASSWORD``
Login password for a remote scan, if required.
``--path=PATH``
Login path to use when connecting to the target (WinRM).
``-p``, ``--port=N``
Specify the login port for a remote scan.
``--self-signed``, ``--no-self-signed``
Allow remote scans with self-signed certificates (WinRM).
``--ssl``, ``--no-ssl``
Use SSL for transport layer encryption (WinRM).
``--sudo``, ``--no-sudo``
Run scans with sudo. Only activates on Unix and non-root user.
``--sudo-command=SUDO_COMMAND``
Alternate command for sudo.
``--sudo-options=SUDO_OPTIONS``
Additional sudo options for a remote scan.
``--sudo-password=SUDO_PASSWORD``
Specify a sudo password, if it is required.
``-t``, ``--target=TARGET``
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
``--user=USER``
The login user for a remote scan.
env
=====================================================
Output shell-appropriate completion configuration
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec env
exec
=====================================================
Run all test files at the specified path.
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec exec PATHS
Options
-----------------------------------------------------
This subcommand has additional options:
``--attrs=one two three``
Load attributes file (experimental)
``-b``, ``--backend=BACKEND``
Choose a backend: local, ssh, winrm, docker.
``--color``, ``--no-color``
Use colors in output.
``--controls=one two three``
A list of controls to run. Ignore all other tests.
``--format=FORMAT``
Which formatter to use: cli, progress, documentation, json, json-min
``--host=HOST``
Specify a remote host which is tested.
``--json-config=JSON_CONFIG``
Read configuration from JSON file (`-` reads from stdin).
``-i``, ``--key-files=one two three``
Login key or certificate file for a remote scan.
``-l``, ``--log-level=LOG_LEVEL``
Set the log level: info (default), debug, warn, error
``--password=PASSWORD``
Login password for a remote scan, if required.
``--path=PATH``
Login path to use when connecting to the target (WinRM).
``-p``, ``--port=N``
Specify the login port for a remote scan.
``--profiles-path=PROFILES_PATH``
Folder which contains referenced profiles.
``--self-signed``, ``--no-self-signed``
Allow remote scans with self-signed certificates (WinRM).
``--ssl``, ``--no-ssl``
Use SSL for transport layer encryption (WinRM).
``--sudo``, ``--no-sudo``
Run scans with sudo. Only activates on Unix and non-root user.
``--sudo-command=SUDO_COMMAND``
Alternate command for sudo.
``--sudo-options=SUDO_OPTIONS``
Additional sudo options for a remote scan.
``--sudo-password=SUDO_PASSWORD``
Specify a sudo password, if it is required.
``-t``, ``--target=TARGET``
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
``--user=USER``
The login user for a remote scan.
help
=====================================================
Describe available commands or one specific command
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec help [COMMAND]
init
=====================================================
Scaffolds a new project
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec init TEMPLATE ...
json
=====================================================
Read all tests in path and generate a json summary
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec json PATH
Options
-----------------------------------------------------
This subcommand has additional options:
``--controls=one two three``
A list of controls to include. Ignore all other tests.
``-o``, ``--output=OUTPUT``
Save the created profile to a path
``--profiles-path=PROFILES_PATH``
Folder which contains referenced profiles.
scap
=====================================================
Scap commands
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec scap SUBCOMMAND ...
shell
=====================================================
Open an interactive debugging shell
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec shell
Options
-----------------------------------------------------
This subcommand has additional options:
``-b``, ``--backend=BACKEND``
Choose a backend: local, ssh, winrm, docker.
``-c``, ``--command=COMMAND``
``--host=HOST``
Specify a remote host which is tested.
``--json-config=JSON_CONFIG``
Read configuration from JSON file (`-` reads from stdin).
``-i``, ``--key-files=one two three``
Login key or certificate file for a remote scan.
``-l``, ``--log-level=LOG_LEVEL``
Set the log level: info (default), debug, warn, error
``--password=PASSWORD``
Login password for a remote scan, if required.
``--path=PATH``
Login path to use when connecting to the target (WinRM).
``-p``, ``--port=N``
Specify the login port for a remote scan.
``--self-signed``, ``--no-self-signed``
Allow remote scans with self-signed certificates (WinRM).
``--ssl``, ``--no-ssl``
Use SSL for transport layer encryption (WinRM).
``--sudo``, ``--no-sudo``
Run scans with sudo. Only activates on Unix and non-root user.
``--sudo-command=SUDO_COMMAND``
Alternate command for sudo.
``--sudo-options=SUDO_OPTIONS``
Additional sudo options for a remote scan.
``--sudo-password=SUDO_PASSWORD``
Specify a sudo password, if it is required.
``-t``, ``--target=TARGET``
Simple targeting option using URIs, e.g. ssh://user:pass@host:port
``--user=USER``
The login user for a remote scan.
supermarket
=====================================================
Supermarket commands
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec supermarket SUBCOMMAND ...
version
=====================================================
Prints the version of this tool
Syntax
-----------------------------------------------------
This subcommand has the following syntax:
.. code-block:: bash
$ inspec version

245
docs/dsl_inspec.md Normal file
View file

@ -0,0 +1,245 @@
---
title: InSpec DSL
---
# InSpec DSL
InSpec is a run-time framework and rule language used to specify compliance, security, and policy requirements. It includes a collection of resources that help you write auditing controls quickly and easily. The syntax used by both open source and |chef compliance| auditing is the same. The open source |inspec resource| framework is compatible with |chef compliance|.
The InSpec DSL is a Ruby DSL for writing audit controls, which includes audit resources that you can invoke.
The following sections describe the syntax and show some simple examples of using the InSpec resources.
## Syntax
The following resource tests |ssh| server configuration. For example, a simple control may described as:
```ruby
describe sshd_config do
its('Port') { should eq('22') }
end
```
In various use cases like implementing IT compliance across different departments, it becomes handy to extend the control with metadata. Each control may define an additional ``impact``, ``title`` or ``desc``. An example looks like:
```ruby
control 'sshd-8' do
impact 0.6
title 'Server: Configure the service port'
desc '
Always specify which port the SSH server should listen to.
Prevent unexpected settings.
'
tag 'ssh','sshd','openssh-server'
tag cce: 'CCE-27072-8'
ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
describe sshd_config do
its('Port') { should eq('22') }
end
end
```
where
* `'sshd-8'` is the name of the control
* `impact`, `title`, and `desc` define metadata that fully describes the importance of the control, its purpose, with a succinct and complete description
* `impact` is an float that measures the importance of the compliance results and must be a value between `0.0` and `1.0`.
* `tag` is optional meta-information with with key or key-value pairs
* `ref` is a reference to an external document
* `describe` is a block that contains at least one test. A `control` block must contain at least one `describe` block, but may contain as many as required
* `sshd_config` is an InSpec resource. For the full list of InSpec resources, see InSpec resource documentation
* `its('Port')` is the matcher; `{ should eq('22') }` is the test. A `describe` block must contain at least one matcher, but may contain as many as required
## Advanced concepts
With inspec it is possible to check if at least one of a collection of checks is true. For example: If a setting is configured in two different locations, you may want to test if either configuration A or configuration B have been set. This is accomplished via `describe.one`. It defines a block of tests with at least one valid check.
```ruby
describe.one do
describe ConfigurationA do
its('setting_1') { should eq true }
end
describe ConfigurationB do
its('setting_2') { should eq true }
end
end
```
## Examples
The following examples show simple compliance tests using a single `control` block.
## Test System Event Log
The following test shows how to audit machines running Windows 2012 R2 that password complexity is enabled:
```ruby
control 'windows-account-102' do
impact 1.0
title 'Windows Password Complexity is Enabled'
desc 'Password must meet complexity requirement'
describe security_policy do
its('PasswordComplexity') { should eq 1 }
end
end
```
## Are PosgtreSQL passwords empty?
The following test shows how to audit machines running PostgreSQL to ensure that passwords are not empty.
```ruby
control 'postgres-7' do
impact 1.0
title 'Don't allow empty passwords'
describe postgres_session('user', 'pass').query("SELECT * FROM pg_shadow WHERE passwd IS NULL;") do
its('output') { should eq('') }
end
end
```
## Are MySQL passwords in ENV?
The following test shows how to audit machines running MySQL to ensure that passwords are not stored in `ENV`:
```ruby
control 'mysql-3' do
impact 1.0
title 'Do not store your MySQL password in your ENV'
desc '
Storing credentials in your ENV may easily expose
them to an attacker. Prevent this at all costs.
'
describe command('env') do
its('stdout') { should_not match(/^MYSQL_PWD=/) }
end
end
```
## Is `/etc/ssh` a Directory?
The following test shows how to audit machines to ensure that `/etc/ssh` is a directory:
```ruby
control 'basic-1' do
impact 1.0
title '/etc/ssh should be a directory'
desc '
In order for OpenSSH to function correctly, its
configuration path must be a folder.
'
describe file('/etc/ssh') do
it { should be_directory }
end
end
```
## Is Apache running?
The following test shows how to audit machines to ensure that Apache is enabled and running:
```ruby
control 'apache-1' do
impact 0.3
title 'Apache2 should be configured and running'
describe service(apache.service) do
it { should be_enabled }
it { should be_running }
end
end
```
## Are insecure packages installed ?
The following test shows how to audit machines for insecure packages:
```ruby
control 'cis-os-services-5.1.3' do
impact 0.7
title '5.1.3 Ensure rsh client is not installed'
describe package('rsh') do
it { should_not be_installed }
end
describe package('rsh-redone-client') do
it { should_not be_installed }
end
end
```
## Test Windows Registry Keys
The following test shows how to audit machines to ensure Safe DLL Search Mode is enabled:
```ruby
control 'windows-base-101' do
impact 1.0
title 'Safe DLL Search Mode is Enabled'
desc '
@link: https://msdn.microsoft.com/en-us/library/ms682586(v=vs.85).aspx
'
describe registry_key('HKLM\\System\\CurrentControlSet\\Control\\Session Manager') do
it { should exist }
it { should_not have_property_value('SafeDllSearchMode', :type_dword, '0') }
end
end
```
## Exclude specific test
This shows how to allow skipping certain tests if conditions are not met, by using `only_if`.
In this example the test will not be performed if `redis-cli` command does not exist, because for example package on remote host was not installed.
```ruby
control 'nutcracker-connect-redis-001' do
impact 1.0
title 'Check if nutcracker can pass commands to redis'
desc 'execute redis-cli set key command, to check connectivity of the service'
only_if do
command('redis-cli').exist?
end
describe command('redis-cli SET test_inspec "HELLO"') do
its(:stdout) { should match(/OK/) }
end
end
```
Mixing this with other conditionals (like checking existence of the files etc.) can help to test different test paths using inspec. This way you can skip certain tests which would 100% fail due to the way servers are prepared, but you know that the same test suites are reused later in different circumstances by different teams.
## Additional metadata for controls
The following example illustrates various ways to add tags and references to `control`
```ruby
control 'ssh-1' do
impact 1.0
title 'Allow only SSH Protocol 2'
desc 'Only SSH protocol version 2 connections should be permitted.
The default setting in /etc/ssh/sshd_config is correct, and can be
verified by ensuring that the following line appears: Protocol 2'
tag 'production','development'
tag 'ssh','sshd','openssh-server'
tag cce: 'CCE-27072-8'
tag disa: 'RHEL-06-000227'
tag remediation: 'stig_rhel6/recipes/sshd-config.rb'
tag remediation: 'https://supermarket.chef.io/cookbooks/ssh-hardening'
ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
ref 'http://people.redhat.com/swells/scap-security-guide/RHEL/6/output/ssg-centos6-guide-C2S.html'
describe ssh_config do
its ('Protocol') { should eq '2'}
end
end
```

238
docs/dsl_inspec.rst
View file

@ -1,238 +0,0 @@
=====================================================
InSpec DSL
=====================================================
|inspec| is a run-time framework and rule language used to specify compliance, security, and policy requirements. It includes a collection of resources that help you write auditing controls quickly and easily. The syntax used by both open source and |chef compliance| auditing is the same. The open source |inspec resource| framework is compatible with |chef compliance|.
The InSpec DSL is a Ruby DSL for writing audit controls, which includes audit resources that you can invoke.
The following sections describe the syntax and show some simple examples of using the |inspec resources| to define
Syntax
=====================================================
The following resource tests |ssh| server configuration. For example, a simple control may described as:
.. code-block:: ruby
describe sshd_config do
its('Port') { should eq('22') }
end
In various use cases like implementing IT compliance across different departments, it becomes handy to extend the control with metadata. Each control may define an additional ``impact``, ``title`` or ``desc``. An example looks like:
.. code-block:: ruby
control 'sshd-8' do
impact 0.6
title 'Server: Configure the service port'
desc '
Always specify which port the SSH server should listen to.
Prevent unexpected settings.
'
tag 'ssh','sshd','openssh-server'
tag cce: 'CCE-27072-8'
ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
describe sshd_config do
its('Port') { should eq('22') }
end
end
where
* ``'sshd-8'`` is the name of the control
* ``impact``, ``title``, and ``desc`` define metadata that fully describes the importance of the control, its purpose, with a succinct and complete description
* ``impact`` is an float that measures the importance of the compliance results and must be a value between ``0.0`` and ``1.0``.
* ``tag`` is optional meta-information with with key or key-value pairs
* ``ref`` is a reference to an external document
* ``describe`` is a block that contains at least one test. A ``control`` block must contain at least one ``describe`` block, but may contain as many as required
* ``sshd_config`` is an |inspec| resource. For the full list of InSpec resources, see |inspec| resource documentation
* ``its('Port')`` is the matcher; ``{ should eq('22') }`` is the test. A ``describe`` block must contain at least one matcher, but may contain as many as required
Advanced concepts
=====================================================
With inspec it is possible to check if at least one of a collection of checks is true. For example: If a setting is configured in two different locations, you may want to test if either configuration A or configuration B have been set. This is accomplished via ``describe.one``. It defines a block of tests with at least one valid check.
.. code-block:: ruby
describe.one do
describe ConfigurationA do
its('setting_1') { should eq true }
end
describe ConfigurationB do
its('setting_2') { should eq true }
end
end
Examples
=====================================================
The following examples show simple compliance tests using a single ``control`` block.
Test System Event Log
-----------------------------------------------------
The following test shows how to audit machines running |windows| 2012 R2 that pwassword complexity is enabled:
.. code-block:: ruby
control 'windows-account-102' do
impact 1.0
title 'Windows Password Complexity is Enabled'
desc 'Password must meet complexity requirement'
describe security_policy do
its('PasswordComplexity') { should eq 1 }
end
end
Are PosgtreSQL passwords empty?
-----------------------------------------------------
The following test shows how to audit machines running |postgresql| to ensure that passwords are not empty.
.. code-block:: ruby
control 'postgres-7' do
impact 1.0
title 'Don't allow empty passwords'
describe postgres_session('user', 'pass').query("SELECT * FROM pg_shadow WHERE passwd IS NULL;") do
its('output') { should eq('') }
end
end
Are MySQL passwords in ENV?
-----------------------------------------------------
The following test shows how to audit machines running |mysql| to ensure that passwords are not stored in ``ENV``:
.. code-block:: ruby
control 'mysql-3' do
impact 1.0
title 'Do not store your MySQL password in your ENV'
desc '
Storing credentials in your ENV may easily expose
them to an attacker. Prevent this at all costs.
'
describe command('env') do
its('stdout') { should_not match(/^MYSQL_PWD=/) }
end
end
Is /etc/ssh a Directory?
-----------------------------------------------------
The following test shows how to audit machines to ensure that ``/etc/ssh`` is a directory:
.. code-block:: ruby
control 'basic-1' do
impact 1.0
title '/etc/ssh should be a directory'
desc '
In order for OpenSSH to function correctly, its
configuration path must be a folder.
'
describe file('/etc/ssh') do
it { should be_directory }
end
end
Is Apache running?
-----------------------------------------------------
The following test shows how to audit machines to ensure that |apache| is enabled and running:
.. code-block:: ruby
control 'apache-1' do
impact 0.3
title 'Apache2 should be configured and running'
describe service(apache.service) do
it { should be_enabled }
it { should be_running }
end
end
Are insecure packages installed ?
-----------------------------------------------------
The following test shows how to audit machines for insecure packages:
.. code-block:: ruby
control 'cis-os-services-5.1.3' do
impact 0.7
title '5.1.3 Ensure rsh client is not installed'
describe package('rsh') do
it { should_not be_installed }
end
describe package('rsh-redone-client') do
it { should_not be_installed }
end
end
Test Windows Registry Keys
-----------------------------------------------------
The following test shows how to audit machines to ensure Safe DLL Seach Mode is enabled:
.. code-block:: ruby
control 'windows-base-101' do
impact 1.0
title 'Safe DLL Search Mode is Enabled'
desc '
@link: https://msdn.microsoft.com/en-us/library/ms682586(v=vs.85).aspx
'
describe registry_key('HKLM\\System\\CurrentControlSet\\Control\\Session Manager') do
it { should exist }
it { should_not have_property_value('SafeDllSearchMode', :type_dword, '0') }
end
end
Additional metadata for controls
-----------------------------------------------------
The following example illustrates various ways to add tags and references to `control`
.. code-block:: ruby
control 'ssh-1' do
impact 1.0
title 'Allow only SSH Protocol 2'
desc 'Only SSH protocol version 2 connections should be permitted.
The default setting in /etc/ssh/sshd_config is correct, and can be
verified by ensuring that the following line appears: Protocol 2'
tag 'production','development'
tag 'ssh','sshd','openssh-server'
tag cce: 'CCE-27072-8'
tag disa: 'RHEL-06-000227'
tag remediation: 'stig_rhel6/recipes/sshd-config.rb'
tag remediation: 'https://supermarket.chef.io/cookbooks/ssh-hardening'
ref 'NSA-RH6-STIG - Section 3.5.2.1', url: 'https://www.nsa.gov/ia/_files/os/redhat/rhel5-guide-i731.pdf'
ref 'http://people.redhat.com/swells/scap-security-guide/RHEL/6/output/ssg-centos6-guide-C2S.html'
describe ssh_config do
its ('Protocol') { should eq '2'}
end
end`
.. |inspec| replace:: InSpec
.. |inspec resource| replace:: InSpec Resource
.. |chef compliance| replace:: Chef Compliance
.. |ruby| replace:: Ruby
.. |ssh| replace:: SSH
.. |windows| replace:: Microsoft Windows
.. |postgresql| replace:: PostgreSQL
.. |apache| replace:: Apache

93
docs/dsl_resource.md Normal file
View file

@ -0,0 +1,93 @@
---
title: Resource DSL
---
# Resource DSL
InSpec provides a mechanism for defining custom resources. These become
available with their respective names and provide easy functionality to
profiles.
## Resource location
Resources may be added to profiles in the libraries folder:
```bash
$ tree examples/profile
examples/profile
...
├── libraries
│   └── gordon_config.rb
```
## Resource structure
The smallest possible resource takes this form:
```ruby
class Tiny < Inspec.resource(1)
name 'tiny'
end
```
Resources are written as a regular Ruby class which inherits from
Inspec.resource. The number (1) specifies the version this resource
plugin targets. As InSpec evolves, this interface may change and may
require a higher version.
The following attributes can be configured:
* name - Identifier of the resource (required)
* desc - Description of the resource (optional)
* example - Example usage of the resource (optional)
The following methods are available to the resource:
* inspec - Contains a registry of all other resources to interact with the operating system or target in general.
* skip\_resource - A resource may call this method to indicate, that requirements aren't met. All tests that use this resource will be marked as skipped.
The following example shows a full resource using attributes and methods
to provide simple access to a configuration file:
```ruby
class GordonConfig < Inspec.resource(1)
name 'gordon_config'
desc '
Resource description ...
'
example '
describe gordon_config do
its("signal") { should eq "on" }
end
'
# Load the configuration file on initialization
def initialize(path = nil)
@path = path || '/etc/gordon.conf'
@params = SimpleConfig.new( read_content )
end
# Expose all parameters of the configuration file.
def method_missing(name)
@params[name]
end
private
def read_content
f = inspec.file(@path)
# Test if the path exist and that it's a file
if f.file?
# Retrieve the file's contents
f.content
else
# If the file doesn't exist, skip all tests that use gordon_config
skip_resource "Can't read config from #{@path}."
end
end
end
```
For a full example, see our [example resource](../examples/profile/libraries/gordon_config.rb).

90
docs/dsl_resource.rst
View file

@ -1,90 +0,0 @@
=====================================================
Resource DSL
=====================================================
InSpec provides a mechanism for defining custom resources. These become available with their respective names and provide easy functionality to profiles.
Resource location
-----------------------------------------------------
Resources may be added to profiles in the `libraries` folder:
.. code-block:: bash
$ tree examples/profile
examples/profile
...
├── libraries
│   └── gordon_config.rb
Resource structure
-----------------------------------------------------
The smallest possible resource takes this form:
.. code-block:: ruby
class Tiny < Inspec.resource(1)
name 'tiny'
end
Resources are written as a regular Ruby `class` which inherits from `Inspec.resource`. The number (`1`) specifies the version this resource plugin targets. As InSpec evolves, this interface may change and may require a higher version.
The following attributes can be configured:
* `name` - Identifier of the resource (required)
* `desc` - Description of the resource (optional)
* `example` - Example usage of the resource (optional)
The following methods are available to the resource:
* `inspec` - Contains a registry of all other resources to interact with the operating system or target in general.
* `skip_resource` - A resource may call this method to indicate, that requirements aren't met. All tests that use this resource will be marked as `skipped`.
The following example shows a full resource using attributes and methods to provide simple access to a configuration file:
.. code-block:: ruby
class GordonConfig < Inspec.resource(1)
name 'gordon_config'
desc '
Resource description ...
'
example '
describe gordon_config do
its("signal") { should eq "on" }
end
'
# Load the configuration file on initialization
def initialize(path = nil)
@path = path || '/etc/gordon.conf'
@params = SimpleConfig.new( read_content )
end
# Expose all parameters of the configuration file.
def method_missing(name)
@params[name]
end
private
def read_content
f = inspec.file(@path)
# Test if the path exist and that it's a file
if f.file?
# Retrieve the file's contents
f.content
else
# If the file doesn't exist, skip all tests that use gordon_config
skip_resource "Can't read config from #{@path}."
end
end
end
For a full example, see our `example resource`_.
.. _example resource: ../examples/profile/libraries/gordon_config.rb

105
docs/inspec_and_friends.md Normal file
View file

@ -0,0 +1,105 @@
---
title: InSpec and friends
---
# InSpec and friends
This page looks at projects that are similar to InSpec to explain how they
relate to each other.
## RSpec
RSpec is an awesome framework that is widely used to test Ruby code. It
enables test-driven development (TDD) and helps developers to write
better code every day.
InSpec is built on top of RSpec and uses it as the underlying foundation
to execute tests. It uses the key strengths of RSpec, easily execute
tests and a DSL to write tests, but extends the functionality for use as
compliance audits. InSpec ships with custom audit resources that make it
easy to write audit checks and with the ability to run those checks on
remote servers. These audit resources provided know the differences
between operating systems and help you abstract from the local operating
system, similar to other resources you might use in your Chef recipes.
A complete InSpec rule looks like:
```ruby
control "sshd-11" do
impact 1.0
title "Server: Set protocol version to SSHv2"
desc "Set the SSH protocol version to 2. Don't use legacy
insecure SSHv1 connections anymore."
tag security: "level-1"
tag "openssh-server"
ref "Server Security Guide v.1.0", url: "http://..."
describe sshd_config do
its('Protocol') { should eq('2') }
end
end
```
## Serverspec
Serverspec can be credited as the first extension of RSpec that enabled
users to run RSpec tests on servers to verify deployed artifacts. It was
created in March 2013 by Gosuke Miyashita and has been widely adopted.
It is also one of the core test frameworks within test-kitchen and has
been widely used within the Chef ecosystem. InSpec takes lessons learned
implementing and using Serverspec and builds on them to make auditing
and compliance easier.
Lessons learned from Serverspec include:
* IT, compliance, and security professional require metadata beyond what Serverspec offers, such as criticality, to fully describe controls.
* Setting up and running the same tests across multiple machines must be easy.
* It must be easy to locate, debug, and extend operating system-dependent code.
* It must be easy to extend the language and create custom resources.
* It must run multiple tests simultaneously.
* Support for Windows is a first-class requirement.
* A command line interface (CLI) is required for faster iteration of test code.
### How is InSpec different than Serverspec
One of the key differences is that InSpec targets more user groups. It
is optimized for DevOps, Security, and Compliance professionals.
Additional metadata, such as impact, title, and description, make it
easier to fully describe the controls which makes it easier to share the
controls with other departments. This enables Security departments to
prioritize rules. DevOps teams use this information to focus on the most
critical issues to remediate.
```ruby
control "sshd-11" do
impact 1.0
title "Server: Set protocol version to SSHv2"
desc "Set the SSH protocol version to 2. Don't use legacy
insecure SSHv1 connections anymore."
tag security: "level-1"
tag "openssh-server"
ref "Server Security Guide v.1.0" url: "http://..."
describe sshd_config do
its('Protocol') { should cmp 2 }
end
end
```
**Why not fork Serverspec?**
InSpec started as an extension of Serverspec. As the extension grew, it
became clear that a new library was required. Creating and maintaining a
fork was not practical so a new project was born.
**Will InSpec only work on machines managed by Chef?**
No, InSpec can be used on any machine. It doesn’t matter if that machine
was configured by Chef or configured lovingly by the hands of your local
System Administrator.
**Is InSpec a replacement of Serverspec?**
InSpec is intended to be a drop-in replacement of Serverspec. Popular
Serverspec resources have been ported to InSpec. It changed some
behaviour as documented in our migration guide.

85
docs/inspec_and_friends.rst
View file

@ -1,85 +0,0 @@
=====================================================
InSpec and friends
=====================================================
RSpec
=====================================================
RSpec is an awesome framework that is widely used to test Ruby code. It enables test-driven development (TDD) and helps developers to write better code every day.
InSpec is built on top of RSpec and uses it as the underlying foundation to execute tests. It uses the key strengths of RSpec, easily execute tests and a DSL to write tests, but extends the functionality for use as compliance audits. InSpec ships with custom audit resources that make it easy to write audit checks and with the ability to run those checks on remote servers. These audit resources provided know the differences between operating systems and help you abstract from the local operating system, similar to other resources you might use in your Chef recipes.
A complete InSpec rule looks like:
.. code-block:: ruby
control "sshd-11" do
impact 1.0
title "Server: Set protocol version to SSHv2"
desc "Set the SSH protocol version to 2. Don't use legacy
insecure SSHv1 connections anymore."
tag security: "level-1"
tag "openssh-server"
ref "Server Security Guide v.1.0", url: "http://..."
describe sshd_config do
its('Protocol') { should eq('2') }
end
end
Serverspec
=====================================================
Serverspec can be credited as the first extension of RSpec that enabled users to run RSpec tests on servers to verify deployed artifacts. It was created in March 2013 by Gosuke Miyashita and has been widely adopted. It is also one of the core test frameworks within test-kitchen and has been widely used within the Chef ecosystem. InSpec takes lessons learned implementing and using Serverspec and builds on them to make auditing and compliance easier.
Lessons learned from Serverspec include:
* IT, compliance, and security professional require metadata beyond what Serverspec offers, such as criticality, to fully describe controls.
* Setting up and running the same tests across multiple machines must be easy.
* It must be easy to locate, debug, and extend operating system-dependent code.
* It must be easy to extend the language and create custom resources.
* It must run multiple tests simultaneously.
* Support for Windows is a first-class requirement.
* A command line interface (CLI) is required for faster iteration of test code.
How is InSpec different than Serverspec
-----------------------------------------------------
One of the key differences is that InSpec targets more user groups. It is optimized for DevOps, Security, and Compliance professionals. Additional metadata, such as impact, title, and description, make it easier to fully describe the controls which makes it easier to share the controls with other departments. This enables Security departments to prioritize rules. DevOps teams use this information to focus on the most critical issues to remediate.
.. code-block:: ruby
control "sshd-11" do
impact 1.0
title "Server: Set protocol version to SSHv2"
desc "Set the SSH protocol version to 2. Don't use legacy
insecure SSHv1 connections anymore."
tag security: "level-1"
tag "openssh-server"
ref "Server Security Guide v.1.0" url: "http://..."
describe sshd_config do
its('Protocol') { should cmp 2 }
end
end
**Why not fork Serverspec?**
InSpec started as an extension of Serverspec. As the extension grew, it became clear that a new library was required. Creating and maintaining a fork was not practical so a new project was born.
**Will InSpec only work on machines managed by Chef?**
No, InSpec can be used on any machine. It doesn’t matter if that machine was configured by Chef or configured lovingly by the hands of your local System Administrator.
**Is InSpec a replacement of Serverspec?**
InSpec is intended to be a drop-in replacement of Serverspec. Popular Serverspec resources have been ported to InSpec. It changed some behaviour as documented in our migration guide.

136
docs/matchers.md Normal file
View file

@ -0,0 +1,136 @@
---
title: InSpec Matchers Reference
---
# InSpec Matchers Reference
Inspec uses matchers to help compare resource values to expectations.
The following matchers are available:
* `be`
* `cmp`
* `eq`
* `include`
* `match`
## be
This matcher can be followed by many different comparison operators.
Always make sure to use numbers, not strings, for these comparisons.
```ruby
describe file('/proc/cpuinfo') do
its('size') { should be >= 10 }
its('size') { should be < 1000 }
end
```
## cmp
Unlike `eq`, cmp is a matcher for less-restrictive comparisons. It will
try to fit the actual value to the type you are comparing it to. This is
meant to relieve the user from having to write type-casts and
resolutions.
```ruby
describe sshd_config do
its('Protocol') { should cmp 2 }
end
describe passwd.uid(0) do
its('users') { should cmp 'root' }
end
```
`cmp` behaves in the following way:
* Compare strings to numbers
```ruby
describe sshd_config do
its('Protocol') { should eq '2' }
its('Protocol') { should cmp '2' }
its('Protocol') { should cmp 2 }
end
```
* String comparisons are not case-sensitive
```ruby
describe auditd_conf do
its('log_format') { should cmp 'raw' }
its('log_format') { should cmp 'RAW' }
end
```
* Compare arrays with only one entry to a value
```ruby
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('users') { should cmp ['root'] }
end
```
* Single-value arrays of strings may also be compared to a regex
```ruby
describe auditd_conf do
its('log_format') { should cmp /raw/i }
end
```
* Improved printing of octal comparisons
```ruby
describe file('/proc/cpuinfo') do
its('mode') { should cmp '0345' }
end
expected: 0345
got: 0444
```
## eq
Test for exact equality of two values.
```ruby
describe sshd_config do
its('RSAAuthentication') { should_not eq 'no' }
its('Protocol') { should eq '2' }
end
```
It fails if types don't match. Please keep this in mind, when comparing
configuration entries that are numbers:
```ruby
its('Port') { should eq '22' } # ok
its('Port') { should eq 22 }
# fails: '2' != 2 (string vs int)
```
For less restrictive comparisons, please use `cmp`.
## include
Verifies if a value is included in a list.
```ruby
describe passwd do
its('users') { should include 'my_user' }
end
```
## match
Check if a string matches a regular expression.
```ruby
describe sshd_config do
its('Ciphers') { should_not match /cbc/ }
end
```

137
docs/matchers.rst
View file

@ -1,137 +0,0 @@
=====================================================
InSpec Matchers Reference
=====================================================
Inspec uses matchers to help compare resource values to expectations. The following matchers are available:
* `be`
* `cmp`
* `eq`
* `include`
* `match`
be
=====================================================
This matcher can be followed by many different comparison operators. Always make sure to use numbers, not strings, for these comparisons.
.. code-block:: ruby
describe file('/proc/cpuinfo') do
its('size') { should be >= 10 }
its('size') { should be < 1000 }
end
cmp
=====================================================
Unlike ``eq``, cmp is a matcher for less-restrictive comparisons. It will try to fit the actual value to the type you are comparing it to. This is meant to relieve the user from having to write type-casts and resolutions.
.. code-block:: ruby
describe sshd_config do
its('Protocol') { should cmp 2 }
end
describe passwd.uid(0) do
its('users') { should cmp 'root' }
end
``cmp`` behaves in the following way:
* Compare strings to numbers
.. code-block:: ruby
describe sshd_config do
its('Protocol') { should eq '2' }
its('Protocol') { should cmp '2' }
its('Protocol') { should cmp 2 }
end
* String comparisons are not case-sensitive
.. code-block:: ruby
describe auditd_conf do
its('log_format') { should cmp 'raw' }
its('log_format') { should cmp 'RAW' }
end
* Compare arrays with only one entry to a value
.. code-block:: ruby
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('users') { should cmp ['root'] }
end
* Single-value arrays of strings may also be compared to a regex
.. code-block:: ruby
describe auditd_conf do
its('log_format') { should cmp /raw/i }
end
* Improved printing of octal comparisons
.. code-block:: ruby
describe file('/proc/cpuinfo') do
its('mode') { should cmp '0345' }
end
expected: 0345
got: 0444
eq
=====================================================
Test for exact equality of two values.
.. code-block:: ruby
describe sshd_config do
its('RSAAuthentication') { should_not eq 'no' }
its('Protocol') { should eq '2' }
end
It fails if types don't match. Please keep this in mind, when comparing configuration
entries that are numbers:
.. code-block:: ruby
its('Port') { should eq '22' } # ok
its('Port') { should eq 22 }
# fails: '2' != 2 (string vs int)
For less restrictive comparisons, please use ``cmp``.
include
=====================================================
Verifies if a value is included in a list.
.. code-block:: ruby
describe passwd do
its('users') { should include 'my_user' }
end
match
=====================================================
Check if a string matches a regular expression.
.. code-block:: ruby
describe sshd_config do
its('Ciphers') { should_not match /cbc/ }
end

55
docs/plugin_kitchen_inspec.html.md Normal file
View file

@ -0,0 +1,55 @@
---
title: About kitchen-inspec
---
# kitchen-inspec
The `kitchen-inspec` driver enables InSpec to be used as a verifier within Kitchen.
To use InSpec as a verifier, add it to the kitchen.yml file:
verifier:
name: inspec
To define a suite that pulls its run-list from the Chef Compliance server:
suites:
- name: compliance
run_list:
- recipe[ssh-hardening]
verifier:
inspec_tests:
- compliance://base/ssh
and then run the following command:
$ inspec compliance login https://compliance.test --user admin --insecure --token ''
where `--insecure` is required when using self-signed certificates.
To define a suite that pulls its run-list from the Chef Supermarket:
suites:
- name: supermarket
run_list:
- recipe[ssh-hardening]
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

302
docs/profiles.md Normal file
View file

@ -0,0 +1,302 @@
---
title: About InSpec Profiles
---
# InSpec Profiles
InSpec supports the creation of complex test and compliance profiles, which organize controls to support dependency management and code reuse. Each profile is a standalone structure with its own distribution and execution flow.
# Profile Structure
A profile should have the following structure::
examples/profile
├── README.md
├── controls
│ ├── example.rb
│ └── control_etc.rb
├── libraries
│ └── extension.rb
└── inspec.yml
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)
* `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
## inspec.yml
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 `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
## Verify Profiles
Use the `inspec check` command to verify the implementation of a profile:
$ 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
and to target only Ubuntu version 14.04
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
and to target anything running on Amazon AWS:
name: ssh
supports:
- platform: aws
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
A profile dependency is needed when:
* using `include_controls` or `require_controls` in order to load controls defined in another profile
* using a custom InSpec resource defined in another profile
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.
## 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. This setting does not support version constraints. If the location of the profile does not exist, an error is returned.
For example:
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, tar.gz format). If the download fails, the profile is inaccessible, or not in the correct format, an error is returned.
For example:
depends:
- name: my-profile
url: https://my.domain/path/to/profile.tgz
## 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.
For example:
depends:
- name: git-profile
git: http://url/to/repo
branch: desired_branch
tag: desired_version
commit: pinned_commit
version: semver_via_tags
## Chef 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.
For example:
depends:
- name: supermarket-profile
git: username/profile
branch: desired_branch
tag: desired_version
commit: pinned_commit
version: semver_via_tags
## GitHub
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.
For example:
depends:
- name: gh-profile
git: username/project
branch: desired_branch
tag: desired_version
commit: pinned_commit
version: semver_via_tags
## Chef Compliance
A `compliance` setting specifies a profile that is located on the Chef Compliance server.
For example:
depends:
- name: linux
compliance: base/linux
## Define in inspec.yml
Use the `depends` setting in the `inspec.yml` file to define any combination of profile dependencies. For example:
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
## Vendoring Dependencies
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:
* running `inspec vendor` inside the profile directory; or
* deleting `inspec.lock` before running `inspec exec`
# Profile Inheritance
When a profile is run, it may include controls that are defined in other profiles. Controls may also be required.
This requires an `inspec.yml` dependency to the profile you inherit from.
## include_controls
The `include_controls` keyword may be used in a profile to import all rules from the named profile.
For example, to include controls from the `cis-level-1` profile when running the `cis-fs-2.7` profile:
include_controls 'cis-level-1' do
control "cis-fs-2.7" do
impact 1.0
...
end
To include controls from the `cis-level-1` profile, but skipping two controls within that profile:
include_controls 'cis-level-1' do
skip_control "cis-fs-2.1"
skip_control "cis-fs-2.2"
end
## require_controls
The `require_controls` keyword may be used to load only specific controls from the named profile.
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 'cis-level-1' do
control "cis-fs-2.1"
control "cis-fs-2.2"
end
## require_resource
By default, all of the 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:
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.
For example, a control:
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
describe val_password do
it { should eq 'secret' }
end
And a Yaml file named `profile-attribute.yml`:
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
See the full example in the InSpec open source repository: https://github.com/chef/inspec/tree/master/examples/profile-attribute

169
docs/profiles.rst
View file

@ -1,169 +0,0 @@
=====================================================
InSpec Profiles
=====================================================
InSpec supports the creation of complex test and compliance profiles, which organize controls to support dependency management and code re-use. These profiles are standalone structures with their own distribution and execution flow.
InSpec profile structure
-----------------------------------------------------
To create a new profile just place the files according to the following structure:
.. code-block:: bash
$ tree examples/profile
examples/profile
├── README.md
├── controls
│   ├── example.rb
│   └── gordon.rb
├── libraries
│   └── gordon_config.rb
└── inspec.yml
* `inspec.yml` - includes the profile description (required)
* `controls` - a folder which contains all tests (required)
* `libraries` - a folder which contains InSpec resource extensions (optional)
* `README.md` - a best-practice readme to each explain the profile and its scope
For a full example, see our `example profile`_.
.. _example profile: ../examples/profile
InSpec profile manifest
-----------------------------------------------------
Each profile has a manifest file `inspec.yml`. It looks as follows
.. code-block:: 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
A manifest description may contain the following values:
* `name` - Identifier of the profile (required)
* `title` - Human-readable name of the profile (optional)
* `maintainer` - Name of the profile maintainer (optional)
* `copyright` - Copyright holder (optional)
* `copyright_email` - Support contact for profile (optional)
* `license` - License of the profile (optional)
* `summary` - One-line summary of the profile (optional)
* `description` - Description of the profile (optional)
* `version` - Version of the profile (optional)
* `supports` - A list of supported targets (optional)
Supported targets
-----------------------------------------------------
The manifest contains the `supports` flag, which specifies operating systems or even cloud systems that the profile is targeting.
This list can contain simple names, names and versions, or detailed flags for the targeted system. These can freely be combined:
.. code-block:: yaml
name: ssh
supports:
// Runs on any version of Debian Linux
- os-name: debian
// Only runs on Ubuntu 14.04
- os-name: ubuntu
release: 14.04
// Targets RedHat, CentOS, Oracle Linux ...
- os-family: redhat
// Or even broader
- platform: aws
InSpec profile verification
-----------------------------------------------------
InSpec ships with a verification command that verifies the implementation of a profile:
.. code-block:: bash
$ inspec check examples/profile
InSpec profile archive
-----------------------------------------------------
Profiles are composed of multiple files. This hinders easy distribution of a profile. InSpec solves the problem by offering to collect all files in one archive.
The InSpec profile archive format aims for flexibility and reuse of standard and common technologies:
* tar and gzip (default)
* zip
* HTTP
This should enable third-parties to easily build InSpec profile archives:
* InSpec archives MUST be named with the stanard suffix
* InSpec archives MUST be a tar.gz or zip formatted file
* InSpec archives MUST have no duplicate entries
* InSpec archives MAY be compressed with gzip, bzip2, or xz.
InSpec is able to create profile archive for you. By default it generates a tar-file on Unix and zip on Windows or Mac.
.. code-block:: bash
# will generate a example-profile.tar.gz
$ inspec archive examples/profile
# will generate a example-profile.zip
$ inspec archive examples/profile --zip
Profile inheritance
-----------------------------------------------------
**Include controls of existing profile**
The `include_controls` keyword allows you to import all rules from an existing profile. This can be easily extended with additional rules.
.. code-block:: bash
include_controls 'cis-level-1' do
control "cis-fs-2.7" do
impact 1.0
...
end
**Inherit from a profile, but skip some rules**
Sometimes, not all requirements can be fulfilled for a legacy application. To manage the derivation, you can skip certain controls with `skip_control`.
.. code-block:: bash
include_controls 'cis-level-1' do
skip_control "cis-fs-2.1"
skip_control "cis-fs-2.2"
end
**Load specific controls from another profile**
.. code-block:: bash
require_controls 'cis-level-1' do
control "cis-fs-2.1"
control "cis-fs-2.2"
end

105
docs/readme.rst
View file

@ -1,105 +0,0 @@
=====================================================
InSpec Documentation
=====================================================
InSpec a collection of resources and matchers to test the compliance of your nodes. This documentation provides an introduction to this mechanism and shows how to write custom tests.
Introduction
-----------------------------------------------------
At first, we add our tests to the ``test`` folder. Each test file must end with ``_spec.rb``:
.. code-block:: bash
mkdir test
touch test/example_spec.rb
We add a control to this file, to check the ``/tmp`` path in our system:
.. code-block:: ruby
# encoding: utf-8
control "cis-fs-2.1" do # A unique ID for this control
impact 0.7 # The criticality, if this control fails.
title "Create separate /tmp partition" # A human-readable title
desc "An optional description..."
tag mygroup: "tag" # A tag can be a simple value or
tag "tag" # can have a more complex key/value pair.
ref "name", url: "http://..." # A reference to a document, uri: is optional
describe file('/tmp') do # The actual test
it { should be_mounted }
end
end
Let's add another spec for checking the SSH server configuration:
.. code-block:: bash
touch test/sshd_spec.rb
It will contain:
.. code-block:: ruby
# encoding: utf-8
# Skip all controls, if SSH doesn't exist on the system
only_if do
command('sshd').exist?
end
control "sshd-11" do
impact 1.0
title "Server: Set protocol version to SSHv2"
desc "Set the SSH protocol version to 2. Don't use legacy
insecure SSHv1 connections anymore."
tag security: "openssh-server"
ref "Document A-12"
describe sshd_config do
its('Protocol') { should eq('2') }
end
end
control "sshd-7" do
impact 1.0
title "Server: Do not permit root-based login with password."
desc "To reduce the potential to gain full privileges
of a system in the course of an attack (by either misconfiguration
or vulnerabilities), do not allow login as root with password"
tag security: "openssh-server"
ref "Document A-12"
describe sshd_config do
its('PermitRootLogin') { should match(/no|without-password/) }
end
end
Now, we are ready to run the tests locally:
bundle exec bin/inspec exec demo/test/example_spec.rb
.. code-block:: bash
# run tests individually
$ inspec exec test/example_spec.rb
$ inspec exec test/sshd_spec.rb
# if you want to run all test located within the directory
$ inspec exec ./test
Stability Index
-----------------------------------------------------
Every available InSpec resource will indicate its stability. As InSpec matures, certain parts are more reliable than others. Brand new features are likely to be redesigned and marked as such.
The stability indices are as follows:
* ``Stability: Deprecated`` - This features will be removed in future versions, because its known for being problematic. Do not rely on it.
* ``Stability: Experimental`` - New features may change or are removed in future versions
* ``Stability: Stable`` - API is well established and proofed. Maintaining compatibility is a high priority
* ``Stability: Locked`` - Only security and performance fixes are allowed

4784
docs/resources.rst
View file

File diff suppressed because it is too large Load diff

75
docs/resources/apache_conf.md.erb Normal file
View file

@ -0,0 +1,75 @@
---
title: About the apache_conf Resource
---
# apache_conf
Use the `apache_conf` InSpec audit resource to test the configuration settings for Apache. This file is typically located under `/etc/apache2` on the Debian and Ubuntu platforms and under `/etc/httpd` on the Fedora, CentOS, RedHat Enterprise Linux, and ArchLinux platforms. The configuration settings may vary significantly from platform to platform.
## Syntax
An `apache_conf` InSpec audit resource block declares configuration settings that should be tested:
describe apache_conf('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a configuration setting defined in the Apache configuration file
* `('path')` is the non-default path to the Apache configuration file
* `{ should eq 'value' }` is the value that is expected
## Matchers
This InSpec audit resource matches any service that is listed in the Apache configuration file:
its('PidFile') { should_not eq '/var/run/httpd.pid' }
or:
its('Timeout') { should eq 300 }
For example:
describe apache_conf do
its('MaxClients') { should eq 100 }
its('Listen') { should eq '443'}
end
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test for blocking .htaccess files on CentOS
describe apache_conf do
its('AllowOverride') { should eq 'None' }
end
### Test ports for SSL
describe apache_conf do
its('Listen') { should eq '443'}
end

84
docs/resources/apt.md.erb Normal file
View file

@ -0,0 +1,84 @@
---
title: About the apt Resource
---
# apt
Use the `apt` InSpec audit resource to verify Apt repositories on the Debian and Ubuntu platforms, and also PPA repositories on the Ubuntu platform.
## Syntax
An `apt` resource block tests the contents of Apt and PPA repositories:
describe apt('path') do
it { should exist }
it { should be_enabled }
end
where
* `apt('path')` must specify an Apt or PPA repository
* `('path')` may be an `http://` address, a `ppa:` address, or a short `repo-name/ppa` address
* `exist` and `be_enabled` are a valid matchers for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_enabled
The `be_enabled` matcher tests if a package exists in the repository:
it { should be_enabled }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if a package exists on the system:
it { should exist }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test if apt repository exists and is enabled
describe apt('http://ppa.launchpad.net/juju/stable/ubuntu') do
it { should exist }
it { should be_enabled }
end
### Verify that a PPA repository exists and is enabled
describe apt('ppa:nginx/stable') do
it { should exist }
it { should be_enabled }
end
### Verify that a repository is not present
describe apt('ubuntu-wine/ppa') do
it { should_not exist }
it { should_not be_enabled }
end

61
docs/resources/audit_policy.md.erb Normal file
View file

@ -0,0 +1,61 @@
---
title: About the audit_policy Resource
---
# audit_policy
Use the `audit_policy` Inspec audit resource to test auditing policies on the Windows platform. An auditing policy is a category of security-related events to be audited. Auditing is disabled by default and may be enabled for categories like account management, logon events, policy changes, process tracking, privilege use, system events, or object access. For each auditing category property that is enabled, the auditing level may be set to `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`.
## Syntax
An `audit_policy` resource block declares a parameter that belongs to an audit policy category or subcategory:
describe audit_policy do
its('parameter') { should eq 'value' }
end
where
* `'parameter'` must specify a parameter
* `'value'` must be one of `No Auditing`, `Not Specified`, `Success`, `Success and Failure`, or `Failure`
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test that a parameter is not set to "No Auditing"
describe audit_policy do
its('Other Account Logon Events') { should_not eq 'No Auditing' }
end
### Test that a parameter is set to "Success"
describe audit_policy do
its('User Account Management') { should eq 'Success' }
end

79
docs/resources/auditd_conf.md.erb Normal file
View file

@ -0,0 +1,79 @@
---
title: About the auditd_conf Resource
---
# auditd_conf
Use the `auditd_conf` InSpec audit resource to test the configuration settings for the audit daemon. This file is typically located under `/etc/audit/auditd.conf'` on Unix and Linux platforms.
## Syntax
A `auditd_conf` resource block declares configuration settings that should be tested:
describe auditd_conf('path') do
its('keyword') { should cmp 'value' }
end
where
* `'keyword'` is a configuration setting defined in the `auditd.conf` configuration file
* `('path')` is the non-default path to the `auditd.conf` configuration file
* `{ should cmp 'value' }` is the value that is expected
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### keyword
This matcher will matche any keyword that is listed in the `auditd.conf` configuration file. Option names and values are case-insensitive:
its('log_format') { should cmp 'raw' }
or:
its('max_log_file') { should cmp 6 }
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test the auditd.conf file
describe auditd_conf do
its('log_file') { should cmp '/full/path/to/file' }
its('log_format') { should cmp 'raw' }
its('flush') { should cmp 'none' }
its('freq') { should cmp 1 }
its('num_logs') { should cmp 0 }
its('max_log_file') { should cmp 6 }
its('max_log_file_action') { should cmp 'email' }
its('space_left') { should cmp 2 }
its('action_mail_acct') { should cmp 'root' }
its('space_left_action') { should cmp 'email' }
its('admin_space_left') { should cmp 1 }
its('admin_space_left_action') { should cmp 'halt' }
its('disk_full_action') { should cmp 'halt' }
its('disk_error_action') { should cmp 'halt' }
end

132
docs/resources/auditd_rules.md.erb Normal file
View file

@ -0,0 +1,132 @@
---
title: About the auditd_rules Resource
---
# auditd_rules
Use the `auditd_rules` InSpec audit resource to test the rules for logging that exist on the system. The `audit.rules` file is typically located under `/etc/audit/` and contains the list of rules that define what is captured in log files. This resource uses `auditctl` to query the run-time `auditd` rules setup, which may be different from `audit.rules`.
## Syntax
An `auditd_rules` resource block declares one (or more) rules to be tested, and then what that rule should do. The syntax depends on the version of `audit`:
For `audit` >= 2.3:
describe auditd_rules do
its('lines') { should contain_match(rule) }
end
For `audit` < 2.3:
describe audit_daemon_rules do
its("LIST_RULES") {
rule
}
end
For example:
describe auditd_rules do
its('LIST_RULES') { should eq [
'exit,always syscall=rmdir,unlink',
'exit,always auid=1001 (0x3e9) syscall=open',
'exit,always watch=/etc/group perm=wa',
'exit,always watch=/etc/passwd perm=wa',
'exit,always watch=/etc/shadow perm=wa',
'exit,always watch=/etc/sudoers perm=wa',
'exit,always watch=/etc/secret_directory perm=r',
] }
end
or test that individual rules are defined:
describe auditd_rules do
its('LIST_RULES') {
should contain_match(/^exit,always watch=\/etc\/group perm=wa key=identity/)
}
its('LIST_RULES') {
should contain_match(/^exit,always watch=\/etc\/passwd perm=wa key=identity/)
}
its('LIST_RULES') {
should contain_match(/^exit,always watch=\/etc\/gshadow perm=wa key=identity/)
}
its('LIST_RULES') {
should contain_match(/^exit,always watch=\/etc\/shadow perm=wa key=identity/)
}
its('LIST_RULES') {
should contain_match(/^exit,always watch=\/etc\/security\/opasswd perm=wa key=identity/)
}
end
where each test must declare one (or more) rules to be tested.
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test if a rule contains a matching element that is identified by a regular expression
For `audit` >= 2.3:
describe auditd_rules do
its('lines') { should contain_match(%r{-w /etc/ssh/sshd_config/}) }
end
For `audit` < 2.3:
describe audit_daemon_rules do
its("LIST_RULES") {
should contain_match(/^exit,always arch=.*\
key=time-change\
syscall=adjtimex,settimeofday/)
}
end
### Query the audit daemon status
describe auditd_rules.status('backlog') do
it { should cmp 0 }
end
### Query properties of rules targeting specific syscalls or files
describe auditd_rules.syscall('open').action do
it { should eq(['always']) }
end
describe auditd_rules.key('sshd_config') do
its('permissions') { should contain_match(/x/) }
end
Filters may be chained. For example:
describe auditd_rules.syscall('open').action('always').list do
it { should eq(['exit']) }
end

84
docs/resources/bash.md.erb Normal file
View file

@ -0,0 +1,84 @@
---
title: About the bash Resource
---
# bash
Use the `bash` InSpec audit resource to test an arbitrary command that is run on the system using a Bash script.
## Syntax
A `command` resource block declares a command to be run, one (or more) expected outputs, and the location to which that output is sent:
describe bash('command') do
it { should exist }
its('matcher') { should eq 'output' }
end
where
* `'command'` must specify a command to be run
* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
* `'output'` tests the output of the command run on the system versus the output value stated in the test
For example:
describe bash('ls -al /') do
its('stdout') { should match /bin/ }
its('stderr') { should eq '' }
its('exit_status') { should eq 0 }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if a command may be run on the system:
it { should exist }
### exit_status
The `exit_status` matcher tests the exit status for the command:
its('exit_status') { should eq 0 }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### stderr
The `stderr` matcher tests results of the command as returned in standard error (stderr):
its('stderr') { should eq '' }
### stdout
The `stdout` matcher tests results of the command as returned in standard output (stdout).
its('stdout') { should match /bin/ }
## Examples
None.

97
docs/resources/bond.md.erb Normal file
View file

@ -0,0 +1,97 @@
---
title: About the bond Resource
---
# bond
Use the `bond` InSpec audit resource to test a logical, bonded network interface (i.e. "two or more network interfaces aggregated into a single, logical network interface"). On Linux platforms, any value in the `/proc/net/bonding` directory may be tested.
## Syntax
A `bond` resource block declares a bonded network interface, and then specifies the properties of that bonded network interface to be tested:
describe bond('name') do
it { should exist }
end
where
* `'name'` is the name of the bonded network interface
* `{ should exist }` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### content
The `content` matcher tests if contents in the file that defines the bonded network interface match the value specified in the test. The values of the `content` matcher are arbitrary:
its('content') { should match('value') }
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the bonded network interface is available:
it { should exist }
### have_interface
The `have_interface` matcher tests if the bonded network interface has one (or more) secondary interfaces:
it { should have_interface }
### include
<%= partial "/shared/matcher_include" %>
### interfaces
The `interfaces` matcher tests if the named secondary interfaces are available:
its('interfaces') { should eq ['eth0', 'eth1', ...] }
### match
<%= partial "/shared/matcher_match" %>
### params
The `params` matcher tests arbitrary parameters for the bonded network interface:
its('params') { should eq 'value' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if eth0 is a secondary interface for bond0
describe bond('bond0') do
it { should exist }
it { should have_interface 'eth0' }
end
### Test parameters for bond0
describe bond('bond0') do
its('Bonding Mode') { should eq 'IEEE 802.3ad Dynamic link aggregation' }
its('Transmit Hash Policy') { should eq 'layer3+4 (1)' }
its('MII Status') { should eq 'up' }
its('MII Polling Interval (ms)') { should eq '100' }
its('Up Delay (ms)') { should eq '0' }
its('Down Delay (ms)') { should eq '0' }
end

67
docs/resources/bridge.md.erb Normal file
View file

@ -0,0 +1,67 @@
---
title: About the bridge Resource
---
# bridge
Use the `bridge` InSpec audit resource to test basic network bridge properties, such as name, if an interface is defined, and the associations for any defined interface.
* On Linux platforms, any value in the `/sys/class/net/{interface}/bridge` directory may be tested
* On the Windows platform, the `Get-NetAdapter` cmdlet is associated with the `Get-NetAdapterBinding` cmdlet and returns the `ComponentID ms_bridge` value as a JSON object
## Syntax
A `bridge` resource block declares the bridge to be tested and what interface it should be associated with:
describe bridge('br0') do
it { should exist }
it { should have_interface 'eth0' }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the network bridge is available:
it { should exist }
### have_interface
The `have_interface` matcher tests if the named interface is defined for the network bridge:
it { should have_interface 'eth0' }
### include
<%= partial "/shared/matcher_include" %>
### interfaces
The `interfaces` matcher tests if the named interface is present:
its('interfaces') { should eq 'foo' }
its('interfaces') { should eq 'bar' }
its('interfaces') { should include('foo') }
### match
<%= partial "/shared/matcher_match" %>
## Examples
None.

76
docs/resources/bsd_service.md.erb Normal file
View file

@ -0,0 +1,76 @@
---
title: About the bsd_service Resource
---
# bsd_service
Use the `bsd_service` InSpec audit resource to test a service using a Berkeley OS-style `init` on the FreeBSD platform.
## Syntax
A `bsd_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe bsd_service('service_name') do
it { should be_installed }
it { should be_enabled }
it { should be_running }
end
where
* `('service_name')` must specify a service name
* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
describe bsd_service('service_name', '/path/to/control') do
it { should be_enabled }
it { should be_installed }
it { should be_running }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_enabled
The `be_enabled` matcher tests if the named service is enabled:
it { should be_enabled }
### be_installed
The `be_installed` matcher tests if the named service is installed:
it { should be_installed }
### be_running
The `be_running` matcher tests if the named service is running:
it { should be_running }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
None.

151
docs/resources/command.md.erb Normal file
View file

@ -0,0 +1,151 @@
---
title: About the command Resource
---
# command
Use the `command` InSpec audit resource to test an arbitrary command that is run on the system.
## Syntax
A `command` resource block declares a command to be run, one (or more) expected outputs, and the location to which that output is sent:
describe command('command') do
it { should exist }
its('matcher') { should eq 'output' }
end
where
* `'command'` must specify a command to be run
* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
* `'output'` tests the output of the command run on the system versus the output value stated in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if a command may be run on the system:
it { should exist }
### exit_status
The `exit_status` matcher tests the exit status for the command:
its('exit_status') { should eq 123 }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### stderr
The `stderr` matcher tests results of the command as returned in standard error (stderr):
its('stderr') { should eq 'error' }
### stdout
The `stdout` matcher tests results of the command as returned in standard output (stdout). The following example shows matching output using a regular expression:
describe command('echo 1') do
its('stdout') { should match (/[0-9]/) }
end
## Examples
The following examples show how to use this InSpec audit resource.
### Test for PostgreSQL database running a RC, development, or beta release
describe command('psql -V') do
its('stdout') { should eq '/RC/' }
its('stdout') { should_not eq '/DEVEL/' }
its('stdout') { should_not eq '/BETA/' }
end
### Test standard output (stdout)
describe command('echo hello') do
its('stdout') { should eq 'hello\n' }
its('stderr') { should eq '' }
its('exit_status') { should eq 0 }
end
### Test standard error (stderr)
describe command('>&2 echo error') do
its('stdout') { should eq '' }
its('stderr') { should eq 'error\n' }
its('exit_status') { should eq 0 }
end
### Test an exit status code
describe command('exit 123') do
its('stdout') { should eq '' }
its('stderr') { should eq '' }
its('exit_status') { should eq 123 }
end
### Test if the command shell exists
describe command('/bin/sh').exist? do
it { should eq true }
end
### Test for a command that should not exist
describe command('this is not existing').exist? do
it { should eq false }
end
### Verify NTP
The following example shows how to use the `file` audit resource to verify if the `ntp.conf` and `leap-seconds` files are present, and then the `command` resource to verify if NTP is installed and running:
describe file('/etc/ntp.conf') do
it { should be_file }
end
describe file('/etc/ntp.leapseconds') do
it { should be_file }
end
describe command('pgrep ntp') do
its('exit_status') { should eq 0 }
end
### Verify WiX
Wix includes serveral tools -- such as `candle` (preprocesses and compiles source files into object files), `light` (links and binds object files to an installer database), and `heat` (harvests files from various input formats). The following example uses a whitespace array and the `file` audit resource to verify if these three tools are present:
%w(
candle.exe
heat.exe
light.exe
).each do |utility|
describe file("C:/wix/##{utility}") do
it { should be_file }
end
end

62
docs/resources/csv.md.erb Normal file
View file

@ -0,0 +1,62 @@
---
title: About the csv Resource
---
# csv
Use the `csv` InSpec audit resource to test configuration data in a CSV file.
## Syntax
A `csv` resource block declares the configuration data to be tested:
describe csv('file') do
its('name') { should eq 'foo' }
end
where
* `'file'` is the path to a CSV file
* `name` is a configuration setting in a CSV file
* `should eq 'foo'` tests a value of `name` as read from a CSV file versus the value declared in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### name
The `name` matcher tests the value of `name` as read from a CSV file versus the value declared in the test:
its('name') { should eq 'foo' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test a CSV file
describe csv('some_file.csv') do
its('setting') { should eq 1 }
end

43
docs/resources/directory.md.erb Normal file
View file

@ -0,0 +1,43 @@
---
title: About the directory Resource
---
# directory
Use the `directory` InSpec audit resource to test if the file type is a directory. This is equivalent to using the `file` resource and the `be_directory` matcher, but provides a simpler and more direct way to test directories. All of the matchers available to `file` may be used with `directory`.
## Syntax
A `directory` resource block declares the location of the directory to be tested, and then one (or more) matchers:
describe directory('path') do
it { should MATCHER 'value' }
end
## Matchers
This resource may use any of the matchers available to the `file` resource that may be useful when testing a directory.
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
None.

116
docs/resources/etc_group.md.erb Normal file
View file

@ -0,0 +1,116 @@
---
title: About the etc_group Resource
---
# etc_group
Use the `etc_group` InSpec audit resource to test groups that are defined on Linux and Unix platforms. The `/etc/group` file stores details about each group---group name, password, group identifier, along with a comma-separate list of users that belong to the group.
## Syntax
A `etc_group` resource block declares a collection of properties to be tested:
describe etc_group('path') do
its('matcher') { should eq 'some_value' }
end
or:
describe etc_group.where(item: 'value', item: 'value') do
its('gids') { should_not contain_duplicates }
its('groups') { should include 'user_name' }
its('users') { should include 'user_name' }
end
where
* `('path')` is the non-default path to the `inetd.conf` file
* `.where()` may specify a specific item and value, to which the matchers are compared
* `'gids'`, `'groups'`, and `'users'` are valid matchers for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### gids
The `gids` matcher tests if the named group identifier is present or if it contains duplicates:
its('gids') { should_not contain_duplicates }
### groups
The `groups` matcher tests all groups for the named user:
its('groups') { should include 'my_group' }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### users
The `users` matcher tests all groups for the named user:
its('users') { should include 'my_user' }
### where
The `where` matcher allows the test to be focused to one (or more) specific items:
etc_group.where(item: 'value', item: 'value')
where `item` may be one (or more) of:
* `name: 'name'`
* `group_name: 'group_name'`
* `password: 'password'`
* `gid: 'gid'`
* `group_id: 'gid'`
* `users: 'user_name'`
* `members: 'member_name'`
## Examples
The following examples show how to use this InSpec audit resource.
### Test group identifiers (GIDs) for duplicates
describe etc_group do
its('gids') { should_not contain_duplicates }
end
### Test all groups to see if a specific user belongs to one (or more) groups
describe etc_group do
its('groups') { should include 'my_group' }
end
### Test all groups for a specific user name
describe etc_group do
its('users') { should include 'my_user' }
end
### Filter a list of groups for a specific user
describe etc_group.where(name: 'my_group') do
its('users') { should include 'my_user' }
end

155
docs/resources/etc_passwd.md.erb Normal file
View file

@ -0,0 +1,155 @@
---
title: About the passwd Resource
---
# passwd
Use the `passwd` InSpec audit resource to test the contents of `/etc/passwd`, which contains the following information for users that may log into the system and/or as users that own running processes. The format for `/etc/passwd` includes:
* A username
* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
* The user identifier (UID) assigned to that user
* The group identifier (GID) assigned to that user
* Additional information about that user
* That user's home directory
* That user's default command shell
These entries are defined as a colon-delimited row in the file, one row per user:
root:x:1234:5678:additional_info:/home/dir/:/bin/bash
## Syntax
A `passwd` resource block declares one (or more) users and associated user information to be tested:
describe passwd do
its('users') { should_not include 'forbidden_user' }
end
describe passwd.uid(filter) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
where
* `homes`, `gids`, `passwords`, `shells`, `uids`, and `users` are valid accessors for `passwd`
* `filter` one (or more) arguments, for example: `passwd.users(/name/)` used to define filtering
* `filter` may take any of the following arguments: `count` (retrieves the number of entries), `lines` (provides raw `passwd` lines), and `params` (returns an array of maps for all entries)
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### gids
The `gids` matcher tests if the group indentifiers in the test match group identifiers in `/etc/passwd`:
its('gids') { should include 1234 }
its('gids') { should cmp 0 }
### homes
The `homes` matcher tests the absolute path to a user's home directory:
its('home') { should eq '/' }
### include
<%= partial "/shared/matcher_include" %>
### length
The `length` matcher tests the length of a password that appears in `/etc/passwd`:
its('length') { should be <= 32 }
This matcher is best used in conjunction with filters. For example:
describe passwd.users('highlander') do
its('length') { should_not be < 16 }
end
### match
<%= partial "/shared/matcher_match" %>
### passwords
The `passwords` matcher tests if passwords are
* Encrypted
* Have direct logins disabled, as indicated by an asterisk (`*`)
* In the `/etc/shadow` file, as indicated by the letter x (`x`)
For example:
its('passwords') { should eq ['x'] }
its('passwords') { should cmp '*' }
### shells
The `shells` matcher tests the absolute path of a shell (or command) to which a user has access:
its('shells') { should_not include 'user' }
or to find all users with the nologin shell:
describe passwd.shells(/nologin/) do
its('users') { should_not include 'my_login_user' }
end
### uids
The `uids` matcher tests if the user indentifiers in the test match user identifiers in `/etc/passwd`:
its('uids') { should eq ['1234', '1235'] }
or:
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
### users
The `users` matcher tests if the user names in the test match user names in `/etc/passwd`:
its('users') { should eq ['root', 'www-data'] }
## Examples
The following examples show how to use this InSpec audit resource.
### Test usernames and UIDs
describe passwd do
its('users') { should eq ['root', 'www-data'] }
its('uids') { should eq [0, 33] }
end
### Select one user and test for multiple occurrences
describe passwd.uids(0) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
describe passwd.filter(user: 'www-data') do
its('uids') { should cmp 33 }
its('count') { should eq 1 }
end

149
docs/resources/etc_shadow.md.erb Normal file
View file

@ -0,0 +1,149 @@
---
title: About the shadow Resource
---
# shadow
Use the `shadow` InSpec audit resource to test the contents of `/etc/shadow`, which contains password details that are only readable by the `root` user. The format for `/etc/shadow` includes:
* A username
* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
* The last time a password was changed
* The minimum number of days a password must exist, before it may be changed
* The maximum number of days after which a password must be changed
* The number of days a user is warned about an expiring password
* The number of days a user must be inactive before the user account is disabled
* The number of days a user account has been disabled
These entries are defined as a colon-delimited row in the file, one row per user:
dannos:Gb7crrO5CDF.:10063:0:99999:7:::
## Syntax
A `shadow` resource block declares one (or more) users and associated user information to be tested:
describe shadow do
its('users') { should_not include 'forbidden_user' }
end
or with a filter:
describe shadow.uid(filter) do
its('users') { should cmp 'root' }
its('count') { should eq 1 }
end
where
* `homes`, `gids`, `passwords`, `shells`, `uids`, and `users` are valid accessors for `passwd`
* `filter` one (or more) arguments, for example: `passwd.users(/name/)` used to define filtering; `filter` may take any of the following arguments: `count` (retrieves the number of entries), `lines` (provides raw `passwd` lines), and `params` (returns an array of maps for all entries)
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### count
The `count` matcher tests the number of times the named user appears in `/etc/shadow`:
its('count') { should eq 1 }
TThis matcher is best used in conjunction with filters. For example:
describe shadow.users('dannos') do
its('count') { should eq 1 }
end
### eq
<%= partial "/shared/matcher_eq" %>
### expiry_dates
The `expiry_dates` matcher tests the number of days a user account has been disabled:
its('expiry_dates') { should eq '' }
### inactive_days
The `inactive_days` matcher tests the number of days a user must be inactive before the user account is disabled:
its('inactive_days') { should eq '' }
### include
<%= partial "/shared/matcher_include" %>
### last_changes
The `last_changes` matcher tests the last time a password was changed:
its('last_changes') { should eq '' }
### match
<%= partial "/shared/matcher_match" %>
### max_days
The `max_days` matcher tests the maximum number of days after which a password must be changed:
its('max_days') { should eq 90 }
### min_days
The `min_days` matcher tests the minimum number of days a password must exist, before it may be changed:
its('min_days') { should eq 0 }
### passwords
The `passwords` matcher tests if passwords are
* Encrypted
* Have direct logins disabled, as indicated by an asterisk (`*`)
* In the `/etc/shadow` file, as indicated by the letter x (`x`)
For example:
its('passwords') { should eq ['x'] }
its('passwords') { should cmp '*' }
### users
The `users` matcher tests if the user name exists `/etc/shadow`:
its('users') { should eq 'root' }
### warn_days
The `warn_days` matcher tests the number of days a user is warned about an expiring password:
its('warn_days') { should eq 7 }
## Examples
The following examples show how to use this InSpec audit resource.
### Test for a forbidden user
describe shadow do
its('users') { should_not include 'forbidden_user' }
end
### Test that a user appears one time
describe shadow.users('bin') do
its('passwords') { should cmp 'x' }
its('count') { should eq 1 }
end

460
docs/resources/file.md.erb Normal file
View file

@ -0,0 +1,460 @@
---
title: About the file Resource
---
# file
Use the `file` InSpec audit resource to test all system file types, including files, directories, symbolic links, named pipes, sockets, character devices, block devices, and doors.
## Syntax
A `file` resource block declares the location of the file type to be tested, what type that file should be (if required), and then one (or more) matchers:
describe file('path') do
it { should MATCHER 'value' }
end
where
* `('path')` is the name of the file and/or the path to the file
* `MATCHER` is a valid matcher for this resource
* `'value'` is the value to be tested
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be\_block\_device
The `be_block_device` matcher tests if the file exists as a block device, such as `/dev/disk0` or `/dev/disk0s9`:
it { should be_block_device }
### be\_character\_device
The `be_character_device` matcher tests if the file exists as a character device (that corresponds to a block device), such as `/dev/rdisk0` or `/dev/rdisk0s9`:
it { should be_character_device }
### be_directory
The `be_directory` matcher tests if the file exists as a directory, such as `/etc/passwd`, `/etc/shadow`, or `/var/log/httpd`:
it { should be_directory }
### be_executable
The `be_executable` matcher tests if the file exists as an executable:
it { should be_executable }
The `be_executable` matcher may also test if the file is executable by a specific owner, group, or user. For example, a group:
it { should be_executable.by('group') }
an owner:
it { should be_executable.by('owner') }
a user:
it { should be_executable.by_user('user') }
### be_file
The `be_file` matcher tests if the file exists as a file. This can be useful with configuration files like `/etc/passwd` where there typically is not an associated file extension---`passwd.txt`:
it { should be_file }
### be\_grouped\_into
The `be_grouped_into` matcher tests if the file exists as part of the named group:
it { should be_grouped_into 'group' }
### be_immutable
The `be_immutable` matcher tests if the file is immutable, i.e. "cannot be changed":
it { should be_immutable }
### be\_linked\_to
The `be_linked_to` matcher tests if the file is linked to the named target:
it { should be_linked_to '/etc/target-file' }
### be_mounted
The `be_mounted` matcher tests if the file is accessible from the file system:
it { should be_mounted }
### be\_owned\_by
The `be_owned_by` matcher tests if the file is owned by the named user, such as `root`:
it { should be_owned_by 'root' }
### be_pipe
The `be_pipe` matcher tests if the file exists as first-in, first-out special file (`.fifo`) that is typically used to define a named pipe, such as `/var/log/nginx/access.log.fifo`:
it { should be_pipe }
### be_readable
The `be_readable` matcher tests if the file is readable:
it { should be_readable }
The `be_readable` matcher may also test if the file is readable by a specific owner, group, or user. For example, a group:
it { should be_readable.by('group') }
an owner:
it { should be_readable.by('owner') }
a user:
it { should be_readable.by_user('user') }
### be_socket
The `be_socket` matcher tests if the file exists as socket (`.sock`), such as `/var/run/php-fpm.sock`:
it { should be_socket }
### be_symlink
The `be_symlink` matcher tests if the file exists as a symbolic, or soft link that contains an absolute or relative path reference to another file:
it { should be_symlink }
### be_version
The `be_version` matcher tests the version of the file:
it { should be_version '1.2.3' }
### be_writable
The `be_writable` matcher tests if the file is writable:
it { should be_writable }
The `be_writable` matcher may also test if the file is writable by a specific owner, group, or user. For example, a group:
it { should be_writable.by('group') }
an owner:
it { should be_writable.by('owner') }
a user:
it { should be_writable.by_user('user') }
### cmp
<%= partial "/shared/matcher_cmp" %>
### content
The `content` matcher tests if contents in the file match the value specified in a regular expression. The values of the `content` matcher are arbitrary and depend on the file type being tested and also the type of information that is expected to be in that file:
its('content') { should match REGEX }
The following complete example tests the `pg_hba.conf` file in PostgreSQL for MD5 requirements. The tests look at all `host` and `local` settings in that file, and then compare the MD5 checksums against the values in the test:
describe file(hba_config_file) do
its('content') { should match(%r{local\s.*?all\s.*?all\s.*?md5}) }
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5}) }
its('content') { should match(%r{host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5})
end
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the named file exists:
it { should exist }
### file_version
The `file_version` matcher tests if the file's version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
its('file_version') { should eq '1.2.3' }
### group
The `group` matcher tests if the group to which a file belongs matches the specified value:
its('group') { should eq 'admins' }
### have_mode
The `have_mode` matcher tests if a file has a mode assigned to it:
it { should have_mode }
### include
<%= partial "/shared/matcher_include" %>
### link_path
The `link_path` matcher tests if the file exists at the specified path:
its('link_path') { should eq '/some/path/to/file' }
### link_target
The `link_target` matcher tests if a file that is linked to this file exists at the specified path:
its('link_target') { should eq '/some/path/to/file' }
### match
<%= partial "/shared/matcher_match" %>
### md5sum
The `md5sum` matcher tests if the MD5 checksum for a file matches the specified value:
its('md5sum') { should eq '3329x3hf9130gjs9jlasf2305mx91s4j' }
### mode
The `mode` matcher tests if the mode assigned to the file matches the specified value:
its('mode') { should cmp '0644' }
### mtime
The `mtime` matcher tests if the file modification time for the file matches the specified value:
its('mtime') { should eq 'October 31 2015 12:10:45' }
or:
describe file('/').mtime.to_i do
it { should <= Time.now.to_i }
it { should >= Time.now.to_i - 1000}
end
### owner
The `owner` matcher tests if the owner of the file matches the specified value:
its('owner') { should eq 'root' }
### product_version
The `product_version` matcher tests if the file's product version matches the specified value. The difference between a file's "file version" and "product version" is that the file version is the version number of the file itself, whereas the product version is the version number associated with the application from which that file originates:
its('product_version') { should eq 2.3.4 }
### selinux_label
The `selinux_label` matcher tests if the SELinux label for a file matches the specified value:
its('selinux_label') { should eq 'system_u:system_r:httpd_t:s0' }
### sha256sum
The `sha256sum` matcher tests if the SHA-256 checksum for a file matches the specified value:
its('sha256sum') { should eq 'b837ch38lh19bb8eaopl8jvxwd2e4g58jn9lkho1w3ed9jbkeicalplaad9k0pjn' }
### size
The `size` matcher tests if a file's size matches, is greater than, or is less than the specified value. For example, equal:
its('size') { should eq 32375 }
Greater than:
its('size') { should > 64 }
Less than:
its('size') { should < 10240 }
### type
The `type` matcher tests if the first letter of the file's mode string contains one of the following characters:
* `-` or `f` (the file is a file); use `'file` to test for this file type
* `d` (the file is a directory); use `'directory` to test for this file type
* `l` (the file is a symbolic link); use `'link` to test for this file type
* `p` (the file is a named pipe); use `'pipe` to test for this file type
* `s` (the file is a socket); use `'socket` to test for this file type
* `c` (the file is a character device); use `'character` to test for this file type
* `b` (the file is a block device); use `'block` to test for this file type
* `D` (the file is a door); use `'door` to test for this file type
For example:
its('type') { should eq 'file' }
or:
its('type') { should eq 'socket' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test the contents of a file for MD5 requirements
describe file(hba_config_file) do
its('content') { should match /local\s.*?all\s.*?all\s.*?md5/ }
its('content') { should match %r{/host\s.*?all\s.*?all\s.*?127.0.0.1\/32\s.*?md5/} }
its('content') { should match %r{/host\s.*?all\s.*?all\s.*?::1\/128\s.*?md5/} }
end
### Test if a file exists
describe file('/tmp') do
it { should exist }
end
### Test that a file does not exist
describe file('/tmpest') do
it { should_not exist }
end
### Test if a path is a directory
describe file('/tmp') do
its('type') { should eq :directory }
it { should be_directory }
end
### Test if a path is a file and not a directory
describe file('/proc/version') do
its('type') { should eq 'file' }
it { should be_file }
it { should_not be_directory }
end
### Test if a file is a symbolic link
describe file('/dev/stdout') do
its('type') { should eq 'symlink' }
it { should be_symlink }
it { should_not be_file }
it { should_not be_directory }
end
### Test if a file is a character device
describe file('/dev/zero') do
its('type') { should eq 'character' }
it { should be_character_device }
it { should_not be_file }
it { should_not be_directory }
end
### Test if a file is a block device
describe file('/dev/zero') do
its('type') { should eq 'block' }
it { should be_character_device }
it { should_not be_file }
it { should_not be_directory }
end
### Test the mode for a file
describe file('/dev') do
its('mode') { should cmp '00755' }
end
### Test the owner of a file
describe file('/root') do
its('owner') { should eq 'root' }
end
### Test if a file is owned by the root user
describe file('/dev') do
it { should be_owned_by 'root' }
end
### Test the mtime for a file
describe file('/').mtime.to_i do
it { should <= Time.now.to_i }
it { should >= Time.now.to_i - 1000}
end
### Test that a file's size is between 64 and 10240
describe file('/') do
its('size') { should be > 64 }
its('size') { should be < 10240 }
end
### Test that a file's size is zero
describe file('/proc/cpuinfo') do
its('size') { should be 0 }
end
### Test that a file is not mounted
describe file('/proc/cpuinfo') do
it { should_not be_mounted }
end
### Test an MD5 checksum
require 'digest'
cpuinfo = file('/proc/cpuinfo').content
md5sum = Digest::MD5.hexdigest(cpuinfo)
describe file('/proc/cpuinfo') do
its('md5sum') { should eq md5sum }
end
### Test an SHA-256 checksum
require 'digest'
cpuinfo = file('/proc/cpuinfo').content
sha256sum = Digest::SHA256.hexdigest(cpuinfo)
describe file('/proc/cpuinfo') do
its('sha256sum') { should eq sha256sum }
end
### Verify NTP
The following example shows how to use the `file` audit resource to verify if the `ntp.conf` and `leap-seconds` files are present, and then the `command` resource to verify if NTP is installed and running:
describe file('/etc/ntp.conf') do
it { should be_file }
end
describe file('/etc/ntp.leapseconds') do
it { should be_file }
end
describe command('pgrep ntp') do
its('exit_status') { should eq 0 }
end

73
docs/resources/gem.md.erb Normal file
View file

@ -0,0 +1,73 @@
---
title: About the gem Resource
---
# gem
Use the `gem` InSpec audit resource to test if a global Gem package is installed.
## Syntax
A `gem` resource block declares a package and (optionally) a package version:
describe gem('gem_package_name') do
it { should be_installed }
end
where
* `('gem_package_name')` must specify a Gem package, such as `'rubocop'`
* `be_installed` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_installed
The `be_installed` matcher tests if the named Gem package is installed:
it { should be_installed }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### version
The `version` matcher tests if the named package version is on the system:
its('version') { should eq '0.33.0' }
## Examples
The following examples show how to use this InSpec audit resource.
### Verify that a gem package is installed, with a specific version
describe gem('rubocop') do
it { should be_installed }
its('version') { should eq '0.33.0' }
end
### Verify that a gem package is not installed
describe gem('rubocop') do
it { should_not be_installed }
end

74
docs/resources/group.md.erb Normal file
View file

@ -0,0 +1,74 @@
---
title: About the group Resource
---
# group
Use the `group` InSpec audit resource to test groups on the system.
## Syntax
A `group` resource block declares a group, and then the details to be tested, such as if the group is a local group, the group identifier, or if the group exists:
describe group('group_name') do
it { should exist }
its('gid') { should eq 0 }
end
where
* `'group_name'` must specify the name of a group on the system
* `exist` and `'gid'` are valid matchers for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_local
The `be_local` matcher tests if the group is a local group:
it { should be_local }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the named user exists:
it { should exist }
### gid
The `gid` matcher tests the named group identifier:
its('gid') { should eq 1234 }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test the group identifier for the root group
describe group('root') do
it { should exist }
its('gid') { should eq 0 }
end

115
docs/resources/grub_conf.md.erb Normal file
View file

@ -0,0 +1,115 @@
---
title: About the grub_conf Resource
---
# grub_conf
Grub is a boot loader on the Linux platform used to load and then transfer control to an operating system kernel, after which that kernel initializes the rest of the operating system. Use the `grub_conf` InSpec audit resource to test boot loader configuration settings that are defined in the `grub.conf` configuration file.
## Syntax
A `grub_conf` resource block declares a list of settings in a `grub.conf` file:
describe grub_conf('path', 'kernel') do
its('setting') { should eq 'value' }
end
or:
describe grub_conf('path') do
its('default') { should eq '0' } #
its('setting') { should eq 'value' }
end
where
* `'service_name'` is a service listed in the `grub.conf` file
* `'path'` is the path to the `grub.conf` file
* `'kernel'` specifies the default kernel (by using `'default'`) or a specific kernel; `'default'` defines the position in the list of kernels at which the default kernel is defined, i.e. `should eq '0'` for the first kernel listed or `'path', 'default'` to use the default kernel as specified in the `grub.conf` file
* `'value'` is the value that is expected
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test a grub.conf file
A Grub configuration file located at `/etc/grub.conf` is similar to the following:
# grub.conf generated by anaconda
#
# Note that you do not have to rerun grub after making changes to this file
# NOTICE: You have a /boot partition. This means that
# all kernel and initrd paths are relative to /boot/, eg.
# root (hd0,0)
# kernel /vmlinuz-version ro root=/dev/hda6
# initrd /initrd-version.img
#boot=/dev/hda
default=0
timeout=10
splashimage=(hd0,0)/grub/splash.xpm.gz
title Red Hat Enterprise Linux ES (2.6.32-573.7.1.el6.x86_64)
root (hd0,0)
kernel /vmlinuz-2.6.32-573.7.1.el6.x86_64 ro root=/dev/hda6
initrd /initrd-2.6.32-573.7.1.el6.x86_64.img
title Red Hat Enterprise Linux ES (2.6.32-358.14.1.el6.x86_64)
root (hd0,0)
kernel /vmlinuz-2.6.32-358.14.1.el6.x86_64 ro root=/dev/hda6 ramdisk_size=400000
initrd /initrd-2.6.32-358.14.1.el6.x86_64.img
This file defines two versions of RedHat Enterprise Linux, with version `2.6.32-573.7.1.el6.x86_64` specified as the default.
The following test verifies the kernel, ensures that kernel is the default kernel, its initial RAM disk (`initrd`), and the timeout:
describe grub_conf('/etc/grub.conf', 'default') do
its('kernel') { should include '/vmlinuz-2.6.32-573.7.1.el6.x86_64' }
its('initrd') { should include '/initrd-2.6.32-573.7.1.el6.x86_64.img' }
its('default') { should_not eq '1' }
its('timeout') { should eq '10' }
end
The following test verifies the `ramdisk_size` for the non-deault kernel:
describe grub_conf('/etc/grub.conf', 'Red Hat Enterprise Linux ES (2.6.32-358.14.1.el6.x86_64)') do
its('kernel') { should include 'ramdisk_size=400000' }
end
### Test a configuration file and boot configuration
describe grub_conf('/etc/grub.conf', 'default') do
its('kernel') { should include '/vmlinuz-2.6.32-573.7.1.el6.x86_64' }
its('initrd') { should include '/initramfs-2.6.32-573.el6.x86_64.img=1' }
its('default') { should_not eq '1' }
its('timeout') { should eq '5' }
end
### Test a specific kernel
grub_conf('/etc/grub.conf', 'CentOS (2.6.32-573.12.1.el6.x86_64)') do
its('kernel') { should include 'audit=1' }
end

85
docs/resources/host.md.erb Normal file
View file

@ -0,0 +1,85 @@
---
title: About the host Resource
---
# host
Use the `host` InSpec audit resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.
## Syntax
A `host` resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol:
.. code-block:: ruby
describe host('example.com', port: 80, proto: 'tcp') do
it { should be_reachable }
end
where
* `host()` must specify a host name and may specify a port number and/or a protocol
* `'example.com'` is the host name
* `port:` is the port number
* `proto: 'name'` is the Internet protocol: TCP (`proto: 'tcp'`), UDP (`proto: 'udp'` or ICMP (`proto: 'icmp'`))
* `be_reachable` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_reachable
The `be_reachable` matcher tests if the host name is available:
it { should be_reachable }
### be_resolvable
The `be_resolvable` matcher tests for host name resolution, i.e. "resolvable to an IP address":
it { should be_resolvable }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### ipaddress
The `ipaddress` matcher tests if a host name is resolvable to a specific IP address:
its('ipaddress') { should include '93.184.216.34' }
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Verify host name is reachable over a specific protocol and port number
describe host('example.com', port: 53, proto: 'udp') do
it { should be_reachable }
end
### Verify that a specific IP address can be resolved
describe host('example.com', port: 80, proto: 'tcp') do
it { should be_resolvable }
its('ipaddress') { should include '192.168.1.1' }
end

142
docs/resources/iis_site.md.erb Normal file
View file

@ -0,0 +1,142 @@
---
title: About the iis_site Resource
---
# iis_site
Use the `iis_site` InSpec audit resource to test the state of IIS on Windows Server 2012 (and later).
## Syntax
An `iis_site` resource block declares details about the named site:
describe iis_site('site_name') do
it { should exist }
it { should be_running }
it { should have_app_pool('app_pool_name') }
it { should have_binding('binding_details') }
it { should have_path('path_to_site') }
end
where
* `'site_name'` is the name of the site, such as `'Default Web Site'`
* `('app_pool_name')` is the name of the application pool in which the site's root application is run, such as `'DefaultAppPool'`
* `('binding_details')` is a binding for the site, such as `'net.pipe *'`. A site may have multiple bindings; therefore, use a `have_binding` matcher for each site binding to be tested
* `('path_to_site')` is the path to the site, such as `'C:\\inetpub\\wwwroot'`
For example:
describe iis_site('Default Web Site') do
it { should exist }
it { should be_running }
it { should have_app_pool('DefaultAppPool') }
it { should have_binding('https :443:www.contoso.com sslFlags=0') }
it { should have_binding('net.pipe *') }
it { should have_path('C:\\inetpub\\wwwroot') }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_running
The `be_running` matcher tests if the site is running:
it { should be_running }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the site exists:
it { should exist }
### have\_app\_pool
The `have_app_pool` matcher tests if the named application pool exists for the site:
it { should have_app_pool('DefaultAppPool') }
For example, testing if a site's application pool inherits the settings of the parent application pool:
it { should have_app_pool('/') }
### have_binding
The `have_binding` matcher tests if the specified binding exists for the site:
it { should have_binding('http :80:*') }
or:
it { should have_binding('net.pipe *') }
A site may have multiple bindings; use a `have_binding` matcher for each unique site binding to be tested.
##### Binding Attributes
The `have_binding` matcher can also test attributes that are defined for a site binding. For example, the `sslFlags` attribute defines if SSL is enabled, and (when enabled) what level of SSL is applied to the site.
Testing a site with SSL disabled:
it { should have_binding('https :443:www.contoso.com sslFlags=0') }
Testing a site with SSL enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=Ssl') }
Testing a site with certificate mapping authentication enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=SslMapCert') }
Testing a site with 128-bit SSL enabled:
it { should have_binding('https :443:www.contoso.com sslFlags=Ssl128') }
### have_path
The `have_path` matcher tests if the named path is defined for the site:
it { should have_path('C:\\inetpub\\wwwroot') }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test a default IIS site
describe iis_site('Default Web Site') do
it { should exist }
it { should be_running }
it { should have_app_pool('DefaultAppPool') }
it { should have_binding('http *:80:') }
it { should have_path('%SystemDrive%\\inetpub\\wwwroot\\') }
end
### Test if IIS service is running
describe service('W3SVC') do
it { should be_installed }
it { should be_running }
end

99
docs/resources/inetd_conf.md.erb Normal file
View file

@ -0,0 +1,99 @@
---
title: About the inetd_conf Resource
---
# inetd_conf
Use the `inetd_conf` InSpec audit resource to test if a service is listed in the `inetd.conf` file on Linux and Unix platforms. inetd---the Internet service daemon---listens on dedicated ports, and then loads the appropriate program based on a request. The `inetd.conf` file is typically located at `/etc/inetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.`
## Syntax
An `inetd_conf` resource block declares the list of services that are enabled in the `inetd.conf` file:
describe inetd_conf('path') do
its('service_name') { should eq 'value' }
end
where
* `'service_name'` is a service listed in the `inetd.conf` file
* `('path')` is the non-default path to the `inetd.conf` file
* `should eq 'value'` is the value that is expected
## Matchers
This resource matches any service that is listed in the `inetd.conf` file. You may want to ensure that specific services do not listen via `inetd.conf`:
its('shell') { should eq nil }
or:
its('netstat') { should eq nil }
or:
its('systat') { should eq nil }
For example:
describe inetd_conf do
its('shell') { should eq nil }
its('login') { should eq nil }
its('exec') { should eq nil }
end
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Verify that FTP is disabled
The contents if the `inetd.conf` file contain the following:
#ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l -a
#telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd
and the following test is defined:
describe inetd_conf do
its('ftp') { should eq nil }
its('telnet') { should eq nil }
end
Because both the `ftp` and `telnet` Internet services are commented out (`#`), both services are disabled. Consequently, both tests will return `true`. However, if the `inetd.conf` file is set as follows:
ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l -a
#telnet stream tcp nowait root /usr/sbin/tcpd in.telnetd
then the same test will return `false` for `ftp` and the entire test will fail.
### Test if telnet is installed
describe package('telnetd') do
it { should_not be_installed }
end
describe inetd_conf do
its('telnet') { should eq nil }
end

69
docs/resources/ini.md.erb Normal file
View file

@ -0,0 +1,69 @@
---
title: About the ini Resource
---
# ini
Use the `ini` InSpec audit resource to test settings in an INI file.
## Syntax
An `ini` resource block declares the configuration settings to be tested:
describe ini('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a synchronization setting defined in the INI file
* `('path')` is the path to the INI file
* `{ should eq 'value' }` is the value that is expected
For example:
describe ini('path/to/ini_file.ini') do
its('port') { should eq '143' }
its('server') { should eq '192.0.2.62' }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test SMTP settings in a PHP INI file
For example, a PHP INI file located at contains the following settings:
; SMTP = smtp.gmail.com
; smtp_port = 465
and can be tested like this:
describe ini(/etc/php5/apache2/php.ini) do
its('smtp_port') { should eq('465') }
end

66
docs/resources/interface.md.erb Normal file
View file

@ -0,0 +1,66 @@
---
title: About the interface Resource
---
# interface
Use the `interface` InSpec audit resource to test basic network adapter properties, such as name, status, state, address, and link speed (in MB/sec).
* On Linux platforms, `/sys/class/net/#{iface}` is used as source
* On the Windows platform, the `Get-NetAdapter` cmdlet is used as source
## Syntax
An `interface` resource block declares network interface properties to be tested:
describe interface do
it { should be_up }
its('speed') { should eq 1000 }
its('name') { should eq eth0 }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_up
The `be_up` matcher tests if the network interface is available:
it { should be_up }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### name
The `name` matcher tests if the named network interface exists:
its('name') { should eq eth0 }
### speed
The `speed` matcher tests the speed of the network interface, in MB/sec:
its('speed') { should eq 1000 }
## Examples
None.

70
docs/resources/iptables.md.erb Normal file
View file

@ -0,0 +1,70 @@
---
title: About the iptables Resource
---
# iptables
Use the `iptables` InSpec audit resource to test rules that are defined in `iptables`, which maintains tables of IP packet filtering rules. There may be more than one table. Each table contains one (or more) chains (both built-in and custom). A chain is a list of rules that match packets. When the rule matches, the rule defines what target to assign to the packet.
## Syntax
A `iptables` resource block declares tests for rules in IP tables:
describe iptables(rule:'name', table:'name', chain: 'name') do
it { should have_rule('RULE') }
end
where
* `iptables()` may specify any combination of `rule`, `table`, or `chain`
* `rule:'name'` is the name of a rule that matches a set of packets
* `table:'name'` is the packet matching table against which the test is run
* `chain: 'name'` is the name of a user-defined chain or one of `ACCEPT`, `DROP`, `QUEUE`, or `RETURN`
* `have_rule('RULE')` tests that rule in the iptables file
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### have_rule
The `have_rule` matcher tests the named rule against the information in the `iptables` file:
it { should have_rule('RULE') }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test if the IP table allows a packet through
describe iptables do
it { should have_rule('-P INPUT ACCEPT') }
end
### Test if the IP table allows a packet through, for a specific table and chain
describe iptables(table:'mangle', chain: 'input') do
it { should have_rule('-P INPUT ACCEPT') }
end

76
docs/resources/json.md.erb Normal file
View file

@ -0,0 +1,76 @@
---
title: About the json Resource
---
# json
Use the `json` InSpec audit resource to test data in a JSON file.
## Syntax
A `json` resource block declares the data to be tested. Assume the following JSON file:
{
"name" : "hello",
"meta" : {
"creator" : "John Doe"
},
"array": [
"zero",
"one"
]
}
This file can be queried using:
describe json('/paht/to/name.json') do
its('name') { should eq 'hello' }
its(['meta','creator']) { should eq 'John Doe' }
its(['array', 1]) { should eq 'one' }
end
where
* `name` is a configuration setting in a JSON file
* `should eq 'foo'` tests a value of `name` as read from a JSON file versus the value declared in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### name
The `name` matcher tests the value of `name` as read from a JSON file versus the value declared in the test:
its('name') { should eq 'foo' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test a cookbook version in a policyfile.lock.json file
describe json('policyfile.lock.json') do
its(['cookbook_locks', 'omnibus', 'version']) { should eq('2.2.0') }
end

60
docs/resources/kernel_module.md.erb Normal file
View file

@ -0,0 +1,60 @@
---
title: About the kernel_module Resource
---
# kernel_module
Use the `kernel_module` InSpec audit resource to test kernel modules on Linux platforms. These parameters are located under `/lib/modules`. Any submodule may be tested using this resource.
## Syntax
A `kernel_module` resource block declares a module name, and then tests if that module is a loadable kernel module:
describe kernel_module('module_name') do
it { should be_loaded }
end
where
* `'module_name'` must specify a kernel module, such as `'bridge'`
* `{ should be_loaded }` tests if the module is a loadable kernel module
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_loaded
The `be_loaded` matcher tests if the module is a loadable kernel module:
it { should be_loaded }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test if a module is loaded
describe kernel_module('bridge') do
it { should be_loaded }
end

72
docs/resources/kernel_parameter.md.erb Normal file
View file

@ -0,0 +1,72 @@
---
title: About the kernel_parameter Resource
---
# kernel_parameter
Use the `kernel_parameter` InSpec audit resource to test kernel parameters on Linux platforms.
## Syntax
A `kernel_parameter` resource block declares a parameter and then a value to be tested:
describe kernel_parameter('path.to.parameter') do
its('value') { should eq 0 }
end
where
* `'kernel.parameter'` must specify a kernel parameter, such as `'net.ipv4.conf.all.forwarding'`
* `{ should eq 0 }` states the value to be tested
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### value
The `value` matcher tests the value assigned to the named IP address versus the value declared in the test:
its('value') { should eq 0 }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if global forwarding is enabled for an IPv4 address
describe kernel_parameter('net.ipv4.conf.all.forwarding') do
its('value') { should eq 1 }
end
### Test if global forwarding is disabled for an IPv6 address
describe kernel_parameter('net.ipv6.conf.all.forwarding') do
its('value') { should eq 0 }
end
### Test if an IPv6 address accepts redirects
describe kernel_parameter('net.ipv6.conf.interface.accept_redirects') do
its('value') { should eq 'true' }
end

76
docs/resources/launchd_service.md.erb Normal file
View file

@ -0,0 +1,76 @@
---
title: About the launchd_service Resource
---
# launchd_service
Use the ``launchd_service`` InSpec audit resource to test a service using Launchd.
## Syntax
A ``launchd_service`` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe launchd_service('service_name') do
it { should be_installed }
it { should be_enabled }
it { should be_running }
end
where
* ``('service_name')`` must specify a service name
* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
The path to the service manager's control may be specified for situations where the path isn't available in the current ``PATH``. For example:
describe launchd_service('service_name', '/path/to/control') do
it { should be_enabled }
it { should be_installed }
it { should be_running }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_enabled
The `be_enabled` matcher tests if the named service is enabled:
it { should be_enabled }
### be_installed
The `be_installed` matcher tests if the named service is installed:
it { should be_installed }
### be_running
The `be_running` matcher tests if the named service is running:
it { should be_running }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
None.

80
docs/resources/limits_conf.md.erb Normal file
View file

@ -0,0 +1,80 @@
---
title: About the limits_conf Resource
---
# limits_conf
Use the `limits_conf` InSpec audit resource to test configuration settings in the `/etc/security/limits.conf` file. The `limits.conf` defines limits for processes (by user and/or group names) and helps ensure that the system on which those processes are running remains stable. Each process may be assigned a hard or soft limit.
* Soft limits are maintained by the shell and defines the number of file handles (or open files) available to the user or group after login
* Hard limits are maintained by the kernel and defines the maximum number of allowed file handles
Entries in the `limits.conf` file are similar to:
grantmc soft nofile 4096
grantmc hard nofile 63536
^^^^^^^^^ ^^^^ ^^^^^^ ^^^^^
domain type item value
## Syntax
A `limits_conf` resource block declares a domain to be tested, along with associated type, item, and value:
describe limits_conf('path') do
its('domain') { should include ['type', 'item', 'value'] }
its('domain') { should eq ['type', 'item', 'value'] }
end
where
* `('path')` is the non-default path to the `inetd.conf` file
* `'domain'` is a user or group name, such as `grantmc`
* `'type'` is either `hard` or `soft`
* `'item'` is the item for which limits are defined, such as `core`, `nofile`, `stack`, `nproc`, `priority`, or `maxlogins`
* `'value'` is the value associated with the `item`
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### domain
The `domain` matcher tests the domain in the `limits.conf` file, along with associated type, item, and value:
its('domain') { should include ['type', 'item', 'value'] }
`
For example:
its('grantmc') { should include ['hard', 'nofile', '63536'] }
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test limits
describe limits_conf('path') do
its('*') { should include ['soft', 'core', '0'], ['hard', 'rss', '10000'] }
its('ftp') { should eq ['hard', 'nproc', '0'] }
end

77
docs/resources/login_def.md.erb Normal file
View file

@ -0,0 +1,77 @@
---
title: About the login_defs Resource
---
# login_defs
Use the `login_defs` InSpec audit resource to test configuration settings in the `/etc/login.defs` file. The `logins.defs` file defines site-specific configuration for the shadow password suite on Linux and Unix platforms, such as password expiration ranges, minimum/maximum values for automatic selection of user and group identifiers, or the method with which passwords are encrypted.
## Syntax
A `login_defs` resource block declares the `login.defs` configuration data to be tested:
describe login_defs do
its('name') { should include('foo') }
end
where
* `name` is a configuration setting in `login.defs`
* `{ should include('foo') }` tests the value of `name` as read from `login.defs` versus the value declared in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### name
The `name` matcher tests the value of `name` as read from `login.defs` versus the value declared in the test:
its('name') { should eq 'foo' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test password expiration settings
describe login_defs do
its('PASS_MAX_DAYS') { should eq '180' }
its('PASS_MIN_DAYS') { should eq '1' }
its('PASS_MIN_LEN') { should eq '15' }
its('PASS_WARN_AGE') { should eq '30' }
end
### Test the encryption method
describe login_defs do
its('ENCRYPT_METHOD') { should eq 'SHA512' }
end
### Test umask setting
describe login_def do
its('UMASK') { should eq '077' }
its('PASS_MAX_DAYS') { should eq '90' }
end

83
docs/resources/mount.md.erb Normal file
View file

@ -0,0 +1,83 @@
---
title: About the mount Resource
---
# mount
Use the `mount` InSpec audit resource to test the mount points on Linux systems.
## Syntax
An `mount` resource block declares the synchronization settings that should be tested:
describe mount('path') do
it { should MATCHER 'value' }
end
where
* `('path')` is the path to the mounted directory
* `MATCHER` is a valid matcher for this resource
* `'value'` is the value to be tested
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_mounted
The `be_mounted` matcher tests if the file is accessible from the file system:
it { should be_mounted }
### cmp
<%= partial "/shared/matcher_cmp" %>
### device
The `device` matcher tests the device from the `fstab` table:
its('device') { should eq '/dev/mapper/VolGroup-lv_root' }
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### options
The `options` matcher tests the mount options for the file system from the `fstab` table:
its('options') { should eq ['rw', 'mode=620'] }
### type
The `type` matcher tests the file system type:
its('type') { should eq 'ext4' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test a the mount point on '/'
describe mount('/') do
it { should be_mounted }
its('device') { should eq '/dev/mapper/VolGroup-lv_root' }
its('type') { should eq 'ext4' }
its('options') { should eq ['rw', 'mode=620'] }
end

102
docs/resources/mysql_conf.md.erb Normal file
View file

@ -0,0 +1,102 @@
---
title: About the mysql_conf Resource
---
# mysql_conf
Use the `mysql_conf` InSpec audit resource to test the contents of the configuration file for MySQL, typically located at `/etc/mysql/my.cnf` or `/etc/my.cnf`.
## Syntax
A `mysql_conf` resource block declares one (or more) settings in the `my.cnf` file, and then compares the setting in the configuration file to the value stated in the test:
describe mysql_conf('path') do
its('setting') { should eq 'value' }
end
where
* `'setting'` specifies a setting in the `my.cnf` file, such as `max_connections`
* `('path')` is the non-default path to the `my.cnf` file
* `should eq 'value'` is the value that is expected
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### setting
The `setting` matcher tests specific, named settings in the `my.cnf` file:
its('setting') { should eq 'value' }
Use a `setting` matcher for each setting to be tested.
## Examples
The following examples show how to use this InSpec audit resource.
### Test the maximum number of allowed connections
describe mysql_conf do
its('max_connections') { should eq '505' }
its('max_user_connections') { should eq '500' }
end
### Test slow query logging**
describe mysql_conf do
its('slow_query_log_file') { should eq 'hostname_slow.log' }
its('slow_query_log') { should eq '0' }
its('log_queries_not_using_indexes') { should eq '1' }
its('long_query_time') { should eq '0.5' }
its('min_examined_row_limit') { should eq '100' }
end
### Test the port and socket on which MySQL listens
describe mysql_conf do
its('port') { should eq '3306' }
its('socket') { should eq '/var/run/mysqld/mysql.sock' }
end
### Test connection and thread variables
describe mysql_conf do
its('port') { should eq '3306' }
its('socket') { should eq '/var/run/mysqld/mysql.sock' }
its('max_allowed_packet') { should eq '12M' }
its('default_storage_engine') { should eq 'InnoDB' }
its('character_set_server') { should eq 'utf8' }
its('collation_server') { should eq 'utf8_general_ci' }
its('max_connections') { should eq '505' }
its('max_user_connections') { should eq '500' }
its('thread_cache_size') { should eq '505' }
end
### Test the safe-user-create parameter
describe mysql_conf.params('mysqld') do
its('safe-user-create') { should eq('1') }
end

63
docs/resources/mysql_session.md.erb Normal file
View file

@ -0,0 +1,63 @@
---
title: About the mysql_session Resource
---
# mysql_session
Use the `mysql_session` InSpec audit resource to test SQL commands run against a MySQL database.
## Syntax
A `mysql_session` resource block declares the username and password to use for the session, and then the command to be run:
describe mysql_session('username', 'password').query('QUERY') do
its('output') { should eq('') }
end
where
* `mysql_session` declares a username and password with permission to run the query
* `query('QUERY')` contains the query to be run
* `its('output') { should eq('') }` compares the results of the query against the expected result in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### output
The `output` matcher tests the results of the query:
its('output') { should eq(/^0/) }
## Examples
The following examples show how to use this InSpec audit resource.
### Test for matching databases
sql = mysql_session('my_user','password')
describe sql.query('show databases like \'test\';') do
its('stdout') { should_not match(/test/) }
end

75
docs/resources/npm.md.erb Normal file
View file

@ -0,0 +1,75 @@
---
title: About the npm Resource
---
# npm
Use the `npm` InSpec audit resource to test if a global NPM package is installed. NPM is the the package manager for Node.js packages (https://docs.npmjs.com), such as Bower and StatsD.
## Syntax
A `npm` resource block declares a package and (optionally) a package version:
describe gem('npm_package_name') do
it { should be_installed }
end
where
* `('npm_package_name')` must specify an NPM package, such as `'bower'` or `'statsd'`
* `be_installed` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_installed
The `be_installed` matcher tests if the named Gem package and package version (if specified) is installed:
it { should be_installed }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### version
The `version` matcher tests if the named package version is on the system:
its('version') { should eq '1.2.3' }
## Examples
The following examples show how to use this InSpec audit resource.
### Verify that bower is installed, with a specific version
describe npm('bower') do
it { should be_installed }
its('version') { should eq '1.4.1' }
end
### Verify that statsd is not installed
describe npm('statsd') do
it { should_not be_installed }
end

76
docs/resources/ntp_conf.md.erb Normal file
View file

@ -0,0 +1,76 @@
---
title: About the ntp_conf Resource
---
# ntp_conf
Use the `ntp_conf` InSpec audit resource to test the synchronization settings defined in the `ntp.conf` file. This file is typically located at `/etc/ntp.conf`.
## Syntax
An `ntp_conf` resource block declares the synchronization settings that should be tested:
describe ntp_conf('path') do
its('setting_name') { should eq 'value' }
end
where
* `'setting_name'` is a synchronization setting defined in the `ntp.conf` file
* `('path')` is the non-default path to the `ntp.conf` file
* `{ should eq 'value' }` is the value that is expected
## Matchers
This resource matches any service that is listed in the `ntp.conf` file:
its('server') { should_not eq nil }
or:
its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
For example:
describe ntp_conf do
its('server') { should_not eq nil }
its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
end
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
The following examples show how to use this InSpec audit resource.
### Test for clock drift against named servers
describe ntp_conf do
its('driftfile') { should eq '/var/lib/ntp/ntp.drift' }
its('server') { should eq [
0.ubuntu.pool.ntp.org,
1.ubuntu.pool.ntp.org,
2.ubuntu.pool.ntp.org
] }
end

67
docs/resources/oneget.md.erb Normal file
View file

@ -0,0 +1,67 @@
---
title: About the oneget Resource
---
# oneget
Use the `oneget` InSpec audit resource to test if the named package and/or package version is installed on the system. This resource uses Oneget, which is `part of the Windows Management Framework 5.0 and Windows 10 <https://github.com/OneGet/oneget>`__. This resource uses the `Get-Package` cmdlet to return all of the package names in the Oneget repository.
## Syntax
A `oneget` resource block declares a package and (optionally) a package version:
describe oneget('name') do
it { should be_installed }
end
where
* `('name')` must specify the name of a package, such as `'VLC'`
* `be_installed` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_installed
The `be_installed` matcher tests if the named package is installed on the system:
it { should be_installed }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### version
The `version` matcher tests if the named package version is on the system:
its('version') { should eq '1.2.3' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if VLC is installed
describe oneget('VLC') do
it { should be_installed }
end

154
docs/resources/os.md.erb Normal file
View file

@ -0,0 +1,154 @@
---
title: About the os Resource
---
# os
Use the `os` InSpec audit resource to test the platform on which the system is running.
## Syntax
An `os` resource block declares the platform to be tested. The platform may specified via matcher or control block name. For example, using a matcher:
describe os[:family] do
it { should eq 'platform_name' }
end
or using the block name:
describe os[:family_name] do
...
end
* `'platform_name'` (a string) or `:family_name` (a symbol) is one of `aix`, `bsd`, `darwin`, `debian`, `hpux`, `linux`, `redhat`, `solaris`, `suse`, `unix`, or `windows`
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## os.family? Helpers
The `os` audit resource includes a collection of helpers that enable more granular testing of platforms, platform names, architectures, and releases. Use any of the following platform-specific helpers to test for specific platforms:
* `aix?`
* `bsd?` (including Darwin, FreeBSD, NetBSD, and OpenBSD)
* `darwin?`
* `debian?`
* `hpux?`
* `linux?` (including Alpine Linux, Amazon Linux, ArchLinux, CoreOS, Exherbo, Fedora, Gentoo, and Slackware)
* `redhat?`
* `solaris?` (including Nexenta Core, OmniOS, Open Indiana, Solaris Open, and SmartOS)
* `suse?`
* `unix?`
* `windows?`
For example, to test for Darwin use:
describe os.bsd? do
it { should eq true }
end
To test for Windows use:
describe os.windows? do
it { should eq true }
end
and to test for Redhat use:
describe os.redhat? do
it { should eq true }
end
Use the following helpers to test for operating system names, releases, and architectures:
describe os.name do
it { should eq 'foo' }
end
describe os.release do
it { should eq 'foo' }
end
describe os.arch do
it { should eq 'foo' }
end
## os[:family] Symbols
Use `os[:family]` to enable more granular testing of platforms, platform names, architectures, and releases. Use any of the following platform-specific symbols to test for specific platforms:
* `:aix`
* `:bsd` For platforms that are part of the Berkeley OS family: `:darwin`, `:freebsd`, `:netbsd`, and `:openbsd`.
* `:debian`
* `:hpux`
* `:linux`. For platforms that are part of the Linux family: `:alpine`, `:amazon`, `:arch`, `:coreos`, `:exherbo`, `:fedora`, `:gentoo`, and `:slackware`.
* `:redhat`
* `:solaris`. For platforms that are part of the Solaris family: `:nexentacore`, `:omnios`, `:openindiana`, `:opensolaris`, and `:smartos`.
* `:suse`
* `:unix`
* `:windows`
For example, both of the following tests should have the same result:
if os[:family] == 'debian'
describe port(69) do
its('processes') { should include 'in.tftpd' }
end
elsif os[:family] == 'rhel'
describe port(69) do
its('processes') { should include 'xinetd' }
end
end
if os[:debian]
describe port(69) do
its('processes') { should include 'in.tftpd' }
end
elsif os[:rhel]
describe port(69) do
its('processes') { should include 'xinetd' }
end
end
## Examples
The following examples show how to use this InSpec audit resource.
### Test for RedHat
describe os[:family] do
it { should eq 'redhat' }
end
### Test for Ubuntu
describe os[:family] do
it { should eq 'debian' }
end
### Test for Microsoft Windows
describe os[:family] do
it { should eq 'windows' }
end

98
docs/resources/os_env.md.erb Normal file
View file

@ -0,0 +1,98 @@
---
title: About the os_env Resource
---
# os_env
Use the `os_env` InSpec audit resource to test the environment variables for the platform on which the system is running.
## Syntax
A `os_env` resource block declares an environment variable, and then declares its value:
describe os_env('VARIABLE') do
its('matcher') { should eq 1 }
end
where
* `('VARIABLE')` must specify an environment variable, such as `PATH`
* `matcher` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### content
The `content` matcher return the value of the environment variable:
its('content') { should eq '/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin' }
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### split
The `split` splits the content with the `:` deliminator:
its('split') { should include (':') }
or:
its('split') { should_not include ('.') }
Use `-1` to test for cases where there is a trailing colon (`:`), such as `dir1::dir2:`:
its('split') { should include ('-1') }
## Examples
The following examples show how to use this InSpec audit resource.
### Test the PATH environment variable
describe os_env('PATH') do
its('split') { should_not include('') }
its('split') { should_not include('.') }
end
### Test Habitat environment variables
Habitat uses the `os_env` resource to test environment variables. The environment variables are first defined in a whitespace array, after which each environment variable is tested:
hab_env_vars = %w(HAB_AUTH_TOKEN
HAB_CACHE_KEY_PATH
HAB_DEPOT_URL
HAB_ORG
HAB_ORIGIN
HAB_ORIGIN_KEYS
HAB_RING
HAB_RING_KEY
HAB_STUDIOS_HOME
HAB_STUDIO_ROOT
HAB_USER)
hab_env_vars.each do |e|
describe os_env(e) do
its('content') { should eq nil }
end
end

115
docs/resources/package.md.erb Normal file
View file

@ -0,0 +1,115 @@
---
title: About the package Resource
---
# package
Use the `package` InSpec audit resource to test if the named package and/or package version is installed on the system.
## Syntax
A `package` resource block declares a package and (optionally) a package version:
describe package('name') do
it { should be_installed }
end
where
* `('name')` must specify the name of a package, such as `'nginx'`
* `be_installed` is a valid matcher for this resource
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_installed
The `be_installed` matcher tests if the named package is installed on the system:
it { should be_installed }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### version
The `version` matcher tests if the named package version is on the system:
its('version') { should eq '1.2.3' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if nginx version 1.9.5 is installed
describe package('nginx') do
it { should be_installed }
its('version') { should eq 1.9.5 }
end
### Test that a package is not installed
describe package('some_package') do
it { should_not be_installed }
end
### Test if telnet is installed
describe package('telnetd') do
it { should_not be_installed }
end
describe inetd_conf do
its('telnet') { should eq nil }
end
### Test if ClamAV (an antivirus engine) is installed and running
describe package('clamav') do
it { should be_installed }
its('version') { should eq '0.98.7' }
end
describe service('clamd') do
it { should_not be_enabled }
it { should_not be_installed }
it { should_not be_running }
end
### Verify if Memcached is installed, enabled, and running
Memcached is an in-memory key-value store that helps improve the performance of database-driven websites and can be installed, maintained, and tested using the `memcached` cookbook (maintained by Chef). The following example is from the `memcached` cookbook and shows how to use a combination of the `package`, `service`, and `port` InSpec audit resources to test if Memcached is installed, enabled, and running:
describe package('memcached') do
it { should be_installed }
end
describe service('memcached') do
it { should be_installed }
it { should be_enabled }
it { should be_running }
end
describe port(11_211) do
it { should be_listening }
end

122
docs/resources/parse_config.md.erb Normal file
View file

@ -0,0 +1,122 @@
---
title: About the parse_config Resource
---
# parse_config
Use the `parse_config` InSpec audit resource to test arbitrary configuration files.
## Syntax
A `parse_config` resource block declares the location of the configuration setting to be tested, and then what value is to be tested. Because this resource relies on arbitrary configuration files, the test itself is often arbitrary and relies on custom Ruby code:
output = command('some-command').stdout
describe parse_config(output, { data_config_option: value } ) do
its('setting') { should eq 1 }
end
or:
audit = command('/sbin/auditctl -l').stdout
options = {
assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
multiple_values: true
}
describe parse_config(audit, options) do
its('setting') { should eq 1 }
end
where each test
* Must declare the location of the configuration file to be tested
* Must declare one (or more) settings to be tested
* May run a command to `stdout`, and then run the test against that output
* May use options to define how configuration data is to be parsed
## Matchers
This InSpec audit resource has the following matchers:
### assignment_re
Use `assignment_re` to test a key value using a regular expression:
'key = value'
may be tested using the following regular expression, which determines assignment from key to value:
assignment_re: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### comment_char
Use `comment_char` to test for comments in a configuration file:
comment_char: '#'
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### key_vals
Use `key_vals` to test how many values a key contains:
key = a b c
contains three values. To test that value to ensure it only contains one, use:
key_vals: 1
### match
<%= partial "/shared/matcher_match" %>
### multiple_values
Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
# # file structure:
# key = a
# key = b
# key2 = c
params['key'] = ['a', 'b']
params['key2'] = ['c']
To use plain key value mapping, use `multiple_values: false`:
# # file structure:
# key = a
# key = b
# key2 = c
params['key'] = 'b'
params['key2'] = 'c'
### standalone_comments
Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
'key = value # comment'
params['key'] = 'value # comment'
Use `standalone_comments: false`, to parse the following:
'key = value # comment'
params['key'] = 'value'
## Examples
None.

149
docs/resources/parse_config_file.md.erb Normal file
View file

@ -0,0 +1,149 @@
---
title: About the parse_config_file Resource
---
# parse\_config\_file
Use the `parse_config_file` InSpec audit resource to test arbitrary configuration files. It works in the same way as `parse_config`. Instead of using a command output, this resource works with files.
## Syntax
A `parse_config_file` InSpec audit resource block declares the location of the configuration file to be tested, and then which settings in that file are to be tested.
describe parse_config_file('/path/to/file', { data_config_option: value } ) do
its('setting') { should eq 1 }
end
or:
options = {
assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
multiple_values: true
}
describe parse_config_file('path/to/file', options) do
its('setting') { should eq 1 }
end
where each test
* Must declare the location of the configuration file to be tested
* Must declare one (or more) settings to be tested
* May run a command to `stdout`, and then run the test against that output
* May use options to define how configuration data is to be parsed
## Options
This resource supports the following options for parsing configuration data. Use them in an `options` block stated outside of (and immediately before) the actual test:
options = {
assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
multiple_values: true
}
describe parse_config_file('path/to/file', options) do
its('setting') { should eq 1 }
end
## Matchers
This InSpec audit resource has the following matchers:
### assignment_re
Use `assignment_re` to test a key value using a regular expression:
'key = value'
may be tested using the following regular expression, which determines assignment from key to value:
assignment_re: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### comment_char
Use `comment_char` to test for comments in a configuration file:
comment_char: '#'
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### key_vals
Use `key_vals` to test how many values a key contains:
key = a b c
contains three values. To test that value to ensure it only contains one, use:
key_vals: 1
### match
<%= partial "/shared/matcher_match" %>
### multiple_values
Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
# # file structure:
# key = a
# key = b
# key2 = c
params['key'] = ['a', 'b']
params['key2'] = ['c']
To use plain key value mapping, use `multiple_values: false`:
# # file structure:
# key = a
# key = b
# key2 = c
params['key'] = 'b'
params['key2'] = 'c'
### standalone_comments
Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
'key = value # comment'
params['key'] = 'value # comment'
Use `standalone_comments: false`, to parse the following:
'key = value # comment'
params['key'] = 'value'
## Examples
The following examples show how to use this InSpec audit resource.
### Test a configuration setting
describe parse_config_file('/path/to/file.conf') do
its('PARAM_X') { should eq 'Y' }
end
### Use options, and then test a configuration setting
describe parse_config_file('/path/to/file.conf', { multiple_values: true }) do
its('PARAM_X') { should include 'Y' }
end
## Test a file with an ini-like structure (such as a yum.conf)
describe parse_config_file('/path/to/yum.conf') do
its('main') { should include('gpgcheck' => '1') }
end

74
docs/resources/pip.md.erb Normal file
View file

@ -0,0 +1,74 @@
---
title: About the pip Resource
---
# pip
Use the `pip` InSpec audit resource to test packages that are installed using the Python PIP installer.
## Syntax
A `pip` resource block declares a package and (optionally) a package version:
describe pip('Jinja2') do
it { should be_installed }
end
where
* `'Jinja2'` is the name of the package
* `be_installed` tests to see if the `Jinja2` package is installed
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_installed
The `be_installed` matcher tests if the named package is installed on the system:
it { should be_installed }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### version
The `version` matcher tests if the named package version is on the system:
its('version') { should eq '1.2.3' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if Jinja2 is installed on the system
describe pip('Jinja2') do
it { should be_installed }
end
### Test if Jinja2 2.8 is installed on the system
describe pip('Jinja2') do
it { should be_installed }
its('version') { should eq '2.8' }
end

150
docs/resources/port.md.erb Normal file
View file

@ -0,0 +1,150 @@
---
title: About the port Resource
---
# port
Use the `port` InSpec audit resource to test basic port properties, such as port, process, if it's listening.
## Syntax
A `port` resource block declares a port, and then depending on what needs to be tested, a process, protocol, process identifier, and its state (is it listening?):
describe port(514) do
it { should be_listening }
its('processes') {should include 'syslog'}
end
where the `processes` returns the processes listening on port 514.
A filter may specify an attribute:
describe port.where { protocol =~ /tcp/ && port > 22 && port < 80 } do
it { should_not be_listening }
end
where
* `.where{}` specifies a block in which one (or more) attributes---`port`, `address`, `protocol`, `process`, `pid`, or `listening?`----scope the test to ports that match those attributes
For example, to test if the SSH daemon is available on a Linux machine via the default port (22):
describe port(22) do
its('processes') { should include 'sshd' }
its('protocols') { should include 'tcp' }
its('addresses') { should include '0.0.0.0' }
end
## Matchers
This InSpec audit resource has the following matchers:
### address
The `addresses` matcher tests if the specified address is associated with a port:
its('addresses') { should include '0.0.0.0' }
### be
<%= partial "/shared/matcher_be" %>
### be_listening
The `be_listening` matcher tests if the port is listening for traffic:
it { should be_listening }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### pids
The `pids` matcher tests the process identifiers (PIDs):
its('pids') { should eq ['27808'] }
### processes
The `processes` matcher tests if the named process is running on the system:
its('processes') { should eq ['syslog'] }
### protocols
The `protocols` matcher tests the Internet protocol: ICMP (`'icmp'`), TCP (`'tcp'` or `'tcp6'`), or UDP (`'udp'` or `'udp6'`):
its('protocols') { should include 'tcp' }
or for the IPv6 protocol:
its('protocols') { should include 'tcp6' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test port 80, listening with the TCP protocol
describe port(80) do
it { should be_listening }
its('protocols') {should eq ['tcp']}
end
### Test port 80, on a specific address
A specific port address may be checked using either of the following examples:
describe port(80) do
it { should be_listening }
its('addresses') {should include '0.0.0.0'}
end
or:
describe port('0.0.0.0', 80) do
it { should be_listening }
end
### Test port 80, listening with TCP version IPv6 protocol
describe port(80) do
it { should be_listening }
its('protocols') {should eq ['tcp6']}
end
### Test that only secure ports accept requests
describe port(80) do
it { should_not be_listening }
end
describe port(443) do
it { should be_listening }
its('protocols') {should eq ['tcp']}
end
### Verify port 65432 is not listening
describe port(22) do
it { should be_listening }
its('protocols') { should include('tcp') }
its('protocols') { should_not include('udp') }
end
describe port(65432) do
it { should_not be_listening }
end

90
docs/resources/postgres_conf.md.erb Normal file
View file

@ -0,0 +1,90 @@
---
title: About the postgres_conf Resource
---
# postgres_conf
Use the `postgres_conf` InSpec audit resource to test the contents of the configuration file for PostgreSQL, typically located at `/etc/postgresql/<version>/main/postgresql.conf` or `/var/lib/postgres/data/postgresql.conf`, depending on the platform.
## Syntax
A `postgres_conf` resource block declares one (or more) settings in the `postgresql.conf` file, and then compares the setting in the configuration file to the value stated in the test:
describe postgres_conf('path') do
its('setting') { should eq 'value' }
end
where
* `'setting'` specifies a setting in the `postgresql.conf` file
* `('path')` is the non-default path to the `postgresql.conf` file (optional)
* `should eq 'value'` is the value that is expected
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### setting
The `setting` matcher tests specific, named settings in the `postgresql.conf` file:
its('setting') { should eq 'value' }
Use a `setting` matcher for each setting to be tested.
## Examples
The following examples show how to use this InSpec audit resource.
### Test the maximum number of allowed client connections
describe postgres_conf do
its('max_connections') { should eq '5' }
end
### Test system logging
describe postgres_conf do
its('logging_collector') { should eq 'on' }
its('log_connections') { should eq 'on' }
its('log_disconnections') { should eq 'on' }
its('log_duration') { should eq 'on' }
its('log_hostname') { should eq 'on' }
its('log_line_prefix') { should eq '%t %u %d %h' }
end
### Test the port on which PostgreSQL listens
describe postgres_conf do
its('port') { should eq '5432' }
end
### Test the Unix socket settings
describe postgres_conf do
its('unix_socket_directories') { should eq '.s.PGSQL.5432' }
its('unix_socket_group') { should eq nil }
its('unix_socket_permissions') { should eq '0770' }
end
where `unix_socket_group` is set to the PostgreSQL default setting (the group to which the server user belongs).

75
docs/resources/postgres_session.md.erb Normal file
View file

@ -0,0 +1,75 @@
---
title: About the postgres_session Resource
---
# postgres_session
Use the `postgres_session` InSpec audit resource to test SQL commands run against a PostgreSQL database.
## Syntax
A `postgres_session` resource block declares the username and password to use for the session, and then the command to be run:
sql = postgres_session('username', 'password')
describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
its('output') { should eq('') }
end
where
* `sql = postgres_session` declares a username and password with permission to run the query
* `sql.query('')` contains the query to be run
* `its('output') { should eq('') }` compares the results of the query against the expected result in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### output
The `output` matcher tests the results of the query:
its('output') { should eq(/^0/) }
## Examples
The following examples show how to use this InSpec audit resource.
### Test the PostgreSQL shadow password
sql = postgres_session('my_user', 'password')
describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
its('output') { should eq('') }
end
### Test for risky database entries
describe postgres_session('my_user', 'password').query('SELECT count (*)
FROM pg_language
WHERE lanpltrusted = \'f\'
AND lanname!=\'internal\'
AND lanname!=\'c\';') do
its('output') { should eq '0' }
end

116
docs/resources/powershell.md.erb Normal file
View file

@ -0,0 +1,116 @@
---
title: About the powershell Resource
---
# powershell
Use the `powershell` InSpec audit resource to test a Powershell script on the Windows platform.
## Syntax
A `powershell` resource block declares a Powershell script to be tested, and then compares the output of that command to the matcher in the test:
script = <<-EOH
# a PowerShell script
EOH
describe script(script) do
its('matcher') { should eq 'output' }
end
where
* `'script'` must specify a Powershell script to be run
* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
* `'output'` tests the output of the command run on the system versus the output value stated in the test
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exit_status
The `exit_status` matcher tests the exit status for the command:
its('exit_status') { should eq 123 }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### stderr
The `stderr` matcher tests results of the command as returned in standard error (stderr):
its('stderr') { should eq 'error' }
### stdout
The `stdout` matcher tests results of the command as returned in standard output (stdout):
its('stdout') { should eq '/^1$/' }
## Examples
The following examples show how to use this InSpec audit resource.
### Get all groups of Administrator user
script = <<-EOH
# find user
$user = Get-WmiObject Win32_UserAccount -filter "Name = 'Administrator'"
# get related groups
$groups = $user.GetRelated('Win32_Group') | Select-Object -Property Caption, Domain, Name, LocalAccount, SID, SIDType, Status
$groups | ConvertTo-Json
EOH
describe powershell(script) do
its('stdout') { should_not eq '' }
end
### Write-Output 'hello'
The following Powershell script:
script = <<-EOH
Write-Output 'hello'
EOH
can be tested in the following ways.
For a newline:
describe powershell(script) do
its('stdout') { should eq "hello\r\n" }
its('stderr') { should eq '' }
end
Removing whitespace `\r\n` from `stdout`:
describe powershell(script) do
its('strip') { should eq "hello" }
end
No newline:
describe powershell("'hello' | Write-Host -NoNewLine") do
its('stdout') { should eq 'hello' }
its('stderr') { should eq '' }
end

73
docs/resources/process.md.erb Normal file
View file

@ -0,0 +1,73 @@
---
title: About the processes Resource
---
# processes
Use the `processes` InSpec audit resource to test properties for programs that are running on the system.
## Syntax
A `processes` resource block declares the name of the process to be tested, and then declares one (or more) property/value pairs:
describe processes('process_name') do
its('property_name') { should eq ['property_value'] }
end
where
* `processes('process_name')` must specify the name of a process that is running on the system
* `property_name` may be used to test user (`its('users')`) and state properties (`its('states')`)
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### property_name
The `property_name` matcher tests the named property for the specified value:
its('property_name') { should eq ['property_value'] }
## Examples
The following examples show how to use this InSpec audit resource.
### Test if the list length for the mysqld process is 1
describe processes('mysqld') do
its('list.length') { should eq 1 }
end
### Test if the init process is owned by the root user
describe processes('init') do
its('users') { should eq ['root'] }
end
### Test if a high-priority process is running
describe processes('some_process') do
its('states') { should eq ['R<'] }
end

148
docs/resources/registry_key.md.erb Normal file
View file

@ -0,0 +1,148 @@
---
title: About the registry_key Resource
---
# registry_key
Use the `registry_key` InSpec audit resource to test key values in the Windows registry.
## Syntax
A `registry_key` resource block declares the item in the Windows registry, the path to a setting under that item, and then one (or more) name/value pairs to be tested.
Use a registry key name and path:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
its('Start') { should eq 2 }
end
Use only a registry key path:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
its('Start') { should eq 2 }
end
Or use a Ruby Hash:
describe registry_key({
name: 'Task Scheduler',
hive: 'HKEY_LOCAL_MACHINE',
key: ''\SYSTEM\CurrentControlSet\services\Schedule'
}) do
its('Start') { should eq 2 }
end
### Registry Key Path Separators
A Windows registry key can be used as a string in Ruby code, such as when a registry key is used as the name of a recipe. In Ruby, when a registry key is enclosed in a double-quoted string (`" "`), the same backslash character (`\`) that is used to define the registry key path separator is also used in Ruby to define an escape character. Therefore, the registry key path separators must be escaped when they are enclosed in a double-quoted string. For example, the following registry key:
HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes
may be encloused in a single-quoted string with a single backslash:
'HKCU\SOFTWARE\path\to\key\Themes'
or may be enclosed in a double-quoted string with an extra backslash as an escape character:
"HKCU\\SOFTWARE\\path\\to\\key\\Themes"
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### children
The `children` matcher return all of the child items of a registry key. A regular expression may be used to filter child items:
describe registry_key('Key Name', '\path\to\key').children(regex)
...
end
For example, to get all child items for a registry key:
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet').children do
it { should_not eq [] }
end
The following example shows how find a property that may exist against multiple registry keys, and then test that property for every registry key in which that property is located:
describe registry_key({
hive: 'HKEY_USERS'
}).children(/^S-1-5-21-[0-9]+-[0-9]+-[0-9]+-[0-9]{3,}\\Software\\Policies\\Microsoft\\Windows\\Installer/).each { |key|
describe registry_key(key) do
its('AlwaysInstallElevated') { should eq 'value' }
end
}
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### exist
The `exist` matcher tests if the registry key is present:
it { should exist }
### have_property
The `have_property` matcher tests if a property exists for a registry key:
it { should have_property 'value' }
### have\_property\_value
The `have_property_value` matcher tests if a property value exists for a registry key:
it { should have_property_value 'value' }
### have_value
The `have_value` matcher tests if a value exists for a registry key:
it { should have_value 'value' }
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
### name
The `name` matcher tests the value for the specified registry setting:
its('name') { should eq 'value' }
## Examples
The following examples show how to use this InSpec audit resource.
### Test the start time for the Schedule service
describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\...\Schedule') do
its('Start') { should eq 2 }
end
where `'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule'` is the full path to the setting.
### Use a regular expression in responses
describe registry_key({
hive: 'HKEY_LOCAL_MACHINE',
key: 'SOFTWARE\Microsoft\Windows NT\CurrentVersion'
}) do
its('ProductName') { should match /^[a-zA-Z0-9\(\)\s]*2012\s[rR]2[a-zA-Z0-9\(\)\s]*$/ }
end

76
docs/resources/runit_service.md.erb Normal file
View file

@ -0,0 +1,76 @@
---
title: About the runit_service Resource
---
# runit_service
Use the `runit_service` InSpec audit resource to test a service using runit.
## Syntax
A `runit_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
describe runit_service('service_name') do
it { should be_installed }
it { should be_enabled }
it { should be_running }
end
where
* `('service_name')` must specify a service name
* `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource; all matchers available to the `service` resource may be used
The path to the service manager's control may be specified for situations where the path isn't available in the current `PATH`. For example:
describe runit_service('service_name', '/path/to/control') do
it { should be_enabled }
it { should be_installed }
it { should be_running }
end
## Matchers
This InSpec audit resource has the following matchers:
### be
<%= partial "/shared/matcher_be" %>
### be_enabled
The `be_enabled` matcher tests if the named service is enabled:
it { should be_enabled }
### be_installed
The `be_installed` matcher tests if the named service is installed:
it { should be_installed }
### be_running
The `be_running` matcher tests if the named service is running:
it { should be_running }
### cmp
<%= partial "/shared/matcher_cmp" %>
### eq
<%= partial "/shared/matcher_eq" %>
### include
<%= partial "/shared/matcher_include" %>
### match
<%= partial "/shared/matcher_match" %>
## Examples
None.

Some files were not shown because too many files have changed in this diff Show more