inspec 0.34.1 → 1.0.0

data/docs/ruby_usage.rst

@@ -1,145 +0,0 @@
-=====================================================
-Using |ruby| in InSpec
-=====================================================
-
-The |inspec| DSL is a |ruby| based DSL for writing audit controls, which includes audit resources that you can invoke.
-Core and custom resources are written as regular |ruby| classes which inherit from ``Inspec.resource``.
-
-Assuming we have a |json| file like this on the node to be tested:
-
-.. code-block:: json
-
-    {
-      "keys":[
-        {"username":"john", "key":"/opt/keys/johnd.key"},
-        {"username":"jane", "key":"/opt/keys/janed.key"},
-        {"username":"sunny ", "key":"/opt/keys/sunnym.key"}
-      ]
-    }
-
-The following example shows how you can use pure |ruby| code(variables, loops, conditionals, regular expressions, etc) to run a few tests against the above |json| file:
-
-.. code-block:: ruby
-
-    control 'check-interns' do
-      # use the json inspec resource to get the file
-      json_obj = json('/opt/keys/interns.json')
-      describe json_obj do
-        its('keys') { should_not eq nil }
-      end
-      if json_obj['keys']
-        # loop over the keys array
-        json_obj['keys'].each do |intern|
-          username = intern['username'].strip
-          # check for white spaces chars in usernames
-          describe username do
-            it { should_not match(/\s/) }
-          end
-          # check key file owners and permissions
-          describe file(intern['key']) do
-            it { should be_owned_by username }
-            its('mode') { should cmp '0600' }
-          end
-        end
-      end
-    end
-
-Execution
-=====================================================
-
-It's important to understand that |ruby| code used in custom resources and controls DSL is executed on the system that runs |inspec|. This allows |inspec| to work without |ruby| and rubygems being required on remote targets(servers or containers).
-
-For example, using ```ls``` or ``system('ls')`` will result in the ``ls`` command being run locally and not on the target(remote) system.
-In order to process the output of ``ls`` executed on the target system, use ``inspec.command('ls')`` or ``inspec.powershell('ls')``
-
-Similarly, use ``inspec.file(PATH)`` to access files or directories from remote systems in your tests or custom resources.
-
-Using rubygems
-=====================================================
-
-|ruby| gems are self-contained programs and libraries ...
-
-
-Interactive Debugging with Pry
-=====================================================
-
-Here's a sample |inspec| control that users |ruby| variables to instantiate an |inspec| resource once and use the content in multipLe tests.
-
-.. code-block:: ruby
-
-    control 'check-perl' do
-      impact 0.3
-      title 'Check perl compiled options and permissions'
-      perl_out = command('perl -V')
-      #require 'pry'; binding.pry;
-      describe perl_out do
-        its('exit_status') { should eq 0 }
-        its('stdout') { should match (/USE_64_BIT_ALL/) }
-        its('stdout') { should match (/useposix=true/) }
-        its('stdout') { should match (/-fstack-protector/) }
-      end
-
-      # extract an array of include directories
-      perl_inc = perl_out.stdout.partition('@INC:').last.strip.split("\n")
-      # ensure include directories are only writable by 'owner'
-      perl_inc.each do |path|
-        describe directory(path.strip) do
-          it { should_not be_writable.by('group') }
-          it { should_not be_writable.by('other') }
-        end
-      end
-    end
-
-An **advanced** but very useful |ruby| tip. In the previous example, I commented out the ``require 'pry'; binding.pry;`` line. If you remove  the ``#`` prefix and run the control, the execution will stop at that line and give you a ``pry`` shell. Use that to troubleshoot, print variables, see methods available, etc. For the above example:
-
-.. code-block:: ruby
-
-    [1] pry> perl_out.exit_status
-    => 0
-    [2] pry> perl_out.stderr
-    => ""
-    [3] pry> ls perl_out
-    Inspec::Plugins::Resource#methods: inspect
-    Inspec::Resources::Cmd#methods: command  exist?  exit_status  result  stderr  stdout  to_s
-    Inspec::Plugins::ResourceCommon#methods: resource_skipped  skip_resource
-    Inspec::Resource::Registry::Command#methods: inspec
-    instance variables: @__backend_runner__  @__resource_name__  @command  @result
-    [4] pry> perl_out.stdout.partition('@INC:').last.strip.split("\n")
-    => ["/Library/Perl/5.18/darwin-thread-multi-2level",
-     "    /Library/Perl/5.18",
-    ...REDACTED...
-    [5] pry> exit    # or abort
-
-You can use ``pry`` inside both the controls DSL and resources.
-Similarly, for dev and test, you can use ``inspec shell`` which is based on ``pry``, for example:
-
-.. code-block:: ruby
-
-    $ inspec shell
-    Welcome to the interactive InSpec Shell
-    To find out how to use it, type: help
-
-    inspec> command('ls /home/gordon/git/inspec/docs').stdout
-    => "ctl_inspec.rst\ndsl_inspec.rst\ndsl_resource.rst\n"
-    inspec> command('ls').stdout.split("\n")
-    => ["ctl_inspec.rst", "dsl_inspec.rst", "dsl_resource.rst"]
-
-    inspec> help command
-    Name: command
-
-    Description:
-    Use the command InSpec audit resource to test an arbitrary command that is run on the system.
-
-    Example:
-    describe command('ls -al /') do
-      it { should exist }
-      its('stdout') { should match /bin/ }
-      its('stderr') { should eq '' }
-      its('exit_status') { should eq 0 }
-    end
-
-.. |inspec| replace:: InSpec
-.. |chef compliance| replace:: Chef Compliance
-.. |ruby| replace:: Ruby
-.. |csv| replace:: CSV
-.. |json| replace:: JSON

data/docs/shell.rst

@@ -1,130 +0,0 @@
-=====================================================
-InSpec Shell Usage
-=====================================================
-
-The InSpec interactive shell is a pry based REPL that can be used to quickly run InSpec controls and tests without having to write it to a file.  Its functionality is similar to ``chef shell`` - it provides a way to exercise the InSpec DSL, its resources, tests and plugins without having to create a profile or write a test file.  See http://pryrepl.org/ for an introduction to what pry is and what it can do.
-
-
-Launching the shell
------------------------------------------------------
-
-If you are using InSpec from a platform-specific package (rpm, msi, etc.) or from a chef prepared shell in ChefDK, you can directly launch InSpec shell against your local machine using the following.  See https://docs.chef.io/install_dk.html#set-system-ruby for details.
-
-.. code-block:: bash
-
-    $ inspec shell
-    $ inspec help shell # This will describe inspec shell usage
-
-If you wish to connect to a remote machine (called a target within InSpec), you can use the ``-t`` flag.  We support connecting using ssh, WinRm and docker.  If no target is provided, we implicitly support the "local" target - i.e. tests running on the current machine running InSpec.  For an ssh connection, use ``-i`` for specifying ssh key files, and the ``--sudo*`` commands for requesting a privelege escalation after logging in.  For a WinRM connection, use ``--path`` to change the login path, ``--ssl`` to use SSL for transport layer encryption.
-
-.. code-block:: bash
-
-    $ inspec shell -t ssh://root@192.168.64.2:11022  # Login to remote machine using ssh as root.
-    $ inspec shell -t ssh://user@hostname:1234 -i /path/to/user_key  # Login to hostname on port 1234 as user using given ssh key.
-    $ inspec shell -t winrm://UserName:Password@windowsmachine:1234  # Login to windowsmachine over WinRM as UserName.
-    $ inspec shell -t docker://container_id # Login to a docker container.
-
-
-Using Ruby in InSpec shell
------------------------------------------------------
-
-Since InSpec shell is pry based, you may treat the shell as an interactive Ruby session.  You may write Ruby expressions and evaluate them.  Source high-lighting, automatic indentation and command history (using the up and down arrow keys) are available to make your experience more delightful.  You can exit the shell using ``exit``.
-
-.. code-block:: bash
-
-    $ inspec shell
-    Welcome to the interactive InSpec Shell
-    To find out how to use it, type: help
-
-    inspec> 1 + 2
-    => 3
-    inspec> exit
-
-
-Using InSpec DSL in InSpec shell
------------------------------------------------------
-
-InSpec shell will automatically evaluate the result of every command as if it were a test file.  If you type in a Ruby command that is not an InSpec control or test, the shell will evaluate it as if it were a regular ruby command.
-
-Bare InSpec resources are instantiated and their help text is presented.  You may also access the resource contents or other matchers that they define.  Run ``help <resource>`` to get more help on using a particular resource or see the InSpec resources documentation online.
-
-.. code-block:: bash
-
-    $ inspec shell
-    Welcome to the interactive InSpec Shell
-    To find out how to use it, type: help
-
-    inspec> file('/Users/ksubramanian').directory?
-    => true
-    inspec> os_env('HOME')
-    => Environment variable HOME
-    inspec> os_env('HOME').content
-    => /Users/ksubramanian
-    inspec> exit
-
-InSpec tests are immediately executed.
-
-
-.. code-block:: bash
-
-    inspec> describe file('/Users')     # Empty test.
-    Summary: 0 successful, 0 failures, 0 skipped
-    inspec> describe file('/Users') do  # Test with one check.
-    inspec>   it { should exist }
-    inspec> end
-      ✔  File /Users should exist
-
-    Summary: 1 successful, 0 failures, 0 skipped
-
-
-All tests in a control are immediately executed as well.  If a control is redefined in the shell, the old control's tests are destroyed and replaced with the redefinition and the control is re-run.
-
-.. code-block:: bash
-
-    inspec> control 'my_control' do
-    inspec>   describe os_env('HOME') do
-    inspec>     its('content') { should eq '/Users/ksubramanian' }
-    inspec>   end
-    inspec> end
-      ✔  my_control: Environment variable HOME content should eq "/Users/ksubramanian"
-
-      Summary: 1 successful, 0 failures, 0 skipped
-
-Syntax errors are illegal tests are also detected and reported.
-
-
-.. code-block:: bash
-
-    inspec> control 'foo' do
-    inspec>   thisisnonsense
-    inspec> end
-    NameError: undefined local variable or method `thisisnonsense' for #<#<Class:0x007fd63b571f98>:0x007fd639825cc8>
-    from /usr/local/lib/ruby/gems/2.3.0/gems/rspec-expectations-3.5.0/lib/rspec/matchers.rb:967:in `method_missing'
-    inspec> control 'foo' do
-    inspec>   describe file('wut') do
-    inspec>     its('thismakesnosense') { should cmp 'fail' }
-    inspec>   end
-    inspec> end
-      ✖  foo: File wut thismakesnosense  (undefined method `thismakesnosense' for File wut:Inspec::Resource::Registry::File)
-
-      Summary: 0 successful, 1 failures, 0 skipped
-
-
-Running a single InSpec command
------------------------------------------------------
-
-If you wish to run a single InSpec command and fetch its results, you may use the ``-c`` flag.  This is similar to using ``bash -c``.
-
-.. code-block:: bash
-    $ inspec shell -c 'describe file("/Users/ksubramanian") do it { should exist } end'
-
-    Target:  local://
-
-      ✔  File /Users/ksubramanian should exist
-
-    Summary: 1 successful, 0 failures, 0 skipped
-
-
-.. code-block:: bash
-    $ inspec shell --format json -c 'describe file("/Users/ksubramanian") do it { should exist } end'
-    {"version":"0.30.0","profiles":{"":{"supports":[],"controls":{"(generated from in_memory.rb:1 5aab65c33fb1f133d9244017958eef64)":{"title":null,"desc":null,"impact":0.5,"refs":[],"tags":{},"code":"          rule = rule_class.new(id, profile_id, {}) do\n            res = describe(*args, &block)\n          end\n","source_location":{"ref":"/Users/ksubramanian/repo/chef/inspec/lib/inspec/profile_context.rb","line":184},"results":[{"status":"passed","code_desc":"File /Users/ksubramanian should exist","run_time":0.000747,"start_time":"2016-08-16 11:41:40 -0400"}]}},"groups":{"in_memory.rb":{"title":null,"controls":["(generated from in_memory.rb:1 5aab65c33fb1f133d9244017958eef64)"]}},"attributes":[]}},"other_checks":[],"summary":{"duration":0.001078,"example_count":1,"failure_count":0,"skip_count":0}}

data/docs/template.rst

@@ -1,51 +0,0 @@
-resource_name
-=====================================================
-Use the ``resource_name`` audit resource to xxxxx.
-
-Syntax
------------------------------------------------------
-A ``resource_name`` audit resource block declares xxxxx. For example:
-
-.. code-block:: ruby
-
-   describe xxxxx(xxxxx) do
-     it { should xxxxx }
-   end
-
-where
-
-* ``xxxxx`` must specify xxxxx
-* xxxxx
-* ``xxxxx`` is a valid matcher for this audit resource
-
-Matchers
------------------------------------------------------
-This audit resource has the following matchers.
-
-xxxxx
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
-The ``xxxxx`` matcher tests if xxxxx. For example:
-
-.. code-block:: ruby
-
-   it { should xxxxx }
-
-xxxxx
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
-The ``xxxxx`` matcher tests if xxxxx. For example:
-
-.. code-block:: ruby
-
-   it { should xxxxx }
-
-Examples
------------------------------------------------------
-The following examples show how to use this audit resource in a recipe.
-
-**xxxxx**
-
-xxxxx
-
-**xxxxx**
-
-xxxxx

data/lib/resources/group.rb

@@ -1,137 +0,0 @@
-# encoding: utf-8
-# author: Christoph Hartmann
-# author: Dominik Richter
-
-# Usage:
-# describe group('root') do
-#   it { should exist }
-#   its('gid') { should eq 0 }
-# end
-#
-# deprecated has matcher
-# describe group('root') do
-#  it { should have_gid 0 }
-# end
-
-module Inspec::Resources
-  class Group < Inspec.resource(1)
-    name 'group'
-    desc 'Use the group InSpec audit resource to test groups on the system.'
-    example "
-      describe group('root') do
-        it { should exist }
-        its('gid') { should eq 0 }
-      end
-    "
-
-    def initialize(groupname, domain = nil)
-      @group = groupname.downcase
-      @domain = domain
-      @domain = @domain.downcase unless @domain.nil?
-
-      @cache = nil
-
-      # select group manager
-      @group_provider = nil
-      if inspec.os.unix?
-        @group_provider = UnixGroup.new(inspec)
-      elsif inspec.os.windows?
-        @group_provider = WindowsGroup.new(inspec)
-      else
-        return skip_resource 'The `group` resource is not supported on your OS yet.'
-      end
-    end
-
-    # verifies if a group exists
-    def exists?
-      # ensure that we found one group
-      !group_info.nil? && group_info.size > 0
-    end
-
-    def gid
-      return nil if group_info.nil? || group_info.size == 0
-
-      # the default case should be one group
-      return group_info[0][:gid] if group_info.size == 1
-
-      # return array if we got multiple gids
-      group_info.map { |grp| grp[:gid] }
-    end
-
-    # implements rspec has matcher, to be compatible with serverspec
-    def has_gid?(compare_gid)
-      gid == compare_gid
-    end
-
-    def local
-      return nil if group_info.nil? || group_info.size == 0
-
-      # the default case should be one group
-      return group_info[0][:local] if group_info.size == 1
-
-      # return array if we got multiple gids
-      group_info.map { |grp| grp[:local] }
-    end
-
-    def to_s
-      "Group #{@group}"
-    end
-
-    private
-
-    def group_info
-      return @cache if !@cache.nil?
-      @cache = @group_provider.group_info(@group, @domain) if !@group_provider.nil?
-    end
-  end
-
-  class GroupInfo
-    attr_reader :inspec
-    def initialize(inspec)
-      @inspec = inspec
-    end
-  end
-
-  # implements generic unix groups via /etc/group
-  class UnixGroup < GroupInfo
-    def group_info(group, _domain = nil)
-      inspec.etc_group.where(name: group).entries.map { |grp|
-        {
-          name: grp['name'],
-          gid: grp['gid'],
-        }
-      }
-    end
-  end
-
-  class WindowsGroup < GroupInfo
-    def group_info(compare_group, compare_domain = nil)
-      cmd = inspec.command('Get-WmiObject Win32_Group | Select-Object -Property Caption, Domain, Name, SID, LocalAccount | ConvertTo-Json')
-
-      # cannot rely on exit code for now, successful command returns exit code 1
-      # return nil if cmd.exit_status != 0, try to parse json
-      begin
-        groups = JSON.parse(cmd.stdout)
-      rescue JSON::ParserError => _e
-        return nil
-      end
-
-      # ensure we have an array of groups
-      groups = [groups] if !groups.is_a?(Array)
-
-      # reduce list
-      groups.each_with_object([]) do |grp, grp_collection|
-        # map object
-        grp_info = {
-          name: grp['Name'],
-          domain: grp['Domain'],
-          caption: grp['Caption'],
-          gid: nil,
-          sid: grp['SID'],
-          local: grp['LocalAccount'],
-        }
-        return grp_collection.push(grp_info) if grp_info[:name].casecmp(compare_group) == 0 && (compare_domain.nil? || grp_info[:domain].casecmp(compare_domain) == 0)
-      end
-    end
-  end
-end