inspec-core 4.56.17 → 5.10.5

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

data/lib/inspec/schema/primitives.rb

@@ -35,7 +35,7 @@ module Inspec
       # Use this class to quickly add/use object types to/in a definition block
       class SchemaType
         attr_accessor :name, :depends
-        def initialize(name, body, dependencies)
+        def initialize(name, body, dependencies, description = nil)
           # Validate the schema
           Primitives.validate_schema(body)
           # The title of the type
@@ -44,14 +44,17 @@ module Inspec
           @body = body
           # What SchemaType[]s it depends on. In essence, any thing that you .ref in the body
           @depends = Set.new(dependencies)
+          # The description of the type
+          @description = description
         end
 
         # Produce this schema types generated body.
         # Use to actually define the ref!
         def body
           @body.merge({
+              "description" => @description,
               "title" => @name,
-          })
+          }).compact
         end
 
         # Formats this to have a JSON pointer compatible title
@@ -89,22 +92,32 @@ module Inspec
       URL = { "type" => "string" }.freeze
 
       # A controls tags can have any number of properties, and any sorts of values
-      TAGS = { "type" => "object", "additionalProperties" => true }.freeze
+      TAGS = {
+        "type" => "object",
+        "additionalProperties" => true,
+        "description" => "A set of any number of tags - they can have any sort of value and are usually metadata.  Example: 'nist' => ['AC-10'].",
+      }.freeze
 
       # Attributes/Inputs specify the inputs to a profile.
-      INPUT = { "type" => "object", "additionalProperties" => true }.freeze
+      INPUT = {
+        "type" => "object",
+        "additionalProperties" => true,
+        "description" => "An input or attribute used in the run.",
+      }.freeze
 
-      # Within a control file, impacts can be numeric 0-1 or string in [none,low,medium,high,critical]
-      # However, when they are output, the string types are automatically converted as follows:
-      # none      -> 0    to 0.01
-      # low       -> 0.01 to 0.4
-      # medium    -> 0.4  to 0.7
-      # high      -> 0.7  to 0.9
-      # Critical  -> 0.9  to 1.0 (inclusive)
       IMPACT = {
         "type" => "number",
         "minimum" => 0.0,
         "maximum" => 1.0,
+        "description" => %q{
+           Within a control file, impacts can be a decimal number in the range [0,1] or a string that is one of [none,low,medium,high,critical].
+           However, the string will be automatically converted as follows:
+           none      -> 0    to 0.01
+           low       -> 0.01 to 0.4
+           medium    -> 0.4  to 0.7
+           high      -> 0.7  to 0.9
+           critical  -> 0.9  to 1.0
+        },
       }.freeze
 
       # A status for a control
@@ -123,9 +136,9 @@ module Inspec
         "additionalProperties" => true,
         "required" => ["total"],
         "properties" => {
-          "total" => desc(NUMBER, "Total number of controls (in this category) for this inspec execution."),
+          "total" => desc(NUMBER, "The total.  Example: the total number of controls in a given category for a run."),
         },
-      }, [])
+      }, [], "Statistics for a given item, such as the total.")
 
       # Bundles several results statistics, representing distinct groups of controls
       STATISTIC_GROUPING = SchemaType.new("Statistic Hash", {
@@ -133,11 +146,11 @@ module Inspec
         "additionalProperties" => true,
         "required" => [],
         "properties" => {
-            "passed" => STATISTIC_ITEM.ref,
-            "skipped" => STATISTIC_ITEM.ref,
-            "failed" => STATISTIC_ITEM.ref,
+          "passed" => desc(STATISTIC_ITEM.ref, "Statistics for the controls that passed."),
+          "skipped" => desc(STATISTIC_ITEM.ref, "Statistics for the controls that were skipped."),
+          "failed" => desc(STATISTIC_ITEM.ref, "Statistics for the controls that failed."),
         },
-      }, [STATISTIC_ITEM])
+      }, [STATISTIC_ITEM], "Statistics for the control results.")
 
       # Contains statistics of an exec run.
       STATISTICS = SchemaType.new("Statistics", {
@@ -145,10 +158,10 @@ module Inspec
         "additionalProperties" => true,
         "required" => ["duration"],
         "properties" => {
-          "duration" => desc(NUMBER, "How long (in seconds) this inspec exec ran for."),
+          "duration" => desc(NUMBER, "How long (in seconds) this run by the tool was."),
           "controls" => desc(STATISTIC_GROUPING.ref, "Breakdowns of control statistics by result"),
         },
-      }, [STATISTIC_GROUPING])
+      }, [STATISTIC_GROUPING], "Statistics for the run(s) such as how long it took.")
 
       # Profile dependencies
       DEPENDENCY = SchemaType.new("Dependency", {
@@ -156,17 +169,17 @@ module Inspec
         "additionalProperties" => true, # Weird stuff shows up here sometimes
         "required" => [], # Mysteriously even in a run profile we can have no status
         "properties" => {
-          "name" => STRING,
-          "url" => URL,
-          "branch" => STRING,
-          "path" => STRING,
-          "status_message" => STRING,
-          "status" => STRING,
-          "git" => URL,
-          "supermarket" => STRING,
-          "compliance" => STRING,
+          "name" => desc(STRING, "The name/assigned alias."),
+          "url" => desc(URL, "The address of the dependency."),
+          "branch" => desc(STRING, "The branch name for a git repo."),
+          "path" => desc(STRING, "The relative path if the dependency is locally available."),
+          "status_message" => desc(STRING, "The reason for the status if it is 'failed' or 'skipped'."),
+          "status" => desc(STRING, "The status.  Should be: 'loaded', 'failed', or 'skipped'."), # NOTE: enum?
+          "git" => desc(URL, "The location of the git repo.  Example: 'https://github.com/mitre/canonical-ubuntu-18.04-lts-stig-baseline.git'."),
+          "supermarket" => desc(STRING, "The 'user/profilename' attribute for a Supermarket server."),
+          "compliance" => desc(STRING, "The 'user/profilename' attribute for an Automate server."),
         },
-      }, [])
+      }, [], "A dependency for a profile.  Can include relative paths or urls for where to find the dependency.")
 
       # Represents the platform the test was run on
       PLATFORM = SchemaType.new("Platform", {
@@ -176,9 +189,9 @@ module Inspec
         "properties" => {
           "name" => desc(STRING, "The name of the platform this was run on."),
           "release" => desc(STRING, "The version of the platform this was run on."),
-          "target_id" => STRING,
+          "target_id" => desc(STRING, "The id of the target.  Example: the name and version of the operating system were not sufficient to identify the platform so a release identifier can additionally be provided like '21H2' for the release version of MS Windows 10."),
         },
-      }, [])
+      }, [], "Platform information such as its name.")
 
       # Explains what software ran the inspec profile/made this file. Typically inspec but could in theory be a different software
       GENERATOR = SchemaType.new("Generator", {
@@ -186,10 +199,10 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{name version},
         "properties" => {
-          "name" => desc(STRING, "The name of the software that generated this report."),
-          "version" => desc(STRING, "The version of the software that generated this report."),
+          "name" => desc(STRING, "The name.  Example: Chef Inspec."),
+          "version" => desc(STRING, "The version.  Example: 4.18.108."),
         },
-      }, [])
+      }, [], "The tool that generated this file.  Example: Chef Inspec.")
 
       # Occurs from "exec --reporter json" and "inspec json"
       # Denotes what file this control comes from, and where within
@@ -197,11 +210,11 @@ module Inspec
         "type" => "object",
         "additionalProperties" => true,
         "properties" => {
-          "ref" => desc(STRING, "Path to the file that this statement originates from"),
-          "line" => desc(NUMBER, "The line at which this statement is located in the file"),
+          "ref" => desc(STRING, "Path to the file that this control originates from."),
+          "line" => desc(NUMBER, "The line on which this control is located."),
         },
         "required" => %w{ref line},
-      }, [])
+      }, [], "The explicit location of the control.")
 
       # References an external document
       REFERENCE = SchemaType.new("Reference", {
@@ -211,26 +224,30 @@ module Inspec
             "type" => "object",
             "required" => ["ref"],
             "properties" => { "ref" => STRING },
+            "description" => "A human readable/meaningful reference.  Example: a book title.",
           },
           {
             "type" => "object",
             "required" => ["url"],
-            "properties" => { "url" => STRING },
+            "properties" => { "url" => STRING }, # NOTE: should this be a URL?
+            "description" => "A url pointing at the reference.",
           },
           {
             "type" => "object",
             "required" => ["uri"],
-            "properties" => { "uri" => STRING },
+            "properties" => { "uri" => STRING }, # NOTE: should this be a URL?
+            "description" => "A uri pointing at the reference.",
           },
           # I am of the opinion that this is just an error in the codebase itself. See profiles/wrapper-override to uncover new mysteries!
           {
             "type" => "object",
             "required" => ["ref"],
             "properties" => { "ref" => array(OBJECT) },
+            "description" => "", # TODO: I'm not sure what goes here.  Maybe it's supposed to be objects similar to { "title" => "blah", "text" => "blah" }?
 
           },
         ],
-      }, [])
+      }, [], "A reference to an external document.")
 
       # Represents a group of controls within a profile/.rb file
       CONTROL_GROUP = SchemaType.new("Control Group", {
@@ -238,11 +255,11 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{id controls},
         "properties" => {
-          "id" => desc(STRING, "The unique identifier of the group"),
-          "title" => desc({ type: %w{string null} }, "The name of the group"),
-          "controls" => desc(array(STRING), "The control IDs in this group"),
+          "id" => desc(STRING, "The unique identifier for the group.  Example: the relative path to the file specifying the controls."),
+          "title" => desc({ type: %w{string null} }, "The title of the group - should be human readable."), # NOTE: pretty unique type like this - wouldn't it be better to have it be a STRING and then continue to not make it required?
+          "controls" => desc(array(STRING), "The set of controls as specified by their ids in this group.  Example: 'V-75443'."),
         },
-      }, [])
+      }, [], "Descriptions for controls in a group, such as the list of all the controls.")
 
       # Occurs from "inspec exec --reporter json" and "inspec json"
       # Represents a platfrom or group of platforms that this profile supports
@@ -251,15 +268,15 @@ module Inspec
         "additionalProperties" => true, # NOTE: This should really be false, and inspec should validate profiles to ensure people don't make dumb mistakes like platform_family
         "required" => [],
         "properties" => {
-          "platform-family" => STRING,
-          "platform-name" => STRING,
-          "platform" => STRING,
-          "release" => STRING,
+          "platform-family" => desc(STRING, "The platform family.  Example: 'redhat'."),
+          "platform-name" => desc(STRING, "The platform name - can include wildcards.  Example: 'debian'."),
+          "platform" => desc(STRING, "The location of the platform.  Can be: 'os', 'aws', 'azure', or 'gcp'."), # NOTE: enum?
+          "release" => desc(STRING, "The release of the platform.  Example: '20.04' for 'ubuntu'."),
           # os-* supports are being deprecated
-          "os-family" => STRING,
-          "os-name" => STRING,
+          "os-family" => desc(STRING, "Deprecated in favor of platform-family."),
+          "os-name" => desc(STRING, "Deprecated in favor of platform-name."),
         },
-      }, [])
+      }, [], "A supported platform target.  Example: the platform name being 'ubuntu'.")
 
     end
   end

data/lib/inspec/schema/profile_json.rb

@@ -8,9 +8,9 @@ module Inspec
       # Represents descriptions. Can have any string => string pairing
       CONTROL_DESCRIPTIONS = Primitives::SchemaType.new("Profile JSON Control Descriptions", {
         "type" => "object",
-        "aditionalProperties" => Primitives::STRING,
+        "additionalProperties" => Primitives::STRING,
         "required" => [],
-      }, [])
+      }, [], "An arbitrary set of descriptions for a control.")
 
       # Represents a control that hasn't been run
       # Differs slightly from a normal control, in that it lacks results, and its descriptions are different
@@ -19,17 +19,17 @@ module Inspec
         "additionalProperties" => true,
         "required" => %w{id title desc impact tags code},
         "properties" => {
-          "id" => Primitives.desc(Primitives::STRING, "The ID of this control"),
-          "title" => { "type" => %w{string null} },
-          "desc" => { "type" => %w{string null} },
-          "descriptions" => CONTROL_DESCRIPTIONS.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,
+          "id" => Primitives.desc(Primitives::STRING, "The id."),
+          "title" => Primitives.desc({ "type" => %w{string null} }, "The title - is nullable."),
+          "desc" => Primitives.desc({ "type" => %w{string null} }, "The description for the overarching control."),
+          "descriptions" => Primitives.desc(CONTROL_DESCRIPTIONS.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."),
         },
-      }, [CONTROL_DESCRIPTIONS, Primitives::REFERENCE, Primitives::SOURCE_LOCATION])
+      }, [CONTROL_DESCRIPTIONS, Primitives::REFERENCE, Primitives::SOURCE_LOCATION], "The set of all tests within the control.")
 
       # A profile that has not been run.
       PROFILE = Primitives::SchemaType.new("Profile JSON Profile", {
@@ -37,24 +37,24 @@ module Inspec
         "additionalProperties" => true, # Anything in the yaml will be put in here. LTTODO: Make this stricter!
         "required" => %w{name supports controls groups sha256},
         "properties" => {
-          "name" => Primitives::STRING,
-          "supports" => Primitives.array(Primitives::SUPPORT.ref),
-          "controls" => Primitives.array(CONTROL.ref),
-          "groups" => Primitives.array(Primitives::CONTROL_GROUP.ref),
-          "inputs" => Primitives.array(Primitives::INPUT),
-          "sha256" => Primitives::STRING,
-          "status" => Primitives::STRING,
-          "generator" => Primitives::GENERATOR.ref,
-          "version" => Primitives::STRING,
+          "name" => Primitives.desc(Primitives::STRING, "The name - must be unique."),
+          "supports" => Primitives.desc(Primitives.array(Primitives::SUPPORT.ref), "The set of supported platform targets."),
+          "controls" => Primitives.desc(Primitives.array(CONTROL.ref), "The set of controls - contains no findings as the assessment has not yet occurred."),
+          "groups" => Primitives.desc(Primitives.array(Primitives::CONTROL_GROUP.ref), "A set of descriptions for the control groups.  Example: the ids of the controls."),
+          "inputs" => Primitives.desc(Primitives.array(Primitives::INPUT), "The input(s) or attribute(s) used to be in the run."),
+          "sha256" => Primitives.desc(Primitives::STRING, "The checksum of the profile."),
+          "status" => Primitives.desc(Primitives::STRING, "The status.  Example: skipped."),
+          "generator" => Primitives.desc(Primitives::GENERATOR.ref, "The tool that generated this file.  Example: Chef Inspec."),
+          "version" => Primitives.desc(Primitives::STRING, "The version of the profile."),
 
           # Other properties possible in inspec docs, but that aren"t guaranteed
-          "title" => Primitives::STRING,
-          "maintainer" => Primitives::STRING,
-          "copyright" => Primitives::STRING,
-          "copyright_email" => Primitives::STRING,
-          "depends" => Primitives.array(Primitives::DEPENDENCY.ref), # Can have depends, but NOT a parentprofile
+          "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 contract 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."), # Can have depends, but NOT a parentprofile
         },
-      }, [Primitives::SUPPORT, CONTROL, Primitives::CONTROL_GROUP, Primitives::DEPENDENCY, Primitives::GENERATOR])
+      }, [Primitives::SUPPORT, CONTROL, Primitives::CONTROL_GROUP, Primitives::DEPENDENCY, Primitives::GENERATOR], "Information on the set of controls that can be assessed.  Example: it can include the name of the Inspec profile.")
     end
   end
 end

data/lib/inspec/schema.rb

@@ -57,6 +57,7 @@ module Inspec
         "run_time" => { "type" => "number" },
         "start_time" => { "type" => "string" },
         "resource_class" => { "type" => "string", "optional" => true },
+        "resource_id" => { "type" => "string", "optional" => true },
         "skip_message" => { "type" => "string", "optional" => true },
         "resource" => { "type" => "string", "optional" => true },
         "message" => { "type" => "string", "optional" => true },