Skip to content

Commit

Permalink
content: draft: define source-track objective in terms of revisions a…
Browse files Browse the repository at this point in the history 
…nd provenance. (#1083)

fixes #1072

This PR modifies _draft_ content of the slsa spec. 

## Context
Based on discussion from
#1037

See [discussion
here](https://docs.google.com/document/d/13Xt8mA_2b00McGX2vkyhu4GQdFAqtXPu7YXE8ZA6ISE/edit?resourcekey=0-EqfHF79tUWAKp4PzsE3z1A#heading=h.svjr333bawb).

Copied from [draft proposal
here](https://docs.google.com/document/d/13Xt8mA_2b00McGX2vkyhu4GQdFAqtXPu7YXE8ZA6ISE/edit?resourcekey=0-EqfHF79tUWAKp4PzsE3z1A#bookmark=id.4qr65cfy6ufj).

Google document requires slsa-discussion@googlegroups.com membership.

## Source revision provenance
Repos contain many revisions, most of which are not "official" or
otherwise approved for release.
The goal of the source track is to attest to why a specific revision
_was_ approved for release.

We can think of the SCP / code review tool as “building” the next
official revision of a repository using a codified process that involves
collecting commits, acquiring reviews, running CI, etc.
If the change review process is successful, the code review tooling will
merge the code changes and attest to the process used to produce the new
revision.

The source provenance attestations associate a specific revision of a
repository to security claims and documents (basically build logs) of
the process that produced it.

In GitHub terms, a merged pull request and its associated rules
evaluation justify why and how a specific git SHA is reachable from a
protected branch.

## Example Scenario
1. A CI system is trying to build some artifact and will download all
necessary resources, including repos and packages.
2. After download, the system will proceed to verify all fetched
resources.
1. For package artifacts, it takes the hash and looks for build
provenance attestations from sigstore or github.
1. For source artifacts that are not packaged (EG, cloned via git), it
takes the revision id and looks for the source provenance from sigstore
or github.
5. Based on the claims in the provenance attestations, the CI system can
determine if all resources comply with required policy and choose to
proceed.

---------

Signed-off-by: Zachariah Cox <zachariahcox@github.com>
Co-authored-by: Joshua Lock <joshuagloe@gmail.com>
Co-authored-by: Tom Hennen <TomHennen@users.noreply.github.com>
  • Loading branch information
@zachariahcox @joshuagl @TomHennen
3 people authored Jul 15, 2024
1 parent 772967c commit 7c6ba23
Showing 1 changed file with 23 additions and 16 deletions.
39 changes: 23 additions & 16 deletions docs/spec/draft/source-requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,34 +18,41 @@ Open issues are tracked with the [source-track](https://github.com/slsa-framewor

## Objective

The SLSA Source Track mitigates [Threat A ("Submit unauthorized change")](/spec/v1.0/threats#a-submit-unauthorized-change), scoped to a code repository and the organization that owns that repository. Concretely: an attacker must compromise the accounts of two organization members to publish code in a Source Level 3-conformant repository, and the evidence of those unauthorized changes cannot be destroyed without further attacks.
The SLSA source track describes increasing levels of trustworthiness and completeness in a repository revision's provenance (e.g. how it was generated, who the contributors were, etc...).

## Source model
The Source track is scoped to revisions of a single repository that is controlled by an organization.
That organization determines the intent of the software in the repository, what Source level should apply to the repository and administers technical controls to enforce that level.

The Source track is scoped to a single project that is controlled by some organization. That organization determines what Source level should apply to the project and administers technical controls to enforce that level.
The primary purpose of the Source track is to enable verification that the creation of a revision followed the expected process.
Consumers can examine the various source provenance attestations to determine if all sources used during the build meet their requirements.

## Definitions

| Term | Description
| --- | ---
| Source | An identifiable set of text and binary files and associated metadata usually used as input for the build system (see SLSA Build Track).
| Organization | A collection of people who collectively create the Source. Examples of organizations include an open-source projects, a company, or a team within a company.
| Change | A set of modifications to one or more source files and associated metadata. Change metadata MUST include any information required to situate the change in relation to other changes (e.g. parent revision).
| Version Control System | Software for tracking and managing changes to source. Git and Subversion are examples of version control systems.
| Revision | A specific identifier provided by the version control system that identifies a given state of the source. As an example, you can identify a git revision by its tree hash.
| Change History | A record of the history of changes that went into the revision.
| Source Control Platform | A service or suite of services for hosting version controlled software. GitHub and GitLab are examples of source control platforms, as are combinations of tools like Gerrit code reviews with GitHub source control.

### Source Roles
| Source | An identifiable set of text and binary files and associated metadata. Source is regularly used as input to a build system (see [SLSA Build Track](requirements.md)).
| Version Control System (VCS)| Software for tracking and managing changes to source. Git and Subversion are examples of version control systems.
| Revision | A specific state of the source with an identifier provided by the version control system. As an example, you can identify a git revision by its tree hash.
| Source Control Platform (SCP) | A service or suite of services (self-hosted or SaaS) for hosting version-controlled software. GitHub and GitLab are examples of source control platforms, as are combinations of tools like Gerrit code reviews with GitHub source control.
| Source Provenance | Information about which Source Control Platform (SCP) produced a revision, when it was generated, what process was used, who the contributors were, and what parent revisions it was based on.
| Organization | A collection of people who collectively create the Source. Examples of organizations include open-source projects, a company, or a team within a company. The organization defines the goals and methods of the repository.
| Repository | A uniquely identifiable instance of a VCS hosted on an SCP. The repository controls access to the Source in the version control system. The objective of a repository is to reflect the intent of the organization that controls it.
| Branch | A named pointer to a revision. Branches may be modified by authorized actors. In git, cloning a repo will download all revisions in the history of the "default" branch to the local machine.
| Change | A set of modifications to the source in a specific context. As an example, a proposed change to a "releases/1" branch may require higher scrutiny than a change to "users/1".
| Change History | A record of the history of revisions that preceded a specific revision.

## Source Roles

| Role | Description
| --- | ---
| Administrator | A human who can perform privileged operations on one or more projects. Privileged actions include, but are not limited to, modifying the change history and modifying project- or organization-wide security policies.
| Trusted person | A human who is authorized by the organization to propose and approve changes to the source.
| Trusted robot | Automation with an authentic identity that is authorized by the organization to propose and/or approve changes to the source.
| Untrusted person | A human who has limited access to the project. They MAY be able to read the source. They MAY be able to propose or review changes to the source. They MAY NOT approve changes to the source or perform any privileged actions on the project.
| Proposer | The role that proposes a particular change to the source.
| Reviewer | The role that reviews a particular proposed change to the source.
| Approver | The role that approves a particular change to the source.
| Merger | The role that applies a change to the source. This person may be the proposer or a different trusted person, depending on the version control platform.
| Proposer | An actor that proposes a particular change to the source.
| Reviewer | An actor that reviews a particular change to the source.
| Approver | An actor that approves a particular change to the source.
| Merger | An actor that applies a change to the source. This typically involves creating the new revision and updating a branch. This person may be the proposer or a different trusted person, depending on the version control platform.

## Source Platform Requirements

Expand Down

0 comments on commit 7c6ba23

Please sign in to comment.