inspec-core 4.56.17 → 5.7.9

data/lib/inspec/reporters/json.rb

@@ -29,28 +29,48 @@ module Inspec::Reporters
       {
         name:      run_data[:platform][:name],
         release:   run_data[:platform][:release],
-        target_id: run_data[:platform][:target_id] || @config["target_id"],
+        target_id: run_data[:platform][:target_id] || "",
       }.reject { |_k, v| v.nil? }
     end
 
     def profile_results(control)
       (control[:results] || []).map { |r|
         {
-          status:       r[:status],
-          code_desc:    r[:code_desc],
-          run_time:     r[:run_time],
-          start_time:   r[:start_time],
-          resource:     r[:resource],
-          skip_message: r[:skip_message],
-          message:      r[:message],
-          exception:    r[:exception],
-          backtrace:    r[:backtrace],
-          resource_class: r[:resource_class],
+          status:          r[:status],
+          code_desc:       r[:code_desc],
+          run_time:        r[:run_time],
+          start_time:      r[:start_time],
+          resource:        r[:resource],
+          skip_message:    r[:skip_message],
+          message:         r[:message],
+          exception:       r[:exception],
+          backtrace:       r[:backtrace],
+          resource_class:  r[:resource_class],
           resource_params: r[:resource_params].to_s,
+          resource_id:     extract_resource_id(r),
         }.reject { |_k, v| v.nil? }
       }
     end
 
+    def extract_resource_id(r)
+      # According to the RunData API, this is supposed to be an anonymous
+      # class that represents a resource, with embedded instance methods....
+      resource_obj = r[:resource_title]
+      return resource_obj.resource_id if resource_obj.respond_to?(:resource_id)
+
+      # But sometimes, it isn't, and has been collapsed into the to_s stringification of the resource.
+      if resource_obj.is_a?(String)
+        orig_str = resource_obj
+        # Try to trim off the resource class - eg "File /some/path" => "/some/path"
+        trimmed_str = orig_str.sub(/^#{r[:resource_class]}/i, "").strip
+        trimmed_str.empty? ? orig_str : trimmed_str
+      else
+        # Boo, InSpec is crazy, and we don't know what it possibly could be.
+        # Failsafe for resource_id is empty string.
+        ""
+      end
+    end
+
     def profiles
       run_data[:profiles].map do |p|
         res = {

data/lib/inspec/resource.rb

@@ -34,6 +34,12 @@ module Inspec
       Inspec::Resource.support_registry[key].push(criteria)
     end
 
+    def resource_id(value = nil)
+      @resource_id = value if value
+      @resource_id = ""    if @resource_id.nil?
+      @resource_id
+    end
+
     # TODO: this is pretty terrible and is only here to work around
     # the idea that we've trained resource authors to make initialize
     # methods w/o calling super.

data/lib/inspec/resources/cron.rb

@@ -0,0 +1,49 @@
+require "inspec/resources/crontab"
+
+module Inspec::Resources
+  class Cron < Crontab
+    name "cron"
+    supports platform: "unix"
+    desc "Use the cron InSpec audit resource to test entires in the crontab file for a given user. This also can be used as alias to crontab resource."
+    example <<~EXAMPLE
+      describe cron do
+         it { should have_entry '* * * * * /usr/local/bin/foo' }
+      end
+
+      describe cron(user: "username") do
+        its(:table) { should match /you can use regexp/ }
+      end
+    EXAMPLE
+
+    def initialize(opts = nil)
+      super
+      @params = read_cron_contents
+    end
+
+    def read_cron_contents
+      result = inspec.command(crontab_cmd)
+      if result.exit_status == 0
+        result.stdout.lines.map { |l| parse_comment_line(l, comment_char: "#", standalone_comments: false)[0].strip }
+      else
+        error = result.stdout + "\n" + result.stderr
+        raise Inspec::Exceptions::ResourceFailed, "Error while executing #{crontab_cmd} command: #{error}"
+      end
+    end
+
+    def table
+      @params.reject(&:empty?).join("\n")
+    end
+
+    def has_entry?(rule)
+      @params.include?(rule)
+    end
+
+    def to_s
+      if is_user_crontab?
+        "cron for user #{@user}"
+      else
+        "cron for current user"
+      end
+    end
+  end
+end

data/lib/inspec/resources/ipfilter.rb

@@ -0,0 +1,59 @@
+require "inspec/resources/command"
+module Inspec::Resources
+  class IpFilter < Inspec.resource(1)
+    name "ipfilter"
+    supports platform: "bsd"
+    supports platform: "solaris"
+    desc "Use the ipfilter InSpec audit resource to test rules that are defined for ipfilter, which maintains the IP rule set"
+    example <<~EXAMPLE
+      describe ipfilter do
+        it { should have_rule("pass in quick on lo0 all") }
+      end
+    EXAMPLE
+
+    def initialize
+      # checks if the instance is either bsd or solaris
+      return if (inspec.os.bsd? && !inspec.os.darwin?) || inspec.os.solaris?
+
+      # ensures, all calls are aborted for non-supported os
+      @ipfilter_cache = []
+      skip_resource "The `ipfilter` resource is not supported on your OS yet."
+    end
+
+    def has_rule?(rule = nil)
+      # checks if the rule is part of the ruleset
+      retrieve_rules.any? { |line| line.casecmp(rule) == 0 }
+    end
+
+    def retrieve_rules
+      # this would be true if the OS family was not bsd/solaris when checked in initliaze
+      return @ipfilter_cache if defined?(@ipfilter_cache)
+
+      # construct ipfstat command to read all rules
+      bin = find_ipfstat_or_error
+      ipfstat_cmd = "#{bin} -io"
+      cmd = inspec.command(ipfstat_cmd)
+
+      # Return empty array when command is not executed successfully
+      # or there is no output since no rules are active
+      return [] if cmd.exit_status.to_i != 0 || cmd.stdout == ""
+
+      # split rules, returns array or rules
+      @ipfilter_cache = cmd.stdout.split("\n").map(&:strip)
+    end
+
+    def to_s
+      "Ipfilter"
+    end
+
+    private
+
+    def find_ipfstat_or_error
+      %w{/usr/sbin/ipfstat /sbin/ipfstat ipfstat}.each do |cmd|
+        return cmd if inspec.command(cmd).exist?
+      end
+
+      raise Inspec::Exceptions::ResourceFailed, "Could not find `ipfstat`"
+    end
+  end
+end

data/lib/inspec/resources/ipnat.rb

@@ -0,0 +1,58 @@
+require "inspec/resources/command"
+module Inspec::Resources
+  class IpNat < Inspec.resource(1)
+    name "ipnat"
+    supports platform: "bsd"
+    supports platform: "solaris"
+    desc "Use the ipnat InSpec audit resource to test rules that are defined for IP NAT"
+    example <<~EXAMPLE
+      describe ipnat do
+        it { should have_rule("map net1 192.168.0.0/24 -> 0/32") }
+      end
+    EXAMPLE
+
+    def initialize
+      # checks if the instance is either bsd or solaris
+      return if (inspec.os.bsd? && !inspec.os.darwin?) || inspec.os.solaris?
+
+      # ensures, all calls are aborted for non-supported os
+      @ipnat_cache = []
+      skip_resource "The `ipnat` resource is not supported on your OS yet."
+    end
+
+    def has_rule?(rule = nil)
+      # checks if the rule is part of the ruleset
+      retrieve_rules.any? { |line| line.casecmp(rule) == 0 }
+    end
+
+    def retrieve_rules
+      # this would be true if the OS family was not bsd/solaris when checked in initliaze
+      return @ipnat_cache if defined?(@ipnat_cache)
+
+      # construct ipnat command to show the list of current IP NAT table entry mappings
+      bin = find_ipnat_or_error
+      ipnat_cmd = "#{bin} -l"
+      cmd = inspec.command(ipnat_cmd)
+
+      # Return empty array when command is not executed successfully
+      return [] if cmd.exit_status.to_i != 0
+
+      # split rules, returns array or rules
+      @ipnat_cache = cmd.stdout.split("\n").map(&:strip)
+    end
+
+    def to_s
+      "Ipnat"
+    end
+
+    private
+
+    def find_ipnat_or_error
+      %w{/usr/sbin/ipnat /sbin/ipnat ipnat}.each do |cmd|
+        return cmd if inspec.command(cmd).exist?
+      end
+
+      raise Inspec::Exceptions::ResourceFailed, "Could not find `ipnat`"
+    end
+  end
+end

data/lib/inspec/resources.rb

@@ -8,21 +8,6 @@
 # glob so this remains a sort of manifest for our resources.
 
 require "inspec/resource"
-
-# Detect if we are running the stripped-down inspec-core
-# This relies on AWS being stripped from the inspec-core gem
-inspec_core_only = ENV["NO_AWS"] || !File.exist?(File.join(File.dirname(__FILE__), "..", "resource_support", "aws.rb"))
-
-# Do not attempt to load cloud resources if we are in inspec-core mode
-unless inspec_core_only
-  require "resource_support/aws"
-  require "resources/azure/azure_backend"
-  require "resources/azure/azure_generic_resource"
-  require "resources/azure/azure_resource_group"
-  require "resources/azure/azure_virtual_machine"
-  require "resources/azure/azure_virtual_machine_data_disk"
-end
-
 require "inspec/resources/aide_conf"
 require "inspec/resources/apache"
 require "inspec/resources/apache_conf"
@@ -41,6 +26,7 @@ require "inspec/resources/cassandradb_session"
 require "inspec/resources/cassandradb_conf"
 require "inspec/resources/cassandra"
 require "inspec/resources/crontab"
+require "inspec/resources/cron"
 require "inspec/resources/timezone"
 require "inspec/resources/dh_params"
 require "inspec/resources/directory"
@@ -138,7 +124,8 @@ require "inspec/resources/xinetd_conf"
 require "inspec/resources/yum"
 require "inspec/resources/zfs_dataset"
 require "inspec/resources/zfs_pool"
-
+require "inspec/resources/ipnat"
+require "inspec/resources/ipfilter"
 # file formats, depend on json implementation
 require "inspec/resources/json"
 require "inspec/resources/yaml"

data/lib/inspec/runner.rb

@@ -105,6 +105,7 @@ module Inspec
 
         write_lockfile(profile) if @create_lockfile
         profile.locked_dependencies
+        profile.load_gem_dependencies
         profile_context = profile.load_libraries
 
         profile_context.dependencies.list.values.each do |requirement|
@@ -126,9 +127,25 @@ module Inspec
         end
       end
 
+      controls_count = 0
+      control_checks_count_map = {}
+
       all_controls.each do |rule|
-        register_rule(rule) unless rule.nil?
+        unless rule.nil?
+          register_rule(rule)
+          checks = ::Inspec::Rule.prepare_checks(rule)
+          unless checks.empty?
+            # controls with empty tests are avoided
+            # checks represent tests within control
+            controls_count += 1
+            control_checks_count_map[rule.to_s] = checks.count
+          end
+        end
       end
+
+      # this sets data via runner-rspec into base RSpec formatter object, which gets used up within streaming plugins
+      @test_collector.set_controls_count(controls_count)
+      @test_collector.set_control_checks_count_map(control_checks_count_map)
     end
 
     def run(with = nil)

data/lib/inspec/runner_rspec.rb

@@ -42,6 +42,21 @@ module Inspec
       end
     end
 
+    # These control count related methods are called from load logic of runner library of inspec
+    ######### Start of control count related methods
+    def set_controls_count(controls_count)
+      formatters.each do |fmt|
+        fmt.set_controls_count(controls_count)
+      end
+    end
+
+    def set_control_checks_count_map(mapping)
+      formatters.each do |fmt|
+        fmt.set_control_checks_count_map(mapping)
+      end
+    end
+    ######### end of control count related methods
+
     def backend
       formatters.first.backend
     end

data/lib/inspec/schema/exec_json.rb

@@ -11,16 +11,16 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{label data},
         "properties" => {
-          "label" => Primitives::STRING,
-          "data" => Primitives::STRING,
+          "label" => Primitives.desc(Primitives::STRING, "The type of description.  Examples: 'fix' or 'check'."),
+          "data" => Primitives.desc(Primitives::STRING, "The text of the description."),
         },
-      }, [])
+      }, [], "A description for a control.")
 
       # Lists the potential values for a control result
       CONTROL_RESULT_STATUS = Primitives::SchemaType.new("Control Result Status", {
         "type" => "string",
         "enum" => %w{passed failed skipped error},
-      }, [])
+      }, [], "The status of a control.  Should be one of 'passed', 'failed', 'skipped', or 'error'.")
 
       # Represents the statistics/result of a control"s execution
       CONTROL_RESULT = Primitives::SchemaType.new("Control Result", {
@@ -28,24 +28,26 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{code_desc run_time start_time},
         "properties" => {
-          "status" => CONTROL_RESULT_STATUS.ref,
-          "code_desc" => Primitives::STRING,
-          "run_time" => Primitives::NUMBER,
-          "start_time" => Primitives::STRING,
+          "status" => Primitives.desc(CONTROL_RESULT_STATUS.ref, "The status of this test within the control.  Example: 'failed'."),
+          "code_desc" => Primitives.desc(Primitives::STRING, "A description of this test.  Example: 'limits.conf * is expected to include ['hard', 'maxlogins', '10']."),
+          "run_time" => Primitives.desc(Primitives::NUMBER, "The execution time in seconds for the test."),
+          "start_time" => Primitives.desc(Primitives::STRING, "The time at which the test started."),
 
           # All optional
-          "resource" => Primitives::STRING,
-          "message" => Primitives::STRING,
-          "skip_message" => Primitives::STRING,
-          "exception" => Primitives::STRING,
+          "resource" => Primitives.desc(Primitives::STRING, "The resource used in the test.  Example: in Inspec, you can use the 'File' resource."),
+          "message" => Primitives.desc(Primitives::STRING, "An explanation of the test status - usually only provided when the test fails."),
+          "skip_message" => Primitives.desc(Primitives::STRING, "An explanation of the test status if the status was 'skipped."),
+          "exception" => Primitives.desc(Primitives::STRING, "The type of exception if an exception was thrown."),
+          "resource_id" => Primitives.desc(Primitives::STRING, "The unique identifier of the resource."),
           "backtrace" => {
             "anyOf" => [
               Primitives.array(Primitives::STRING),
               Primitives::NULL,
             ],
+            "description" => "The stacktrace/backtrace of the exception if one occurred.",
           },
         },
-      }, [CONTROL_RESULT_STATUS])
+      }, [CONTROL_RESULT_STATUS], "A test within a control and its results and findings such as how long it took to run.")
 
       # Represents a control produced
       CONTROL = Primitives::SchemaType.new("Exec JSON Control", {
@@ -53,26 +55,25 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{id title desc impact refs tags code source_location results},
         "properties" => {
-          "id" => Primitives.desc(Primitives::STRING, "The ID of this control"),
-          "title" => { "type" => %w{string null} }, # Nullable string
-          "desc" => { "type" => %w{string null} },
-          "descriptions" => Primitives.array(CONTROL_DESCRIPTION.ref),
-          "impact" => Primitives::IMPACT,
-          "refs" => Primitives.array(Primitives::REFERENCE.ref),
-          "tags" => Primitives::TAGS,
-          "code" => Primitives.desc(Primitives::STRING, "The raw source code of the control. Note that if this is an overlay control, it does not include the underlying source code"),
-          "source_location" => Primitives::SOURCE_LOCATION.ref,
-          "results" => Primitives.desc(Primitives.array(CONTROL_RESULT.ref), %q{
-              A list of all results of the controls describe blocks.
-
-              For instance, if in the controls code we had the following:
-                describe sshd_config do
-                  its('Port') { should cmp 22 }
-                end
-              The result of this block as a ControlResult would be appended to the results list.
-              }),
+          "id" => Primitives.desc(Primitives::STRING, "The id."),
+          "title" => Primitives.desc({ "type" => %w{string null} }, "The title - is nullable."), # Nullable string
+          "desc" => Primitives.desc({ "type" => %w{string null} }, "The description for the overarching control."),
+          "descriptions" => Primitives.desc(Primitives.array(CONTROL_DESCRIPTION.ref), "A set of additional descriptions.  Example: the 'fix' text."),
+          "impact" => Primitives.desc(Primitives::IMPACT, "The impactfulness or severity."),
+          "refs" => Primitives.desc(Primitives.array(Primitives::REFERENCE.ref), "The set of references to external documents."),
+          "tags" => Primitives.desc(Primitives::TAGS, "A set of tags - usually metadata."),
+          "code" => Primitives.desc(Primitives::STRING, "The raw source code of the control. Note that if this is an overlay control, it does not include the underlying source code."),
+          "source_location" => Primitives.desc(Primitives::SOURCE_LOCATION.ref, "The explicit location of the control within the source code."),
+          "results" => Primitives.desc(Primitives.array(CONTROL_RESULT.ref), %q(
+             The set of all tests within the control and their results and findings.  Example:
+             For Chef Inspec, if in the control's code we had the following:
+               describe sshd_config do
+                 its('Port') { should cmp 22 }
+               end
+             The findings from this block would be appended to the results, as well as those of any other blocks within the control.
+          )),
         },
-      }, [CONTROL_DESCRIPTION, Primitives::REFERENCE, Primitives::SOURCE_LOCATION, CONTROL_RESULT])
+      }, [CONTROL_DESCRIPTION, Primitives::REFERENCE, Primitives::SOURCE_LOCATION, CONTROL_RESULT], "Describes a control and any findings it has.")
 
       # Based loosely on https://docs.chef.io/inspec/profiles/ as of July 3, 2019
       # However, concessions were made to the reality of current reporters, specifically
@@ -86,30 +87,30 @@ module Inspec
         # sha256, status, status_message
         "properties" => {
           # These are provided in inspec.yml
-          "name" => Primitives::STRING,
-          "title" => Primitives::STRING,
-          "maintainer" => Primitives::STRING,
-          "copyright" => Primitives::STRING,
-          "copyright_email" => Primitives::STRING,
-          "depends" => Primitives.array(Primitives::DEPENDENCY.ref),
-          "parent_profile" => Primitives::STRING,
-          "license" => Primitives::STRING,
-          "summary" => Primitives::STRING,
-          "version" => Primitives::STRING,
-          "supports" => Primitives.array(Primitives::SUPPORT.ref),
-          "description" => Primitives::STRING,
-          "inspec_version" => Primitives::STRING,
+          "name" => Primitives.desc(Primitives::STRING, "The name - must be unique."),
+          "title" => Primitives.desc(Primitives::STRING, "The title - should be human readable."),
+          "maintainer" => Primitives.desc(Primitives::STRING, "The maintainer(s)."),
+          "copyright" => Primitives.desc(Primitives::STRING, "The copyright holder(s)."),
+          "copyright_email" => Primitives.desc(Primitives::STRING, "The email address or other contact information of the copyright holder(s)."),
+          "depends" => Primitives.desc(Primitives.array(Primitives::DEPENDENCY.ref), "The set of dependencies this profile depends on.  Example: an overlay profile is dependent on another profile."),
+          "parent_profile" => Primitives.desc(Primitives::STRING, "The name of the parent profile if the profile is a dependency of another."),
+          "license" => Primitives.desc(Primitives::STRING, "The copyright license.  Example: the full text or the name, such as 'Apache License, Version 2.0'."),
+          "summary" => Primitives.desc(Primitives::STRING, "The summary.  Example: the Security Technical Implementation Guide (STIG) header."),
+          "version" => Primitives.desc(Primitives::STRING, "The version of the profile."),
+          "supports" => Primitives.desc(Primitives.array(Primitives::SUPPORT.ref), "The set of supported platform targets."),
+          "description" => Primitives.desc(Primitives::STRING, "The description - should be more detailed than the summary."),
+          "inspec_version" => Primitives.desc(Primitives::STRING, "The version of Inspec."),
 
           # These are generated at runtime, and all except status_message and skip_message are guaranteed
-          "sha256" => Primitives::STRING,
-          "status" => Primitives::STRING,
-          "status_message" => Primitives::STRING, # If skipped or failed to load, why
-          "skip_message" => Primitives::STRING,   # Deprecated field storing reason for skipping. status_message should be used instead.
-          "controls" => Primitives.array(CONTROL.ref),
-          "groups" => Primitives.array(Primitives::CONTROL_GROUP.ref),
-          "attributes" => Primitives.array(Primitives::INPUT),
+          "sha256" => Primitives.desc(Primitives::STRING, "The checksum of the profile."),
+          "status" => Primitives.desc(Primitives::STRING, "The status.  Example: loaded."), # enum? loaded, failed, skipped
+          "status_message" => Primitives.desc(Primitives::STRING, "The reason for the status.  Example: why it was skipped or failed to load."),
+          "skip_message" => Primitives.desc(Primitives::STRING, "The reason for skipping if it was skipped."), # Deprecated field - status_message should be used instead.
+          "controls" => Primitives.desc(Primitives.array(CONTROL.ref), "The set of controls including any findings."),
+          "groups" => Primitives.desc(Primitives.array(Primitives::CONTROL_GROUP.ref), "A set of descriptions for the control groups.  Example: the ids of the controls."),
+          "attributes" => Primitives.desc(Primitives.array(Primitives::INPUT), "The input(s) or attribute(s) used in the run."),
         },
-      }, [CONTROL, Primitives::CONTROL_GROUP, Primitives::DEPENDENCY, Primitives::SUPPORT])
+      }, [CONTROL, Primitives::CONTROL_GROUP, Primitives::DEPENDENCY, Primitives::SUPPORT], "Information on the set of controls assessed.  Example: it can include the name of the Inspec profile and any findings.")
 
       # Result of exec json. Top level value
       # TODO: Include the format of top level controls. This was omitted for lack of sufficient examples
@@ -118,12 +119,12 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{platform profiles statistics version},
         "properties" => {
-          "platform" => Primitives::PLATFORM.ref,
-          "profiles" => Primitives.array(PROFILE.ref),
-          "statistics" => Primitives::STATISTICS.ref,
-          "version" => Primitives::STRING,
+          "platform" => Primitives.desc(Primitives::PLATFORM.ref, "Information on the platform the run from the tool that generated the findings was from.  Example: the name of the operating system."),
+          "profiles" => Primitives.desc(Primitives.array(PROFILE.ref), "Information on the run(s) from the tool that generated the findings.  Example: the findings."),
+          "statistics" => Primitives.desc(Primitives::STATISTICS.ref, "Statistics for the run(s) from the tool that generated the findings.  Example: the runtime duration."),
+          "version" => Primitives.desc(Primitives::STRING, "Version number of the tool that generated the findings.  Example: '4.18.108' is a version of Chef InSpec."),
         },
-      }, [Primitives::PLATFORM, PROFILE, Primitives::STATISTICS])
+      }, [Primitives::PLATFORM, PROFILE, Primitives::STATISTICS], "The top level value containing all of the results.")
     end
   end
 end

data/lib/inspec/schema/exec_json_min.rb

@@ -1,6 +1,6 @@
 require "inspec/schema/primitives"
 
-# These type occur only when running "exec --reporter json-min <file>".
+# These type occur only when running "exec --reporter exec-jsonmin <file>".
 
 module Inspec
   module Schema
@@ -11,28 +11,28 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{id profile_id profile_sha256 status code_desc},
         "properties" => {
-          "id" => Primitives::STRING,
-          "profile_id" => { "type" => %w{string null} },
-          "profile_sha256" => Primitives::STRING,
-          "status" => Primitives::STRING,
-          "code_desc" => Primitives::STRING,
-          "skip_message" => Primitives::STRING,
-          "resource" => Primitives::STRING,
-          "message" => Primitives::STRING,
-          "exception" => Primitives::STRING,
-          "backtrace" => Primitives.array(Primitives::STRING),
+          "id" => Primitives.desc(Primitives::STRING, "The id."),
+          "profile_id" => Primitives.desc({ "type" => %w{string null} }, "The name of the profile that can uniquely identify it - is nullable."),
+          "profile_sha256" => Primitives.desc(Primitives::STRING, "The checksum of the profile."),
+          "status" => Primitives.desc(Primitives::STRING, "The status of the control.  Example: 'failed'."),
+          "code_desc" => Primitives.desc(Primitives::STRING, "A description of the control.  Example: 'limits.conf * is expected to include ['hard', 'maxlogins', '10']."),
+          "message" => Primitives.desc(Primitives::STRING, "An explanation of the control status - usually only provided when the control fails."),
+          "skip_message" => Primitives.desc(Primitives::STRING, "An explanation of the status if the status was 'skipped'."),
+          "resource" => Primitives.desc(Primitives::STRING, "The resource used in the test.  Example: in Inspec, you can use the 'File' resource."),
+          "exception" => Primitives.desc(Primitives::STRING, "The type of exception if an exception was thrown."),
+          "backtrace" => Primitives.desc(Primitives.array(Primitives::STRING), "The stacktrace/backtrace of the exception if one occurred."), # shouldn't this also be an anyOf similar to the CONTROL_RESULT from exec_json?
         },
-      }, [])
+      }, [], "The set of all tests within the control and their results and findings.")
 
       # Result of exec jsonmin. Top level value
-      OUTPUT = Primitives::SchemaType.new("Exec JSON-MIN output", {
+      OUTPUT = Primitives::SchemaType.new("Exec JSON-MIN Output", {
         "type" => "object",
         "additionalProperties" => true,
         "required" => %w{statistics controls version},
         "properties" => {
-          "statistics" => Primitives::STATISTICS.ref,
-          "version" => Primitives::STRING,
-          "controls" => Primitives.array(CONTROL.ref),
+          "statistics" => Primitives.desc(Primitives::STATISTICS.ref, "Statistics for the run(s) from the tool that generated the findings.  Example: the runtime duration."),
+          "version" => Primitives.desc(Primitives::STRING, "Version number of the tool that generated the findings.  Example: '4.18.108' is a version of Chef Inspec."),
+          "controls" => Primitives.desc(Primitives.array(CONTROL.ref), "The set of controls including any findings as reported by the tool."),
         },
       }, [Primitives::STATISTICS, CONTROL])
     end