inspec 0.9.5 → 0.9.6

data/lib/resources/gem.rb

@@ -2,12 +2,14 @@
 # author: Christoph Hartmann
 # author: Dominik Richter
 
-# Usage:
-# describe gem('rubocop') do
-#   it { should be_installed }
-# end
 class GemPackage < Inspec.resource(1)
   name 'gem'
+  desc 'Use the gem InSpec audit resource to test if a global gem package is installed.'
+  example "
+    describe gem('rubocop') do
+      it { should be_installed }
+    end
+  "
 
   def initialize(package_name)
     @package_name = package_name

data/lib/resources/group.rb

@@ -15,6 +15,13 @@
 
 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

data/lib/resources/host.rb

@@ -26,6 +26,12 @@
 
 class Host < Inspec.resource(1)
   name 'host'
+  desc 'Use the host InSpec audit resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.'
+  example "
+    describe host('example.com') do
+      it { should be_reachable }
+    end
+  "
 
   def initialize(hostname, params = {})
     @hostname = hostname

data/lib/resources/inetd_conf.rb

@@ -6,16 +6,16 @@
 
 require 'utils/simpleconfig'
 
-# Usage:
-#
-# describe inetd_conf do
-#   its('shell') { should eq nil }
-#   its('login') { should eq nil }
-#   its('exec') { should eq nil }
-# end
-
 class InetdConf < Inspec.resource(1)
   name 'inetd_conf'
+  desc 'Use the inetd_conf InSpec audit resource to test if a service is enabled in the inetd.conf file on Linux and UNIX platforms. inetd---the Internet service daemon---listens on dedicated ports, and then loads the appropriate program based on a request. The inetd.conf file is typically located at /etc/inetd.conf and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.'
+  example "
+    describe inetd_conf do
+      its('shell') { should eq nil }
+      its('login') { should eq nil }
+      its('exec') { should eq nil }
+    end
+  "
 
   def initialize(path = nil)
     @conf_path = path || '/etc/inetd.conf'

data/lib/resources/ini.rb

@@ -4,14 +4,14 @@
 
 require 'utils/simpleconfig'
 
-# Parses a ini file
-# Usage:
-# descibe ini do
-#   its("auth_protocol") { should eq "https" }
-# end
 class IniConfig < JsonConfig
   name 'ini'
-
+  desc 'Use the ini InSpec audit resource to test data in a INI file.'
+  example "
+    descibe ini do
+      its('auth_protocol') { should eq 'https' }
+    end
+  "
   # override file load and parse hash with simple config
   def parse(content)
     SimpleConfig.new(content).params

data/lib/resources/interface.rb

@@ -2,18 +2,18 @@
 # author: Christoph Hartmann
 # author: Dominik Richter
 
-# Usage:
-# describe interface('eth0') do
-#   it { should exist }
-#   it { should be_up }
-#   its(:speed) { should eq 1000 }
-# end
-
 require 'utils/convert'
 
 class NetworkInterface < Inspec.resource(1)
   name 'interface'
-
+  desc 'Use the interface InSpec audit resource to test basic network adapter properties, such as name, status, state, address, and link speed (in MB/sec).'
+  example "
+    describe interface('eth0') do
+      it { should exist }
+      it { should be_up }
+      its(:speed) { should eq 1000 }
+    end
+  "
   def initialize(iface)
     @iface = iface
 

data/lib/resources/iptables.rb

@@ -23,6 +23,12 @@
 # @see https://www.frozentux.net/iptables-tutorial/iptables-tutorial.html
 class IpTables < Inspec.resource(1)
   name 'iptables'
+  desc 'Use the iptables InSpec audit resource to test rules that are defined in iptables, which maintains tables of IP packet filtering rules. There may be more than one table. Each table contains one (or more) chains (both built-in and custom). A chain is a list of rules that match packets. When the rule matches, the rule defines what target to assign to the packet.'
+  example "
+    describe iptables do
+      it { should have_rule('-P INPUT ACCEPT') }
+    end
+  "
 
   def initialize(params = {})
     @table = params[:table] || nil

data/lib/resources/json.rb

@@ -2,13 +2,14 @@
 # author: Christoph Hartmann
 # author: Dominik Richter
 
-# Parses a json document
-# Usage:
-# describe json('policyfile.lock.json') do
-#   its('cookbook_locks.omnibus.version') { should eq('2.2.0') }
-# end
 class JsonConfig < Inspec.resource(1)
   name 'json'
+  desc 'Use the json InSpec audit resource to test data in a JSON file.'
+  example "
+    describe json('policyfile.lock.json') do
+      its('cookbook_locks.omnibus.version') { should eq('2.2.0') }
+    end
+  "
 
   # make params readable
   attr_reader :params

data/lib/resources/kernel_module.rb

@@ -3,13 +3,14 @@
 # author: Dominik Richter
 # license: All rights reserved
 
-# Verifies if a kernel module is loaded
-# Usage:
-# describe kernel_module('bridge') do
-#   it { should be_loaded }
-# end
 class KernelModule < Inspec.resource(1)
   name 'kernel_module'
+  desc 'Use the kernel_module InSpec audit resource to test kernel modules on Linux platforms. These parameters are located under /lib/modules. Any submodule may be tested using this resource.'
+  example "
+    describe kernel_module('bridge') do
+      it { should be_loaded }
+    end
+  "
 
   def initialize(modulename = nil)
     @module = modulename

data/lib/resources/kernel_parameter.rb

@@ -2,12 +2,14 @@
 # author: Christoph Hartmann
 # license: All rights reserved
 
-# Verifies if a kernel parameter is set
-# describe kernel_parameter('net.ipv4.conf.all.forwarding') do
-#   its(:value) { should eq 0 }
-# end
 class KernelParameter < Inspec.resource(1)
   name 'kernel_parameter'
+  desc 'Use the kernel_parameter InSpec audit resource to test kernel parameters on Linux platforms.'
+  example "
+    describe kernel_parameter('net.ipv4.conf.all.forwarding') do
+      its(:value) { should eq 0 }
+    end
+  "
 
   def initialize(parameter = nil)
     @parameter = parameter

data/lib/resources/limits_conf.rb

@@ -6,14 +6,14 @@
 
 require 'utils/simpleconfig'
 
-# Usage:
-#
-# describe limits_conf do
-#   its('*') { should include ['hard','core','0'] }
-# end
-
 class LimitsConf < Inspec.resource(1)
   name 'limits_conf'
+  desc 'Use the limits_conf InSpec audit resource to test configuration settings in the /etc/security/limits.conf file. The limits.conf defines limits for processes (by user and/or group names) and helps ensure that the system on which those processes are running remains stable. Each process may be assigned a hard or soft limit.'
+  example "
+    describe limits_conf do
+      its('*') { should include ['hard','core','0'] }
+    end
+  "
 
   def initialize(path = nil)
     @conf_path = path || '/etc/security/limits.conf'

data/lib/resources/login_def.rb

@@ -20,6 +20,12 @@ require 'utils/simpleconfig'
 
 class LoginDef < Inspec.resource(1)
   name 'login_defs'
+  desc 'Use the login_defs InSpec audit resource to test configuration settings in the /etc/login.defs file. The logins.defs file defines site-specific configuration for the shadow password suite on Linux and UNIX platforms, such as password expiration ranges, minimum/maximum values for automatic selection of user and group identifiers, or the method with which passwords are encrypted.'
+  example "
+    describe login_defs do
+      its('ENCRYPT_METHOD') { should eq 'SHA512' }
+    end
+  "
 
   def initialize(path = nil)
     @conf_path = path || '/etc/login.defs'

data/lib/resources/mysql_conf.rb

@@ -28,6 +28,12 @@ end
 
 class MysqlConf < Inspec.resource(1)
   name 'mysql_conf'
+  desc 'Use the mysql_conf InSpec audit resource to test the contents of the configuration file for MySQL, typically located at /etc/mysql/my.cnf or /etc/my.cnf.'
+  example "
+    describe mysql_conf('path') do
+      its('setting') { should eq 'value' }
+    end
+  "
 
   include FindFiles
 

data/lib/resources/mysql_session.rb

@@ -6,6 +6,13 @@
 
 class MysqlSession < Inspec.resource(1)
   name 'mysql_session'
+  desc 'Use the mysql_session InSpec audit resource to test SQL commands run against a MySQL database.'
+  example "
+    sql = mysql_session('my_user','password')
+    describe sql.query('show databases like \'test\';') do
+      its(:stdout) { should_not match(/test/) }
+    end
+  "
 
   def initialize(user = nil, pass = nil)
     @user = user

data/lib/resources/npm.rb

@@ -2,12 +2,14 @@
 # author: Christoph Hartmann
 # author: Dominik Richter
 
-# Usage:
-# describe npm('bower') do
-#   it { should be_installed }
-# end
 class NpmPackage < Inspec.resource(1)
   name 'npm'
+  desc 'Use the npm InSpec audit resource to test if a global npm package is installed. npm is the the package manager for Nodejs packages, such as bower and StatsD.'
+  example "
+    describe npm('bower') do
+      it { should be_installed }
+    end
+  "
 
   def initialize(package_name)
     @package_name = package_name

data/lib/resources/ntp_conf.rb

@@ -6,15 +6,15 @@
 
 require 'utils/simpleconfig'
 
-# Usage:
-#
-# describe ntp_conf do
-#   its('server') { should_not eq nil }
-#   its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
-# end
-
 class NtpConf < Inspec.resource(1)
   name 'ntp_conf'
+  desc 'Use the ntp_conf InSpec audit resource to test the synchronization settings defined in the ntp.conf file. This file is typically located at /etc/ntp.conf.'
+  example "
+    describe ntp_conf do
+      its('server') { should_not eq nil }
+      its('restrict') { should include '-4 default kod notrap nomodify nopeer noquery'}
+    end
+  "
 
   def initialize(path = nil)
     @conf_path = path || '/etc/ntp.conf'

data/lib/resources/oneget.rb

@@ -11,6 +11,12 @@
 # end
 class OneGetPackage < Inspec.resource(1)
   name 'oneget'
+  desc 'Use the oneget InSpec audit resource to test if the named package and/or package version is installed on the system. This resource uses OneGet, which is part of the Windows Management Framework 5.0 and Windows 10. This resource uses the Get-Package cmdlet to return all of the package names in the OneGet repository.'
+  example "
+    describe oneget('zoomit') do
+      it { should be_installed }
+    end
+  "
 
   def initialize(package_name)
     @package_name = package_name

data/lib/resources/os.rb

@@ -4,6 +4,12 @@
 
 class OS < Inspec.resource(1)
   name 'os'
+  desc 'Use the os InSpec audit resource to test the platform on which the system is running.'
+  example "
+    describe os[:family] do
+      it { should eq 'redhat' }
+    end
+  "
 
   # reuse helper methods from backend
   %w{redhat? debian? suse? bsd? solaris? linux? unix? windows?}.each do |os_family|
@@ -13,6 +19,8 @@ class OS < Inspec.resource(1)
   end
 
   def [](name)
+    # convert string to symbol
+    name = name.to_sym if name.is_a? String
     inspec.backend.os[name]
   end
 

data/lib/resources/os_env.rb

@@ -15,6 +15,12 @@ require 'utils/simpleconfig'
 
 class OsEnv < Inspec.resource(1)
   name 'os_env'
+  desc 'Use the os_env InSpec audit resource to test the environment variables for the platform on which the system is running.'
+  example "
+    describe os_env('VARIABLE') do
+      its('matcher') { should eq 1 }
+    end
+  "
 
   attr_reader :content
   def initialize(env = nil)

data/lib/resources/package.rb

@@ -10,6 +10,13 @@
 # end
 class Package < Inspec.resource(1)
   name 'package'
+  desc 'Use the package InSpec audit resource to test if the named package and/or package version is installed on the system.'
+  example "
+    describe package('nginx') do
+      it { should be_installed }
+      its('version') { should eq 1.9.5 }
+    end
+  "
 
   def initialize(package_name = nil)
     @package_name = package_name
@@ -21,7 +28,7 @@ class Package < Inspec.resource(1)
     case inspec.os[:family]
     when 'ubuntu', 'debian'
       @pkgman = Deb.new(inspec)
-    when 'redhat', 'fedora', 'centos', 'opensuse'
+    when 'redhat', 'fedora', 'centos', 'opensuse', 'wrlinux'
       @pkgman = Rpm.new(inspec)
     when 'arch'
       @pkgman = Pacman.new(inspec)

data/lib/resources/parse_config.rb

@@ -15,6 +15,14 @@
 
 class PConfig < Inspec.resource(1)
   name 'parse_config'
+  desc 'Use the parse_config InSpec audit resource to test arbitrary configuration files.'
+  example "
+    output = command('some-command').stdout
+
+    describe parse_config(output, { data_config_option: value } ) do
+      its('setting') { should eq 1 }
+    end
+  "
 
   def initialize(content = nil, useropts = nil)
     @opts = {}
@@ -63,6 +71,12 @@ end
 
 class PConfigFile < PConfig
   name 'parse_config_file'
+  desc 'Use the parse_config_file InSpec audit resource to test arbitrary configuration files. It works identiacal to parse_config. Instead of using a command output, this resource works with files.'
+  example "
+    describe parse_config_file('/path/to/file') do
+      its('setting') { should eq 1 }
+    end
+  "
 
   def initialize(path, opts = nil)
     super(nil, opts)

data/lib/resources/passwd.rb

@@ -29,6 +29,13 @@ require 'utils/parser'
 
 class Passwd < Inspec.resource(1)
   name 'passwd'
+  desc 'Use the passwd InSpec audit resource to test the contents of /etc/passwd, which contains the following information for users that may log into the system and/or as users that own running processes.'
+  example "
+    describe passwd.uid(0) do
+      its('username') { should eq 'root' }
+      its('count') { should eq 1 }
+    end
+  "
 
   include ContentParser
 

data/lib/resources/pip.rb

@@ -9,6 +9,12 @@
 #
 class PipPackage < Inspec.resource(1)
   name 'pip'
+  desc 'Use the pip InSpec audit resource to test packages that are installed using the pip installer.'
+  example "
+    describe pip('Jinja2') do
+      it { should be_installed }
+    end
+  "
 
   def initialize(package_name)
     @package_name = package_name

data/lib/resources/port.rb

@@ -17,14 +17,22 @@
 # TODO: improve handling of same port on multiple interfaces
 class Port < Inspec.resource(1)
   name 'port'
+  desc "Use the port InSpec audit resource to test basic port properties, such as port, process, if it's listening."
+  example "
+    describe port(80) do
+      it { should be_listening }
+      its('protocols') {should eq ['tcp']}
+    end
+  "
 
-  def initialize(port)
+  def initialize(ip = nil, port) # rubocop:disable OptionalArguments
+    @ip = ip
     @port = port
     @port_manager = nil
     @cache = nil
 
     case inspec.os[:family]
-    when 'ubuntu', 'debian', 'redhat', 'fedora', 'centos', 'arch'
+    when 'ubuntu', 'debian', 'redhat', 'fedora', 'centos', 'arch', 'wrlinux'
       @port_manager = LinuxPorts.new(inspec)
     when 'darwin'
       @port_manager = DarwinPorts.new(inspec)
@@ -41,17 +49,17 @@ class Port < Inspec.resource(1)
     info.size > 0
   end
 
-  def protocol
+  def protocols
     res = info.map { |x| x[:protocol] }.uniq.compact
     res.size > 0 ? res : nil
   end
 
-  def process
+  def processes
     res = info.map { |x| x[:process] }.uniq.compact
     res.size > 0 ? res : nil
   end
 
-  def pid
+  def pids
     res = info.map { |x| x[:pid] }.uniq.compact
     res.size > 0 ? res : nil
   end
@@ -68,18 +76,21 @@ class Port < Inspec.resource(1)
     return @cache = [] if @port_manager.nil?
     # query ports
     ports = @port_manager.info || []
-    @cache = ports.select { |p| p[:port] == @port }
+    @cache = ports.select { |p| p[:port] == @port && (!@ip || p[:address] == @ip) }
   end
 end
 
 # implements an info method and returns all ip adresses and protocols for
 # each port
 # [{
-#   port: 80,
-#   address: [{
-#     ip: '0.0.0.0'
-#     protocol: 'tcp'
-#   }],
+#   port: 22,
+#   address: '0.0.0.0'
+#   protocol: 'tcp'
+# },
+# {
+#   port: 22,
+#   address: '::'
+#   protocol: 'tcp6'
 # }]
 class PortsInfo
   attr_reader :inspec