No description
Find a file
Sonu Saha e7726bf7c2 CFINSPEC-78: Complete unit test for the resource
Signed-off-by: Sonu Saha <sonu.saha@progress.com>
2022-04-19 09:33:07 +05:30
.expeditor Extend CI test timeout to 60 minutes 2022-03-23 19:30:38 -04:00
.github CFINSPEC-38 Rename the stable branch to Inspec-4 2022-02-11 17:56:45 +05:30
contrib Adding inspec-aws to contrib 2019-07-12 13:57:16 -07:00
dev-docs Merge pull request #5916 from inspec/RESOURCE-312-extend-filter-table 2022-03-11 14:39:54 -05:00
docs-chef-io Merge pull request #5987 from inspec/ss/enhance-group-resource 2022-04-18 18:06:20 -04:00
etc CFINSPEC-82: Remove ppa resource deprecation for backward compatibility 2022-03-17 22:59:16 +05:30
examples With .rubocop.yml temporarily disabled, autocorrect example profile control code with cookstyle 2021-11-23 22:44:41 -05:00
habitat CFINSPEC-17 Update plan.ps1 to get ruby 3 pkg and let validate windows habitat build for ruby 3 2022-02-10 22:42:02 +05:30
inspec-bin Bump version to 5.13.4 by Chef Expeditor 2022-04-18 22:07:20 +00:00
kitchen/rake-tests blindly applied chefstyle -a 2019-06-11 18:52:03 -07:00
lib CFINSPEC-78: Add comments for new matchers & property 2022-04-19 09:33:07 +05:30
omnibus Bump omnibus-software from 82b14e3 to 960cb6e in /omnibus 2022-04-06 04:54:48 +00:00
support Update code to remove ruby 2.4 support 2021-09-01 18:07:56 +05:30
tasks Remove outdated / unmaintained maintainers task / docs 2020-12-08 17:12:38 -08:00
test CFINSPEC-78: Complete unit test for the resource 2022-04-19 09:33:07 +05:30
.bldr.toml Add windows to build_targets on builder 2019-10-16 19:55:54 -07:00
.codeclimate.yml enable reek and shellcheck 2019-12-03 19:09:01 -08:00
.dockerignore Avoid pulling in the local context when building the docker image 2020-12-18 11:40:54 -08:00
.gitignore Merge pull request #5618 from inspec/nm/check-cookstyle 2021-10-25 19:32:45 -04:00
.mdlrc Simmer down, linter 2019-06-06 14:18:24 -04:00
.rubocop.yml Exclude all example .rb files from .rubocop.yml to avoid chefstyle/cookstyle conflict 2021-11-23 22:46:54 -05:00
Berksfile Remove unused build-essential dep in berksfile 2020-12-09 10:53:00 -08:00
CHANGELOG.md Bump version to 5.13.4 by Chef Expeditor 2022-04-18 22:07:20 +00:00
CODE_OF_CONDUCT.md Update our Code of Conduct 2019-05-15 13:33:47 -07:00
CONTRIBUTING.md Fix downloads links 2021-12-20 17:53:29 -05:00
dobi.yaml Update Dobi annotations to address tagging bug 2021-04-19 15:28:08 -05:00
Dockerfile Executed '.expeditor/update_dockerfile.sh' 2022-04-08 15:39:12 +00:00
Gemfile Configure SimpleCov to no longer use at_exit hack; use JSON reporter 2022-02-06 22:09:38 -05:00
GITHUB_LABELS.md Change Inspec to InSpec where appropriate (#3494) 2018-10-15 12:09:46 -04:00
inspec-core.gemspec Merge pull request #5837 from inspec/vasundhara/support-rsepc-3-11 2022-02-21 13:18:27 -05:00
inspec.gemspec Merge pull request #5863 from inspec/nm/progress-bar 2022-03-07 10:28:39 -05:00
inspec_team-working_agreement.md update estimation points based on discussion to be consecutive integers 2019-11-25 16:20:29 -05:00
kitchen.dokken.yml Add back Ubuntu 16.04 packages + testing 2021-10-02 16:56:53 -07:00
kitchen.run_context.yml Test kitchen setup to test detection of audit-cookbook 2020-05-25 21:00:24 -04:00
LICENSE license belongs in LICENSE 2015-11-03 10:04:16 -08:00
omnibus_overrides.rb Pin openssl to 1.1.1m 2022-02-16 11:35:51 +05:30
Rakefile Removed aws and azure resources, unit and integration tests 2022-03-10 19:24:52 +05:30
README.md Update copyright year in README 2022-03-16 11:36:35 -04:00
RELEASE_PROCESS.md Update various readmes and docs 2020-09-14 14:09:23 -07:00
sonar-project.properties Exclude vendor directory 2022-02-24 11:54:32 -05:00
VERSION Bump version to 5.13.4 by Chef Expeditor 2022-04-18 22:07:20 +00:00

Chef InSpec: Inspect Your Infrastructure

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

For more information on project states and SLAs, see this documentation.

Slack Build status Coverage Status

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 testing

describe package('telnetd') do
  it { should_not be_installed }
end

describe inetd_conf do
  its("telnet") { should eq nil }
end

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

# run test locally
inspec exec test.rb

# run test on remote host via SSH
inspec exec 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.1
inspec exec test.rb -t ssh://user@hostname

# run test on remote windows host via WinRM
inspec exec test.rb -t winrm://Administrator@windowshost --password 'your-password'

# run test on remote windows host via WinRM as a domain user
inspec exec test.rb -t winrm://windowshost --user 'UserName@domain' --password 'your-password'

# run test on docker container
inspec exec test.rb -t docker://container_id

Features

  • 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

Installation

Chef InSpec requires Ruby ( >= 2.7 ).

Note: Versions of Chef InSpec 4.0 and later require accepting the EULA to use. Please visit the license acceptance page on the Chef docs site for more information.

Install as package

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

# RedHat, Ubuntu, and macOS
curl https://omnitruck.chef.io/install.sh | sudo bash -s -- -P inspec

# Windows
. { iwr -useb https://omnitruck.chef.io/install.ps1 } | iex; install -project inspec

Install it via rubygems.org

Installing Chef InSpec from source may require installing ruby build tools to manage gem dependencies. (A compiler-free variant is available with reduced functionality; use inspec-core-bin and inspec-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 the inspec executable, which requires accepting the Chef License, run:

gem install inspec-bin

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

gem install inspec

Usage via Docker

Download the image and define a function for convenience:

For Linux:

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

For Windows (PowerShell):

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

If you call inspec 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 -1
vagrant
test.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

Install it from source

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

That requires bundler:

bundle install
bundle exec inspec help

To install it as a gem locally, run:

gem build inspec.gemspec
gem install inspec-*.gem

On Windows, you need to install Ruby with Ruby Development Kit to build dependencies with its native extensions.

Install via Chef Habitat

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

Download the hab binary from the Chef Habitat site.

hab pkg install chef/inspec --binlink

inspec

Run Chef InSpec

You should now be able to run:

$ inspec --help
Commands:
  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
  inspec exec PATH(S)                                       # run all test files at the specified PATH.
  inspec help [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 tool

Options:
  [--diagnose], [--no-diagnose]  # Show diagnostics (versions, configurations)

Examples

  • Only accept requests on secure ports - This test ensures that a web server is only listening on well-secured ports.
describe port(80) do
  it { should_not be_listening }
end

describe port(443) do
  it { should be_listening }
  its('protocols') {should include 'tcp'}
end
  • Test your kitchen.yml file to verify that only Vagrant is configured as the driver. The %w() formatting will pass rubocop linting and allow you to access nested mappings.
describe yaml('.kitchen.yml') do
  its(%w(driver name)) { should eq('vagrant') }
end

Also have a look at our examples for:

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.
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

exec

Run tests against different targets:

# run test locally
inspec exec test.rb

# run test on remote host on SSH
inspec exec test.rb -t ssh://user@hostname

# run test on remote windows host on WinRM
inspec exec test.rb -t winrm://Administrator@windowshost --password 'your-password'

# run test on docker container
inspec exec test.rb -t docker://container_id

# run with sudo
inspec exec test.rb --sudo [--sudo-password ...] [--sudo-options ...] [--sudo_command ...]

# run in a subshell
inspec exec test.rb --shell [--shell-options ...] [--shell-command ...]

# run a profile targeting AWS using env vars
inspec exec test.rb -t aws://

# or store your AWS credentials in your ~/.aws/credentials profiles file
inspec exec test.rb -t aws://us-east-2/my-profile

# run a profile targeting Azure using env vars
inspec exec test.rb -t azure://

# or store your Azure credentials in your ~/.azure/credentials profiles file
inspec exec test.rb -t azure://subscription_id

detect

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}

Supported OS

Remote Targets

Platform Versions Architectures
AIX 6.1, 7.1, 7.2 ppc64
CentOS 6, 7, 8 i386, x86_64
Debian 9, 10 i386, x86_64
FreeBSD 9, 10, 11 i386, amd64
macOS 10.14, 10.15, 11.0 x86_64
Oracle Enterprise Linux 6, 7, 8 i386, x86_64
Red Hat Enterprise Linux 6, 7, 8 i386, x86_64
Solaris 10, 11 sparc, x86
Windows* 8, 8.1, 10, 2012, 2012R2, 2016, 2019 x86, x86_64
Ubuntu Linux x86, x86_64
SUSE Linux Enterprise Server 12, 15 x86_64
Scientific Linux 6, 7 i386, x86_64
Fedora x86_64
OpenSUSE 15 x86_64
OmniOS x86_64
Gentoo Linux x86_64
Arch Linux x86_64
HP-UX 11.31 ia64
Alpine Linux x86_64

*For Windows, PowerShell 5.0 or above is required.

In addition, runtime support is provided for:

Platform Versions Arch
macOS 10.14+ x86_64
Debian 9, 10 x86_64
RHEL 6, 7, 8 x86_64
Fedora 29+ x86_64
Ubuntu 16.04+ x86_64
Windows 8+ x86_64
Windows 2012+ x86_64

Documentation

Documentation

Learn Chef:

Relationship to other tools (RSpec, Serverspec):

Share your Profiles

You may share your Chef InSpec Profiles in the Tools & Plugins section of the Chef Supermarket. Sign in and add the details of your profile.

You may also browse the Supermarket for shared Compliance Profiles.

Kudos

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

Chef InSpec is inspired by the wonderful Serverspec project. Kudos to mizzy and all contributors!

The AWS resources were inspired by inspec-aws from arothian.

Contribute

  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 the Chef Community Slack.

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

Slack

Testing Chef InSpec

We offer unit and integration tests.

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

Unit tests

bundle exec rake test

If you like to run only one test file:

bundle exec m test/unit/resources/user_test.rb

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

bundle exec m test/unit/resources/user_test.rb -l 123

Integration tests

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 the integration 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.

Running Integration tests

List the various test instances available:

KITCHEN_YAML=kitchen.dokken.yml bundle exec kitchen list

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

KITCHEN_YAML=kitchen.dokken.yml bundle exec kitchen test <INSTANCE_NAME>

You may test all instances in parallel with:

KITCHEN_YAML=kitchen.dokken.yml bundle exec kitchen test -c 3

License

Author: Dominik Richter (drichter@chef.io)
Author: Christoph Hartmann (chartmann@chef.io)
Copyright: Copyright (c) 2015 Vulcano Security GmbH.
Copyright: Copyright (c) 2017-2020 Chef Software Inc.
Copyright: Copyright (c) 2020-2022 Progress Software Corp.
License: Apache License, Version 2.0
License: Chef End User License Agreement

Chef InSpec is distributed under the Apache License, Version 2.0. Permission to use the software is governed by the Chef EULA.

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, software distributed 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 and limitations under the License.