(WIP) Address feedback re inspections, wordsmith

Signed-off-by: Aditya Sirish <[email protected]>

ITE/10/README.adoc

@@ -41,32 +41,35 @@ Framework. This framework introduced the idea of context-specific "predicates"
 with their own definitions. This ITE builds on ITE-6 and describes how in-toto
 layouts and artifact rules can support contextual predicates.
 
+[[motivation]]
+== Motivation
+
+in-toto v1.0 defines only one type of metadata that is captured during supply
+chain operations. As such, it has a uniform verification workflow and provides
+supply chain owners the semantics, i.e. artifact rules, to verify the flow of
+artifacts in their supply chains. ITE-6 expanded the metadata formats to
+support the generation of custom attestations that have context-specific
+schemas. This means that in-toto v1.0 layouts and artifact rules cannot be used
+to verify artifacts recorded in ITE-6 attestations.
+
 [[specification]]
 == Specification
 
 Note: this document assumes the reader is familiar with ITE-6 and the in-toto
 Attestation Framework.
 
-To support different predicate types in an in-toto layout's steps and
-inspections, it is first necessary to recognize that there are two broad classes
-of predicates.
+To support different predicate types in an in-toto layout's steps, it is first
+necessary to recognize that there are two broad classes of predicates.
 
 === Classifying Predicates
 
-Prior to ITE-6, all steps were validated against in-toto links. Inspection
-executions also resulted in the generation of in-toto links that were then
-verified. With the introduction of the in-toto Attestation Framework, it is
-necessary to rework the layout to support verifying a variety of _predicates_.
-As the framework is designed to generate claims pertaining to how software is
-produced, each predicate type can be mapped to a step in the software supply
-chain. However, it is first necessary to understand the nature of each step, and
-therefore its predicate types. in-toto was originally designed with the
-assumption that a step in the software supply chain affects in some manner the
-artifacts that constitute the supply chain. ITE-6 showed that some steps do not
-fit the materials and products model. This is a factor in _verifying_ such
-predicates using in-toto layouts.
-
-Therefore, all predicates supported for verification in an in-toto layout must
+As the in-toto Attestation Framework is designed to generate claims pertaining
+to how software is produced, each predicate type can be mapped to a step in the
+software supply chain. in-toto v1.0 assumes that each step affects the
+artifacts that constitute the supply chain in some manner. These artifacts are
+represented as the materials and products of supply chain steps. ITE-6 showed
+that some steps do not fit the materials and products model. This ITE shows
+that all predicates supported for verification in an in-toto layout can be
 categorized as one of two classes:
 
 * transformational predicates: these are based on classic in-toto links for
@@ -76,19 +79,21 @@ categorized as one of two classes:
 * informational predicates: these predicates record contextual attributes about
   one or more artifacts. The operations they represent consume artifacts as
   materials (recorded as the subject of such attestations) and produce
-  attributes about them as the outcome. Eg. test results, reviews.
+  attributes about them as the outcome. Eg. test results, code reviews, SCAI.
 
-Note that transformational predicates may also record certain information about
-certain attributes. For example, the environment field in in-toto links can
-include such information.
+Note that transformational predicates can also record attribute information.
+For example, the environment field in in-toto links can include such
+information. The impact of this classification is seen in how the subject of
+an attestation is handled.
 
 With this representation of different predicate types, step declarations in
-layouts can _chain_ different operations represented by distinct predicate types
-together, a fundamental feature of in-toto. For example, a code review step
-represented by a review predicate type that follows a checkout step that fetches
-source code represented by an in-toto link can use in-toto's artifact rules to
-ensure the review was performed against the sources fetched by the checkout
-step.
+layouts can _chain_ different operations represented by distinct predicate
+types together, a fundamental feature of in-toto. For example, consider a
+supply chain with a code review step represented by a review predicate type
+that follows a source checkout step that fetches source code represented by an
+in-toto link. The review step in the layout can use in-toto's artifact rules to
+ensure the materials for the review match the products fetched by the source
+checkout step.
 
 === Setting Predicate Type Expectations for Steps and Inspections
 
@@ -121,43 +126,23 @@ functionaries: list of authorized functionary key IDs
 threshold: int
 ```
 
-The `predicateType` field identifies the type of predicate expected for the
-step. `expectedProducts` is moved to being predicate specific as informational
-predicates may be generated alongside transformational predicates for the same
-step. This means that product rules do not generalize across all of the step's
-predicates. However, `expectedMaterials` is retained at the step level as all
-predicates generated for a step are expected to be for the same set of
-artifacts. `pubkeys` is updated to `functionaries` to generalize signing
-semantics. Finally, `threshold` applies per predicate type rather than the step
-as a whole.
-
-Similarly, inspections are also updated to support generating different
-predicate types.
-
-```yaml
-name: string
-command: list of strings
-expectedMaterials: list of artifact rules
-expectedPredicates: list of expectedInspectionPredicates
-```
-
-Each `expectedInspectionPredicate` object has the following schema.
-
-```yaml
-predicateType: string
-expectedProducts: list of artifact rules
-```
-
-As the attestations generated during inspection executions are not signed,
-`functionaries` and `threshold` are omitted.
+The `predicateType` field contains the matching `TypeURI` of the predicate
+expected for the step. `expectedProducts` is moved to being predicate specific
+as informational predicates may be generated alongside transformational
+predicates for the same step. This means that product rules do not generalize
+across all of the step's predicates. However, `expectedMaterials` is retained
+at the step level as all predicates generated for a step are expected to be for
+the same set of artifacts. `pubkeys` is updated to `functionaries` to
+generalize signing semantics. Finally, `threshold` applies per predicate type
+rather than the step as a whole.
 
 === Supporting Sublayouts
 
-The in-toto specification has support for sublayouts which are steps in a layout
-that have not links but a bundle of another layout and links which are
+The in-toto specification has support for sublayouts which are steps in a
+layout that have not links but a bundle of another layout and links which are
 recursively verified first. To support this semantic, this ITE proposes making
-sublayout declarations explicit. Therefore, a step declaration declares that it
-expects a layout and identifies it. This layout is then verified recursively
+sublayout declarations explicit. Therefore, a step in the layout declares that
+it expects a layout and identifies it. This layout is then verified recursively
 before verification continues at the original layout.
 
 === Verifying Artifact Rules
@@ -194,33 +179,14 @@ func Verify(layoutEnvelope, layoutKeys, attestations, now) {
     }
 
     for _, inspection := range layout.Inspections {
-        expectedPredicateTypes := []string{}
-        for _, expectedPredicate := range inspection.ExpectedPredicates {
-            expectedPredicateTypes = append(expectedPredicateTypes, expectedPredicate.PredicateType)
-        }
-        inspectionAttestations := executeInspection(inspection.Command, expectedPredicateTypes) // {predicateType: attestation}
-        allAttestations := combineAttestations(inspectionAttestations, attestations)
-        for _, expectedPredicate := range inspection.ExpectedPredicates {
-            attestation := inspectionAttestations[expectedPredicate.PredicateType]
-            applyMaterialRules(inspection.ExpectedMaterials, attestation.Materials, allAttestations)
-            applyProductRules(expectedPredicate.ExpectedProducts, attestation.Products, allAttestations)
-        }
+        inspectionAttestation := executeInspection(inspection.Command)
+        allAttestations := combineAttestations(inspectionAttestation, attestations)
+        applyMaterialRules(inspection.ExpectedMaterials, inspectionAttestation.Materials, allAttestations)
+        applyProductRules(inspection.ExpectedProducts, inspectionAttestation.Products, allAttestations)
     }
 }
 ```
 
-[[motivation]]
-== Motivation
-
-The original in-toto specification defined only one type of metadata that was to
-be captured during supply chain operations. As such, it had a uniform
-verification workflow and provided supply chain owners the semantics, i.e.
-artifact rules, to verify the flow of artifacts in their supply chains. ITE-6
-expanded the metadata formats to support the generation of custom attestations
-that have context-specific schemas. Current in-toto layouts as defined in the
-in-toto specification and artifact rules cannot be used to verify artifacts
-recorded in ITE-6 predicates.
-
 [[reasoning]]
 == Reasoning
 
@@ -237,7 +203,7 @@ the steps graph.
 [[backwards-compatibility]]
 == Backwards Compatibility
 
-All the capabilities currently enabled by in-toto inspections are retained in
+All the capabilities currently enabled by in-toto verification are retained in
 the changes proposed here. As such, there is no regression in capabilities.
 
 However, new layouts following the scheme specified here cannot be verified
@@ -262,7 +228,7 @@ None.
 [[prototype-implementation]]
 == Prototype Implementation
 
-None yet.
+See: https://github.com/adityasaky/in-toto-attestation-verifier
 
 [[testing]]
 == Testing
@@ -274,5 +240,5 @@ old layouts.
 [[references]]
 == References
 
-* link:https://github.com/in-toto/docs/blob/master/in-toto-spec.md[in-toto Specification]
+* link:https://github.com/in-toto/docs/blob/v1.0/in-toto-spec.md[in-toto v1.0]
 * link:https://github.com/in-toto/attestation[in-toto Attestation Framework]