Repository files navigation

• Project State: Active
• Issues Response SLA: 14 business days
• Pull Request Response SLA: 14 business days

For more information on project states and SLAs, seethis documentation.

Chef InSpec is an open-source testing framework for infrastructure with a human- and machine-readable language for specifying compliance, security and policy requirements.

# Disallow insecure protocols by testingdescribepackage('telnetd')do it{should_notbe_installed}enddescribeinetd_confdo its("telnet"){shouldeqnil}end

Chef InSpec makes it easy to run your tests wherever you need. More options are found in ourCLI docs.

# run test locallyinspecexec test.rb# run test on remote host via SSHinspecexec test.rb -t ssh://user@hostname -i /path/to/key# run test on remote host using SSH agent private key authentication. Requires Chef InSpec 1.7.1inspecexec test.rb -t ssh://user@hostname# run test on remote windows host via WinRMinspecexec test.rb -t winrm://Administrator@windowshost --password'your-password'# run test on remote windows host via WinRM as a domain userinspecexec test.rb -t winrm://windowshost --user'UserName@domain' --password'your-password'# run test on docker containerinspecexec test.rb -t docker://container_id

• Built-in Compliance: Compliance no longer occurs at the end of the release cycle
• Targeted Tests: Chef InSpec writes tests that specifically target compliance issues
• Metadata: Includes the metadata required by security and compliance pros
• Easy Testing: Includes a command-line interface to run tests quickly

Chef InSpec requires Ruby ( >= 3.0.3 ).

All currently supported versions of Chef InSpec (4.0 and later) require accepting the EULA to use. Please visit thelicense acceptance page on the Chef docs site for more information.

The Chef InSpec package is available for MacOS, RedHat, Ubuntu and Windows. Download the latest package atChef InSpec Downloads or install Chef InSpec via script:

# RedHat, Ubuntu, and macOScurl https://chefdownload-commercial.chef.io/install.sh?license_id=<LICENSE_ID> | sudo bash -s -- -P inspec# Windows. { iwr -useb https://chefdownload-commercial.chef.io/install.ps1?license_id=<LICENSE_ID> } | iex; install -project inspec

Replace<LICENSE_ID> with your license ID.

For more information about the install scripts, see theChef Install Script documentation.

Installing Chef InSpec from source may require installing ruby build tools to manage gem dependencies. (A compiler-free variant is available with reduced functionality; useinspec-core-bin andinspec-core.)

To install build tools, use your package manager.

For CentOS/RedHat/Fedora:

yum -y install ruby ruby-devel make gcc gcc-c++

For Ubuntu:

apt-get -y install ruby ruby-dev gcc g++ make

To install theinspec executable, which requires accepting theChef License, run:

gem install inspec-bin

You may also useinspec as a library, with no executable. This does not require accepting the license. To install the library as a gem, run:

gem install inspec

Download the image and define a function for convenience:

For Linux:

docker pull chef/inspecfunction inspec { docker run -it --rm -v $(pwd):/share chef/inspec "$@"; }

For Windows (PowerShell):

docker pull chef/inspecfunction inspec { docker run -it --rm -v "$(pwd):/share" chef/inspec $args; }

If you callinspec from your shell, it automatically mounts the current directory into the Docker container. Therefore you can easily use local tests and key files. Note: Only files in the current directory and sub-directories are available within the container.

$ ls -1vagranttest.rb$ inspec exec test.rb -t ssh://root@192.168.64.2:11022 -i vagrant..Finished in 0.04321 seconds (files took 0.54917 seconds to load)2 examples, 0 failures

To scan the docker containers running on the host using the containerized InSpec, we need to bind-mount the Unix socket/var/run/docker.sock from the host machine to the InSpec Container.

docker pull chef/inspecfunction inspec { docker run -it --rm -v $(pwd):/share -v /var/run/docker.sock:/var/run/docker.sock chef/inspec "$@"; }

/var/run/docker.sock is the Unix socket the Docker daemon listens on by default.

Note that installing from OS packages fromthe download page is the preferred method.

That requiresbundler:

bundle installbundleexec inspechelp

To install it as a gem locally, run:

gem build inspec.gemspecgem install inspec-*.gem

On Windows, you need to installRuby withRuby Development Kit to build dependencies with its native extensions.

Currently, this method of installation only supports Linux. See theChef Habitat site for more information.

Download thehab binary from theChef Habitat site.

hab pkg install chef/inspec --binlinkinspec

You should now be able to run:

$ inspec --helpCommands:  inspec archive PATH# archive a profile to tar.gz (default) ...  inspec check PATH# verify all tests at the specified PATH  inspec automate SUBCOMMAND ...# Chef Automate commands  inspec compliance SUBCOMMAND ...# Chef Automate commands (backwards compatible alias)  inspec detect# detect the target OS  inspecexec PATH(S)# run all test files at the specified PATH.  inspechelp [COMMAND]# Describe available commands or one spe...  inspec init TEMPLATE ...# Scaffolds a new project  inspec json PATH# read all tests in PATH and generate a ...  inspec shell# open an interactive debugging shell  inspec supermarket SUBCOMMAND ...# Supermarket commands  inspec version# prints the version of this toolOptions:  [--diagnose], [--no-diagnose]# Show diagnostics (versions, configurations)

• Only accept requests on secure ports - This test ensures that a web server is only listening on well-secured ports.

describeport(80)do it{should_notbe_listening}enddescribeport(443)do it{shouldbe_listening} its('protocols'){shouldinclude'tcp'}end

• Test yourkitchen.yml file to verify that only Vagrant is configured as the driver. The %w() formatting willpass rubocop linting and allow you to access nested mappings.

describeyaml('.kitchen.yml')doits(%w(drivername)){shouldeq('vagrant')}end

Also have a look at our examples for:

• Using Chef InSpec with Test Kitchen & Chef Infra
• Using Chef InSpec with Test Kitchen & Puppet
• Using Chef InSpec with Test Kitchen & Ansible
• Implementing an Chef InSpec profile

• Using describe.one, you can test for a or b. The control will be marked as passing if EITHER condition is met.

control'or-test'doimpact1.0title'This is a OR test'describe.onedodescribessh_configdoits('Protocol'){shouldeq('3')}enddescribessh_configdoits('Protocol'){shouldeq('2')}endendend

Run tests against different targets:

# run test locallyinspecexec test.rb# run test on remote host on SSHinspecexec test.rb -t ssh://user@hostname# run test on remote windows host on WinRMinspecexec test.rb -t winrm://Administrator@windowshost --password'your-password'# run test on docker containerinspecexec test.rb -t docker://container_id# run test on podman containerinspecexec test.rb -t podman://container_id --podman-url"unix:///run/user/1000/podman/podman.sock"# run with sudoinspecexec test.rb --sudo [--sudo-password ...] [--sudo-options ...] [--sudo_command ...]# run in a subshellinspecexec test.rb --shell [--shell-options ...] [--shell-command ...]# run a profile targeting AWS using env varsinspecexec test.rb -t aws://# or store your AWS credentials in your ~/.aws/credentials profiles fileinspecexec test.rb -t aws://us-east-2/my-profile# run a profile targeting Azure using env varsinspecexec test.rb -t azure://# or store your Azure credentials in your ~/.azure/credentials profiles fileinspecexec test.rb -t azure://subscription_id

Verify your configuration and detect

id=$( docker run -dti ubuntu:14.04 /bin/bash)inspec detect -t docker://$id

Which will provide you with:

{"family":"ubuntu","release":"14.04","arch":null}

Remote Targets

*For Windows, PowerShell 5.0 or above is required.

In addition, runtime support is provided for:

Documentation

• https://docs.chef.io/inspec/
• https://docs.chef.io/inspec/resources/
• https://github.com/inspec/inspec/tree/main/docs-chef-io

Learn Chef:

• https://community.chef.io/products/chef-inspec/#learn

Relationship to other tools (RSpec, Serverspec):

• https://docs.chef.io/inspec/inspec_and_friends/

You may share your Chef InSpec Profiles in theTools & Plugins section of theChef Supermarket.Sign in andadd the details of your profile.

You may alsobrowse the Supermarket for shared Compliance Profiles.

Chef InSpec was originally created by Christoph Hartmann (@chris-rock) and Dominik Richter (@arlimus).

Chef InSpec is inspired by the wonderfulServerspec project. Kudos tomizzy andall contributors!

The AWS resources were inspired byinspec-aws fromarothian.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The Chef InSpec community and maintainers are very active and helpful. This project benefits greatly from this activity.

If you'd like to chat with the community and maintainers directly join us in the#inspec channel on theChef Community Slack.

As a reminder, all participants are expected to follow theCode of Conduct.

We offerunit andintegration tests.

• unit tests ensure the intended behaviour of the implementation
• integration tests run against Docker-based VMs via test-kitchen andkitchen-inspec

bundleexec raketest

If you like to run only one test file:

bundleexec m test/unit/resources/user_test.rb

You may also run a single test within a file by line number:

bundleexec m test/unit/resources/user_test.rb -l 123

These tests download various virtual machines, to ensure Chef InSpec is working as expected across different operating systems.

These tests require the following gems:

• test-kitchen
• kitchen-dokken
• kitchen-inspec

These gems are provided via theintegration group in the project's Gemfile.

In addition, these test require Docker to be available on your machine or a remote Docker machine configured via the standard Docker environment variables.

List the various test instances available:

KITCHEN_YAML=kitchen.dokken.yml bundleexec kitchen list

The platforms and test suites are configured in thekitchen.dokken.yml file. Once you know which instance you wish to test, test that instance:

KITCHEN_YAML=kitchen.dokken.yml bundleexec kitchentest<INSTANCE_NAME>

You may test all instances in parallel with:

KITCHEN_YAML=kitchen.dokken.yml bundleexec kitchentest -c 3

Packaged distributions of Progress® Chef® products obtained from any authorised Progress Chef distribution source are made available pursuant to the Progress Chef EULA athttps://www.chef.io/end-user-license-agreement, unless there is an executed agreement in effect between you and Progress that covers the Progress Chef products ("Master Agreement"), in which case the Master Agreement shall govern.

Source code obtained from the Chef GitHub repository is made available under Apache-2.0, a copy of which is included below.

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.