Merge branch 'main' of https://github.com/kpk47/slsa into vsa2

.github/workflows/conventional-commits.yml

@@ -17,7 +17,7 @@ jobs:
       - name: semantic-pull-request
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        uses: amannn/action-semantic-pull-request@c3cd5d1ea3580753008872425915e343e351ab54 # v5.2.0
+        uses: amannn/action-semantic-pull-request@47b15d52c5c30e94a17ec87eb8dd51ff5221fed9 # v5.3.0
         with:
           types: |
             content

.github/workflows/lint.yml

@@ -6,7 +6,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3.6.0
+      uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
     - name: Setup Node
       uses: actions/setup-node@5e21ff4d9bc1a8cf6de233a3057d20ec6b3fb69d # v3.8.1
     - run: npm ci --ignore-scripts

docs/Gemfile.lock

@@ -1,7 +1,7 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.6)
+    activesupport (7.0.7.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)

docs/_redirects

@@ -70,4 +70,5 @@
 /verification_summary/v1.1      /spec/v1.1/verification_summary     301
 
 # Removed files. Keep URLs working forever.
-/example    https://github.com/slsa-framework/slsa/blob/a25364a3b312f572e4620c812820249853bb40e5/docs/example.md  301
+/example       https://github.com/slsa-framework/slsa/blob/a25364a3b312f572e4620c812820249853bb40e5/docs/example.md  301
+/example.md    https://github.com/slsa-framework/slsa/blob/a25364a3b312f572e4620c812820249853bb40e5/docs/example.md  301

docs/spec/v0.1/provenance.md

@@ -248,7 +248,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
 `metadata.completeness.arguments` _boolean, optional_
 
 > If true, the `builder` claims that `recipe.arguments` is complete, meaning
-> that all external inputs are propertly captured in `recipe`.
+> that all external inputs are properly captured in `recipe`.
 
 <a id="metadata.completeness.environment"></a>
 `metadata.completeness.environment` _boolean, optional_

docs/spec/v0.1/threats.md

@@ -682,7 +682,7 @@ ad-hoc analysis, and can complement source-based typosquatting solutions.
 
 ## Availability threats
 
-An availabiliy threat is a potential for an adversary to deny someone from
+An availability threat is a potential for an adversary to deny someone from
 reading a source and its associated change history, or from building a package.
 
 <details><summary>(A)(B) Delete the code <span>(SLSA 3)</span></summary>
@@ -704,11 +704,11 @@ attestation showing that some system, such as GitHub, ensures retention and
 availability.
 
 </details>
-<details><summary>(E) A dependency becomes temporarily or permenantly unavailable to the build process <span>(out of scope)</span></summary>
+<details><summary>(E) A dependency becomes temporarily or permanently unavailable to the build process <span>(out of scope)</span></summary>
 
 *Threat:* Unable to perform a build with the intended dependencies.
 
-*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to support Hermetic and Reproducable builds may also reduce the impact of this threat.
+*Mitigation:* **Outside the scope of SLSA.** That said, some solutions to support Hermetic and Reproducible builds may also reduce the impact of this threat.
 <sup>[[Hermetic] [Reproducible] @ SLSA 4]</sup>
 
 </details>

docs/spec/v0.2/provenance.md

@@ -260,7 +260,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
 `metadata.completeness.parameters` _boolean, optional_
 
 > If true, the `builder` claims that `invocation.parameters` is complete, meaning
-> that all external inputs are propertly captured in `invocation.parameters`.
+> that all external inputs are properly captured in `invocation.parameters`.
 
 <a id="metadata.completeness.environment"></a>
 `metadata.completeness.environment` _boolean, optional_

docs/spec/v1.0-rc1/requirements.md

@@ -90,7 +90,7 @@ choose a builder capable of producing Build Level 3 provenance.
 
 The producer MUST build their artifact in a consistent
 manner such that verifiers can form expectations about the build process. In
-some implemenatations, the producer MAY provide explicit metadata to a verifier
+some implementations, the producer MAY provide explicit metadata to a verifier
 about their build process. In others, the verifier will form their expectations
 implicitly (e.g. trust on first use).
 

docs/spec/v1.0-rc2/principles.md

@@ -18,7 +18,7 @@ expensive manual work, and each trusted system expands the attack surface of the
 supply chain. Verifying that an artifact is produced by a trusted system,
 though, is easy to automate.
 
-To simultaniously scale and reduce attack surfaces, it is most efficient to trust a limited
+To simultaneously scale and reduce attack surfaces, it is most efficient to trust a limited
 numbers of systems and then automate verification of the artifacts produced by those systems.
 The attack surface and work to establish trust does not scale with the number of artifacts produced,
 as happens when artifacts each use a different trusted system.

docs/spec/v1.0-rc2/requirements.md

@@ -103,7 +103,7 @@ choose a builder capable of producing Build Level 3 provenance.
 
 The producer MUST build their artifact in a consistent
 manner such that verifiers can form expectations about the build process. In
-some implemenatations, the producer MAY provide explicit metadata to a verifier
+some implementations, the producer MAY provide explicit metadata to a verifier
 about their build process. In others, the verifier will form their expectations
 implicitly (e.g. trust on first use).
 

docs/spec/v1.0-rc2/threats.md

@@ -187,7 +187,7 @@ producer.
 
 The SLSA Build track mitigates these threats when the consumer
 [verifies artifacts](verifying-artifacts.md) against expectations, confirming
-that the artifact they recieved was built in the expected manner.
+that the artifact they received was built in the expected manner.
 
 ### (E) Compromise build process
 

docs/spec/v1.0-rc2/verifying-artifacts.md

@@ -91,9 +91,9 @@ Once, when bootstrapping the verifier:
 
 Given an artifact and its provenance:
 
-1.  [Verify][processing-model] the envelope's signature using the roots of
+1.  [Verify][validation-model] the envelope's signature using the roots of
     trust, resulting in a list of recognized public keys (or equivalent).
-2.  [Verify][processing-model] that statement's `subject` matches the digest of
+2.  [Verify][validation-model] that statement's `subject` matches the digest of
     the artifact in question.
 3.  Verify that the `predicateType` is `https://slsa.dev/provenance/v1-rc2`.
 4.  Look up the SLSA Build Level in the roots of trust, using the recognized
@@ -129,7 +129,7 @@ Resulting threat mitigation:
 [Threat "G"]: threats#g-compromise-package-repo
 [Threat "H"]: threats#h-use-compromised-package
 
-[processing-model]: https://github.com/in-toto/attestation/tree/main/spec#processing-model
+[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model
 
 ### Step 2: Check expectations
 

docs/spec/v1.0/faq.md

@@ -87,7 +87,7 @@ Jenkins plugin.
 
 ## Q. What is the difference between a build platform, system, and service?
 
-Build platform and build system have been used interchangably in the past. With
+Build platform and build system have been used interchangeably in the past. With
 the v1.0 specification, however, there has been a unification around the term
 platform as indicated in the [Terminology](terminology.md). The use of the word
 `system` still exists related to software and services within the build platform

docs/spec/v1.0/requirements.md

@@ -102,7 +102,7 @@ choose a builder capable of producing Build Level 3 provenance.
 
 The producer MUST build their artifact in a consistent
 manner such that verifiers can form expectations about the build process. In
-some implemenatations, the producer MAY provide explicit metadata to a verifier
+some implementations, the producer MAY provide explicit metadata to a verifier
 about their build process. In others, the verifier will form their expectations
 implicitly (e.g. trust on first use).
 

docs/spec/v1.0/threats.md

@@ -189,7 +189,7 @@ producer.
 
 The SLSA Build track mitigates these threats when the consumer
 [verifies artifacts](verifying-artifacts.md) against expectations, confirming
-that the artifact they recieved was built in the expected manner.
+that the artifact they received was built in the expected manner.
 
 ### (E) Compromise build process
 

docs/spec/v1.0/verifying-artifacts.md

@@ -94,9 +94,9 @@ Once, when bootstrapping the verifier:
 
 Given an artifact and its provenance:
 
-1.  [Verify][processing-model] the envelope's signature using the roots of
+1.  [Verify][validation-model] the envelope's signature using the roots of
     trust, resulting in a list of recognized public keys (or equivalent).
-2.  [Verify][processing-model] that statement's `subject` matches the digest of
+2.  [Verify][validation-model] that statement's `subject` matches the digest of
     the artifact in question.
 3.  Verify that the `predicateType` is `https://slsa.dev/provenance/v1`.
 4.  Look up the SLSA Build Level in the roots of trust, using the recognized
@@ -132,7 +132,7 @@ Resulting threat mitigation:
 [Threat "G"]: threats#g-compromise-package-repo
 [Threat "H"]: threats#h-use-compromised-package
 
-[processing-model]: https://github.com/in-toto/attestation/tree/main/spec#processing-model
+[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model
 
 ### Step 2: Check expectations
 

docs/spec/v1.1/faq.md

@@ -87,7 +87,7 @@ Jenkins plugin.
 
 ## Q. What is the difference between a build platform, system, and service?
 
-Build platform and build system have been used interchangably in the past. With
+Build platform and build system have been used interchangeably in the past. With
 the v1.0 specification, however, there has been a unification around the term
 platform as indicated in the [Terminology](terminology.md). The use of the word
 `system` still exists related to software and services within the build platform

docs/spec/v1.1/requirements.md

@@ -102,7 +102,7 @@ choose a builder capable of producing Build Level 3 provenance.
 
 The producer MUST build their artifact in a consistent
 manner such that verifiers can form expectations about the build process. In
-some implemenatations, the producer MAY provide explicit metadata to a verifier
+some implementations, the producer MAY provide explicit metadata to a verifier
 about their build process. In others, the verifier will form their expectations
 implicitly (e.g. trust on first use).
 

docs/spec/v1.1/threats.md

@@ -5,7 +5,7 @@ description: A comprehensive technical analysis of supply chain threats and thei
 
 What follows is a comprehensive technical analysis of supply chain threats and
 their corresponding mitigations in SLSA. For an introduction to the
-supply chain threats that SLSA protects agains, see [Supply chain threats].
+supply chain threats that SLSA protects against, see [Supply chain threats].
 
 The examples on this page are meant to:
 
@@ -189,7 +189,7 @@ producer.
 
 The SLSA Build track mitigates these threats when the consumer
 [verifies artifacts](verifying-artifacts.md) against expectations, confirming
-that the artifact they recieved was built in the expected manner.
+that the artifact they received was built in the expected manner.
 
 ### (E) Compromise build process
 

docs/spec/v1.1/verification_summary.md

@@ -147,7 +147,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
 > Map of names of components of the verification platform to their version.
 
 <a id="timeVerified"></a>
-`timeVerified` _string ([Timestamp]), required_
+`timeVerified` _string ([Timestamp]), optional_
 
 > Timestamp indicating what time the verification occurred.
 
@@ -257,6 +257,103 @@ WARNING: This is just for demonstration purposes.
 }
 ```
 
+## How to verify
+
+VSA consumers use VSAs to accomplish goals based on delegated trust. We call the
+process of establishing a VSA's authenticity and determining whether it meets
+the consumer's goals 'verification'. Goals differ, as do levels of confidence
+in VSA producers, so the verification procedure changes to suit its context.
+However, there are certain steps that most verification procedures have in
+common.
+
+Verification MUST include the following steps:
+
+1.  Verify the signature on the VSA envelope using the preconfigured roots of
+    trust. This step ensures that the VSA was produced by a trusted producer
+    and that it hasn't been tampered with.
+
+2.  Verify the statement's `subject` matches the digest of the artifact in
+    question. This step ensures that the VSA pertains to the intended artifact.
+
+3.  Verify that the `predicateType` is
+    `https://slsa.dev/verification_summary/v1`. This step ensures that the
+    in-toto predicate is using this version of the VSA format.
+
+4.  Verify that the `verifier` matches the public key (or equivalent) used to
+    verify the signature in step 1. This step identifies the VSA producer in
+    cases where their identity is not implicitly revealed in step 1.
+
+5.  Verify that the value for `resourceUri` in the VSA matches the expected
+    value. This step ensures that the consumer is using the VSA for the
+    producer's intended purpose.
+
+6.  Verify that the value for `slsaResult` is `PASSED`. This step ensures the
+    artifact is suitable for the consumer's purposes.
+
+7.  Verify that `verifiedLevels` contains the expected value. This step ensures
+    that the artifact is suitable for the consumer's purposes.
+
+Verification MAY additionally contain the following step:
+
+1.  (Optional) Verify additional fields required to determine whether the VSA
+    meets your goal.
+
+Verification mitigates different threats depending on the VSA's contents and the
+verification procudure.
+
+IMPORTANT: A VSA does not protect against compromise of the verifier, such as by
+a malicious insider. Instead, VSA consumers SHOULD carefully consider which
+verifiers they add to their roots of trust.
+
+### Examples
+
+1.  Suppose consumer C wants to delegate to verifier V the decision for whether
+    to accept artifact A as resource R. Consumer C verifies that:
+
+    -   The signature on the VSA envelope using V's public signing key from their
+      preconfigured root of trust.
+
+    -   `subject` is A.
+
+    -   `predicateType` is `https://slsa.dev/verification_summary/v1`.
+
+    -   `verifier.id` is V.
+
+    -   `resourceUri` is R.
+
+    -   `slsaResult` is `PASSED`.
+
+    -   `verifiedLevels` contains `SLSA_BUILD_LEVEL_UNEVALUATED`.
+
+    Note: This example is analogous to traditional code signing. The expected
+    value for `verifiedLevels` is arbitrary but prenegotiated by the producer and
+    the consumer. The consumer does not need to check additional fields, as C
+    fully delegates the decision to V.
+
+2.  Suppose consumer C wants to enforce the rule "Artifact A at resource R must
+    have a passing VSA from verifier V showing it meets SLSA Build Level 2+."
+    Consumer C verifies that:
+
+    -   The signature on the VSA envelope using V's public signing key from their
+      preconfigured root of trust.
+
+    -   `subject` is A.
+
+    -   `predicateType` is `https://slsa.dev/verification_summary/v1`.
+
+    -   `verifier.id` is V.
+
+    -   `resourceUri` is R.
+
+    -   `slsaResult` is `PASSED`.
+
+    -   `verifiedLevels` is `SLSA_BUILD_LEVEL_2` or `SLSA_BUILD_LEVEL_3`.
+
+    Note: In this example, verifying the VSA mitigates the same threats as
+    verifying the artifact's SLSA provenance. See
+    [Verifying artifacts](/spec/v1.0/verifying-artifacts) for details about which
+    threats are addressed by verifying each SLSA level.
+
 <div id="slsaresult">
 
 ## _SlsaResult (String)_
@@ -266,6 +363,7 @@ WARNING: This is just for demonstration purposes.
 The result of evaluating an artifact (or set of artifacts) against SLSA.
 SHOULD be one of these values:
 
+-   SLSA_BUILD_LEVEL_UNEVALUATED
 -   SLSA_BUILD_LEVEL_0
 -   SLSA_BUILD_LEVEL_1
 -   SLSA_BUILD_LEVEL_2
@@ -283,6 +381,8 @@ Users MAY use custom values here but MUST NOT use custom values starting with
 
 -   1.1:
     -   Added optional `verifier.version` field to record verification tools.
+    -   Added Verification section with examples.
+    -   Made `timeVerified` optional.
 -   1.0:
     -   Replaced `materials` with `resolvedDependencies`.
     -   Relaxed `SlsaResult` to allow other values.

docs/spec/v1.1/verifying-artifacts.md

@@ -94,9 +94,9 @@ Once, when bootstrapping the verifier:
 
 Given an artifact and its provenance:
 
-1.  [Verify][processing-model] the envelope's signature using the roots of
+1.  [Verify][validation-model] the envelope's signature using the roots of
     trust, resulting in a list of recognized public keys (or equivalent).
-2.  [Verify][processing-model] that statement's `subject` matches the digest of
+2.  [Verify][validation-model] that statement's `subject` matches the digest of
     the artifact in question.
 3.  Verify that the `predicateType` is `https://slsa.dev/provenance/v1`.
 4.  Look up the SLSA Build Level in the roots of trust, using the recognized
@@ -132,7 +132,7 @@ Resulting threat mitigation:
 [Threat "G"]: threats#g-compromise-package-repo
 [Threat "H"]: threats#h-use-compromised-package
 
-[processing-model]: https://github.com/in-toto/attestation/tree/main/spec#processing-model
+[validation-model]: https://github.com/in-toto/attestation/blob/main/docs/validation.md#validation-model
 
 ### Step 2: Check expectations
 

docs/spec/v1.1/whats-new.md

@@ -12,6 +12,7 @@ changes in v1.1 relative to the prior release, [v1.0].
 -   Clarify that attestation format schema are informative and the
     specification texts (SLSA and [in-toto attestation]) are the canonical
     source of definitions.
+-   Add procedure for verifying VSAs.
 
 <!-- Footnotes and link definitions -->