inspec 1.0.0.beta2 → 1.0.0.beta3

data/docs/resources/xinetd_conf.md.erb

@@ -0,0 +1,170 @@
+---
+title: About the xinetd_conf Resource
+---
+
+# xinetd_conf
+
+Use the `xinetd_conf` InSpec audit resource to test services under `/etc/xinet.d` on Linux and Unix platforms. xinetd---the extended Internet service daemon---listens on all ports, and then loads the appropriate program based on a request. The `xinetd.conf` file is typically located at `/etc/xinetd.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.
+
+# Syntax
+
+An `xinetd_conf` resource block declares settings found in a `xinetd.conf` file for the named service:
+
+    describe xinetd_conf('service_name') do
+      it { should be_enabled } # or be_disabled
+      its('setting') { should eq 'value' }
+    end
+
+where
+
+* `'service_name'` is a service located under `/etc/xinet.d`
+* `('setting')` is a setting in the `xinetd.conf` file
+* `should eq 'value'` is the value that is expected
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabed
+
+The `be_enabled` matcher tests if a service listed under `/etc/xinet.d` is enabled:
+
+    it { should be_enabled }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## ids
+
+The `ids` matcher tests if the named service is located under `/etc/xinet.d`:
+
+    its('ids') { should include 'service_name' }
+
+For example:
+
+    its('ids') { should include 'chargen-stream chargen-dgram'}
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## services
+
+The `services` matcher tests if the named service is listed under `/etc/xinet.d`:
+
+    its('services') { should include 'service_name' }
+
+## socket_types
+
+The `socket_types` matcher tests if a service listed under `/etc/xinet.d` is configured to use the named socket type:
+
+    its('socket_types') { should eq 'socket' }
+
+where `socket` is one of `dgram`, `raw`, or `stream`. For a UDP-based service:
+
+    its('socket_types') { should eq 'dgram' }
+
+For a raw socket (such as a service using a non-standard protocol or a service that requires direct access to IP):
+
+    its('socket_types') { should eq 'raw' }
+
+For a TCP-based service:
+
+    its('socket_types') { should eq 'stream' }
+
+## types
+
+The `types` matcher tests the service type:
+
+    its('type') { should eq 'TYPE' }
+
+where `'TYPE'` is `INTERNAL` (for a service provided by xinetd), `RPC` (for a service based on remote procedure call), or `UNLISTED` (for services not under `/etc/services` or `/etc/rpc`).
+
+## wait
+
+The `wait` matcher tests how a service handles incoming connections.
+
+For UDP (`dgram`) socket types the `wait` matcher should test for `yes`:
+
+    its('socket_types') { should eq 'dgram' }
+    its('wait') { should eq 'yes' }
+
+For TCP (`stream`) socket types the `wait` matcher should test for `no`:
+
+    its('socket_types') { should eq 'stream' }
+    its('wait') { should eq 'no' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a socket_type
+
+The network socket type: `dgram` (a datagram-based service), `raw` (a service that requires direct access to an IP address), `stream` (a stream-based service), or `seqpacket` (a service that requires a sequenced packet).
+
+    describe xinetd_conf.services('service_name') do
+       its('socket_types') { should include 'dgram' }
+    end
+
+## Test a service type
+
+The type of service: `INTERNAL` (a service provided by xinetd), `RPC` (an RPC-based service), `TCPMUX` (a service that is started on a well-known TPCMUX port), or `UNLISTED` (a service that is not listed in a standard system file location).
+
+    describe xinetd_conf.services('service_name') do
+       its('type') { should include 'RPC' }
+    end
+
+## Test the telnet service
+
+For example, a `telnet` file under `/etc/xinet.d` contains the following settings:
+
+    service telnet
+    {
+      disable         = yes
+      flags           = REUSE
+      socket_type     = stream
+      wait            = no
+      user            = root
+      server          = /usr/sbin/in.telnetd
+      log_on_failure  += USERID
+    }
+
+Some examples of tests that can be run against that file include:
+
+    describe xinetd_conf.services('telnet') do
+      it { should be_disabled }
+    end
+
+and
+
+    describe xinetd_conf.services('telnet') do
+      its('socket_type') { should include 'stream' }
+    end
+
+and
+
+    describe xinetd_conf.services('telnet') do
+      its('wait') { should eq 'no' }
+    end
+
+All three settings can be tested in the same block as well:
+
+    describe xinetd_conf.services('telnet') do
+      it { should be_disabled }
+      its('socket_type') { should include 'stream' }
+      its('wait') { should eq 'no' }
+    end

data/docs/resources/yaml.md.erb

@@ -0,0 +1,69 @@
+---
+title: About the yaml Resource
+---
+
+# yaml
+
+Use the `yaml` InSpec audit resource to test configuration data in a Yaml file.
+
+# Syntax
+
+A `yaml` resource block declares the configuration data to be tested. Assume the following Yaml file:
+
+    name: foo
+    array:
+      - zero
+      - one
+
+This file can be queried using:
+
+    describe yaml do
+      its('name') { should eq 'foo' }
+      its(['array', 1]) { should eq 'one' }
+    end
+
+where
+
+* `name` is a configuration setting in a Yaml file
+* `should eq 'foo'` tests a value of `name` as read from a Yaml file versus the value declared in the test
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## name
+
+The `name` matcher tests the value of `name` as read from a Yaml file versus the value declared in the test:
+
+    its('name') { should eq 'foo' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a kitchen.yml file driver
+
+    describe yaml('.kitchen.yaml') do
+      its('driver.name') { should eq('vagrant') }
+    end

data/docs/resources/yum.md.erb

@@ -0,0 +1,103 @@
+---
+title: About the yum Resource
+---
+
+# yum
+
+Use the `yum` InSpec audit resource to test packages in the Yum repository.
+
+# Syntax
+
+A `yum` resource block declares a package repo, tests if the package repository is present, and if it that package repository is a valid package source (i.e. "is enabled"):
+
+    describe yum.repo('name') do
+      it { should exist }
+      it { should be_enabled }
+    end
+
+where
+
+* `repo('name')` is the (optional) name of a package repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`)
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if the package repository is a valid package source:
+
+    it { should be_enabled }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## exist
+
+The `exist` matcher tests if the package repository exists:
+
+    it { should exist }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## repo('name')
+
+The `repo('name')` matcher names a specific package repository:
+
+    describe yum.repo('epel') do
+      ...
+    end
+
+## repos
+
+The `repos` matcher tests if a named repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`), is included in the Yum repo:
+
+    its('repos') { should include 'some_repo' }
+
+## shortname
+
+The `shortname` matcher names a specific package repository's group identifier. For example, if a repository's group name is "Directory Server", the corresponding group idenfier is typically "directory-server":
+
+    describe yum.repo('Directory Server') do
+      its('shortname') { should eq 'directory-server' }
+    end
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if the yum repo exists
+
+    describe yum do
+      its('repos') { should exist }
+    end
+
+## Test if the 'base/7/x86_64' repo exists and is enabled
+
+    describe yum do
+      its('repos') { should include 'base/7/x86_64' }
+      its('epel') { should exist }
+      its('epel') { should be_enabled }
+    end
+
+## Test if a specific yum repo exists
+
+    describe yum.repo('epel') do
+      it { should exist }
+      it { should be_enabled }
+    end

data/docs/ruby_usage.md

@@ -0,0 +1,154 @@
+# 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:
+
+```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:
+
+```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. If you create a custom
+resource please vendor gems into the library. This ensures that all resources
+are self-contained and complete and don't need any resolution at runtime. We
+vendor resources and requirements through dependency resolution, which is
+independent of programming languages and their resolver mechanisms.
+
+## 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.
+
+```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:
+
+```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:
+
+```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
+```