inspec-core 4.56.19 → 5.12.2

data/lib/inspec/resources/routing_table.rb

@@ -0,0 +1,137 @@
+require "inspec/resources/command"
+
+module Inspec::Resources
+  class Routingtable < Inspec.resource(1)
+    # resource internal name.
+    name "routing_table"
+
+    # Restrict to only run on the below platforms (if none were given,
+    # all OS's and cloud API's supported)
+    supports platform: "unix"
+    supports platform: "windows"
+
+    desc "Use the `routing_table` Chef InSpec audit resource to test the routing information parameters(destination, gateway and interface) present in the routing table."
+
+    example <<~EXAMPLE
+      describe routing_table do
+        it do
+          should have_entry(
+            :destination => '192.168.43.1/32',
+            :interface   => 'lxdbr0',
+            :gateway     => '172.31.80.1',
+          )
+        end
+      end
+
+      describe routing_table do
+        it { should have_entry(destination: '0.0.0.0', interface: 'eth0', gateway: '172.31.80.1') }
+      end
+    EXAMPLE
+
+    def initialize
+      skip_resource "The `routing_table` resource is not yet available on your OS." unless inspec.os.unix? || inspec.os.windows?
+      # fetch the routing information and store it in @routing_info (could be hash, tbd)
+      @routing_info = {}
+      fetch_routing_information
+    end
+
+    # resource appearance in test reports.
+    def to_s
+      "routing_table"
+    end
+
+    def has_entry?(input_route)
+      # check if the destination, gateway, interface exists as part of the routing_info
+      if input_route.key?(:destination) && input_route.key?(:gateway) && input_route.key?(:interface)
+        # check if there is key with destination's value in hash;
+        # if yes, check if destination and gateway is present else return false
+        @routing_info.key?(input_route[:destination]) ? @routing_info[input_route[:destination]].include?([input_route[:gateway], input_route[:interface]]) : false
+      else
+        raise Inspec::Exceptions::ResourceSkipped, "One or more missing key, have_entry? matcher expects a hash with 3 keys: destination, gateway and interface"
+      end
+    end
+
+    private
+
+    # fetches the routing information for the system
+    def fetch_routing_information
+      # check if netstat is available on the system
+      utility = find_netstat_or_error
+
+      # the command to fetch the routing information
+      fetch_route_cmd = "#{utility} -rn"
+
+      # execute the above netstat command
+      cmd = inspec.command(fetch_route_cmd)
+
+      # raise error if the exit status is not zero;
+      raise Inspec::Exceptions::ResourceFailed, "Executing netstat failed: #{cmd.stderr}" if cmd.exit_status.to_i != 0
+
+      # Todo:
+      # Improve logic to fetch destination, gateway & interface efficiently.
+      # The below logic assumes the following:
+      # 1. destination, gateway & interface header is present as Destination, Gateway & (Iface or Netif or Interface) respectively.
+      #    (Netif on BSD, Darwin,Iface on linux & Interface on Windows)
+      # 2. there is no blank data for any columns or the blank data are present after the interface column.
+
+      # cmd.stdout is the standard out of netstat -rn; split on new line to get the rows
+      raw_route_info = cmd.stdout.split("\n")
+
+      # since raw_route_info contains some row before the header (i.e. Destination Gateway ...); remove those rows
+      raw_route_info.shift until raw_route_info[0] =~ /Destination/i
+
+      # split each rows based on space to get the individual columns
+      # raw_route_info is now array of arrays with the routing information
+      raw_route_info.map! { |info| info.strip.split }
+
+      # these variables will store the indices where destination, gateway and interface are present
+      destination_index, gateway_index, interface_index = -1, -1, -1
+
+      # The headers in windows are as:
+      # Network Destination        Netmask          Gateway       Interface  Metric
+      # Splitting on space makes "Network Destination" to be two separate values as "Network" & "Destination"
+      # Remove "Network" value to apply the logic of finding index
+      raw_route_info[0].shift if inspec.os.windows?
+
+      # find the indices of destination, gateway and interface;
+      # because the position of gateway & interface varies with operating system
+      raw_route_info[0].each_with_index do |header, index|
+        if header =~ /Destination/i
+          destination_index = index
+        elsif header =~ /Gateway/i
+          gateway_index = index
+        elsif header =~ /Iface|Netif|Interface/i
+          interface_index = index
+        end
+      end
+
+      # remove the initial header consisting of Destination, Gateway, Mask, ... since this is of no use
+      raw_route_info.shift
+
+      # check the indices are assigned with some index and not -1
+      if destination_index != -1 && gateway_index != -1 && interface_index != -1
+        # iterate through the route_info; and find destination, gateway and interface from each row
+        raw_route_info.each do |info|
+          # if value exists at the destination_index, gateway_index, and interface_index; store the value in @routing_info
+          if !info[destination_index].nil? && !info[gateway_index].nil? && !info[interface_index].nil?
+            # if the destination_key is already present, append the gateway & interface; else create new array and add them
+            if @routing_info.key?(info[destination_index])
+              @routing_info[info[destination_index]] << [info[gateway_index], info[interface_index]]
+            else
+              @routing_info[info[destination_index]] = [[info[gateway_index], info[interface_index]]]
+            end
+          end
+        end
+      end
+    end
+
+    # check if netstat is available on the system
+    def find_netstat_or_error
+      %w{/usr/sbin/netstat /sbin/netstat /usr/bin/netstat /bin/netstat netstat}.each do |cmd|
+        return cmd if inspec.command(cmd).exist?
+      end
+
+      raise Inspec::Exceptions::ResourceFailed, "Could not find `netstat` utility to view routing table information"
+    end
+  end
+end

data/lib/inspec/resources/service.rb

@@ -537,9 +537,22 @@ module Inspec::Resources
     end
 
     def info(service_name)
+      # `service -l` lists all files in /etc/rc.d and the local startup directories
+      # % service -l
+      # accounting
+      # addswap
+      # adjkerntz
+      # apm
+      # archdep
+      cmd = inspec.command("#{service_ctl} -l")
+      return nil if cmd.exit_status != 0
+
+      # search for the service
+      srv = /^#{service_name}$/.match(cmd.stdout)
+      return nil if srv.nil? || srv[0].nil?
+
       # check if service is enabled
       cmd = inspec.command("#{service_ctl} #{service_name} enabled")
-
       enabled = cmd.exit_status == 0
 
       # check if the service is running

data/lib/inspec/resources/user.rb

@@ -1 +1,13 @@
 require "inspec/resources/users"
+# user resource belong_to matcher for serverspec compatibility
+RSpec::Matchers.define :belong_to_primary_group do |group|
+  match do |user|
+    user.belongs_to_primary_group?(group)
+  end
+end
+
+RSpec::Matchers.define :belong_to_group do |group|
+  match do |user|
+    user.belongs_to_group?(group)
+  end
+end

data/lib/inspec/resources/users.rb

@@ -137,20 +137,17 @@ module Inspec::Resources
   #   its('badpasswordattempts') { should eq 0 }
   # end
   #
-  # The following  Serverspec  matchers are deprecated in favor for direct value access
+  # The following  Serverspec  matchers were deprecated in favor for direct value access
+  # but are made available as part of Serverspec compatibility in March, 2022.
   #
   # describe user('root') do
   #   it { should belong_to_group 'root' }
+  #   it { should belong_to_primary_group 'root' }
   #   it { should have_uid 0 }
   #   it { should have_home_directory '/root' }
   #   it { should have_login_shell '/bin/bash' }
   #   its('minimum_days_between_password_change') { should eq 0 }
   #   its('maximum_days_between_password_change') { should eq 99 }
-  # end
-  #
-  # ServerSpec tests that are not supported:
-  #
-  # describe user('root') do
   #   it { should have_authorized_key 'ssh-rsa ADg54...3434 user@example.local' }
   #   its(:encrypted_password) { should eq 1234 }
   # end
@@ -258,36 +255,56 @@ module Inspec::Resources
 
     # implement 'mindays' method to be compatible with serverspec
     def minimum_days_between_password_change
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `minimum_days_between_password_change` property is deprecated. Please use `mindays`.")
       mindays
     end
 
     # implement 'maxdays' method to be compatible with serverspec
     def maximum_days_between_password_change
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `maximum_days_between_password_change` property is deprecated. Please use `maxdays`.")
       maxdays
     end
 
     # implements rspec has matcher, to be compatible with serverspec
     # @see: https://github.com/rspec/rspec-expectations/blob/master/lib/rspec/matchers/built_in/has.rb
+    # has_uid matcher: compatibility with serverspec
     def has_uid?(compare_uid)
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `has_uid?` matcher is deprecated.")
       uid == compare_uid
     end
 
+    # has_home_directory matcher: compatibility with serverspec
     def has_home_directory?(compare_home)
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `has_home_directory?` matcher is deprecated. Please use `its('home')`.")
       home == compare_home
     end
 
+    # has_login_shell matcher: compatibility with serverspec
     def has_login_shell?(compare_shell)
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `has_login_shell?` matcher is deprecated. Please use `its('shell')`.")
       shell == compare_shell
     end
 
-    def has_authorized_key?(_compare_key)
-      Inspec.deprecate(:resource_user_serverspec_compat, "The user resource `has_authorized_key?` matcher is deprecated. There is no currently implemented alternative")
-      raise NotImplementedError
+    # has_authorized_key matcher: compatibility with serverspec
+    def has_authorized_key?(compare_key)
+      # get_authorized_keys returns the list of key, check if given key is included.
+      get_authorized_keys.include?(compare_key)
+    end
+
+    # belongs_to_primary_group matcher: compatibility with serverspec
+    def belongs_to_primary_group?(group_name)
+      groupname == group_name
+    end
+
+    # belongs_to_group matcher: compatibility with serverspec
+    def belongs_to_group?(group_name)
+      groups.include?(group_name)
+    end
+
+    # encrypted_password property: compatibility with serverspec
+    # it allows to run test against the hashed passwords of the given user
+    # applicable for unix/linux systems with getent utility.
+    def encrypted_password
+      raise Inspec::Exceptions::ResourceSkipped, "encrypted_password property is not applicable for your system" if inspec.os.windows? || inspec.os.darwin?
+
+      # shadow_information returns array of the information from the shadow file
+      # the value at 1st index is the encrypted_password information
+      shadow_information[1]
     end
 
     def to_s
@@ -314,6 +331,54 @@ module Inspec::Resources
 
       @cred_cache = @user_provider.credentials(@username) unless @user_provider.nil?
     end
+
+    # helper method for has_authorized_key matcher
+    # get_authorized_keys return the key/keys stored in the authorized_keys path
+    def get_authorized_keys
+      # cat is used in unix system to display content of file; similarly type is used for windows
+      bin = inspec.os.windows? ? "type" : "cat"
+
+      # auth_path gets assigned with the valid path for authorized_keys
+      auth_path = ""
+
+      # possible paths where authorized_keys are stored
+      # inspec.command is used over inspec.file because inspec.file requires absolute path
+      %w{~/.ssh/authorized_keys ~/.ssh/authorized_keys2}.each do |path|
+        if inspec.command("#{bin} #{path}").exit_status == 0
+          auth_path = path
+          break
+        end
+      end
+
+      # if auth_path is empty, no valid path was found, hence raise exception
+      raise Inspec::Exceptions::ResourceSkipped, "Can't find any valid path for authorized_keys" if auth_path.empty?
+
+      # authorized_keys are obtained in the standard output;
+      # split keys on newline if more than one keys are part of authorized_keys
+      inspec.command("#{bin} #{auth_path}").stdout.split("\n").map(&:strip)
+    end
+
+    # Helper method for encrypted_password property
+    def shadow_information
+      # check if getent is available on the system
+      bin = find_getent_utility
+
+      # fetch details of the passwd file for the current user using getent
+      cmd = inspec.command("#{bin} shadow #{@username}")
+      raise Inspec::Exceptions::ResourceFailed, "Executing #{bin} shadow #{@username} failed: #{cmd.stderr}" if cmd.exit_status.to_i != 0
+
+      # shadow information are : separated values, split and return
+      cmd.stdout.split(":").map(&:strip)
+    end
+
+    # check if getent exist in the system
+    def find_getent_utility
+      %w{/usr/bin/getent /bin/getent getent}.each do |cmd|
+        return cmd if inspec.command(cmd).exist?
+      end
+
+      raise Inspec::Exceptions::ResourceFailed, "Could not find `getent` on your system."
+    end
   end
 
   # Class defined to compare for groups without case-sensitivity

data/lib/inspec/resources/virtualization.rb

@@ -190,7 +190,7 @@ module Inspec::Resources
       true
     end
 
-    # Detect LXC/Docker
+    # Detect LXC/Docker/k8s/podman
     #
     # /proc/self/cgroup will look like this inside a docker container:
     # <index #>:<subsystem>:/lxc/<hexadecimal container id>
@@ -208,7 +208,7 @@ module Inspec::Resources
     #
     # Full notes, https://tickets.opscode.com/browse/OHAI-551
     # Kernel docs, https://www.kernel.org/doc/Documentation/cgroups
-    def detect_lxc_docker
+    def detect_container
       return false unless inspec.file("/proc/self/cgroup").exist?
 
       cgroup_content = inspec.file("/proc/self/cgroup").content
@@ -216,6 +216,12 @@ module Inspec::Resources
           cgroup_content =~ %r{^\d+:[^:]+:/[^/]+/(lxc|docker)-.+$} # rubocop:disable Layout/MultilineOperationIndentation
         @virtualization_data[:system] = $1 # rubocop:disable Style/PerlBackrefs
         @virtualization_data[:role] = "guest"
+      elsif cgroup_content =~ %r{^\d+:[^:]+:/(kubepods)/.+$}
+        @virtualization_data[:system] = $1
+        @virtualization_data[:role] = "guest"
+      elsif /container=podman/.match?(file_read("/proc/1/environ"))
+        @virtualization_data[:system] = "podman"
+        @virtualization_data[:role] = "guest"
       elsif lxc_version_exists? && cgroup_content =~ %r{\d:[^:]+:/$}
         # lxc-version shouldn't be installed by default
         # Even so, it is likely we are on an LXC capable host that is not being used as such
@@ -297,7 +303,7 @@ module Inspec::Resources
       return if detect_docker
       return if detect_virtualbox
       return if detect_lxd
-      return if detect_lxc_docker
+      return if detect_container
       return if detect_linux_vserver
       return if detect_kvm_from_cpuinfo
       return if detect_kvm_from_sys

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