inspec 0.9.5 → 0.9.6

data/lib/inspec/shell.rb

@@ -2,6 +2,8 @@
 # author: Dominik Richter
 # author: Christoph Hartmann
 
+require 'rspec/core/formatters/base_text_formatter'
+
 module Inspec
   class Shell
     def initialize(runner)
@@ -24,10 +26,14 @@ module Inspec
       that = self
 
       # Add the help command
-      Pry::Commands.block_command 'usage', 'Show examples' do
-        that.usage
+      Pry::Commands.block_command 'help', 'Show examples' do |resource|
+        that.help(resource)
       end
 
+      # configure pry shell prompt
+      Pry.config.prompt_name = 'inspec'
+      Pry.prompt = [proc { "\e[0;32m#{Pry.config.prompt_name}>\e[0m " }]
+
       # Add a help menu as the default intro
       Pry.hooks.add_hook(:before_session, :intro) do
         intro
@@ -38,23 +44,42 @@ module Inspec
       "\033[1m#{x}\033[0m"
     end
 
+    def print_example(example)
+      # determine min whitespace that can be removed
+      min = nil
+      example.lines.each do |line|
+        if line.strip.length > 0 # ignore empty lines
+          line_whitespace = line.length - line.lstrip.length
+          min = line_whitespace if min.nil? || line_whitespace < min
+        end
+      end
+      # remove whitespace from each line
+      example.gsub(/\n\s{#{min}}/, "\n")
+    end
+
     def intro
-      puts 'Welcome to the interactive Inspec Shell'
-      puts "To find out how to use it, type: #{mark 'usage'}"
+      puts 'Welcome to the interactive InSpec Shell'
+      puts "To find out how to use it, type: #{mark 'help'}"
       puts
     end
 
-    def usage
-      ctx = @runner.backend
-      puts <<EOF
+    def help(resource = nil)
+      if resource.nil?
+
+        ctx = @runner.backend
+        puts <<EOF
 
-Welcome to the interactive Inspec Shell.
+Available commands:
 
-You can use resources in this environment to test the target machine.
-For example:
+    `[resource]` - run resource on target machine
+    `help resources` - show all available resources that can be used as commands
+    `help [resource]` - information about a specific resource
+    `exit` - exit the InSpec shell
+
+You can use resources in this environment to test the target machine. For example:
 
     command('uname -a').stdout
-    file('/proc/cpuinfo').content
+    file('/proc/cpuinfo').content => "value",
 
 You are currently running on:
 
@@ -62,6 +87,43 @@ You are currently running on:
     OS release: #{mark ctx.os[:release] || 'unknown'}
 
 EOF
+      elsif resource == 'resources'
+        resources
+      else
+
+        if !Inspec::Resource.registry[resource].nil?
+          puts <<EOF
+#{mark 'Name:'} #{resource}
+
+#{mark 'Description:'}
+
+#{Inspec::Resource.registry[resource].desc}
+
+#{mark 'Example:'}
+#{print_example(Inspec::Resource.registry[resource].example)}
+
+#{mark 'Web Reference:'}
+
+https://github.com/chef/inspec/blob/master/docs/resources.rst##{resource}
+
+EOF
+        else
+          puts 'Only the following resources are available:'
+          resources
+        end
+      end
+    end
+
+    def resources
+      puts Inspec::Resource.registry.keys.join(' ')
+    end
+  end
+
+  class NoSummaryFormatter < RSpec::Core::Formatters::BaseTextFormatter
+    RSpec::Core::Formatters.register self, :dump_summary
+
+    def dump_summary(*_args)
+      # output nothing
     end
   end
 end

data/lib/inspec/version.rb

@@ -3,5 +3,5 @@
 # author: Christoph Hartmann
 
 module Inspec
-  VERSION = '0.9.5'
+  VERSION = '0.9.6'
 end

data/lib/matchers/matchers.rb

@@ -219,3 +219,46 @@ RSpec::Matchers.define :contain do |_rule|
     fail "[UNSUPPORTED] `contain` matcher. Please use the following syntax `its('content') { should match('value') }`."
   end
 end
+
+# This matcher implements a compare feature that cannot be covered by the default
+# `eq` matcher
+# You can use it in the following cases:
+# - compare strings case-insensitive
+# - you expect a number (strings will be converted if possible)
+#
+RSpec::Matchers.define :cmp do |expected|
+
+  def integer?(value)
+    return true if value =~ /\A\d+\Z/
+    false
+  end
+
+  def float?(value)
+    return true if Float(value)
+    false
+  rescue ArgumentError => _ex
+    false
+  end
+
+  match do |actual|
+    # if actual and expected are strings
+    if actual.is_a?(String) && expected.is_a?(String)
+      actual.casecmp(expected) == 0
+    elsif expected.is_a?(Integer) && integer?(actual)
+      expected == actual.to_i
+    elsif expected.is_a?(Float) && float?(actual)
+      expected == actual.to_f
+    # fallback to equal
+    else
+      actual == expected
+    end
+  end
+
+  failure_message do |actual|
+    "\nexpected: #{expected}\n     got: #{actual}\n\n(compared using `cmp` matcher)\n"
+  end
+
+  failure_message_when_negated do |actual|
+    "\nexpected: value != #{expected}\n     got: #{actual}\n\n(compared using `cmp` matcher)\n"
+  end
+end

data/lib/resources/apache_conf.rb

@@ -9,6 +9,12 @@ require 'utils/find_files'
 
 class ApacheConf < Inspec.resource(1)
   name 'apache_conf'
+  desc 'Use the apache_conf InSpec audit resource to test the configuration settings for Apache. This file is typically located under /etc/apache2 on the Debian and Ubuntu platforms and under /etc/httpd on the Fedora, CentOS, Red Hat Enterprise Linux, and Arch Linux platforms. The configuration settings may vary significantly from platform to platform.'
+  example "
+    describe apache_conf do
+      its('setting_name') { should eq 'value' }
+    end
+  "
 
   include FindFiles
 
@@ -88,19 +94,16 @@ class ApacheConf < Inspec.resource(1)
     include_files = params['Include'] || []
     include_files_optional = params['IncludeOptional'] || []
 
-    required = []
-    include_files.each do |f|
+    includes = []
+    (include_files + include_files_optional).each do |f|
       id = File.join(@conf_dir, f)
-      required.push(find_files(id, depth: 1, type: 'file'))
-    end
+      files = find_files(id, depth: 1, type: 'file')
 
-    optional = []
-    include_files_optional.each do |f|
-      id = File.join(@conf_dir, f)
-      optional.push(find_files(id, depth: 1, type: 'file'))
+      includes.push(files) if files
     end
 
-    required.flatten! + optional.flatten!
+    # [].flatten! == nil
+    includes.flatten! || []
   end
 
   def read_file(path)

data/lib/resources/apt.rb

@@ -30,6 +30,13 @@ require 'uri'
 
 class AptRepository < Inspec.resource(1)
   name 'apt'
+  desc 'Use the apt InSpec audit resource to verify Apt repositories on the Debian and Ubuntu platforms, and also PPA repositories on the Ubuntu platform.'
+  example "
+    describe apt('nginx/stable') do
+      it { should exist }
+      it { should be_enabled }
+    end
+  "
 
   def initialize(ppa_name)
     @deb_url = nil

data/lib/resources/audit_policy.rb

@@ -23,15 +23,15 @@
 # - "Failure"
 #
 # Further information is available at: https://msdn.microsoft.com/en-us/library/dd973859.aspx
-#
-# Usage:
-#
-# describe audit_policy do
-#   its('Other Account Logon Events') { should_not eq 'No Auditing' }
-# end
 
 class AuditPolicy < Inspec.resource(1)
   name 'audit_policy'
+  desc 'Use the audit_policy InSpec audit resource to test auditing policies on the Microsoft Windows platform. An auditing policy is a category of security-related events to be audited. Auditing is disabled by default and may be enabled for categories like account management, logon events, policy changes, process tracking, privilege use, system events, or object access. For each auditing category property that is enabled, the auditing level may be set to No Auditing, Not Specified, Success, Success and Failure, or Failure.'
+  example "
+    describe audit_policy do
+      its('parameter') { should eq 'value' }
+    end
+  "
 
   def method_missing(method)
     key = method.to_s

data/lib/resources/auditd_conf.rb

@@ -6,15 +6,14 @@
 
 require 'utils/simpleconfig'
 
-# Usage:
-# describe audit_daemon_conf do
-#   its("space_left_action") { should eq "email" }
-#   its("action_mail_acct") { should eq "root" }
-#   its("admin_space_left_action") { should eq "halt" }
-# end
-
 class AuditDaemonConf < Inspec.resource(1)
   name 'auditd_conf'
+  desc "Use the auditd_conf InSpec audit resource to test the configuration settings for the audit daemon. This file is typically located under /etc/audit/auditd.conf' on UNIX and Linux platforms."
+  example "
+    describe auditd_conf do
+      its('space_left_action') { should eq 'email' }
+    end
+  "
 
   def initialize(path = nil)
     @conf_path = path || '/etc/audit/auditd.conf'

data/lib/resources/auditd_rules.rb

@@ -4,16 +4,17 @@
 # author: Dominik Richter
 # license: All rights reserved
 
-# Usage:
-# describe audit_daemon_rules do
-#   its("LIST_RULES") {should contain_match(/^exit,always arch=.* key=time-change syscall=adjtimex,settimeofday/) }
-#   its("LIST_RULES") {should contain_match(/^exit,always arch=.* key=time-change syscall=stime,settimeofday,adjtimex/) }
-#   its("LIST_RULES") {should contain_match(/^exit,always arch=.* key=time-change syscall=clock_settime/)}
-#   its("LIST_RULES") {should contain_match(/^exit,always watch=\/etc\/localtime perm=wa key=time-change/)}
-# end
-
 class AuditDaemonRules < Inspec.resource(1)
   name 'auditd_rules'
+  desc 'Use the auditd_rules InSpec audit resource to test the rules for logging that exist on the system. The audit.rules file is typically located under /etc/audit/ and contains the list of rules that define what is captured in log files.'
+  example "
+    describe auditd_rules do
+      its('LIST_RULES') {should contain_match(/^exit,always arch=.* key=time-change syscall=adjtimex,settimeofday/) }
+      its('LIST_RULES') {should contain_match(/^exit,always arch=.* key=time-change syscall=stime,settimeofday,adjtimex/) }
+      its('LIST_RULES') {should contain_match(/^exit,always arch=.* key=time-change syscall=clock_settime/)}
+      its('LIST_RULES') {should contain_match(/^exit,always watch=\/etc\/localtime perm=wa key=time-change/)}
+    end
+  "
 
   def initialize
     @content = inspec.command('/sbin/auditctl -l').stdout.chomp

data/lib/resources/bond.rb

@@ -4,15 +4,15 @@
 
 require 'resources/file'
 
-# Usage:
-# describe bond('bond0') do
-#   it { should exist }
-#   it { should have_interface 'eth0' }
-# end
-
 module Inspec::Resources
   class Bond < File
     name 'bond'
+    desc 'Use the bond InSpec audit resource to test a logical, bonded network interface (i.e. "two or more network interfaces aggregated into a single, logical network interface"). On Linux platforms, any value in the /proc/net/bonding directory may be tested.'
+    example "
+      describe bond('bond0') do
+        it { should exist }
+      end
+    "
 
     def initialize(bond)
       @bond = bond

data/lib/resources/bridge.rb

@@ -10,6 +10,13 @@
 
 class Bridge < Inspec.resource(1)
   name 'bridge'
+  desc 'Use the bridge InSpec audit resource to test basic network bridge properties, such as name, if an interface is defined, and the associations for any defined interface.'
+  example "
+    describe bridge 'br0' do
+      it { should exist }
+      it { should have_interface 'eth0' }
+    end
+  "
 
   def initialize(bridge_name)
     @bridge_name = bridge_name

data/lib/resources/command.rb

@@ -4,16 +4,18 @@
 # author: Christoph Hartmann
 # license: All rights reserved
 
-# Usage:
-# describe command('ls -al /') do
-#   it { should exist }
-#   its(:stdout) { should match /bin/ }
-#   its(:stderr) { should match /No such file or directory/ }
-#   its(:exit_status) { should eq 0 }
-# end
-
 class Cmd < Inspec.resource(1)
   name 'command'
+  desc '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
+  "
+
   attr_reader :command
 
   def initialize(cmd)

data/lib/resources/csv.rb

@@ -3,15 +3,16 @@
 # author: Dominik Richter
 
 # Parses a csv document
-# Usage:
-# describe csv('example.csv') do
-#   its('name') { should eq(['John', 'Alice']) }
-# end
-#
 # This implementation was inspired by a blog post
 # @see http://technicalpickles.com/posts/parsing-csv-with-ruby
 class CsvConfig < JsonConfig
   name 'csv'
+  desc 'Use the csv InSpec audit resource to test configuration data in a CSV file.'
+  example "
+    describe csv('example.csv') do
+      its('name') { should eq(['John', 'Alice']) }
+    end
+  "
 
   # override file load and parse hash from csv
   def parse(content)

data/lib/resources/directory.rb

@@ -7,6 +7,12 @@ require 'resources/file'
 module Inspec::Resources
   class Directory < File
     name 'directory'
+    desc 'Use the directory InSpec audit resource to test if the file type is a directory. This is equivalent to using the file InSpec audit resource and the be_directory matcher, but provides a simpler and more direct way to test directories. All of the matchers available to file may be used with directory.'
+    example "
+      describe directory('path') do
+        it { should be_directory }
+      end
+    "
   end
 
   def to_s

data/lib/resources/etc_group.rb

@@ -29,6 +29,14 @@ class EtcGroup < Inspec.resource(1)
   include ContentParser
 
   name 'etc_group'
+  desc 'Use the etc_group InSpec audit resource to test groups that are defined on Linux and UNIX platforms. The /etc/group file stores details about each group---group name, password, group identifier, along with a comma-separate list of users that belong to the group.'
+  example "
+    describe etc_group do
+      its('gids') { should_not contain_duplicates }
+      its('groups') { should include 'my_user' }
+      its('users') { should include 'my_user' }
+    end
+  "
 
   attr_accessor :gid, :entries
   def initialize(path = nil)
@@ -37,7 +45,7 @@ class EtcGroup < Inspec.resource(1)
 
     # skip resource if it is not supported on current OS
     return skip_resource 'The `etc_group` resource is not supported on your OS.' \
-    unless %w{ubuntu debian redhat fedora arch darwin freebsd}.include?(inspec.os[:family])
+    unless %w{ubuntu debian redhat fedora centos arch darwin freebsd wrlinux}.include?(inspec.os[:family])
   end
 
   def groups(filter = nil)

data/lib/resources/file.rb

@@ -7,8 +7,19 @@
 module Inspec::Resources
   class File < Inspec.resource(1)
     name 'file'
+    desc 'Use the file InSpec audit resource to test all system file types, including files, directories, symbolic links, named pipes, sockets, character devices, block devices, and doors.'
+    example "
+      describe file('path') do
+        it { should exist }
+        it { should be_file }
+        it { should be_readable }
+        it { should be_writable }
+        it { should be_owned_by 'root' }
+        its('mode') { should eq 0644 }
+      end
+    "
 
-    attr_reader :path
+    attr_reader :file, :path
     def initialize(path)
       @path = path
       @file = inspec.backend.file(@path)
@@ -21,7 +32,7 @@ module Inspec::Resources
       product_version file_version version? md5sum sha256sum
     }.each do |m|
       define_method m.to_sym do |*args|
-        @file.method(m.to_sym).call(*args)
+        file.method(m.to_sym).call(*args)
       end
     end
 
@@ -29,82 +40,82 @@ module Inspec::Resources
       fail 'Contain is not supported. Please use standard RSpec matchers.'
     end
 
-    def readable?(by_owner, by_user)
-      if inspec.os.unix?
-        by_owner, by_user = check_preconditions(by_owner, by_user)
-
-        if by_user.nil?
-          m = @file.unix_mode_mask(by_owner, 'r') ||
-              fail("#{by_owner} is not a valid unix owner.")
-          (@file.mode & m) != 0
-        else
-          check_user_access(by_user, @path, 'r')
-        end
-      else
-        fail "`file(#{@path}).executable?` is not suported on you OS: #{inspec.os['family']}"
-      end
+    def readable?(by_usergroup, by_specific_user)
+      return false unless exist?
+
+      file_permission_granted?('r', by_usergroup, by_specific_user)
     end
 
-    def writable?(by_owner, by_user)
-      if inspec.os.unix?
-        by_owner, by_user = check_preconditions(by_owner, by_user)
-
-        if by_user.nil?
-          m = @file.unix_mode_mask(by_owner, 'w') ||
-              fail("#{by_owner} is not a valid unix owner.")
-          (@file.mode & m) != 0
-        else
-          check_user_access(by_user, @path, 'w')
-        end
-      else
-        fail "`file(#{@path}).executable?` is not suported on you OS: #{inspec.os['family']}"
-      end
+    def writable?(by_usergroup, by_specific_user)
+      return false unless exist?
+
+      file_permission_granted?('w', by_usergroup, by_specific_user)
     end
 
-    def executable?(by_owner, by_user)
-      if inspec.os.unix?
-        by_owner, by_user = check_preconditions(by_owner, by_user)
-
-        if by_user.nil?
-          m = @file.unix_mode_mask(by_owner, 'x') ||
-              fail("#{by_owner} is not a valid unix owner.")
-          return (@file.mode & m) != 0
-        else
-          return check_user_access(by_user, @path, 'x')
-        end
-      else
-        fail "`file(#{@path}).executable?` is not suported on you OS: #{inspec.os['family']}"
-      end
+    def executable?(by_usergroup, by_specific_user)
+      return false unless exist?
+
+      file_permission_granted?('x', by_usergroup, by_specific_user)
     end
 
     def to_s
-      "File #{@path}"
+      "File #{path}"
     end
 
     private
 
-    def check_preconditions(by_owner, by_user)
-      by_owner = 'other' if by_owner == 'others'
-      by_owner = 'all' if (by_owner.nil? || by_owner.empty?) && (by_user.nil?)
-      [by_owner, by_user]
-    end
+    def file_permission_granted?(flag, by_usergroup, by_specific_user)
+      fail 'Checking file permissions is not supported on your os' unless unix?
 
-    # check permissions on linux
-    def check_user_access(user, file, flag)
-      if inspec.os.linux? == true
-        # use sh on linux
-        perm_cmd = "su -s /bin/sh -c \"test -#{flag} #{file}\" #{user}"
-      elsif inspec.os[:family] == 'freebsd'
-        # use sudo on freebsd
-        perm_cmd = "sudo -u #{user} test -#{flag} #{file}"
+      usergroup = usergroup_for(by_usergroup, by_specific_user)
+
+      if by_specific_user.nil?
+        check_file_permission_by_mask(usergroup, flag)
+      else
+        check_file_permission_by_user(by_specific_user, flag)
       end
+    end
 
-      if !perm_cmd.nil?
-        cmd = inspec.command(perm_cmd)
-        cmd.exit_status == 0 ? true : false
+    def check_file_permission_by_mask(usergroup, flag)
+      mask = file.unix_mode_mask(usergroup, flag)
+      fail 'Invalid usergroup/owner provided' if mask.nil?
+
+      (file.mode & mask) != 0
+    end
+
+    def check_file_permission_by_user(user, flag)
+      if linux?
+        perm_cmd = "su -s /bin/sh -c \"test -#{flag} #{path}\" #{user}"
+      elsif family == 'freebsd'
+        perm_cmd = "sudo -u #{user} test -#{flag} #{path}"
       else
         return skip_resource 'The `file` resource does not support `by_user` on your OS.'
       end
+
+      cmd = inspec.command(perm_cmd)
+      cmd.exit_status == 0 ? true : false
+    end
+
+    def usergroup_for(usergroup, specific_user)
+      if usergroup == 'others'
+        'other'
+      elsif (usergroup.nil? || usergroup.empty?) && specific_user.nil?
+        'all'
+      else
+        usergroup
+      end
+    end
+
+    def unix?
+      inspec.os.unix?
+    end
+
+    def linux?
+      inspec.os.linux?
+    end
+
+    def family
+      inspec.os[:family]
     end
   end
 end