Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

editorial: Clarify language in VSA spec #882

Closed
wants to merge 29 commits into from
Closed

editorial: Clarify language in VSA spec #882

Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
8b0b25e
Update VSA for SLSA v1.1
kpk47 Jun 9, 2023
1233829
Address review comments
kpk47 Jun 23, 2023
68adac3
clarify that you can set verifiedLevels without setting policy
kpk47 Jun 26, 2023
956dc5a
Clarify that verifiedLevels can contain custom values.
kpk47 Jun 28, 2023
b0a877b
reworked How to Verify section
kpk47 Jun 28, 2023
60396db
fix formatting
kpk47 Jun 29, 2023
a71652a
fix formatting
kpk47 Jun 29, 2023
0d386cf
review comments
kpk47 Jun 29, 2023
f841bcf
Apply suggestions from code review
kpk47 Jun 30, 2023
46dcb8f
resolve issues with verifiedLevels
kpk47 Jun 30, 2023
abe634c
Clarify wording around roles; update introduction
kpk47 Jul 5, 2023
b1ef965
Merge branch 'main' of https://github.com/kpk47/slsa into vsa
kpk47 Jul 5, 2023
7800f4b
Apply suggestions from code review
kpk47 Jul 11, 2023
ee07742
impl: update README to explain how to use Netlify (#898)
MarkLodato Jul 6, 2023
359c50a
impl: add missing links in relatedwork doc (#912)
joshuagl Jul 10, 2023
79fdfe1
impl: update renovate config for conventional commits (#911)
joshuagl Jul 10, 2023
2f22cf3
impl: Update github-actions (#909)
renovate-bot Jul 11, 2023
4cde255
impl: Remove dashes from types in PR name lint (#903)
arewm Jul 11, 2023
c0e01a1
nonspec: community meeting is no longer biweekly (#906)
MarkLodato Jul 11, 2023
d0ef5f4
grammar/clarity edits
kpk47 Jul 11, 2023
f2e1d11
Added changelog for this PR
kpk47 Jul 11, 2023
614a115
Merge branch 'main' of https://github.com/kpk47/slsa into vsa
kpk47 Jul 11, 2023
a219938
lint
kpk47 Jul 11, 2023
3c8ee37
Merge branch 'main' of https://github.com/slsa-framework/slsa into vsa
kpk47 Sep 5, 2023
1febf58
move changes to v1.1 directory
kpk47 Sep 5, 2023
1fa3fa9
backport editorial changes to v1.0
kpk47 Sep 6, 2023
e214c2a
move ediorial changes to v1.1 directory
kpk47 Sep 6, 2023
03fe050
fix link refs
kpk47 Sep 6, 2023
ead4e1c
fix link caps
kpk47 Sep 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 38 additions & 34 deletions docs/spec/v1.1/verification_summary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ description: SLSA v1.0 specification for a verification summary of artifacts by
layout: standard
---

Verification summary attestations communicate that an artifact has been verified
at a specific SLSA level and details about that verification.
Verification summary attestations convey high-level information about an
artifact's verification, allowing consumers to delegate verification decisions
to trusted third parties.

This document defines the following predicate type within the [in-toto
attestation] framework:
Expand All @@ -21,17 +22,17 @@ attestation] framework:

## Purpose

Describe what SLSA level an artifact or set of artifacts was verified at
and other details about the verification process including what SLSA level
the dependencies were verified at.
Assert that the VSA producer has verified an artifact or set of artifacts.
Optionally include details about the verification process, such as the verified
SLSA level(s) and the verifier's expectations.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

verifier's expectations == policy? In the rest of the text we say policy. Shall we use the same term throughout the doc? It's a bit confusing otherwise, at least for me.


This allows software consumers to make a decision about the validity of an
VSAs allow software consumers to make a decision about the validity of an
artifact without needing to have access to all of the attestations about the
artifact or all of its transitive dependencies. They can use it to delegate
complex policy decisions to some trusted party and then simply trust that
party's decision regarding the artifact.
artifact or all of its transitive dependencies. The software consumer delegates
complex policy decisions to a trusted party and then acts on those decisions by
consuming the VSA.

It also allows software producers to keep the details of their build pipeline
VSAs also allow software producers to keep the details of their build pipeline
confidential while still communicating that some verification has taken place.
This might be necessary for legal reasons (keeping a software supplier
confidential) or for security reasons (not revealing that an embargoed patch has
Expand All @@ -41,23 +42,20 @@ been included).

A Verification Summary Attestation (VSA) is an attestation that some entity
(`verifier`) verified one or more software artifacts (the `subject` of an
in-toto attestation [Statement]) by evaluating the artifact and a `bundle`
of attestations against some `policy`. Users who trust the `verifier` may
assume that the artifacts met the indicated SLSA level without themselves
needing to evaluate the artifact or to have access to the attestations the
`verifier` used to make its determination.

The VSA also allows consumers to determine the verified levels of
all of an artifact’s _transitive_ dependencies. The verifier does this by
either a) verifying the provenance of each non-source dependency listed in
the [resolvedDependencies](/provenance/v1#resolvedDependencies) of the artifact
being verified (recursively) or b) matching the non-source dependency
listed in `resolvedDependencies` (`subject.digest` ==
`resolvedDependencies.digest` and, ideally, `vsa.resourceUri` ==
`resolvedDependencies.uri`) to a VSA _for that dependency_ and using
`vsa.verifiedLevels` and `vsa.dependencyLevels`. Policy verifiers wishing
to establish minimum requirements on dependencies SLSA levels may use
`vsa.dependencyLevels` to do so.
in-toto attestation [Statement]) by evaluating the artifact and its associated
attestation(s) against the `policy` for `resourceUri`. Consumers who trust
the `verifier` may assume that the artifacts identified by the
`(subject, resourceUri)` pair met the indicated SLSA level without
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to be more general and follow earlier wording, we could say pair met the details about the verification process.

Copy link
Contributor

@AdamZWu AdamZWu Sep 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think including both may be more helpful, i.e. "... met the indicated SLSA level and other criteria in the policy".

We are implementing a producer/consumer of VSA v1.0 and realized that there are two different scenarios:

  1. We consume VSA produced by ourselves: in this case we could leverage the extension attributes to fully convey all the information that we are interested in, such as additional verification beyond what is defined in the SLSA BUILD levels;
  2. We consume VSA produced by others (and similarly, others consume VSA produced by us): in this case, since the consumers and producers may not have mutual definitions on extended checks, to make the VSA useful, we must all resort to the standard language, i.e. SLSA defined levels.

So, if we are producing a VSA without foreknowledge of who will consume it, we should put in both SLSA levels and the extension attributes in the VSA.

themselves needing to evaluate the artifact or to have access to the
attestations the `verifier` used to make its determination.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

may add another example that the VSA works in cases where the repository is not public. That's why we can't verify SLSA provenance directly for closed-source software.


VSAs can also be chained together to meet higher level goals, such as tracking
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what does higher-level goal mean?
Not clear what "chained" means. Do VSAs reference each other like in a block chain, ie do they link to a prior VSA in their output format?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "chained" refers to the following:

  • VSA summarizes verification results; and
  • VSA can short-circuit verification.

These two properties feed each other, so that a VSA is able to summarize the verification results on all transitive dependencies. A VSA represents cumulative verification along the dependency chains of an artifact.

Maybe it is more accurate to describe VSAs subsumes from one another.

For a native example, a system image with 20 packages, each with 50 dependency libraries.

Without VSA, the attestation bundle of the system image will look like:

[system image build provenance]
[package 1 build provenance]
...
[package 20 build provenance]
[package 1 library 1 build provenance]
...
[package 1 library 50 build provenance]
[package 2 library 1 build provenance]
...
...
[package 20 library 50 build provenance]

With VSA and staging repo verification, the attestation bundle of the system image will look like:

[system image build provenance]
[package 1 VSA]
...
[package 20 VSA]

After the system image get verified, the attestation bundle of the system image can be reduced to just:

[system image VSA]

the verified SLSA level(s) for the `subject`'s transitive dependencies. Rather
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comment as before: if we're saying that levels and other verified metadata is optional, we could be more generic tracking details about the verification process for the subject's transitive dependencies.

than verifying provenance for the artifact and each of its transitive
dependencies all at once, the verifier can verify each dependency independently
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a verifier can verify provenance and generate VSA, why does it need to verify them independently? Is this for security or is it a caching (optimization) mechanism? Is there an assumption in the sentence that maybe there are multiple verifiers, one that verified dependencies (say, RedHat) while another consumers it (say, Google) to validate a Google binary? Maybe the sentence can be expanded to motivate both cases...?

Copy link
Contributor

@AdamZWu AdamZWu Sep 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this part refers to the "divide-and-conquer" strategy the VSA enables.

For a naive example, if a system image has 20 software packages, and each package has 50 dependency libraries. A complete transitive dependency verification would involve checking 1+20+20*50 = 1021 artifacts during a single verification, which may consume too much time and violate the verifier's latency SLO.

However, with VSA, what can happen is that, when the 20 software packages get staged in an artifact repo, the repo invokes transitive verification for each, so each verification only checks 1+50 artifacts; and the verification produces VSAs, which propagate to the system image's attestation bundle. Then, when we verify the system image, the verifier will only need to perform at 1+20 checks, because the presence of VSAs of the packages eliminates the need to check the dependency libraries (since VSA is a proof that they are already checked).

Effectively, VSA functions as a "distributed dynamic programming table" and facilitates efficient transitive dependency verification.

and produce VSAs. Finally, the verifier combines those VSAs; the artifact
is the final VSA's `subject` and each transitive dependency is an
entry in `dependencyLevels`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same comment: do we want to be generic about "verified metadata" or mention verified levels? If the former, we could have a dedicated section with examples for different types of metadata, starting with a verified level. Just an idea...


## Schema

Expand Down Expand Up @@ -129,7 +127,7 @@ of the other top-level fields, such as `subject`, see [Statement]._
> can sign provenance for the "Google Cloud Deploy" verifier, but "GitHub" cannot
> sign for the "Google Cloud Deploy" verifier.
>
> The field is required, even if it is implicit from the signer, to aid readability and
> This field is required, even if it is implicit from the signer, to aid readability and
> debugging. It is an object to allow additional fields in the future, in case one
> URI is not sufficient.

Expand All @@ -147,6 +145,12 @@ of the other top-level fields, such as `subject`, see [Statement]._
`resourceUri` _string ([ResourceURI]), required_

> URI that identifies the resource associated with the artifact being verified.
>
> This field is required to prevent confusion attacks. E.g., a VSA indicating
> that a package can be published as `foo` should not be usable to publish
> the package as `bar`; a VSA indicating that a package passed the policy for
> a `dev` environment should not be usable to deploy the package to a `prod`
> environment.

<a id="policy"></a>
`policy` _object ([ResourceDescriptor]), required_
Expand Down Expand Up @@ -179,8 +183,8 @@ of the other top-level fields, such as `subject`, see [Statement]._
> Indicates the highest level of each track verified for the artifact (and not
> its dependencies), or "FAILED" if policy verification failed.
>
> Users MUST NOT include more than one level per SLSA track. Note that each SLSA
> level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies
> VSA producers MUST NOT include more than one level per SLSA track. Note that
> each SLSA level implies all levels below it (e.g. SLSA_BUILD_LEVEL_3 implies
> SLSA_BUILD_LEVEL_2 and SLSA_BUILD_LEVEL_1), so there is no need to
> include more than one level per track.

Expand All @@ -193,8 +197,8 @@ of the other top-level fields, such as `subject`, see [Statement]._
> that were verified at the indicated level. Absence of a given level of
> [SlsaResult] MUST be interpreted as reporting _0_ dependencies at that level.
>
> Users MUST count each dependency only once per SLSA track, at the highest
> level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2,
> VSA producers MUST count each dependency only once per SLSA track, at the
> highest level verified. For example, if a dependency meets SLSA_BUILD_LEVEL_2,
> you include it with the count for SLSA_BUILD_LEVEL_2 but not the count for
>SLSA_BUILD_LEVEL_1.

Expand Down Expand Up @@ -235,7 +239,7 @@ WARNING: This is just for demonstration purposes.
}
],
"verificationResult": "PASSED",
"verifiedLevels": ["SLSA_LEVEL_3"],
"verifiedLevels": ["SLSA_BUILD_LEVEL_3"],
"dependencyLevels": {
"SLSA_BUILD_LEVEL_3": 5,
"SLSA_BUILD_LEVEL_2": 7,
Expand Down Expand Up @@ -269,7 +273,7 @@ Users MAY use custom values here but MUST NOT use custom values starting with

## Change history

- 1:
- 1.0:
- Replaced `materials` with `resolvedDependencies`.
- Relaxed `SlsaResult` to allow other values.
- Converted to lowerCamelCase for consistency with [SLSA Provenance].
Expand Down