inspec-reporter-flex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 462241a08906f9500cc8ac2eff3d66cf9419d933b4166502dd35b5bc4445834c
+  data.tar.gz: c6aefa556b71a5ef91ce07f3d406c4f4dddedf16c89cd577919813aa4ce3fc26
+SHA512:
+  metadata.gz: ffc434833148c5c32706ebc64c479a94b05a673d1fb526ec6d4514c2ac549b542018ed7e0412f0304af4aeeb2205253ef68392a3f429679d6e7f66da9b26bb2c
+  data.tar.gz: a737d31db943e3755e73a695bf58030851d5191e0015b9dd84a2dbe993049f98f30669ba73c4ea700e49aa896a436883853854a069670d26d749e6d5aee8b835

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## v0.1.0
+
+- Initial version

data/README.md

@@ -0,0 +1,133 @@
+# inspec-reporter-flex Plugin
+
+InSpec Flex reporter for freeform templating.
+
+## To Install This Plugin
+
+Inside InSpec:
+
+```shell
+you@machine $ inspec plugin install inspec-reporter-flex
+```
+
+For use within `kitchen`:
+
+```shell
+you@machine $ gem install inspec-reporter-flex
+```
+
+## How to use this plugin
+
+To generate a report using this plugin and save the output to a file named `report.txt`, run:
+
+```shell
+you@machine $ inspec exec some_profile --reporter flex:/tmp/report.txt
+```
+
+## Configuring the Plugin
+
+The `flex` reporter offers only one customization option:
+
+For example:
+
+```json
+{
+  "version": "1.2",
+  "plugins": {
+    "inspec-reporter-flex": {
+      "template_file":"template/markdown.rb"
+    }
+  }
+}
+```
+
+See below all customization options available:
+
+| Option           |        Default       |   Description  |
+|------------------|:--------------------:|:--------------:|
+| `template_file`  | `templates/flex.erb` |  Name of the file for templating. Will look up in order "absolute path", "relative to current directory", "relative to gem directory" |
+
+## Writing Templates
+
+Templates are written in the omnipresent ERB language, which might read like this:
+
+```erb
+<% profiles.each do |profile| %>
+<%= profile.title %>:
+<%   profile.controls.each do |control| %>
+<%=    control.title %>:
+<%     control.results.each do |result| %>
+<%=      <%= result.status %>
+<%    end %>
+<%  end %>
+<% end %>
+```
+
+### Variables
+
+The following variables are passed to your template:
+
+| Name            | Contents                                        |
+| --------------- | ----------------------------------------------- |
+| `profiles`      | Array of all profiles from the InSpec run       |
+| `statistics`    | Statistics (e.g. runtime)                       |
+| `platform`      | Platform information                            |
+| `version`       | InSpec version used                             |
+| `passed_tests`  | Number of passed tests                          |
+| `failed_tests`  | Number of failed tests                          |
+| `percent_pass`  | Percentage of passed tests                      |
+| `percent_fail`  | Percentage of failed tests                      |
+| `platform_arch` | Architecture of the platform (e.g. `x86_64`)    |
+| `platform_name` | Full name of the platform (e.g. `Ubuntu Linux`) |
+
+### Helpers
+
+Some helper functions for easier template processing:
+
+| Name                           | Returns    | Description                                   |
+| ------------------------------ | ---------- | --------------------------------------------- |
+| `scan_time`                    | `DateTime` | Roughly the time of scan end                  |
+| `control_passed?(control)`     | `Boolean`  | If all results of the control are passed      |
+| `status_to_pass(status)`       | `String`   | Translate to "ok"/not ok"                     |
+| `impact_to_severity(severity)` | `String`   | Translate InSpec numeric severity to a string |
+
+You also have the option of running some additional commands against the machine under test. This is sometimes needed for some metadata in reports.
+
+Execution or InSpec resource related helpers:
+
+| Name                                    | Returns             | Description                                                               |
+| --------------------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| `remote_command(cmd)`                   | `CommandResult`     | Execute command (`.stdout`/`.stderr`/`.exit_status`)                      |
+| `remote_file_content(remote_file)`      | `String`            | Contents of a file                                                        |
+| `os`                                    | `os` resource       | OS information (`.arch`/`.family`/`.name`)                                |
+| `sys_info`                              | `sys_info` resource | System Information (`.domain`/`.fqdn`/`.hostname`/`.ip_address`/`.model`) |
+| `inspec_resource.*`                     | Any InSpec resource | Return value varies depending on the resource                             |
+
+### Template-specific settings
+
+You can add your own template-specific settings via the `template_config` hash in the ERB templates. Just add a block to read those and apply defaults like:
+
+```ruby
+<%
+  config_emojis = template_config.fetch("emojis", true)
+%>
+```
+
+You can configure these freeform settings in your `~/.inspec/config.json`:
+
+```json
+{
+  "version": "1.2",
+  "plugins": {
+    "inspec-reporter-flex": {
+      "template_config": {
+        "emojis": true
+      }
+    }
+  }
+}
+```
+
+## Developing This Plugin
+
+Submit PR and will discuss, thank you!

data/lib/inspec-reporter-flex.rb

@@ -0,0 +1,4 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require "inspec-reporter-flex/plugin"

data/lib/inspec-reporter-flex/mixin/erb_helpers.rb

@@ -0,0 +1,92 @@
+module InspecPlugins::FlexReporter
+  module ErbHelpers
+    # Return latest start time of the scan
+    #
+    # @return [DateTime] Timestamp of the last scan in the profile
+    def scan_time
+      DateTime.strptime(report[:profiles].last[:controls].last[:results].last[:start_time])
+    end
+
+    # Execute a remote command.
+    #
+    # @param [String] cmd Command to execute
+    # @return [Train::Extras::CommandResult] Command result (.stdout/.stderr/.exit_status)
+    def remote_command(cmd)
+      runner.backend.backend.run_command(cmd)
+    end
+
+    # Retrieve remote file contents.
+    #
+    # @param [String] remote_file Path to the remote file
+    # @return [String] Contents of the file
+    def remote_file_content(remote_file)
+      runner.backend.backend.file(remote_file).content
+    end
+
+    # Allow access to all InSpec resources from the report.
+    #
+    # @return [Inspec::Backend] The InSpec backend
+    def inspec_resource
+      runner.backend
+    end
+
+    # Return InSpec OS resource results.
+    #
+    # @return [Class] Look into documentation for properties (.arch/.family/.name/...)
+    # @see https://github.com/inspec/inspec/blob/master/lib/inspec/resources/os.rb
+    def os
+      runner.backend.os
+    end
+
+    # Return InSpec SysInfo resource results.
+    #
+    # @return [Class] Look into documentation for properteis (.domain/.fqdn/.hostname/.ip_address/.model/...)
+    # @see https://github.com/inspec/inspec/blob/master/lib/inspec/resources/sys_info.rb
+    def sys_info
+      runner.backend.sys_info
+    end
+
+    # Return if all results of a control have passed/skipped/waived.
+    #
+    # @param [Hash] control Data of a control run
+    # @return [Boolean] If all passed checks
+    def control_passed?(control)
+      control[:results].any? { |result| result[:status] == "failed" }
+    end
+
+    # Map InSpec status to cleartext
+    #
+    # @param [String] inspec_status One of the valid InSpec result status.
+    # @return [Strint] "ok"/"not ok" depending on status
+    def status_to_pass(inspec_status)
+      case inspec_status
+      when "passed", "skipped", "waived"
+        "ok"
+      else
+        "not ok"
+      end
+    end
+
+    # Map InSpec severity (0..1) to CVSS scale (none-low-medium-high-critical)
+    #
+    # @param [Float] inspec_severity Severity from the profile
+    # @return [String] One of the scale values
+    # @see https://www.first.org/cvss/specification-document#Qualitative-Severity-Rating-Scale
+    def impact_to_severity(inspec_severity)
+      case inspec_severity
+      when 0.0...0.1
+        "none"
+      when 0.1...0.4
+        "low"
+      when 0.4...0.7
+        "medium"
+      when 0.7...0.9
+        "high"
+      when 0.9..1.0
+        "critical"
+      else
+        "unknown"
+      end
+    end
+  end
+end

data/lib/inspec-reporter-flex/mixin/file_resolver.rb

@@ -0,0 +1,60 @@
+module InspecPlugins::FlexReporter
+  module FileResolver
+    # Resolve the absolute path for a file in order absolute path/gem bundled file/relative.
+    #
+    # @param [String] name Name or path of a file to resolve
+    # @return [String] Absolute path to the file, if any
+    # @raise [RuntimeError] if file not found
+    def resolve_path(name)
+      if absolute_path?(name)
+        name
+      elsif relative_path?(name)
+        relative_path(name)
+      elsif gem_path?(name)
+        gem_path(name)
+      else
+        raise "Template file #{name} not found"
+      end
+    end
+
+    # Is this an absolute path?
+    #
+    # @param [String] name name or path of a file
+    # @return [Boolean] if it is an absolute path
+    def absolute_path?(name)
+      name.start_with? "/"
+    end
+
+    # Is this an relative path?
+    #
+    # @param [String] name name or path of a file
+    # @return [Boolean] if it is an relative path
+    def relative_path?(name)
+      File.exist? relative_path(name)
+    end
+
+    # Is this a Gem-bundled path?
+    #
+    # @param [String] name name or path of a file
+    # @return [Boolean] if it is a Gem-bundled path
+    def gem_path?(name)
+      File.exist? gem_path(name)
+    end
+
+    # Return absolute path for a file relative to Dir.pwd.
+    #
+    # @param [String] name Name or path of a file
+    # @return [String] Absolute path to the file
+    def relative_path(name)
+      File.join(Dir.pwd, name)
+    end
+
+    # Return absolute path for a file bundled with this Gem.
+    #
+    # @param [String] name Name or path of a file
+    # @return [String] Absolute path to the file
+    def gem_path(name)
+      File.join(__dir__, "../../..", name)
+    end
+  end
+end

data/lib/inspec-reporter-flex/plugin.rb

@@ -0,0 +1,15 @@
+require_relative "version"
+
+module InspecPlugins
+  module FlexReporter
+    class Plugin < ::Inspec.plugin(2)
+      # Internal machine name of the plugin. InSpec will use this in errors, etc.
+      plugin_name :"inspec-reporter-flex"
+
+      reporter :flex do
+        require_relative "reporter"
+        InspecPlugins::FlexReporter::Reporter
+      end
+    end
+  end
+end

data/lib/inspec-reporter-flex/reporter.rb

@@ -0,0 +1,76 @@
+require_relative "mixin/erb_helpers"
+require_relative "mixin/file_resolver"
+
+require "erb" unless defined? ERB
+
+module InspecPlugins::FlexReporter
+  class Reporter < Inspec::Reporters::Json
+    include InspecPlugins::FlexReporter::ErbHelpers
+    include InspecPlugins::FlexReporter::FileResolver
+
+    # Render report
+    def render
+      template_file = resolve_path(config["template"])
+      template = ERB.new(File.read(template_file))
+
+      # Use JSON Reporter base's `report` to have pre-processed data
+      mushy_report = Hashie::Mash.new(report)
+
+      # Eeease of use here
+      platform   = mushy_report.platform
+      profiles   = mushy_report.profiles
+      statistics = mushy_report.statistics
+      version    = mushy_report.version
+
+      # Some pass/fail information
+      test_results = profiles.map(&:controls).flatten.map(&:results).flatten.map(&:status)
+      passed_tests = test_results.select { |text| text == "passed" }.count
+      failed_tests = test_results.count - passed_tests
+      percent_pass = 100.0 * passed_tests / test_results.count
+      percent_fail = 100.0 - percent_pass
+
+      # Detailed OS
+      platform_arch = runner.backend.backend.os.arch
+      platform_name = runner.backend.backend.os.title
+
+      # Allow template-based settings
+      template_config = config.fetch("template_config", {})
+
+      # ... also can use all InSpec resources via "inspec_resource.NAME.PROPERTY"
+
+      output(template.result(binding))
+    end
+
+    # Return Constraints.
+    #
+    # @return [String] Always "~> 0.0"
+    def self.run_data_schema_constraints
+      "~> 0.0"
+    end
+
+    private
+
+    # Initialize configuration with defaults and Plugin config.
+    #
+    # @return [Hash] Configuration data after merge
+    def config
+      @config unless @config.nil?
+
+      # Defaults
+      @config = {
+        "template" => "templates/flex.erb",
+      }
+
+      @config.merge! Inspec::Config.cached.fetch_plugin_config("inspec-reporter-flex")
+    end
+
+    # Return InSpec Runner for further inspection.
+    #
+    # @return [Inspec::Runner] Runner instance
+    def runner
+      require "binding_of_caller"
+
+      binding.callers.find { |b| b.frame_description == "run_tests" }.receiver
+    end
+  end
+end

data/lib/inspec-reporter-flex/version.rb

@@ -0,0 +1,5 @@
+module InspecPlugins
+  module FlexReporter
+    VERSION = "0.1.0".freeze
+  end
+end

data/templates/flex.erb

@@ -0,0 +1,29 @@
+<%
+   # Free-form, template-based settings are available
+   config_emojis = template_config["emojis"]
+
+%># InSpec Report
+
+Scanned on <%= scan_time.strftime('%Y-%m-%d') %>.
+
+Host: <%= sys_info.fqdn %>
+OS: <%= platform_name %> <%= platform[:release] %> (<%= platform_arch %>)
+
+Tests passed: <%= passed_tests %> (<%= format("%2.1f%%", percent_pass) %>)
+Tests failed: <%= failed_tests %> (<%= format("%2.1f%%", percent_fail) %>)
+
+<% profiles.each do |profile|
+
+%>## Profile `<%= profile.title %>`<%
+     profile.controls.each do |control| %>
+
+### Control `<%= control.title %>`
+
+<%= control.desc %>
+
+Results:
+<%     control.results.each do |result| %>
+- <%= result.code_desc %>: <%= result.status %><%= config_emojis ? (result.status == "passed" ? " :heavy_check_mark:" : " :red_circle:") : "" %><%
+       end # result %>
+<%   end # control %>
+<% end # profile %>

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: inspec-reporter-flex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Heinen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: chefstyle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+- !ruby/object:Gem::Dependency
+  name: mdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Plugin for templated reports
+email:
+- theinen@tecracer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/inspec-reporter-flex.rb
+- lib/inspec-reporter-flex/mixin/erb_helpers.rb
+- lib/inspec-reporter-flex/mixin/file_resolver.rb
+- lib/inspec-reporter-flex/plugin.rb
+- lib/inspec-reporter-flex/reporter.rb
+- lib/inspec-reporter-flex/version.rb
+- templates/flex.erb
+homepage: https://github.com/tecracer-chef/inspec-reporter-flex
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: InSpec Reporter for flexible, template-based reports
+test_files: []