inspec/README.md

448 lines
14 KiB
Markdown
Raw Normal View History

2015-11-03 17:15:09 +00:00
# InSpec: Inspect Your Infrastructure
[![Slack](https://community-slack.chef.io/badge.svg)](https://community-slack.chef.io/)
2016-04-06 10:58:17 +00:00
[![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)
2016-03-10 00:39:24 +00:00
2015-12-04 16:29:48 +00:00
InSpec is an open-source testing framework for infrastructure with a human- and machine-readable language for specifying compliance, security and policy requirements.
2015-10-26 22:41:27 +00:00
```ruby
2015-11-03 17:15:09 +00:00
# Disallow insecure protocols by testing
2015-10-26 22:41:27 +00:00
describe package('telnetd') do
2015-10-27 01:16:32 +00:00
  it { should_not be_installed }
2015-10-26 22:41:27 +00:00
end
describe inetd_conf do
2015-10-27 01:16:32 +00:00
  its("telnet") { should eq nil }
2015-10-26 22:41:27 +00:00
end
```
InSpec makes it easy to run your tests wherever you need. More options are found in our [CLI docs](https://www.inspec.io/docs/reference/cli/).
2015-10-26 22:41:27 +00:00
2015-11-03 17:15:09 +00:00
```bash
# run test locally
inspec exec test.rb
2015-11-03 17:15:09 +00:00
# run test on remote host on 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 InSpec 1.7.1
inspec exec test.rb -t ssh://user@hostname
2015-11-03 17:15:09 +00:00
# run test on remote windows host on WinRM
inspec exec test.rb -t winrm://Administrator@windowshost --password 'your-password'
2015-11-03 17:15:09 +00:00
# run test on docker container
inspec exec test.rb -t docker://container_id
```
2015-11-03 17:15:09 +00:00
# Features
2015-11-03 17:30:29 +00:00
- Built-in Compliance: Compliance no longer occurs at the end of the release cycle
- Targeted Tests: 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
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) or install 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
When installing from source, gem dependencies may require ruby build tools to be installed.
For CentOS/RedHat/Fedora:
```bash
yum -y install ruby ruby-devel make gcc gcc-c++
```
For Ubuntu:
```bash
apt-get -y install ruby ruby-dev gcc g++ make
```
To install inspec from [rubygems](https://rubygems.org/):
```bash
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
That requires [bundler](http://bundler.io/):
```bash
bundle install
2015-10-26 03:04:18 +00:00
bundle exec bin/inspec help
```
To install it as a gem locally, run:
```bash
2015-10-26 03:04:18 +00:00
gem build inspec.gemspec
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.
### 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
You should now be able to run:
```bash
$ inspec --help
Commands:
inspec archive PATH # archive a profile to tar.gz (default) ...
inspec check PATH # verify all tests at the specified PATH
inspec compliance SUBCOMMAND ... # Chef Compliance commands
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)
```
2015-11-03 17:15:09 +00:00
# Examples
* Only accept requests on secure ports - This test ensures that a web server is only listening on well-secured ports.
```ruby
describe port(80) do
  it { should_not be_listening }
end
describe port(443) do
  it { should be_listening }
  its('protocols') {should include 'tcp'}
2015-11-03 17:15:09 +00:00
end
```
* Use approved strong ciphers - This test ensures that only enterprise-compliant ciphers are used for SSH servers.
```ruby
describe sshd_config do
   its('Ciphers') { should eq('chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr') }
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.
2015-11-03 17:15:09 +00:00
```ruby
describe yaml('.kitchen.yml') do
its(%w(driver name)) { should eq('vagrant') }
2015-11-03 17:15:09 +00:00
end
```
Also have a look at our examples for:
2016-01-21 12:35:04 +00:00
- [Using InSpec with Test Kitchen & Chef](https://github.com/chef/inspec/tree/master/examples/kitchen-chef)
- [Using InSpec with Test Kitchen & Puppet](https://github.com/chef/inspec/tree/master/examples/kitchen-puppet)
- [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)
2016-08-21 23:01:59 +00:00
## 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
```
2015-11-03 17:15:09 +00:00
## Command Line Usage
### exec
Run tests against different targets:
```bash
# run test locally
2015-10-26 03:04:18 +00:00
inspec exec test.rb
# run test on remote host on SSH
2015-10-26 03:04:18 +00:00
inspec exec test.rb -t ssh://user@hostname
# run test on remote windows host on WinRM
2015-10-26 03:04:18 +00:00
inspec exec test.rb -t winrm://Administrator@windowshost --password 'your-password'
# run test on docker container
2015-10-26 03:04:18 +00:00
inspec exec test.rb -t docker://container_id
2015-11-06 00:38:55 +00:00
# run with sudo
2016-05-15 11:22:18 +00:00
inspec exec test.rb --sudo [--sudo-password ...] [--sudo-options ...] [--sudo_command ...]
2016-09-30 19:18:14 +00:00
# run in a subshell
inspec exec test.rb --shell [--shell-options ...] [--shell-command ...]
2016-12-15 08:53:01 +00:00
# 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
```bash
id=$( docker run -dti ubuntu:14.04 /bin/bash )
2015-10-26 03:04:18 +00:00
inspec detect -t docker://$id
```
Which will provide you with:
```
{"family":"ubuntu","release":"14.04","arch":null}
```
2016-08-01 21:11:48 +00:00
## Supported OS
Remote Targets
| Platform | Versions | Architectures |
| ---------------------------- | ------------------------------------------------ | ------------- |
| AIX | 6.1, 7.1, 7.2 | ppc64 |
| CentOS | 5, 6, 7 | i386, x86_64 |
| Debian | 7, 8 | i386, x86_64 |
| FreeBSD | 9, 10 | i386, amd64 |
| Mac OS X | 10.9, 10.10, 10.11 | x86_64 |
| Oracle Enterprise Linux | 5, 6, 7 | i386, x86_64 |
| Red Hat Enterprise Linux | 5, 6, 7 | i386, x86_64 |
| Solaris | 10, 11 | sparc, x86 |
| Windows\* | 7, 8, 8.1, 10, 2008, 2008R2 , 2012, 2012R2, 2016 | x86, x86_64 |
| Ubuntu Linux | | x86, x86_64 |
| SUSE Linux Enterprise Server | 11, 12 | x86_64 |
| Scientific Linux | 5.x, 6.x and 7.x | i386, x86_64 |
| Fedora | | x86_64 |
| OpenSUSE | 13.1/13.2/42.1 | x86_64 |
| OmniOS | | x86_64 |
| Gentoo Linux | | x86_64 |
| Arch Linux | | x86_64 |
| HP-UX | 11.31 | ia64 |
2016-08-01 21:11:48 +00:00
\**For Windows, PowerShell 5.0 or above is required.*
2016-08-01 21:11:48 +00:00
In addition, runtime support is provided for:
| Platform | Versions |
| -------- | -------- |
| Debian | 8 |
| RHEL | 6, 7 |
| Ubuntu | 12.04+ |
| Windows | 7+ |
| Windows | 2012+ |
2016-08-01 21:11:48 +00:00
2015-11-03 17:15:09 +00:00
## Documentation
2016-05-25 09:40:20 +00:00
Documentation
* https://www.inspec.io/docs/
* https://www.inspec.io/docs/reference/resources/
2016-05-25 09:40:20 +00:00
* https://github.com/chef/inspec/tree/master/docs
Tutorials/Blogs/Podcasts:
* https://www.inspec.io/tutorials/
2015-11-03 17:15:09 +00:00
Relationship to other tools (RSpec, Serverspec):
* https://www.inspec.io/docs/reference/inspec_and_friends/
## Share your Profiles
You may share your InSpec Profiles in the [Tools & Plugins section](https://supermarket.chef.io/tools-directory) of the [Chef Supermarket](https://supermarket.chef.io/). [Sign in](https://supermarket.chef.io/sign-in) and [add the details of your profile](https://supermarket.chef.io/tools/new).
You may also [browse the Supermarket for shared Compliance Profiles](https://supermarket.chef.io/tools?type=compliance_profile).
2015-11-03 17:15:09 +00:00
## Kudos
InSpec is inspired by the wonderful [Serverspec](http://serverspec.org) project. Kudos to [mizzy](https://github.com/mizzy) and [all contributors](https://github.com/mizzy/serverspec/graphs/contributors)!
The AWS resources were inspired by [inspec-aws](https://github.com/arothian/inspec-aws) from [arothian](https://github.com/arothian).
2015-11-03 17:15:09 +00:00
## Contribute
1. Fork it
1. Create your feature branch (git checkout -b my-new-feature)
1. Commit your changes (git commit -am 'Add some feature')
1. Push to the branch (git push origin my-new-feature)
1. Create new Pull Request
2016-09-07 14:32:49 +00:00
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)
2015-11-03 17:15:09 +00:00
## Testing InSpec
We offer `unit`, `integration`, and `aws` tests.
2015-10-30 14:04:10 +00:00
- `unit` tests ensure the intended behaviour of the implementation
- `integration` tests run against Docker-based VMs via test-kitchen and [kitchen-inspec](https://github.com/chef/kitchen-inspec)
- `aws` tests exercise the AWS resources against real AWS accounts
### Unit tests
```bash
2015-10-30 13:05:02 +00:00
bundle exec rake test
```
If you like to run only one test file:
2015-12-03 17:51:47 +00:00
```bash
bundle exec m test/unit/resources/user_test.rb
2015-12-03 17:51:47 +00:00
```
You may also run a single test within a file by line number:
```bash
bundle exec m test/unit/resources/user_test.rb -l 123
```
2015-10-30 14:04:10 +00:00
### Integration tests
These tests download various virtual machines, to ensure InSpec is working as expected across different operating systems.
These tests require the following gems:
- test-kitchen
- kitchen-dokken
- kitchen-inspec
2015-10-30 14:04:10 +00:00
These gems are provided via the `integration` group in the project's Gemfile.
2015-10-30 14:04:10 +00:00
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:
2015-10-30 14:04:10 +00:00
```bash
bundle exec kitchen list
2015-10-30 14:04:10 +00:00
```
The platforms and test suites are configured in the `.kitchen.yml` file. Once you know which instance you wish to test, test that instance:
```bash
bundle exec kitchen test <INSTANCE_NAME>
```
You may test all instances in parallel with:
```bash
bundle exec kitchen test -c
```
### AWS Tests
Use the rake task `bundle exec rake test:aws` to test the AWS resources against a pair of real AWS accounts.
Please see [TESTING_AGAINST_AWS.md](./test/integration/aws/TESTING_AGAINST_AWS.md) for details on how to setup the needed AWS accounts to perform testing.
2015-11-03 08:25:24 +00:00
## License
| | |
| -------------- | ----------------------------------------- |
| **Author:** | Dominik Richter (<drichter@chef.io>) |
| **Author:** | Christoph Hartmann (<chartmann@chef.io>) |
2016-09-07 14:00:23 +00:00
| **Copyright:** | Copyright (c) 2015 Vulcano Security GmbH. |
| **Copyright:** | Copyright (c) 2017 Chef Software Inc. |
| **License:** | Apache License, Version 2.0 |
2015-10-26 22:41:27 +00:00
2015-11-03 08:25:24 +00:00
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
2015-10-26 22:41:27 +00:00
2015-11-03 08:25:24 +00:00
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.