inspec 0.9.0

data/README.md

@@ -0,0 +1,257 @@
+# InSpec
+
+## What is InSpec?
+
+InSpec is an open-source testing framework for infrastructure with an easy language for specifying compliance, security, and policy requirements. The project name stands for "infrastructure specification" and can be thought of as an abbreviation of "inspect".
+
+You can use InSpec to examine any node in your infrastructure. The InSpec framework runs locally or remotely on the node being inspected. It uses test rules written in the InSpec language as input. Detected security, compliance, or policy issues are flagged in a log.
+
+The InSpec project includes many resources that help you write audit rules quickly and easily. Here are some examples.
+
+ * Disallow insecure protocols - In this example, the package and inetd_conf resources ensure that insecure services and protocols, such as telnet, are not used.
+
+```ruby
+describe package('telnetd') do
+  it { should_not be_installed }
+end
+
+describe inetd_conf do
+  its("telnet") { should eq nil }
+end
+```
+
+ * 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('protocol') {should eq 'tcp'}
+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.
+
+```ruby
+describe yaml('.kitchen.yml') do
+  its('driver.name') { should eq('vagrant') }
+end
+```
+
+## Test your Server, VM, or workstation.
+
+Small example: Write a your checks in `test.rb`:
+
+```ruby
+describe file('/proc/cpuinfo') do
+  it { should be_file }
+end
+
+describe ssh_config do
+  its('Protocol') { should eq('2') }
+end
+```
+
+Run this file locally:
+
+```bash
+inspec exec test.rb
+```
+
+## Installation
+
+Requires Ruby ( >1.9 ).
+
+To simply run it without installation, you must install [bundler](http://bundler.io/):
+
+```bash
+bundle install
+bundle exec bin/inspec help
+```
+
+To install it as a gem locally, run:
+
+```bash
+gem build inspec.gemspec
+gem install inspec-*.gem
+```
+
+You should now be able to run:
+
+```bash
+inspec --help
+```
+
+## Usage
+
+### exec
+
+Run tests against different targets:
+
+```bash
+# 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
+```
+
+### detect
+
+Verify your configuration and detect
+
+```bash
+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}
+```
+
+## Custom resources
+
+You can easily create your own resources. Here is a custom resource for an
+application called Gordon and save it in `gordon_config.rb`:
+
+```ruby
+require 'yaml'
+
+class GordonConfig < Inspec.resource
+  name 'gordon_config'
+
+  def initialize
+    @path = '/etc/gordon/config.yaml'
+    @config = inspec.file(@path).content
+    @params = YAML.load(@config)
+  end
+
+  def method_missing(name)
+    @params[name.to_s]
+  end
+end
+```
+
+Include this file in your `test.rb`:
+
+```ruby
+require_relative 'gordon_config'
+```
+
+Now you can start using your new resource:
+
+```ruby
+describe gordon_config do
+  its('Version') { should eq('1.0') }
+end
+```
+
+## Tests
+
+We perform `unit`, `resource` and `integration` tests.
+
+* `unit` tests ensure the intended behaviour of the implementation
+* `resource` tests run against docker containers
+* `integration` tests run against VMs via test-kitchen and [kitchen-inspec](https://github.com/chef/kitchen-inspec)
+
+### Unit tests
+
+Just
+```bash
+bundle exec rake test
+```
+as usual.
+
+### Resource tests
+
+Make sure the backend execution layer behaves as expected. These tests will take a while, as a lot of different operating systems and configurations are being tested.
+
+You will require:
+
+* docker
+
+Run `resource` tests with
+
+```bash
+bundle exec rake test:resources config=test/test.yaml
+bundle exec rake test:resources config=test/test-extra.yaml
+```
+
+### Integration tests
+
+These tests download various virtual machines, to ensure InSpec is working as expected across different operating systems.
+
+You will require:
+
+* vagrant with virtualbox
+* test-kitchen
+
+Run `integration` tests with
+
+```bash
+cd test/integration
+bundle exec kitchen test -t .
+```
+
+### 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.
+
+## Learn More
+
+For more information see the InSpec documentation: https://github.com/chef/inspec/tree/master/docs
+
+## 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)!
+
+## Contributing
+
+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
+
+## License
+
+| **Author:**          | Dominik Richter (<drichter@chef.io>)
+
+| **Author:**          | Christoph Hartmann (<chartmann@chef.io>)
+
+| **Copyright:**       | Copyright (c) 2015 Chef Software Inc.
+
+| **Copyright:**       | Copyright (c) 2015 Vulcano Security GmbH.
+
+| **License:**         | Apache License, Version 2.0
+
+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.

data/Rakefile

@@ -0,0 +1,47 @@
+#!/usr/bin/env rake
+# encoding: utf-8
+
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require_relative 'tasks/maintainers'
+
+# Rubocop
+desc 'Run Rubocop lint checks'
+task :rubocop do
+  RuboCop::RakeTask.new
+end
+
+# lint the project
+desc 'Run robocop linter'
+task lint: [:rubocop]
+
+# run tests
+task default: [:test, :lint]
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.warning = true
+  t.verbose = true
+  t.ruby_opts = ['--dev'] if defined?(JRUBY_VERSION)
+end
+
+namespace :test do
+  task :isolated do
+    Dir.glob('test/unit/*_test.rb').all? do |file|
+      sh(Gem.ruby, '-w', '-Ilib:test', file)
+    end or fail 'Failures'
+  end
+
+  task :resources do
+    tests = Dir['test/resource/*_test.rb']
+    return if tests.empty?
+    sh(Gem.ruby, 'test/docker_test.rb', *tests)
+  end
+
+  task :vm do
+    concurrency = ENV['CONCURRENCY'] || 4
+    path = File.join(File.dirname(__FILE__), 'test', 'integration')
+    sh('sh', '-c', "cd #{path} && bundle exec kitchen test -c #{concurrency} -t .")
+  end
+end

data/bin/inspec

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+# Copyright 2015 Dominik Richter. All rights reserved.
+# author: Dominik Richter
+# author: Christoph Hartmann
+
+require 'thor'
+require 'json'
+require_relative '../lib/inspec'
+
+class InspecCLI < Thor
+  def self.target_options
+    option :target, aliases: :t, type: :string, default: nil,
+      desc: 'Simple targeting option using URIs, e.g. ssh://user:pass@host:port'
+    option :backend, aliases: :b, type: :string, default: nil,
+      desc: 'Choose a backend: local, ssh, winrm, docker.'
+    option :host, type: :string,
+      desc: 'Specify a remote host which is tested.'
+    option :port, type: :numeric,
+      desc: 'Specify the login port for a remote scan.'
+    option :user, type: :string, default: nil,
+      desc: 'The login user for a remote scan.'
+    option :password, type: :string, default: nil,
+      desc: 'Login password for a remote scan, if required.'
+    option :key_files, type: :array, default: nil,
+      desc: 'Login key or certificate file for a remote scan.'
+    option :path, type: :string, default: nil,
+      desc: 'Login path to use when connecting to the target (WinRM).'
+    option :sudo, type: :boolean, default: false,
+      desc: 'Run scans with sudo. Only activates on Unix and non-root user.'
+    option :sudo_password, type: :string, default: nil,
+      desc: 'Specify a sudo password, if it is required.'
+    option :sudo_options, type: :string, default: '',
+      desc: 'Additional sudo options for a remote scan.'
+    option :ssl, type: :boolean, default: false,
+      desc: 'Use SSL for transport layer encryption (WinRM).'
+    option :self_signed, type: :boolean, default: false,
+      desc: 'Allow remote scans with self-signed certificates (WinRM).'
+  end
+
+  desc 'json PATH', 'read all tests in PATH and generate a JSON profile'
+  option :id, type: :string,
+    desc: 'Attach a profile ID to all test results'
+  option :output, aliases: :o, type: :string,
+    desc: 'Save the created profile to a path'
+  def json(path)
+    profile = Inspec::Profile.from_path(path, options)
+    dst = options[:output].to_s
+    if dst.empty?
+      puts JSON.pretty_generate(profile.info)
+    else
+      if File.exist? dst
+        puts "----> updating #{dst}"
+      else
+        puts "----> creating #{dst}"
+      end
+      fdst = File.expand_path(dst)
+      File.write(fdst, JSON.dump(profile.info))
+    end
+  end
+
+  desc 'check PATH', 'verify test structure in PATH'
+  def check(path)
+    o = options.dup
+    o[:logger] = Logger.new(STDOUT)
+    profile = Inspec::Profile.from_path(path, o)
+    exit 1 unless profile.check
+  end
+
+  desc 'exec PATHS', 'run all test files'
+  option :id, type: :string,
+    desc: 'Attach a profile ID to all test results'
+  target_options
+  option :format, type: :string, default: 'progress'
+  def exec(*tests)
+    runner = Inspec::Runner.new(options)
+    runner.add_tests(tests)
+    runner.run
+  rescue RuntimeError => e
+    puts e.message
+  end
+
+  desc 'detect', 'detect the target OS'
+  target_options
+  def detect
+    runner = Inspec::Runner.new(options)
+    rel = File.join(File.dirname(__FILE__), *%w{.. lib utils detect.rb})
+    detect_util = File.expand_path(rel)
+    runner.add_tests([detect_util])
+    runner.run
+  rescue RuntimeError => e
+    puts e.message
+  end
+
+  desc 'shell', 'open an interactive debugging shell'
+  target_options
+  def shell_func
+    runner = Inspec::Runner.new(options)
+    Inspec::Shell.new(runner).start
+  rescue RuntimeError => e
+    puts e.message
+  end
+
+  desc 'version', 'prints the version of this tool'
+  def version
+    puts Inspec::VERSION
+  end
+end
+InspecCLI.start(ARGV)

data/docs/ctl_inspec.rst

@@ -0,0 +1,195 @@
+=====================================================
+InSpec CLI
+=====================================================
+
+Use the InSpec CLI to run audit tests against targets using locally, SSH, |winrm|, or on |docker| containers.
+
+Common Options
+=====================================================
+The following options may be used with any of the InSpec CLI subcommands:
+
+``-b``, ``--backend``
+   Specify the backend. Possible values: ``local`` (default), ``ssh``, ``winrm``, or ``docker``.
+
+``--sudo``
+   Run scans with sudo. Only activates on Unix and non-root user. Default value: ``false``.
+
+``--host``
+   The remote host to be tested.
+
+``--key-files``
+   The login key or certificate file required for remote scanning.
+
+``--password``
+   The login password for remote scanning.
+
+``--path``
+   The login path used to connect to the target for |winrm|.
+
+``--port``
+   The port over which remote scanning will occur.
+
+``--self_signed``
+   Use to allow remote scanning with self-signed certificates for |winrm| targets.  Default value: ``false``.
+
+``--ssl``
+   Use to require transport-layer encryption via SSL for |winrm| targets. Default value: ``false``.
+
+``--sudo_options``
+   Additional options that may be required by the sudo password for remote scanning. Default value: ``''``.
+
+``--sudo_password``
+   The sudo password, if required.
+
+``-t``, ``--target``
+   The URI for the target of a remote scan, preceded by the target's backend. For example: ``backend://user:pass@host:port``, where ``backend`` is one of ``docker``, ``local``, ``ssh``, or ``winrm``.
+
+``--user``
+   The login user for remote scanning.
+
+
+
+check
+=====================================================
+Use ``inspec check`` to run all tests at the specified path.
+
+Syntax
+-----------------------------------------------------
+This subcommand has the following syntax:
+
+.. code-block:: bash
+
+   $ inspec check PATH (options)
+
+where:
+
+* ``PATH`` is the location against which tests are run
+
+
+
+detect
+=====================================================
+Use ``inspec detect`` to detect the platform for the target.
+
+For example, if the configuration on the target is:
+
+.. code-block:: bash
+
+   id=$( docker run -dti ubuntu:14.04 /bin/bash )
+
+the following command:
+
+.. code-block:: bash
+
+   $ inspec detect -t docker://$id
+
+will return:
+
+.. code-block:: javascript
+
+   {"family":"ubuntu","release":"14.04","arch":null}
+
+
+exec
+=====================================================
+Use ``inspec exec`` to run all tests at the specified path.
+
+Syntax
+-----------------------------------------------------
+This subcommand has the following syntax:
+
+.. code-block:: bash
+
+   $ inspec exec PATHS (options)
+
+where:
+
+* ``PATHS`` is one (or more) locations against which tests are run
+
+Options
+-----------------------------------------------------
+This subcommand has additional options:
+
+``--id``
+   Use to attach a profile identifier to all test results.
+
+Examples
+-----------------------------------------------------
+The following examples show how to use this subcommand.
+
+**Run a test locally**
+
+.. code-block:: bash
+
+   $ inspec exec test.rb
+
+**Run a test on a remote host using SSH**
+
+.. code-block:: bash
+
+   $ inspec exec test.rb -t ssh://user@hostname
+
+**Run a test on a remote host using WinRM**
+
+.. code-block:: bash
+
+   $ inspec exec test.rb -t winrm://Administrator@windowshost --password 'password'
+
+**Run a test against a Docker container**
+
+.. code-block:: bash
+
+   $ inspec exec test.rb -t docker://container_id
+
+
+
+help
+=====================================================
+Use ``inspec help`` to print help for the |ctl inspec| from the command shell.
+
+
+
+json
+=====================================================
+Use ``inspec json`` to read all tests at the specified path, and then generate a |json| profile to standard output (stdout).
+
+Syntax
+-----------------------------------------------------
+This subcommand has the following syntax:
+
+.. code-block:: bash
+
+   $ inspec json PATH (options)
+
+where:
+
+* ``PATH`` is the location against which tests are run
+
+Options
+-----------------------------------------------------
+This subcommand has additional options:
+
+``--id``
+   Use to attach a profile identifier to all test results.
+
+``-o``, ``--output``
+   Use to save the |json| profile to a file instead of printing to stdout.
+
+
+
+shell
+=====================================================
+Use ``inspec shell`` to open an interactive debugging shell.
+
+
+
+version
+=====================================================
+Use ``inspec version`` to print the version of the InSpec CLI.
+
+
+.. |winrm| replace:: Windows Remote Management
+.. _winrm: https://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx
+.. |docker| replace:: Docker
+.. _docker: https://www.docker.com/
+.. |json| replace:: JSON