serverspec_launcher 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16a247e91baf7609fbc1be30e5bb8b7e9766cbe8769a09143e8f9c8ae719b721
-  data.tar.gz: 1fdd7124db2fc0615fef1355ff4620d0034886bcca7208f3d411be02a07062de
+  metadata.gz: 51df9c0b623e4364ddc2e8230a7c320bbfaf84b8a57a407516a76165ca21ef21
+  data.tar.gz: cac54f2f95343d60e248834d2706cfd3ec0741d24a4d6aad6221c4c70c1d8f3e
 SHA512:
-  metadata.gz: 42e5a8bb6d40db792894dbf5caf88198b5fb97abaa5abbddee1a06e07010015975fe24713e6a92596d0f3f87463da8b320eb7c1d151aa11c02d0e16bb20f3c38
-  data.tar.gz: bc2e640d08d634bac3004736f5a5a8086524fab721727083bfa4d94e42c54a05b1b7cdf6e73d607a5d48f1d41b73ef77ad932f7f7ed0d8ab2138c6e60137703e
+  metadata.gz: fe95afd76a4b1004eb62ac4434326e5d3c49b0d8500dbc21ebc08c0714e23d60cd99719615979e87ae1c264beeb90d19d10f973c203121c393c92d277b30bc1d
+  data.tar.gz: e5e50f3cd690942325ce579a0953104289522ab488315c8de61a4dc4402750cb2f0fda9d6c00f0824e9d6fb95d61c7aef4cd00f87f8142a8674dda7ac7184321

data/README.md

@@ -5,6 +5,20 @@ and containers using a YAML based configuration files.
 
 It allows for spec files (or lists of shared behaviours) to be ran across groups of servers. 
 
+It will generate rake tasks 
+
+Serverspec launcher also has limited support for running inspec based checks, running via the [chef/inspec](https://hub.docker.com/r/chef/inspec/) docker image
+
+## Requirements
+
+* Ruby >= 2.3
+* bundler 
+* docker (if using inspec tests)
+
+
+Currently this only runs on linux, possibly OS X (I don't have a mac to test it with)
+ 
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -46,8 +60,10 @@ the target section, and a task for any hosts specifed within the targets config.
 
 Each target consists of:
 
+###### Serverspec
+
 targetname (hash key): (required) The name of the target
-* backend: (optional) Which backend to run against, supported backend are ssh, exec, docker, and vagrant. Windows based backend will be availible in future versions
+* backend: (optional) Which backend to run against, supported backend are ssh, exec, docker, vagrant, and inspec. Windows based backend will be availible in future versions
 * user: (optional) what user to run the tests as, Defaults to current user
 * hosts: (optional) list or single value specifying the hostname(s) to run this against. defaults to target name 
 * spec_type: (optional) which spec file from the spec directory to execute against the target (do not include the _spec.rb). Defaults to role
@@ -56,6 +72,7 @@ targetname (hash key): (required) The name of the target
 Any values specified here will overwrite environment level(not to be confused with environment variables), and global level variables
 * environment: (optional) hash of environment variables which will be set on the target, environment level(not to be confused with environment variables), and global level environment varaibles(see below) that have previously defined values will be overwritten
 * fail_on_err: Stop running the tests if the target fails its checks
+* formatters: Use specific formatters for this target ([see formatters in option section](#options))
 
 Example :
 
@@ -71,6 +88,69 @@ targets:
     spec_type: webserver  
 ```
 
+###### Inspec
+
+targetname (hash key): (required) The name of the target
+* backend: (optional) Which backend to run against, this should be set to inspec
+* user: (optional) what user to run the tests as, Defaults to current user
+* hosts: (optional) list or single value specifying the hostname(s) to run this against. defaults to target name 
+* spec_type: (optional) which spec file from the spec directory to execute against the target (do not include the _spec.rb). If control or profile are specifed this field is ignored
+* control: (optional) path to inspec control to execute against the target (specify full path to spec file from project root). If profile is specified this field is ignored
+* profile: (optional) path to inspec profile to execute against the target (specify full path to profile from project root, github or chef supermarket). If profile is specified this field is ignored
+* fail_on_err: (optional) Stop running the tests if the target fails its checks
+* auth_method: How to authenticate the target user
+    * ssh-key: use an ssh key for authentication
+    * agent: (recommened) Use an existing ssh agent as the authentication method
+* keyfile: Space separated list ssh-key(s) to use for authentication if using ssh-key as the authentication method
+* bastion_host: (optional) Specify a bastion host 
+* bastion_user: (optional) Specify the user for a bastion host
+* bastion_port: (optional) Specify the port for a bastion host
+* formatters: Use specific reporters for this target ([see formatters in option section](#options))
+
+
+Examples :
+
+This would create the rake tasks serverspec:security, serverspec:security:webserver1 and serverspec:security:webserver2
+which run test contained in spec/webserver_spec.rb
+```yaml
+targets: 
+  security: # the name of the target
+    backend: inspec # use the 'inspec' backend.
+    user: ec2-user
+    auth_method: agent
+    hosts:
+      - webserver1
+      - webserver2
+    spec_type: webserver  
+```
+This would create the rake tasks serverspec:security, serverspec:security:env01 and serverspec:security:env02
+which run tests contained in spec/ssh_access.rb
+```yaml
+targets: 
+  security: # the name of the target
+    backend: inspec # use the 'inspec' backend.
+    user: ec2-user
+    auth_method: agent
+    hosts:
+      - env01
+      - env02
+    control: spec/ssh_access.rb 
+```
+This would create the rake tasks serverspec:security, serverspec:security:env01 and serverspec:security:env02
+which run the CIS Distribution Independent Linux Benchmark profile against the target
+```yaml
+targets: 
+  security: # the name of the target
+    backend: inspec # use the 'inspec' backend.
+    user: ec2-user
+    auth_method: agent
+    hosts:
+      - env01
+      - env02
+    control: https://github.com/dev-sec/cis-dil-benchmark
+```
+
+
 ##### environments
 serverspec_launcher supports the concept of environments. Environments are groups of targets organised as a named entity, i.e. test or qa.
 
@@ -108,6 +188,7 @@ environments:
         - web3.perf.domain
         - web4.perf.domain
 ```
+<a name="options"></a>
 ##### options
 A hash of options to pass to serverspec_launcher
 
@@ -115,14 +196,15 @@ A hash of options to pass to serverspec_launcher
 * color: (optional) colorize the output, defaults to true
 * formatters: (optional) list of RSpec formatter to process the results with. Supported formatters are:
 
-    - docs  RSpec Documentation Formatter writing to file reports/<target>.docs
-    - docs_screen - RSpec Documentation Formatter writing to screen
-    - tick -  Tick/Cross output to screen
-    - tick_file - Tick/Cross output to file reports/<target>.tick
-    - html - HTML Reports
-    - junit - Unit Reports (useful for jenkins jobs)
-    - html_pretty - Pretty HTML Reports
-    - json - JSON Output
+    - docs  RSpec Documentation Formatter writing to file reports/[\<environment\>]/\<target>/\<host>.docs. 
+    If using inspec checks this will use the 'Documentation' reporter.
+    - docs_screen - RSpec Documentation Formatter writing to screen. If using inspec checks this will use the 'Documentation' reporter.
+    - tick -  Tick/Cross output to screen. If using inspec checks this will use the 'cli' reporter.
+    - tick_file - Tick/Cross output to reports/[\<environment\>]/\<target>/\<host>.tick. If using inspec checks this will use the 'cli' reporter.
+    - html - HTML Reports to reports/[\<environment\>]/\<target>/\<host>.html. If using inspec checks this will use the 'html' reporter.
+    - junit - Unit Reports (useful for jenkins jobs) to 
+    - html_pretty - Pretty HTML Reports to reports/[\<environment\>]/\<target>/\<host>.html. If using inspec checks this will use the 'html' reporter.
+    - json - JSON Output to reports/[\<environment\>]/\<target>/\<host>.html. If using inspec checks this will use the 'html' reporter.
     - progress -  RSpec .F* progress output
 
 Example:
@@ -136,7 +218,7 @@ options:
 
 ```
 ##### variables
-A hash containing key value pairs. Each entry will be available as property[:variables][:<key>]
+A hash containing key value pairs. Each entry will be available as property[:variables][:\<key>]
 
 Example:
 ```yaml
@@ -278,6 +360,31 @@ targets:
       # Override a globally set environment var
       SOMEVAR: some other value
 
+  inspec-profile-example: # the name of the target
+    backend: inspec 
+    user: ec2-user
+    auth_method: agent
+    hosts:
+      - env01
+      - env02
+    profile: https://github.com/dev-sec/cis-dil-benchmark
+ 
+   inspec-control-example: # the name of the target
+     backend: inspec 
+     user: ec2-user
+     auth_method: agent
+     hosts:
+       - env01
+       - env02
+     control: spec/ssh_access.rb   
+
+   inspec-spec-example: # the name of the target
+     backend: inspec
+     user: ec2-user
+     auth_method: agent
+     hosts: env01
+     spec_type: webserver  
+    
 environments:
   qa:
     variables:

data/Rakefile

@@ -2,6 +2,7 @@
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'conventional_changelog'
+require 'docker-api'
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -10,4 +11,10 @@ task default: :spec
 
 task :changelog do
   ConventionalChangelog::Generator.new.generate!
+end
+
+
+task :docker do
+
+
 end

data/lib/serverspec_launcher/rake_tasks.rb

@@ -1,8 +1,11 @@
-# frozen_string_literal: true
+# frozen_string_literal: false
 require 'bundler/gem_tasks'
+require 'bundler'
 require 'rake'
 require 'rspec/core/rake_task'
 require 'yaml'
+require 'docker-api'
+require 'etc'
 
 $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'serverspec_launcher/helpers/example_helper'
@@ -18,7 +21,7 @@ class ServerspecLauncherRakeTasks
     @properties = properties ? properties.deep_symbolize_keys : YAML.load_file('properties.yml').deep_symbolize_keys
     options = @properties[:options] || {}
     @fail_on_err = options[:fail_on_err]
-    @formatters = options[:formatters] || ['docs_screen']
+    @formatters = options[:formatters] || ['tick']
     @colorize = options[:color].nil? ? true : options[:color]
   end
 
@@ -48,8 +51,8 @@ class ServerspecLauncherRakeTasks
     end
   end
 
-  def task_array(key, spec_type, target, options)
-    env = options[:source] == 'environment' ? ":"+ options[:environment]: ""
+  def serverspec_task_array(key, spec_type, target, options)
+    env = options[:source] == 'environment' ? ":"+ options[:environment] : ""
     desc "Run serverspec to #{key}"
     task key.to_sym => "serverspec#{env}:#{key}:all"
       namespace key.to_sym do
@@ -61,12 +64,12 @@ class ServerspecLauncherRakeTasks
         end
         target[:hosts].each do |host|
           task_name = "#{host || target[:name]}"
-          rake_task(host, key, task_name, spec_type, options)
+          serverspec_rake_task(host, key, task_name, spec_type, options)
         end
       end
   end
 
-  def rake_task(host, key, task_name, spec_type, options = {})
+  def serverspec_rake_task(host, key, task_name, spec_type, options = {}, target = {})
     desc "Run serverspec to #{key}"
     RSpec::Core::RakeTask.new(task_name.to_s.to_sym) do |t|
       ENV['TARGET_HOST'] = host.to_s
@@ -76,17 +79,18 @@ class ServerspecLauncherRakeTasks
       ENV['TASK_ENV'] = options[:environment]
       t.pattern = "spec/#{spec_type}_spec.rb"
       t.fail_on_error = options[:fail_on_err]
-      set_formatters(task_name, options, t)
+      report_name = options[:environment] ? "reports/#{options[:environment]}/#{key.to_s}/#{host.to_s}" : "reports/#{key.to_s}/#{host.to_s}"
+      set_formatters(report_name, options, t)
     end
   end
 
-  def set_formatters(key, options, t)
+  def set_formatters(report_path, options, t)
     opts = t.rspec_opts
     if options[:formatters].include?('junit') || options[:formatters].include?('xml')
-      opts = "#{opts}  --format RspecJunitFormatter --out reports/#{key}.xml"
+      opts = "#{opts}  --format RspecJunitFormatter --out #{report_path}.xml"
     end
     if options[:formatters].include?('docs') || options[:formatters].include?('documentation') || options[:formatters].include?('docs_file')
-      opts = "#{opts}  --format documentation --out reports/#{key}.docs"
+      opts = "#{opts}  --format documentation --out #{report_path}.docs"
     end
     if options[:formatters].include?('docs_screen')
       opts = "#{opts}  --format documentation"
@@ -95,19 +99,19 @@ class ServerspecLauncherRakeTasks
       opts = "#{opts}  --format RspecTickFormatter"
     end
     if options[:formatters].include?('tick_file')
-      opts = "#{opts}  --format RspecTickFormatter --out reports/#{key}.tick"
+      opts = "#{opts}  --format RspecTickFormatter --out #{report_path}.tick"
     end
     if options[:formatters].include?('progress')
       opts = "#{opts}  --format progress"
     end
     if options[:formatters].include?('html')
-      opts = "#{opts}  --format html --out reports/#{key}.html"
+      opts = "#{opts}  --format html --out #{report_path}.html"
     end
     if options[:formatters].include?('html_report') || options[:formatters].include?('html_pretty')
       opts = "#{opts}  --format RspecHtmlReporter"
     end
     if options[:formatters].include?('json')
-      opts = "#{opts}  --format j --out reports/#{key}.json"
+      opts = "#{opts}  --format j --out #{report_path}.json"
     end
     unless options[:color]
       opts = "#{opts} --no-color"
@@ -146,16 +150,186 @@ class ServerspecLauncherRakeTasks
         source: task_source,
         environment: environment
     }
+    if target[:backend] == 'inspec'
+      inspec_target(key, options, target)
+    else
+      serverspec_target(key, options, target)
+    end
+  end
+
+  def inspec_target(key, options, target)
+    spec_type, options = get_inspec_type(target, options)
+    if target[:hosts].is_a?(Array)
+      inspec_task_array(key, spec_type, target, options)
+    elsif target[:hosts]
+      host = target[:hosts]
+      task_name = (key || target[:name]).to_s
+      inspec_task(host, "#{key}/#{host}", task_name, spec_type, options, target)
+    else
+      host = (target[:hosts] || 'local' )
+      task_name = (key || target[:name]).to_s
+      inspec_task(host, "#{key}/#{host}", task_name, spec_type, options, target)
+    end
+  end
+
+  def inspec_task_array(key, spec_type, target, options)
+    env = options[:source] == 'environment' ? ":"+ options[:environment] : ""
+    desc "Run serverspec to #{key}"
+    task key.to_sym => "serverspec#{env}:#{key}:all"
+    namespace key.to_sym do
+      desc "Run #{key} against all hosts"
+      task :all do
+        target[:hosts].each do |host|
+          Rake::Task["serverspec#{env}:#{key}:#{host.split(':')[0].to_sym}"].execute
+        end
+      end
+      target[:hosts].each do |host|
+        task_name = "#{host || target[:name]}"
+        inspec_task(host, "#{key}/#{host}", task_name, spec_type, options, target)
+      end
+    end
+  end
+
+  def get_inspec_type(target, options)
+    spec_type = 'role'
+    if (target[:control] && target[:profile]) || (target[:control] && target[:spec_type]) || (target[:spec_type] && target[:profile])
+      puts 'WARNING: Multiple options specified: they will be evalated in the follow precidence profile > control > spec_type'
+    end
+    if target[:spec_type]
+      spec_type = target[:spec_type]
+      options[:spec_type] = 'spec'
+    end
+    if target[:control]
+      spec_type = target[:control]
+      options[:spec_type] = 'control'
+    end
+    if target[:profile]
+      spec_type = target[:profile]
+      options[:spec_type] = 'control'
+    end
+    return spec_type, options
+  end
+
+  def inspec_task(host, key, task_name, spec_type, options = {}, target = {})
+    protocol = host == 'local' ? 'local' : 'ssh'
+    command = inspec_commandline(target,key,host, spec_type, protocol, options)
+    Rake::Task.define_task(task_name.to_s.to_sym) do
+
+      unless Docker::Image.exist? 'chef/inspec:latest'
+        Docker::Image.create('fromImage' => 'chef/inspec:latest')
+      end
+
+      container = Docker::Container.create(
+          'Image' => 'chef/inspec:latest',
+          'Mounts' => inspec_mounts(target, protocol),
+          'Cmd' => command,
+          'Tty' => STDIN.tty?,
+          'Env' => inspec_environment(target, protocol)
+      )
+      begin
+        puts "inspec #{command.join(' ')}"
+        container.start
+        container.wait
+      rescue Docker::Error::TimeoutError => ex
+        container.stop
+        puts "A Docker::Error::TimeoutError occurred, most likey because you are using password protected ssh key, whihc is not supported"
+        puts "Either agent your ssh key and use 'agent' as the auth_method in your target settings or use an unprotected key (not recommended)"
+        puts 'Container Logs: '
+        puts container.logs(stderr: true)
+      ensure
+        puts container.logs(stdout: true)
+        container.delete
+        #Report have wrong permission hookie fix
+        chown_files(protocol, target)
+      end
+    end
+  end
+
+  def chown_files(protocol, target)
+    unless Docker::Image.exist? 'alpine:latest'
+      Docker::Image.create('fromImage' => 'alpine:latest')
+    end
+    command = %W[chown -R #{Etc.getpwnam(ENV['USER']).uid}:#{Etc.getpwnam(ENV['USER']).gid} /share/reports/]
+    container = Docker::Container.create(
+        'Image' => 'alpine:latest',
+        'Mounts' => inspec_mounts(target, protocol),
+        'Cmd' => command
+    )
+    container.start
+    container.wait
+    container.delete
+  end
+
+  def inspec_environment(target_info, protocol)
+    environment = []
+    environment << "SSH_AUTH_SOCK=#{ENV['SSH_AUTH_SOCK']}" if target_info[:auth_method] == 'agent'
+    environment
+  end
+
+  def inspec_mounts(target_info, protocol)
+    mounts = [{
+         'Type' => 'bind',
+         'Source' => "#{Dir.pwd}",
+         'Target' => "/share"
+     }, {
+         'Type' => 'bind',
+         'Source' => "/etc/hosts",
+         'Target' => "/etc/hosts"
+     }]
+    mount_ssh = target_info[:mount_ssh_dir] ? target_info[:mount_ssh_dir] : true
+    mounts <<  { 'Type' => 'bind', 'Source' => "#{File.expand_path('~')}/.ssh", 'Target' => "#{File.expand_path('~')}/.ssh" } if mount_ssh && protocol == 'ssh'
+    mounts <<  { 'Type' => 'bind', 'Source' => "#{ENV['SSH_AUTH_SOCK']}", 'Target' => "#{ENV['SSH_AUTH_SOCK']}" } if target_info[:auth_method] == 'agent'
+    mounts
+  end
+
+  def inspec_commandline(target_info, key, host, spec_type, protocol, options = {})
+    spec = if options[:spec_type] == 'spec'
+      "spec/#{spec_type}_spec.rb"
+    else
+      spec_type
+    end
+    target = "#{protocol}://#{protocol == 'local' ? '' : host}"
+    command =  %W[exec #{spec} -t #{target}]
+    authmethod = target_info[:auth_method] ? target_info[:auth_method] : 'ssh-keys'
+    keyfile = target_info[:keyfile] ? target_info[:keyfile] : "#{File.expand_path('~')}/.ssh/id_rsa"
+    if protocol == 'ssh' && authmethod == 'ssh-keys'
+      command << '-i'
+      command << keyfile
+    end
+    command << "--user=#{target_info[:user]}" if target_info[:user]
+    command << "--bastion-host=#{target_info[:bastion_host]}" if target_info[:bastion_host]
+    command << "--bastion-port=#{target_info[:bastion_port]}" if target_info[:bastion_port]
+    command << "--bastion-user=#{target_info[:bastion_user]}" if target_info[:bastion_user]
+    command <<  set_inspec_reporters(key, host, options)
+    command
+  end
+
+  def set_inspec_reporters(key, host, options)
+    reporters = []
+    report_path = options[:environment] ? "/share/reports/#{options[:environment]}/#{key}" :  "/share/#{report_path}"
+    reporters <<  "junit:#{report_path}.xml" if options[:formatters].include?('junit') || options[:formatters].include?('xml')
+    reporters <<  "documentation:#{report_path}.docs" if options[:formatters].include?('docs') || options[:formatters].include?('documentation') || options[:formatters].include?('docs_file')
+    reporters <<  'documentation' if options[:formatters].include?('docs_screen')
+    reporters <<  'cli' if options[:formatters].include?('tick')
+    reporters <<  "cli:#{report_path}.tick" if options[:formatters].include?('tick_file')
+    reporters <<  'progress' if options[:formatters].include?('progress')
+    reporters <<  "html:#{report_path}.html" if options[:formatters].include?('html')
+    reporters <<  "html#{report_path}.html" if (options[:formatters].include?('html_report') || options[:formatters].include?('html_pretty')) && !options[:formatters].include?('html')
+    reporters <<  "json-rspec:#{report_path}.json" if options[:formatters].include?('json')
+    "--reporter=#{reporters.join(' ')}"
+  end
+
+  def serverspec_target(key, options, target)
     spec_type = target[:spec_type] || 'role'
     if target[:hosts].is_a?(Array)
-      task_array(key, spec_type, target, options)
+      serverspec_task_array(key, spec_type, target, options)
     elsif target[:hosts]
       host = target[:hosts]
       task_name = (key || target[:name]).to_s
-      rake_task(host, key, task_name, spec_type, options)
+      serverspec_rake_task(host, key, task_name, spec_type, options)
     else
       task_name = (key || target[:name]).to_s
-      rake_task(key, key, task_name, spec_type, options)
+      serverspec_rake_task(key, key, task_name, spec_type, options)
     end
   end
 end

data/lib/serverspec_launcher/spec_helper.rb

@@ -58,6 +58,7 @@ class SpecHelper
       set :backend, :exec
     elsif @backend == 'docker'
       docker_backend
+    elsif @backend == 'inspec'
     else
       ssh_backend
     end

data/lib/serverspec_launcher/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module ServerspecLauncher
-  VERSION = '0.2.4'
+  VERSION = '0.3.0'
 end

data/serverspec_launcher.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.13'
+  spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 12.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serverspec_launcher
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Andrew Wardrobe
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-08 00:00:00.000000000 Z
+date: 2019-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.13'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement