inspec-core 4.56.58 → 5.7.9

data/lib/inspec/resources/ibmdb2_session.rb

@@ -1,11 +1,10 @@
 module Inspec::Resources
   class Lines
-    attr_reader :output, :exit_status
+    attr_reader :output
 
-    def initialize(raw, desc, exit_status)
+    def initialize(raw, desc)
       @output = raw
       @desc = desc
-      @exit_status = exit_status
     end
 
     def to_s
@@ -59,7 +58,7 @@ module Inspec::Resources
       if cmd.exit_status != 0 || out =~ /Can't connect to IBM Db2 / || out.downcase =~ /^error:.*/
         raise Inspec::Exceptions::ResourceFailed, "IBM Db2 connection error: #{out}"
       else
-        Lines.new(cmd.stdout.strip, "IBM Db2 Query: #{q}", cmd.exit_status)
+        Lines.new(cmd.stdout.strip, "IBM Db2 Query: #{q}")
       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/mongodb_session.rb

@@ -4,10 +4,9 @@ module Inspec::Resources
   class Lines
     attr_reader :params
 
-    def initialize(raw, desc, exit_status = nil)
+    def initialize(raw, desc)
       @params = raw
       @desc = desc
-      @exit_status = exit_status
     end
 
     def to_s
@@ -80,11 +79,6 @@ module Inspec::Resources
       options[:ssl_cert] = @ssl_cert unless @ssl_cert.nil?
       options[:ssl_ca_cert] = @ssl_ca_cert unless @ssl_ca_cert.nil?
 
-      # Setting the logger level to INFO as mongo gem version 2.13.2 is using DEBUG as the log level Ref: https://github.com/mongodb/mongo-ruby-driver/blob/v2.13.2/lib/mongo/logger.rb#L79
-      # Latest version of the mongo gem don't have this issue as it set to INFO level Ref: https://github.com/mongodb/mongo-ruby-driver/blob/master/lib/mongo/logger.rb#L82
-      # We pinned the version to 2.13.2 as the latest version of the mongo gem has broken symlink https://jira.mongodb.org/browse/RUBY-2546 which causes omnibus build failure.
-      # Once we get the latest version working we can remove logger level set here.
-      Mongo::Logger.logger.level = Logger::INFO
       @client = Mongo::Client.new([ "#{host}:#{port}" ], options)
 
     rescue => e

data/lib/inspec/resources/oracledb_session.rb

@@ -61,13 +61,9 @@ module Inspec::Resources
         raise Inspec::Exceptions::ResourceFailed, "Oracle query with errors: #{out}"
       else
         begin
-          unless inspec_cmd.stdout.empty?
-            DatabaseHelper::SQLQueryResult.new(inspec_cmd, parse_csv_result(inspec_cmd.stdout))
-          else
-            inspec_cmd.stdout
-          end
-        rescue Exception => ex
-          raise Inspec::Exceptions::ResourceFailed, "Oracle query with exception: #{ex}"
+          DatabaseHelper::SQLQueryResult.new(inspec_cmd, parse_csv_result(inspec_cmd.stdout))
+        rescue
+          raise Inspec::Exceptions::ResourceFailed, "Oracle query with errors: #{out}"
         end
       end
     end
@@ -91,31 +87,22 @@ module Inspec::Resources
         verified_query = verify_query(escaped_query)
       end
 
-      sql_prefix, sql_postfix, oracle_echo_str = "", "", ""
+      sql_prefix, sql_postfix = "", ""
       if inspec.os.windows?
         sql_prefix = %{@'\n#{format_options}\n#{verified_query}\nEXIT\n'@ | }
       else
         sql_postfix = %{ <<'EOC'\n#{format_options}\n#{verified_query}\nEXIT\nEOC}
-        # oracle_query_string is echoed to be able to extract the query output clearly
-        oracle_echo_str = %{echo 'oracle_query_string';}
-      end
-
-      # Resetting sql_postfix if system is using AIX OS and C shell installation for oracle
-      if inspec.os.aix?
-        command_to_fetch_shell = @su_user ? %{su - #{@su_user} -c "env | grep SHELL"} : %{env | grep SHELL}
-        shell_is_csh = inspec.command(command_to_fetch_shell).stdout&.include? "/csh"
-        sql_postfix = %{ <<'EOC'\n#{format_options}\n#{verified_query}\nEXIT\n'EOC'} if shell_is_csh
       end
 
       if @db_role.nil?
-        %{#{oracle_echo_str}#{sql_prefix}#{bin} #{user}/#{password}@#{host}:#{port}/#{@service}#{sql_postfix}}
+        %{#{sql_prefix}#{bin} #{user}/#{password}@#{host}:#{port}/#{@service}#{sql_postfix}}
       elsif @su_user.nil?
-        %{#{oracle_echo_str}#{sql_prefix}#{bin} #{user}/#{password}@#{host}:#{port}/#{@service} as #{@db_role}#{sql_postfix}}
+        %{#{sql_prefix}#{bin} #{user}/#{password}@#{host}:#{port}/#{@service} as #{@db_role}#{sql_postfix}}
       else
         # oracle_query_string is echoed to be able to extract the query output clearly
         # su - su_user in certain versions of oracle returns a message
         # Example of msg with query output: The Oracle base remains unchanged with value /oracle\n\nVALUE\n3\n
-        %{su - #{@su_user} -c "#{oracle_echo_str} env ORACLE_SID=#{@service} #{@bin} / as #{@db_role}#{sql_postfix}"}
+        %{su - #{@su_user} -c "echo 'oracle_query_string'; env ORACLE_SID=#{@service} #{@bin} / as #{@db_role}#{sql_postfix}"}
       end
     end
 

data/lib/inspec/resources/postgres_session.rb

@@ -4,9 +4,9 @@ require "shellwords" unless defined?(Shellwords)
 
 module Inspec::Resources
   class Lines
-    attr_reader :output, :exit_status
+    attr_reader :output
 
-    def initialize(raw, desc, exit_status)
+    def initialize(raw, desc)
       @output = raw
       @desc = desc
     end
@@ -55,12 +55,10 @@ module Inspec::Resources
       psql_cmd = create_psql_cmd(query, db)
       cmd = inspec.command(psql_cmd, redact_regex: %r{(:\/\/[a-z]*:).*(@)})
       out = cmd.stdout + "\n" + cmd.stderr
-      if cmd.exit_status != 0 && ( out =~ /could not connect to/ || out =~ /password authentication failed/ ) && out.downcase =~ /error:/
-        raise Inspec::Exceptions::ResourceFailed, "PostgreSQL connection error: #{out}"
-      elsif cmd.exit_status != 0 && out.downcase =~ /error:/
-        Lines.new(out, "PostgreSQL query with error: #{query}", cmd.exit_status)
+      if cmd.exit_status != 0 || out =~ /could not connect to .*/ || out.downcase =~ /^error:.*/
+        raise Inspec::Exceptions::ResourceFailed, "PostgreSQL query with errors: #{out}"
       else
-        Lines.new(cmd.stdout.strip, "PostgreSQL query: #{query}", cmd.exit_status)
+        Lines.new(cmd.stdout.strip, "PostgreSQL query: #{query}")
       end
     end
 

data/lib/inspec/resources/processes.rb

@@ -43,7 +43,7 @@ module Inspec::Resources
 
       all_cmds = ps_axo
       @list = all_cmds.find_all do |hm|
-        hm[:command] =~ grep || hm[:process_name] =~ grep
+        hm[:command] =~ grep
       end
     end
 
@@ -73,7 +73,6 @@ module Inspec::Resources
       .register_column(:time,     field: "time")
       .register_column(:users,    field: "user")
       .register_column(:commands, field: "command")
-      .register_column(:process_name, field: "process_name")
       .install_filter_methods_on_resource(self, :filtered_processes)
 
     private
@@ -88,9 +87,9 @@ module Inspec::Resources
       if os.linux?
         command, regex, field_map = ps_configuration_for_linux
       elsif os.windows?
-        command = '$Proc = Get-Process -IncludeUserName | Select-Object PriorityClass,Id,CPU,PM,VirtualMemorySize,NPM,SessionId,Responding,StartTime,TotalProcessorTime,UserName,Path,ProcessName | ConvertTo-Csv -NoTypeInformation;$Proc.Replace("""","").Replace("`r`n","`n")'
+        command = '$Proc = Get-Process -IncludeUserName | Where-Object {$_.Path -ne $null } | Select-Object PriorityClass,Id,CPU,PM,VirtualMemorySize,NPM,SessionId,Responding,StartTime,TotalProcessorTime,UserName,Path | ConvertTo-Csv -NoTypeInformation;$Proc.Replace("""","").Replace("`r`n","`n")'
         # Wanted to use /(?:^|,)([^,]*)/; works on rubular.com not sure why here?
-        regex = /^(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*),(.*)$/
+        regex = /^(.+),(.+),(.+),(.+),(.+),(.+),(.+),(.+),(.+),(.+),(.+),(.+)$/
         field_map = {
           pid: 2,
           cpu: 3,
@@ -103,7 +102,6 @@ module Inspec::Resources
           time: 10,
           user: 11,
           command: 12,
-          process_name: 13,
         }
       else
         command = "ps axo pid,pcpu,pmem,vsz,rss,tty,stat,start,time,user,command"
@@ -195,7 +193,7 @@ module Inspec::Resources
 
         # build a hash of process data that we'll turn into a struct for FilterTable
         process_data = {}
-        %i{label pid cpu mem vsz rss tty stat start time user command process_name}.each do |param|
+        %i{label pid cpu mem vsz rss tty stat start time user command}.each do |param|
           # not all operating systems support all fields, so skip the field if we don't have it
           process_data[param] = line[field_map[param]] if field_map.key?(param)
         end

data/lib/inspec/resources/service.rb

@@ -182,9 +182,7 @@ module Inspec::Resources
       when "aix"
         SrcMstr.new(inspec)
       when "amazon"
-        # If `initctl` exists on the system, use `Upstart`. Else use `Systemd` since all-new Amazon Linux supports `systemctl`.
-        # This way, it is not dependent on the version of Amazon Linux.
-        if inspec.command("initctl").exist? || inspec.command("/sbin/initctl").exist?
+        if os[:release] =~ /^20\d\d/
           Upstart.new(inspec, service_ctl)
         else
           Systemd.new(inspec, service_ctl)
@@ -605,7 +603,7 @@ module Inspec::Resources
       return nil if srv.nil? || srv[0].nil?
 
       # extract values from service
-      parsed_srv = /^(?<pid>[0-9-]+)\t(?<exit>[\-0-9]+)\t(?<name>\S*)$/.match(srv[0])
+      parsed_srv = /^(?<pid>[0-9-]+)\t(?<exit>[0-9]+)\t(?<name>\S*)$/.match(srv[0])
       enabled = !parsed_srv["name"].nil? # it's in the list
 
       # check if the service is running

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/rule.rb

@@ -358,7 +358,7 @@ module Inspec
         # YAML will automagically give us a Date or a Time.
         # If transcoding YAML between languages (e.g. Go) the date might have also ended up as a String.
         # A string that does not represent a valid time results in the date 0000-01-01.
-        if [Date, Time].include?(expiry.class) || (expiry.is_a?(String) && Time.parse(expiry).year != 0)
+        if [Date, Time].include?(expiry.class) || (expiry.is_a?(String) && Time.new(expiry).year != 0)
           expiry = expiry.to_time if expiry.is_a? Date
           expiry = Time.parse(expiry) if expiry.is_a? String
           if expiry < Time.now # If the waiver expired, return - no skip applied

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