From 989aeb8ddca3a2e34a7b5b8e85e47f0c7bd0145d Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 12 Jul 2024 14:23:18 -0400 Subject: [PATCH 01/44] initial content, waiting for main to be updated. --- docs/spec/draft/source-requirements.md | 56 ++++++++++++++++++++------ 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 347b99839..8127c1de4 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -47,33 +47,63 @@ The Source track is scoped to a single project that is controlled by some organi | 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. -## Source Platform Requirements +## Source Control Platform and Version Control System Requirements -The version control system MUST provide at least: +The combination of SCP and VCS MUST provide: -- **[Immutable reference]** There exists a deterministic way to identify this particular revision. This is usually {project identifier + revision ID}. When the revision ID is a digest of the revision, as in git, nothing more is needed. When the revision ID is a number or otherwise not a digest, then the project server MUST guarantee that revisions cannot be altered once created. +### **[Immutable reference]** -- **[Change history]** There exists a record of the history of changes that went into the revision. Each change MUST contain: +There exists a deterministic way to identify a particular revision. + +This is usually a combination of the repository ID and revision ID. +When the revision ID is a digest of the revision, as in git, nothing more is needed. +When the revision ID is a number or otherwise not a digest, then the repository server MUST guarantee that revisions cannot be altered once created. +The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. + +### **[Identity Management]** + +There exists an identity management system or some other means of identifying actors. + +The SCP will use these identities for recording change history and writing provenance attestations. + +### **[Change history]** + +There exists a record of the history of changes conducted on this SCP that went into the revision. + +A merged GitHub pull request is an example of a change record. +Each change MUST contain: - The immutable reference to the new revision. - - The identities of the proposer, reviewers (if any), and merger (if different to the proposer). - - Timestamps of change submission. If a change is reviewed, then the change history MUST also include timestamps for any reviews. + - The list of parent revisions. - The change description/justification. - The content of the change. - - The parent revisions. + - The [Merger](#source-roles) of the change. + - The timestamp when the change was received by the SCP + +Administrators have the necessary permissions to replace the source in a known repo. +In mechanical terms, this means changing the source for a known repository ID without publishing a change record. +This includes changing files, history, or changing references in git. +When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. +If an organization must change the source without publishing a change record, the organization will need to demonstrate that the change was necessary and executed responsibly. + +### **[Change Management]** + +There exists a trusted mechanism for modifying the canonical source through a **revision process**. -Most popular version control systems meet these requirement, such as git, Subversion, Mercurial, and Perforce. +The revision process MUST record at least: -The source control platform MUST provide at least: +- The identities of the proposer, reviewers (if any), and merger (if different from the proposer). +- Timestamps of change submission. If a change is reviewed, then the change history MUST also include timestamps for any reviews. +- The specific change reviewed during the revision process or instructions to recreate it. In git, this might be the two compared object ids and the computed best merge base between them at the time of review. -- An account system or some other means of identifying persons. -- A mechanism for modifying the canonical source through a **revision process**. +### Additional features -The source control platform SHOULD additionally provide: +The combination of SCP and VCS SHOULD additionally provide: -- A mechanism for assigning roles and/or permissions to identities. +- A mechanism for assigning roles and/or permissions to actors. - A mechanism for including code review in the revision process. - Two-factor authentication for the account system (L2+ only). - Audit logs for sensitive actions, such as modifying security controls. +- A mechanism to define code ownership for all files in the source repository. ## Levels From 68e8632720655bf853bc385806376ede84eb2bd2 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Tue, 16 Jul 2024 11:49:47 -0400 Subject: [PATCH 02/44] react to pr feedback. --- docs/spec/draft/source-requirements.md | 66 +++++++++++++------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 7b26c8de3..33f631dc7 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -54,11 +54,24 @@ Consumers can examine the various source provenance attestations to determine if | 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. + +## Safe Expunging Process + +(placeholder text) + +Administrators have the necessary permissions to replace the source in a known repo without publishing a change record. + +This includes changing files, history, or changing references in git. + +When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. + +If an organization must change the source without publishing a change record, the organization will need to demonstrate that the change was necessary and executed responsibly. + ## Source Control Platform and Version Control System Requirements The combination of SCP and VCS MUST provide: -### **[Immutable reference]** +### Immutable reference There exists a deterministic way to identify a particular revision. @@ -67,50 +80,39 @@ When the revision ID is a digest of the revision, as in git, nothing more is nee When the revision ID is a number or otherwise not a digest, then the repository server MUST guarantee that revisions cannot be altered once created. The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. -### **[Identity Management]** +### Identity Management There exists an identity management system or some other means of identifying actors. -The SCP will use these identities for recording change history and writing provenance attestations. - -### **[Change history]** - -There exists a record of the history of changes conducted on this SCP that went into the revision. +The SCP will use these identities to: -A merged GitHub pull request is an example of a change record. -Each change MUST contain: - - The immutable reference to the new revision. - - The list of parent revisions. - - The change description/justification. - - The content of the change. - - The [Merger](#source-roles) of the change. - - The timestamp when the change was received by the SCP - -Administrators have the necessary permissions to replace the source in a known repo. -In mechanical terms, this means changing the source for a known repository ID without publishing a change record. -This includes changing files, history, or changing references in git. -When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. -If an organization must change the source without publishing a change record, the organization will need to demonstrate that the change was necessary and executed responsibly. +- Implement actor-based rules (such as required review from code experts) +- Record contributors to a code revision process +- Issuing source provenance attestations. -### **[Change Management]** +### Revision process -There exists a trusted mechanism for modifying the canonical source through a **revision process**. +There exists a trusted mechanism for modifying the source pointed-to by a [branch](#definitions). +For each [branch](#definitions), the SCP MUST record and keep the full history of changes conducted on this SCP, with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). -The revision process MUST record at least: +The revision process MUST: +- Provide an accurate description of the currently proprosed change, or instructions to recreate it. +- Provide the ability to review a change before it is accepted +- Provide the ability to require pre-approval from specific actors before a change proposal is accepted. +- Record all actors that contributed to the process, including the proposers, merger and reviewers (if any). +- Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. +- Record the specific state of the process when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. -- The identities of the proposer, reviewers (if any), and merger (if different from the proposer). -- Timestamps of change submission. If a change is reviewed, then the change history MUST also include timestamps for any reviews. -- The specific change reviewed during the revision process or instructions to recreate it. In git, this might be the two compared object ids and the computed best merge base between them at the time of review. ### Additional features -The combination of SCP and VCS SHOULD additionally provide: +The combination of SCP and VCS SHOULD provide: -- A mechanism for assigning roles and/or permissions to actors. -- A mechanism for including code review in the revision process. -- Two-factor authentication for the account system (L2+ only). +- A mechanism for assigning roles and/or permissions to [actors](#source-roles). +- A mechanism for including code review in the [revision process](#revision-process). +- Two-factor authentication for the [identity management system](#identity-management). - Audit logs for sensitive actions, such as modifying security controls. -- A mechanism to define code ownership for all files in the source repository. +- A mechanism to define code ownership for all files in the source. ## Levels From 5d5df51a2f9b372197decfd88992420afba9ba7d Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Tue, 16 Jul 2024 11:55:29 -0400 Subject: [PATCH 03/44] linter --- docs/spec/draft/source-requirements.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 33f631dc7..8b6a75895 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -54,7 +54,6 @@ Consumers can examine the various source provenance attestations to determine if | 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. - ## Safe Expunging Process (placeholder text) @@ -96,14 +95,14 @@ There exists a trusted mechanism for modifying the source pointed-to by a [branc For each [branch](#definitions), the SCP MUST record and keep the full history of changes conducted on this SCP, with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). The revision process MUST: + - Provide an accurate description of the currently proprosed change, or instructions to recreate it. -- Provide the ability to review a change before it is accepted +- Provide the ability to review a change before it is accepted. - Provide the ability to require pre-approval from specific actors before a change proposal is accepted. - Record all actors that contributed to the process, including the proposers, merger and reviewers (if any). - Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. - Record the specific state of the process when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. - ### Additional features The combination of SCP and VCS SHOULD provide: From b2071c07e88dbbd5a5f099573f4366fb008afb72 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Tue, 16 Jul 2024 13:02:26 -0400 Subject: [PATCH 04/44] clarity --- docs/spec/draft/source-requirements.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 8b6a75895..34a5a3310 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -82,12 +82,15 @@ The SCP MUST guarantee that repository IDs track the complete history of changes ### Identity Management There exists an identity management system or some other means of identifying actors. +This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). +SCPs SHOULD pick one and use a single identity management system when issuing content in provenance attestations. + The SCP will use these identities to: -- Implement actor-based rules (such as required review from code experts) -- Record contributors to a code revision process -- Issuing source provenance attestations. +- Implement actor-based rules (such as requiring review from code experts). +- Record contributors to a code revision process (in git, this may differ from what is in the commit metadata). +- Refer to actors in issued source provenance attestations. ### Revision process @@ -99,7 +102,7 @@ The revision process MUST: - Provide an accurate description of the currently proprosed change, or instructions to recreate it. - Provide the ability to review a change before it is accepted. - Provide the ability to require pre-approval from specific actors before a change proposal is accepted. -- Record all actors that contributed to the process, including the proposers, merger and reviewers (if any). +- Record all actors that contributed to the process, see [Source Roles](#source-roles). - Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. - Record the specific state of the process when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. From cc8a51ce4e69483cb686f7f12f32692003a4429f Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 17 Jul 2024 09:08:08 -0400 Subject: [PATCH 05/44] linter --- docs/spec/draft/source-requirements.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 34a5a3310..977324bc2 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -85,7 +85,6 @@ There exists an identity management system or some other means of identifying ac This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). SCPs SHOULD pick one and use a single identity management system when issuing content in provenance attestations. - The SCP will use these identities to: - Implement actor-based rules (such as requiring review from code experts). From 5a456d696811c74e52f6d8236ae14683c890e7d1 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 22 Jul 2024 12:16:57 -0400 Subject: [PATCH 06/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 977324bc2..3f286c8d7 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -58,7 +58,7 @@ Consumers can examine the various source provenance attestations to determine if (placeholder text) -Administrators have the necessary permissions to replace the source in a known repo without publishing a change record. +Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content. This includes changing files, history, or changing references in git. From ad62f09145b9d8e7f8329b32638e54301ab2e323 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 22 Jul 2024 16:49:37 -0400 Subject: [PATCH 07/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 3f286c8d7..1f5fb34c9 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -76,7 +76,7 @@ There exists a deterministic way to identify a particular revision. This is usually a combination of the repository ID and revision ID. When the revision ID is a digest of the revision, as in git, nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the repository server MUST guarantee that revisions cannot be altered once created. +When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. ### Identity Management From e4050b4493e7c410331dd0f0212a6345084b4424 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 22 Jul 2024 15:17:00 -0600 Subject: [PATCH 08/44] address pr feedback. --- docs/spec/draft/source-requirements.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 1f5fb34c9..86162d9da 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -56,15 +56,11 @@ Consumers can examine the various source provenance attestations to determine if ## Safe Expunging Process -(placeholder text) - Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content. - This includes changing files, history, or changing references in git. - When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. -If an organization must change the source without publishing a change record, the organization will need to demonstrate that the change was necessary and executed responsibly. +TODO: Determine how organizations can provide transparency around this process. ## Source Control Platform and Version Control System Requirements @@ -83,13 +79,10 @@ The SCP MUST guarantee that repository IDs track the complete history of changes There exists an identity management system or some other means of identifying actors. This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). -SCPs SHOULD pick one and use a single identity management system when issuing content in provenance attestations. - -The SCP will use these identities to: +SCPs SHOULD pick one and use a single identity management system when issuing source provenance attestations. -- Implement actor-based rules (such as requiring review from code experts). -- Record contributors to a code revision process (in git, this may differ from what is in the commit metadata). -- Refer to actors in issued source provenance attestations. +When there are conflicting identity claims the authenticated identity MUST be used. +For example in a single git commit the "author", "committer," and the gpg signature's "user id" may be different, and they may all be different than the authenticated identity used to push the commit to the SCP. ### Revision process @@ -110,7 +103,6 @@ The revision process MUST: The combination of SCP and VCS SHOULD provide: - A mechanism for assigning roles and/or permissions to [actors](#source-roles). -- A mechanism for including code review in the [revision process](#revision-process). - Two-factor authentication for the [identity management system](#identity-management). - Audit logs for sensitive actions, such as modifying security controls. - A mechanism to define code ownership for all files in the source. From 47f8ad30f2f9bccdd4357d5523527c07ff58abd8 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 22 Jul 2024 15:30:23 -0600 Subject: [PATCH 09/44] clarify "code owners" --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 86162d9da..afcc63b43 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -105,7 +105,7 @@ The combination of SCP and VCS SHOULD provide: - A mechanism for assigning roles and/or permissions to [actors](#source-roles). - Two-factor authentication for the [identity management system](#identity-management). - Audit logs for sensitive actions, such as modifying security controls. -- A mechanism to define code ownership for all files in the source. +- A mechanism to define a set of expert reviewers for each file in the source, and the ability to require their approval on any changes. ## Levels From d212e0817779071275cc8bcc98413fbd2b8d1690 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 22 Jul 2024 16:29:18 -0600 Subject: [PATCH 10/44] reimagine as a level 1 requirement --- docs/spec/draft/source-requirements.md | 90 ++++++++++++++------------ 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index afcc63b43..0e682091a 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -62,11 +62,20 @@ When used as an attack, this is called “repo hijacking” (or “repo-jacking TODO: Determine how organizations can provide transparency around this process. -## Source Control Platform and Version Control System Requirements +## Levels + +### Level 1: Version controlled + +Summary: The source is stored and managed through a modern version control system with a revision process. + +Intended for: Organizations that are unwilling or unable to host their source on a source control platform. If possible, skip to Level 2. -The combination of SCP and VCS MUST provide: +Benefits: Version control solves software development challenges ranging from change attribution to effective collaboration. +It is a software development best practice with more benefits than we can discuss here. -### Immutable reference +Requirements: The combination of SCP and VCS MUST provide: + +#### Immutable references There exists a deterministic way to identify a particular revision. @@ -75,7 +84,7 @@ When the revision ID is a digest of the revision, as in git, nothing more is nee When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. -### Identity Management +#### Identity Management There exists an identity management system or some other means of identifying actors. This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). @@ -84,7 +93,7 @@ SCPs SHOULD pick one and use a single identity management system when issuing so When there are conflicting identity claims the authenticated identity MUST be used. For example in a single git commit the "author", "committer," and the gpg signature's "user id" may be different, and they may all be different than the authenticated identity used to push the commit to the SCP. -### Revision process +#### Revision process There exists a trusted mechanism for modifying the source pointed-to by a [branch](#definitions). For each [branch](#definitions), the SCP MUST record and keep the full history of changes conducted on this SCP, with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). @@ -98,66 +107,67 @@ The revision process MUST: - Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. - Record the specific state of the process when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. -### Additional features +### Level 2: TODO, but maybe: Generates Source Provenance Attestations -The combination of SCP and VCS SHOULD provide: +Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. -- A mechanism for assigning roles and/or permissions to [actors](#source-roles). -- Two-factor authentication for the [identity management system](#identity-management). -- Audit logs for sensitive actions, such as modifying security controls. -- A mechanism to define a set of expert reviewers for each file in the source, and the ability to require their approval on any changes. +Intended for: Organizations that need to enforce policy on consumed source. -## Levels +Benefits: Prevents many classes of accidents and pin-to-sha attacks. Provides information to VSA-generation bots. -### Level 1: Version controlled +Requirements: -Summary: The project source is stored and managed through a modern version control system. +#### Source provenance attestation -Intended for: Organizations that are unwilling or unable to host their source on a source control platform. If possible, skip to Level 2. +Results from the revision process are codified into a source provenance attestation document. -Requirements: +TODO: -**[Version controlled]** Every change to the source is tracked in a version control system that meets the requirements listed in [Source Platform Requirements](#source-platform-requirements). +- (minimum requirements for provenance attestations) +- (optional features of provenance attestations) -Benefits: Version control solves software development challenges ranging from change attribution to effective collaboration. It is a software development best practice with more benefits than we can discuss here. +### Level 3: TODO but maybe: Changes are authorized -### Level 2: Verified history +Summary: All changes to the source are approved by two trusted actors prior to submission. -Summary: The source code and its change history metadata are retained and authenticated to allow trustworthy auditing and analysis of the source code. +Intended for: Enterprise projects and mature open source projects. -Intended for: Organizations that are unwilling or unable to incorporate code review into their software development practices. +Benefits: A compromise of a single account does not result in compromise of the source. Requirements: -**[Strong authentication]** User accounts that can modify the source or the project's configuration must use multi-factor authentication or its equivalent. -**[Verified timestamps]** Each entry in the change history must contain at least one timestamp that is determined by the source control platform and cannot be modified by clients. It MUST be clear in the change history which timestamps are determined by the source control platform. +#### Code review by two authorized actors -**[Retained history]** The change history MUST be preserved as long as the source is hosted on the source control system. The source MAY migrate to another source control system, but the organization MUST retain the change history if possible. It MUST NOT be possible for persons to delete or modify the change history, even with multi-party approval, except by trusted platform admins following an established deletion policy. +All changes to the source are approved by two authorized actors prior to submission. +User accounts that can perform code reviews MUST use two-factor authentication or its equivalent. -Benefits: Attributes changes in the version history to specific actors and timestamps, which allows for post-auditing, incident response, and deterrence for bad actors. Multi-factor authentication makes account compromise more difficult, further ensuring the integrity of change attribution. +If the proposer is also an authorized actor, the proposer MAY approve their own proposal and count as one of the two required actors. -### Level 3: Changes are authorized +The code review system must meet the following requirements: -Summary: All changes to the source are approved by two trusted persons prior to submission. +- **[Informed review]** The reviewer is able and encouraged to make an informed decision about what they're approving. The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. For example, it is not sufficient to just indicate that a file changed without showing the contents. +- **[Context-specific approvals]** Approvals are for a specific context, such as a repo + target branch in git. Moving fully reviewed content from one context to another still requires review, except for well-understood automatic processes. For example, you do not need to review each change to cut a release branch, but you do need review when backporting changes from the main branch to an existing release branch. +- **[Atomic change sets]** Changes are recorded in the change history as a single revision that consists of the net delta between the proposed revision and the parent revision. In the case of a nonlinear version control system, where a revision can have more than one parent, the diff must be against the "first common parent" between the parents. In other words, when a feature branch is merged back into the main branch, only the merge itself is in scope. -Intended for: Enterprise projects and mature open source projects. +#### Different actors -Requirements: +The organization strives to ensure that no two user accounts correspond to the same actors. +Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. +For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). -**[Code review]** All changes to the source are approved by two trusted persons prior to submission. User accounts that can perform code reviews MUST use two-factor authentication or its equivalent. -The following combinations of trusted persons are acceptable: +### Level 4: TODO but maybe: Maximum security -- Proposer and reviewer are two different trusted persons. -- Two different reviewers are trusted persons. +Summary: All changes are reviewed by experts. -The code review system must meet the following requirements: +Intended for: The highest of high-security-posture repos / code that is flying to Mars. -- **[Informed review]** The reviewer is able and encouraged to make an informed decision about what they're approving. The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. For example, it is not sufficient to just indicate that a file changed without showing the contents. -- **[Context-specific approvals]** Approvals are for a specific context, such as a repo + target branch + revision in git. Moving fully reviewed content from one context to another still requires review, except for well-understood automatic processes. For example, you do not need to review each change to cut a release branch, but you do need review when backporting changes from the main branch to an existing release branch. -- **[Atomic change sets]** Changes are recorded in the change history as a single revision that consists of the net delta between the proposed revision and the parent revision. In the case of a nonlinear version control system, where a revision can have more than one parent, the diff must be against the "first common parent" between the parents. In other words, when a feature branch is merged back into the main branch, only the merge itself is in scope. +Benefits: Provides the maximum chance for experts to spot and reject problems before they ship. + +Requirements: -Trusted robots MAY be exempted from the code review process. It is RECOMMENDED that trusted robots so exempted be run only software built at Build L3+ from sources that meet Source L3. +#### Reset votes on all changes -**[Different persons]** The organization strives to ensure that no two user accounts correspond to the same person. Should the organization discover that it issued multiple accounts to the same person, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that person's accounts are the author and/or code reviewer(s). +The code review tool MUST ensure that the final proposal is approved by actors identified as experts for all changed files. -Benefits: A compromise of a single human or account does not result in compromise of the project, since all changes require review from two humans. +If a file is modified after receiving expert approval, a new approval MUST be granted. +The new approval MAY be granted by the same actor who granted the first approval. From 8bf4205b068add4d64d56bc5d766144604fd26f2 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 29 Jul 2024 06:24:03 -0700 Subject: [PATCH 11/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 0e682091a..4127bf236 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -56,7 +56,7 @@ Consumers can examine the various source provenance attestations to determine if ## Safe Expunging Process -Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content. +Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content (to accommodate legal or privacy compliance requirements). This includes changing files, history, or changing references in git. When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. From 2343b07c4d0724e179e3ff76cb9ed83f82d705ec Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 29 Jul 2024 06:34:29 -0700 Subject: [PATCH 12/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 4127bf236..8c8dd89f3 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -82,7 +82,7 @@ There exists a deterministic way to identify a particular revision. This is usually a combination of the repository ID and revision ID. When the revision ID is a digest of the revision, as in git, nothing more is needed. When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). -The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. +The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). #### Identity Management From a7fd4fe5e6842c2687375ab453e88e98106cf3ac Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 29 Jul 2024 09:57:07 -0400 Subject: [PATCH 13/44] pr feedback --- docs/spec/draft/source-requirements.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 8c8dd89f3..9bbb0f03e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -68,7 +68,7 @@ TODO: Determine how organizations can provide transparency around this process. Summary: The source is stored and managed through a modern version control system with a revision process. -Intended for: Organizations that are unwilling or unable to host their source on a source control platform. If possible, skip to Level 2. +Intended for: Organizations wanting to easily and quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem without changing their source workflows. Benefits: Version control solves software development challenges ranging from change attribution to effective collaboration. It is a software development best practice with more benefits than we can discuss here. @@ -82,7 +82,7 @@ There exists a deterministic way to identify a particular revision. This is usually a combination of the repository ID and revision ID. When the revision ID is a digest of the revision, as in git, nothing more is needed. When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). -The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). +The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. #### Identity Management @@ -90,8 +90,9 @@ There exists an identity management system or some other means of identifying ac This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). SCPs SHOULD pick one and use a single identity management system when issuing source provenance attestations. -When there are conflicting identity claims the authenticated identity MUST be used. +When there are conflicting identity claims the authenticated identity MUST be used for generating attestations, but other forms of identity MAY be used for informational purposes. For example in a single git commit the "author", "committer," and the gpg signature's "user id" may be different, and they may all be different than the authenticated identity used to push the commit to the SCP. +In this case, the identity used to push the commit MUST be used for source provenance, however the other forms of identity MAY be included as informational. #### Revision process @@ -101,11 +102,9 @@ For each [branch](#definitions), the SCP MUST record and keep the full history o The revision process MUST: - Provide an accurate description of the currently proprosed change, or instructions to recreate it. -- Provide the ability to review a change before it is accepted. - Provide the ability to require pre-approval from specific actors before a change proposal is accepted. - Record all actors that contributed to the process, see [Source Roles](#source-roles). - Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. -- Record the specific state of the process when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. ### Level 2: TODO, but maybe: Generates Source Provenance Attestations @@ -130,7 +129,9 @@ TODO: Summary: All changes to the source are approved by two trusted actors prior to submission. -Intended for: Enterprise projects and mature open source projects. +Intended for: Enterprise repositories and mature open source projects. + +Benefits: A compromise of a single account does not result in compromise of the source. Benefits: A compromise of a single account does not result in compromise of the source. @@ -148,6 +149,7 @@ The code review system must meet the following requirements: - **[Informed review]** The reviewer is able and encouraged to make an informed decision about what they're approving. The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. For example, it is not sufficient to just indicate that a file changed without showing the contents. - **[Context-specific approvals]** Approvals are for a specific context, such as a repo + target branch in git. Moving fully reviewed content from one context to another still requires review, except for well-understood automatic processes. For example, you do not need to review each change to cut a release branch, but you do need review when backporting changes from the main branch to an existing release branch. - **[Atomic change sets]** Changes are recorded in the change history as a single revision that consists of the net delta between the proposed revision and the parent revision. In the case of a nonlinear version control system, where a revision can have more than one parent, the diff must be against the "first common parent" between the parents. In other words, when a feature branch is merged back into the main branch, only the merge itself is in scope. +- **[Record keeping]** Provenance must include the timestamp and the state of proposed revision at the point when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. #### Different actors From b0035483e7272aa931540d47dc2aac692bab6e5c Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 29 Jul 2024 12:03:29 -0400 Subject: [PATCH 14/44] cleanup --- docs/spec/draft/source-requirements.md | 33 +++++++++++++++++--------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 9bbb0f03e..f792b736a 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -75,7 +75,7 @@ It is a software development best practice with more benefits than we can discus Requirements: The combination of SCP and VCS MUST provide: -#### Immutable references +#### Immutable revisions There exists a deterministic way to identify a particular revision. @@ -88,11 +88,6 @@ The SCP MUST guarantee that repository IDs track the complete history of changes There exists an identity management system or some other means of identifying actors. This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). -SCPs SHOULD pick one and use a single identity management system when issuing source provenance attestations. - -When there are conflicting identity claims the authenticated identity MUST be used for generating attestations, but other forms of identity MAY be used for informational purposes. -For example in a single git commit the "author", "committer," and the gpg signature's "user id" may be different, and they may all be different than the authenticated identity used to push the commit to the SCP. -In this case, the identity used to push the commit MUST be used for source provenance, however the other forms of identity MAY be included as informational. #### Revision process @@ -119,11 +114,29 @@ Requirements: #### Source provenance attestation Results from the revision process are codified into a source provenance attestation document. +Must record who, what, when. + +##### Who + +Source provenance attestation issuers SHOULD use a single identity definiton. + +The strongly authenticated idenenty used to login to the SCP MUST be used for the generation of source provenance attestations. +This is typically the identity used to push to a git server. + +Other forms of identity MAY be included as informational. +Examples include a git commit "author" and "committer," and a gpg signature's "user id." +These forms of identity are user-provided and not typically verified by the issuer. -TODO: +##### What -- (minimum requirements for provenance attestations) -- (optional features of provenance attestations) +Must record the proposal provided to reviewers for approval or instructions to reproduce it. +Git-specific stuff: TODO: provide instructions for three sha merge-same diff generation. + +Must record target branch. + +##### When + +Must record when commits and review are received by the server. ### Level 3: TODO but maybe: Changes are authorized @@ -133,8 +146,6 @@ Intended for: Enterprise repositories and mature open source projects. Benefits: A compromise of a single account does not result in compromise of the source. -Benefits: A compromise of a single account does not result in compromise of the source. - Requirements: #### Code review by two authorized actors From 09b0c673eaee110d8c4bb06ba04c0c5a6a49a3c6 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 29 Jul 2024 12:20:00 -0400 Subject: [PATCH 15/44] add two more useful definitions --- docs/spec/draft/source-requirements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index f792b736a..648054842 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -40,6 +40,8 @@ Consumers can examine the various source provenance attestations to determine if | 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. +| Push / upload / publish | When an actor authenticates to an SCP to upload content. +| Review / approve / vote | When an actor authenticates to an change review tool and positively or negatively endorses the exact source change they were presented. ## Source Roles From 6d3e5822636e687c70ce902623382488552749c2 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 31 Jul 2024 14:21:12 -0400 Subject: [PATCH 16/44] large rewrite --- docs/spec/draft/source-requirements.md | 144 +++++++++++++++---------- 1 file changed, 86 insertions(+), 58 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 648054842..2b574c195 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -37,11 +37,11 @@ Consumers can examine the various source provenance attestations to determine if | 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". +| 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. Branches may have different security requirements. +| Change | A set of modifications to the source in a specific context. Can be proposed and reviewed before being accepted. | Change History | A record of the history of revisions that preceded a specific revision. -| Push / upload / publish | When an actor authenticates to an SCP to upload content. -| Review / approve / vote | When an actor authenticates to an change review tool and positively or negatively endorses the exact source change they were presented. +| Push / upload / publish | When an actor authenticates to an SCP to add or modify content. Typically makes a new revision reachable from a branch. +| Review / approve / vote | When an actor authenticates to a change review tool to leave comments or endorse / reject the source change proposal they were presented. ## Source Roles @@ -51,96 +51,113 @@ Consumers can examine the various source provenance attestations to determine if | 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 | 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. +| Proposer | An actor that proposes (or uploads) a particular change to the source. +| Reviewer / Voter / Approver | An actor that reviews (or votes on) a particular change to the source. +| Merger | An actor that applies a change to the source. This actor may be the proposer. ## Safe Expunging Process -Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content (to accommodate legal or privacy compliance requirements). -This includes changing files, history, or changing references in git. +Administrators have the ability to expunge (remove) content from a repository and its change history without leaving a record of the removed content. +This includes changing files, history, or changing references in git and is used to accommodate legal or privacy compliance requirements. When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. TODO: Determine how organizations can provide transparency around this process. ## Levels -### Level 1: Version controlled +### Level 1: Immutable revisions and Change Management Processeses -Summary: The source is stored and managed through a modern version control system with a revision process. +Summary: The source is stored and managed through a modern version control system and modified via a codified revision process. Intended for: Organizations wanting to easily and quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem without changing their source workflows. -Benefits: Version control solves software development challenges ranging from change attribution to effective collaboration. +Benefits: +Version control solves software development challenges ranging from change attribution to effective collaboration. It is a software development best practice with more benefits than we can discuss here. Requirements: The combination of SCP and VCS MUST provide: -#### Immutable revisions +#### Revisions are immutable and uniquely identifiable There exists a deterministic way to identify a particular revision. This is usually a combination of the repository ID and revision ID. -When the revision ID is a digest of the revision, as in git, nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). -The SCP MUST guarantee that repository IDs track the complete history of changes that occur to the source while hosted on the platform. +When the revision ID is a digest of the contend of the revision (as in git) nothing more is needed. +When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. +See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). #### Identity Management There exists an identity management system or some other means of identifying actors. -This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom (gittuf, gpg-signatures on commits, etc). +This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom implementation (gittuf, gpg-signatures on commits, etc). +The SCP MUST document how actors are identified for the purposes of attribution. -#### Revision process +Activities conducted on the SCP SHOULD be attributed to authenticated identities. + +#### Trusted revision process There exists a trusted mechanism for modifying the source pointed-to by a [branch](#definitions). -For each [branch](#definitions), the SCP MUST record and keep the full history of changes conducted on this SCP, with exceptions allowed following the [Safe Expunging Process](#safe-expunging-process). +It MUST NOT be possible to modify the content of a branch without following the documented process. -The revision process MUST: +An example of a revision process could be: all proposed changes MUST be pre-approved by code experts before being included on a protected branch in git. -- Provide an accurate description of the currently proprosed change, or instructions to recreate it. -- Provide the ability to require pre-approval from specific actors before a change proposal is accepted. -- Record all actors that contributed to the process, see [Source Roles](#source-roles). -- Record timestamps of critical activities including process start, process completion, reception of change proposals by the SCP, and reviews. +The revision process MUST specify the branch a contributor is proposing to update. -### Level 2: TODO, but maybe: Generates Source Provenance Attestations +### Level 2: Provenance -Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. +Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. The information is provided in a standardized format. Intended for: Organizations that need to enforce policy on consumed source. -Benefits: Prevents many classes of accidents and pin-to-sha attacks. Provides information to VSA-generation bots. +Benefits: Provides reliable information to policy enforcement tools. Requirements: #### Source provenance attestation -Results from the revision process are codified into a source provenance attestation document. -Must record who, what, when. +Source attestations are associated with the revision identifier delivered to consumers and are a record of everything the SCP knows about the revision's creation process. + +For example, if you perform a `git clone` operation, a consumer MUST be able to fetch the source attestation document using the commit id at the tip of the checked-out branch. + +Failure of the SCP to return a source attestation for the commit id is the same as saying the revision was not known to have been produced on the SCP. -##### Who +#### Trusted revision process requirements -Source provenance attestation issuers SHOULD use a single identity definiton. +The change management tool MUST provide at a minimum: + +##### Strong Authentication The strongly authenticated idenenty used to login to the SCP MUST be used for the generation of source provenance attestations. This is typically the identity used to push to a git server. Other forms of identity MAY be included as informational. -Examples include a git commit "author" and "committer," and a gpg signature's "user id." -These forms of identity are user-provided and not typically verified by the issuer. +Examples include a git commit "author" and "committer" and a gpg signature's "user id." +These forms of identity are user-provided and not typically verified by the source provenance attestation issuer. + +See [source roles](#source-roles). + +##### Change context -##### What +The change management tool MUST record the "target" context for the change proposal and the previous / current revision in that context. -Must record the proposal provided to reviewers for approval or instructions to reproduce it. -Git-specific stuff: TODO: provide instructions for three sha merge-same diff generation. +##### Informed Review -Must record target branch. +The change management tool MUST record the specific code change proposal (a "diff" in git) displayed to reivewers (if any) or instructions to recreate it. +The reviewer is able and encouraged to make an informed decision about what they're approving. +The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. +It is not sufficient to indicate that a file changed without showing the contents. -##### When +##### Verified Timestamps -Must record when commits and review are received by the server. +The change management tool MUST record timestamps for all contributions and review activities. +User-provided values MUST NOT be used. -### Level 3: TODO but maybe: Changes are authorized +##### Human-readable change description + +The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. +All collected content SHOULD be made immutable if the change is accepted. + +### Choose your own adventure: Changes are pre-authorized by two different authorized actors Summary: All changes to the source are approved by two trusted actors prior to submission. @@ -150,31 +167,42 @@ Benefits: A compromise of a single account does not result in compromise of the Requirements: -#### Code review by two authorized actors +#### Two authorized actors All changes to the source are approved by two authorized actors prior to submission. -User accounts that can perform code reviews MUST use two-factor authentication or its equivalent. - If the proposer is also an authorized actor, the proposer MAY approve their own proposal and count as one of the two required actors. -The code review system must meet the following requirements: - -- **[Informed review]** The reviewer is able and encouraged to make an informed decision about what they're approving. The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. For example, it is not sufficient to just indicate that a file changed without showing the contents. -- **[Context-specific approvals]** Approvals are for a specific context, such as a repo + target branch in git. Moving fully reviewed content from one context to another still requires review, except for well-understood automatic processes. For example, you do not need to review each change to cut a release branch, but you do need review when backporting changes from the main branch to an existing release branch. -- **[Atomic change sets]** Changes are recorded in the change history as a single revision that consists of the net delta between the proposed revision and the parent revision. In the case of a nonlinear version control system, where a revision can have more than one parent, the diff must be against the "first common parent" between the parents. In other words, when a feature branch is merged back into the main branch, only the merge itself is in scope. -- **[Record keeping]** Provenance must include the timestamp and the state of proposed revision at the point when each approval was granted. This is most relevant when the proposal content is allowed to change after aprovals have been granted. - #### Different actors -The organization strives to ensure that no two user accounts correspond to the same actors. +It MUST NOT be possible for a single actor to control more than one voting accounts. + Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). -### Level 4: TODO but maybe: Maximum security +### Choose your own adventure: Expert Code Reivew + +Summary: All changes to the source are pre-approved by experts in those areas. + +Intended for: Enterprise repositories and mature open source projects. + +Benefits: Prevents mistakes made by developers who are unfamiliar with the area. + +Requirements: + +#### Code ownership + +Each part of the source MUST have a clearly identified set of experts. + +#### Approvals from all relevant experts + +For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. +A approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. + +### Choose your own adventure: Maximum security -Summary: All changes are reviewed by experts. +Summary: The final revision was reviewed by all relevant experts prior to submission. -Intended for: The highest of high-security-posture repos / code that is flying to Mars. +Intended for: The highest-of-high-security-posture repos. Benefits: Provides the maximum chance for experts to spot and reject problems before they ship. @@ -182,7 +210,7 @@ Requirements: #### Reset votes on all changes -The code review tool MUST ensure that the final proposal is approved by actors identified as experts for all changed files. +If the proposal is modified after receiving expert approval, all previously granted approvals MUST be revoked. +A new approval MUST be granted from ALL required reviewers. -If a file is modified after receiving expert approval, a new approval MUST be granted. -The new approval MAY be granted by the same actor who granted the first approval. +The new approval MAY be granted by an actor who approved a previous iteration. From 99f372a246a770d4cb00ad9e586460b36e7f6a76 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 31 Jul 2024 14:32:03 -0400 Subject: [PATCH 17/44] talk vaguely about unit testing --- docs/spec/draft/source-requirements.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 2b574c195..41fbe7e00 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -214,3 +214,16 @@ If the proposal is modified after receiving expert approval, all previously gran A new approval MUST be granted from ALL required reviewers. The new approval MAY be granted by an actor who approved a previous iteration. + +### Choose your own adventure: Automated testing + +Summary: The final revision was validated against a suite of vetted automated tests. + +Intended for: All organizations and repositories. + +Benefits: Automatic testing has many benefits, including improved accuracy, error prevention and reduced workload on your human developers. + +Requirements: For each configured automatic test, results MUST be collected by the change review tool and included in the source provenance attestation. + +For example, you may configure a "required GitHub Actions workflow" to run your test suites. +Only change proposals with a successful workflow run id would be allowed to be submitted. From 6b82d6dd1917457ffcacbe9ff152c1a72322cc2d Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 31 Jul 2024 14:33:22 -0400 Subject: [PATCH 18/44] every revision --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 41fbe7e00..a8d0b1972 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -198,7 +198,7 @@ Each part of the source MUST have a clearly identified set of experts. For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. A approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. -### Choose your own adventure: Maximum security +### Choose your own adventure: Review Every Single Revision Summary: The final revision was reviewed by all relevant experts prior to submission. From a5834250ffe0b253e7cbea1005968e99915a8d52 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 31 Jul 2024 14:40:39 -0400 Subject: [PATCH 19/44] cleanup --- docs/spec/draft/source-requirements.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index a8d0b1972..d304dbd36 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -157,7 +157,12 @@ User-provided values MUST NOT be used. The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. All collected content SHOULD be made immutable if the change is accepted. -### Choose your own adventure: Changes are pre-authorized by two different authorized actors +## Choose your own adventure + +Now that you have a trustworthy way to communicate your security claims, what should you be looking for in those claims? +Here are a few extremely common examples. + +### Changes are pre-authorized by two different authorized actors Summary: All changes to the source are approved by two trusted actors prior to submission. @@ -179,7 +184,7 @@ It MUST NOT be possible for a single actor to control more than one voting accou Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). -### Choose your own adventure: Expert Code Reivew +### Expert Code Reivew Summary: All changes to the source are pre-approved by experts in those areas. @@ -198,7 +203,7 @@ Each part of the source MUST have a clearly identified set of experts. For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. A approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. -### Choose your own adventure: Review Every Single Revision +### Review Every Single Revision Summary: The final revision was reviewed by all relevant experts prior to submission. @@ -215,7 +220,7 @@ A new approval MUST be granted from ALL required reviewers. The new approval MAY be granted by an actor who approved a previous iteration. -### Choose your own adventure: Automated testing +### Automated testing Summary: The final revision was validated against a suite of vetted automated tests. From 64132b8f5f596f662d67a518291dc2a47b053801 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:34:37 -0700 Subject: [PATCH 20/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index d304dbd36..0fb8d414d 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -107,7 +107,7 @@ The revision process MUST specify the branch a contributor is proposing to updat Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. The information is provided in a standardized format. -Intended for: Organizations that need to enforce policy on consumed source. +Intended for: Organizations that want strong guarantees and auditability of their change management processes. Benefits: Provides reliable information to policy enforcement tools. From 9ab53dce4fcf4bc561b8c37751e347c282967117 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:35:00 -0700 Subject: [PATCH 21/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 0fb8d414d..22769241e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -117,7 +117,7 @@ Requirements: Source attestations are associated with the revision identifier delivered to consumers and are a record of everything the SCP knows about the revision's creation process. -For example, if you perform a `git clone` operation, a consumer MUST be able to fetch the source attestation document using the commit id at the tip of the checked-out branch. +For example, if you perform a `git clone` operation, a consumer MUST be able to fetch the source attestation documents using the commit id at the tip of the checked-out branch. Failure of the SCP to return a source attestation for the commit id is the same as saying the revision was not known to have been produced on the SCP. From 7269b053d5e6f2be7d80820a498e3d1965eb9137 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:35:14 -0700 Subject: [PATCH 22/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 22769241e..0ac074225 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -119,7 +119,7 @@ Source attestations are associated with the revision identifier delivered to con For example, if you perform a `git clone` operation, a consumer MUST be able to fetch the source attestation documents using the commit id at the tip of the checked-out branch. -Failure of the SCP to return a source attestation for the commit id is the same as saying the revision was not known to have been produced on the SCP. +Failure of the SCP to return source attestations for the commit id is the same as saying the revision was not known to have been produced on the SCP. #### Trusted revision process requirements From 1be7b2a6f71f1c34ce105534fde310009c6fba07 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:35:26 -0700 Subject: [PATCH 23/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Aditya Sirish <8928778+adityasaky@users.noreply.github.com> Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 0ac074225..d8aa346a5 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -127,7 +127,7 @@ The change management tool MUST provide at a minimum: ##### Strong Authentication -The strongly authenticated idenenty used to login to the SCP MUST be used for the generation of source provenance attestations. +The strongly authenticated identity used to login to the SCP MUST be used for the generation of source provenance attestations. This is typically the identity used to push to a git server. Other forms of identity MAY be included as informational. From 7faa87dd9521b2186bda6b53e53bdba21535274c Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 16:37:33 -0400 Subject: [PATCH 24/44] typos! --- docs/spec/draft/source-requirements.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index d8aa346a5..c3905d8ca 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -82,7 +82,7 @@ Requirements: The combination of SCP and VCS MUST provide: There exists a deterministic way to identify a particular revision. This is usually a combination of the repository ID and revision ID. -When the revision ID is a digest of the contend of the revision (as in git) nothing more is needed. +When the revision ID is a digest of the content of the revision (as in git) nothing more is needed. When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). @@ -142,7 +142,7 @@ The change management tool MUST record the "target" context for the change propo ##### Informed Review -The change management tool MUST record the specific code change proposal (a "diff" in git) displayed to reivewers (if any) or instructions to recreate it. +The change management tool MUST record the specific code change proposal (a "diff" in git) displayed to reviewers (if any) or instructions to recreate it. The reviewer is able and encouraged to make an informed decision about what they're approving. The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. It is not sufficient to indicate that a file changed without showing the contents. @@ -184,7 +184,7 @@ It MUST NOT be possible for a single actor to control more than one voting accou Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). -### Expert Code Reivew +### Expert Code Review Summary: All changes to the source are pre-approved by experts in those areas. From 843729c44b1e883b9daa181f3bacb5e495cac496 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:50:10 -0700 Subject: [PATCH 25/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Aditya Sirish <8928778+adityasaky@users.noreply.github.com> Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index c3905d8ca..51b1091e1 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -164,7 +164,7 @@ Here are a few extremely common examples. ### Changes are pre-authorized by two different authorized actors -Summary: All changes to the source are approved by two trusted actors prior to submission. +Summary: All changes to the source are approved by two trusted actors prior to acceptance. Intended for: Enterprise repositories and mature open source projects. From 69f611ce16c7ecfe4bdc1e117c8c499e51143a61 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:50:26 -0700 Subject: [PATCH 26/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 51b1091e1..04280fce7 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -222,7 +222,7 @@ The new approval MAY be granted by an actor who approved a previous iteration. ### Automated testing -Summary: The final revision was validated against a suite of vetted automated tests. +Summary: The final revision was validated against a suite of automated tests. Intended for: All organizations and repositories. From 08ec500effbc8bbf7436ece14d329818b3b0a0b3 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:51:43 -0700 Subject: [PATCH 27/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 04280fce7..59cdc8dc1 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -228,7 +228,7 @@ Intended for: All organizations and repositories. Benefits: Automatic testing has many benefits, including improved accuracy, error prevention and reduced workload on your human developers. -Requirements: For each configured automatic test, results MUST be collected by the change review tool and included in the source provenance attestation. +Requirements: For each configured automatic test, results MUST be collected by the change review tool, recorded in an attestation, and made available for verification. For example, you may configure a "required GitHub Actions workflow" to run your test suites. Only change proposals with a successful workflow run id would be allowed to be submitted. From 6515598d8f9c70f014e5d31656229818c7977af0 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:58:04 -0700 Subject: [PATCH 28/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Aditya Sirish <8928778+adityasaky@users.noreply.github.com> Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 59cdc8dc1..0121bb52a 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -174,7 +174,7 @@ Requirements: #### Two authorized actors -All changes to the source are approved by two authorized actors prior to submission. +All changes to the source are approved by two authorized actors prior to acceptance. If the proposer is also an authorized actor, the proposer MAY approve their own proposal and count as one of the two required actors. #### Different actors From f962ac41d67ff946604473e1d807343579b2e8cd Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 2 Aug 2024 13:58:43 -0700 Subject: [PATCH 29/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 0121bb52a..ce2d1fa10 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -184,6 +184,10 @@ It MUST NOT be possible for a single actor to control more than one voting accou Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). +#### Post-approval changes allowed + +When performing a review a reviewer may both approve the change and request modifications. Any modifications made need not reset the approval status of the change. To protect against post-approval change see [Review Every Single Revision](#review-every-single-revision). + ### Expert Code Review Summary: All changes to the source are pre-approved by experts in those areas. From d809349ae3a6402d9750184101394942d7ba0000 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 8 Aug 2024 17:08:54 -0400 Subject: [PATCH 30/44] pr feedback, remove trusted review process stuff --- docs/spec/draft/source-requirements.md | 92 ++++++++++++++++++++------ 1 file changed, 71 insertions(+), 21 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ce2d1fa10..9b0cbca6e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -61,13 +61,17 @@ Administrators have the ability to expunge (remove) content from a repository an This includes changing files, history, or changing references in git and is used to accommodate legal or privacy compliance requirements. When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. +On the git VCS, force pushes allow you to remove data from a protected branch and must follow the safe expunging process. + TODO: Determine how organizations can provide transparency around this process. +At a minimum the organization would need to declare why data was removed from the branch. ## Levels -### Level 1: Immutable revisions and Change Management Processeses +### Level 1: Version controlled -Summary: The source is stored and managed through a modern version control system and modified via a codified revision process. +Summary: +The source is stored and managed through a modern version control system. Intended for: Organizations wanting to easily and quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem without changing their source workflows. @@ -94,44 +98,59 @@ The SCP MUST document how actors are identified for the purposes of attribution. Activities conducted on the SCP SHOULD be attributed to authenticated identities. -#### Trusted revision process +#### Branches -There exists a trusted mechanism for modifying the source pointed-to by a [branch](#definitions). -It MUST NOT be possible to modify the content of a branch without following the documented process. +If the repository supports multiple branches, the organization MUST indicate which branches are intended for consumption. -An example of a revision process could be: all proposed changes MUST be pre-approved by code experts before being included on a protected branch in git. +##### Continuity -The revision process MUST specify the branch a contributor is proposing to update. +For all branches intended for consumption, it MUST be possible to view the ordered prior states of a source. +Exceptions are allowed via the [safe expunging process](#safe-expunging-process). -### Level 2: Provenance +### Level 2: Source Provenance Attestations -Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. The information is provided in a standardized format. +Summary: +A consumer can ask the SCP for everything it knows about a specific revision of a repository. +The information is provided in a standardized format. -Intended for: Organizations that want strong guarantees and auditability of their change management processes. +Intended for: +Organizations that want strong guarantees and auditability of their change management processes. -Benefits: Provides reliable information to policy enforcement tools. +Benefits: +Provides reliable information to policy enforcement tools. Requirements: -#### Source provenance attestation +#### Source provenance attestations + +Source attestations are associated with the revision identifier delivered to consumers. +They are a statement of fact from the perspective of the SCP. +They contain information about how a specific revision was created and how it came to exist in its present context. + +For example, if a consumer is authorized to access source on a particular branch, they MUST be able to fetch the source attestation documents for revisions in the history of that branch. -Source attestations are associated with the revision identifier delivered to consumers and are a record of everything the SCP knows about the revision's creation process. +It is possible that an SCP can make no provenance claims about a particular revision. +For example, this would happen if the revision was created on another SCP. -For example, if you perform a `git clone` operation, a consumer MUST be able to fetch the source attestation documents using the commit id at the tip of the checked-out branch. +#### Change management process -Failure of the SCP to return source attestations for the commit id is the same as saying the revision was not known to have been produced on the SCP. +The repo must define how the content of a [branch](#definitions) is allowed to change. +It MUST NOT be possible to modify the content of a branch without following the documented process. + +An example of a revision process could be: all proposed changes MUST be pre-approved by code experts before being included on a protected branch in git. -#### Trusted revision process requirements +The revision process MUST specify the branch a contributor is proposing to update. The change management tool MUST provide at a minimum: ##### Strong Authentication -The strongly authenticated identity used to login to the SCP MUST be used for the generation of source provenance attestations. -This is typically the identity used to push to a git server. +A strongly-authenticated identity MUST be used for the generation of source provenance attestations. +The SCP MUST declare which forms of identity it considers to be trustworthy for this purpose. +For cloud-based SCPs, this will typically be the identity used to push to a git server. Other forms of identity MAY be included as informational. -Examples include a git commit "author" and "committer" and a gpg signature's "user id." +Examples include a git commit's "author" and "committer" fields and a gpg signature's "user id." These forms of identity are user-provided and not typically verified by the source provenance attestation issuer. See [source roles](#source-roles). @@ -140,6 +159,8 @@ See [source roles](#source-roles). The change management tool MUST record the "target" context for the change proposal and the previous / current revision in that context. +For example, for the git version control system, the attestation MUST record the branch name that will be updated to point to a proposed + ##### Informed Review The change management tool MUST record the specific code change proposal (a "diff" in git) displayed to reviewers (if any) or instructions to recreate it. @@ -149,8 +170,8 @@ It is not sufficient to indicate that a file changed without showing the content ##### Verified Timestamps -The change management tool MUST record timestamps for all contributions and review activities. -User-provided values MUST NOT be used. +The change management tool MUST record timestamps for all contributions and review-related activities. +User-provided timestamps MUST NOT be used. ##### Human-readable change description @@ -236,3 +257,32 @@ Requirements: For each configured automatic test, results MUST be collected by t For example, you may configure a "required GitHub Actions workflow" to run your test suites. Only change proposals with a successful workflow run id would be allowed to be submitted. + +### Only merge the diff that was reviewed + +Summary: +New revisions are created based ONLY on the changes that were reviewed. + +Benefits: Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. + +Requirements: + +#### Context + +In many organizations it is normal to review only the "net difference" between the tip of the topic branch and the "best merge base", the closest shared commit between the topic and target branches computed at the time of review. + +The topic branch may contain many commits of which not all were intended to represent a shippable state of the repository. + +If a repository merges branches with a standard merge commit, all those unreviewed commits on the topic branch will become "reachable" from the protected branch by virtue of the multi-parent merge commit. + +When a repo is cloned, all commits _reachable_ from the main branch are fetched and become accessible from the local checkout. + +This combination of factors allows attacks where the victim performs a `git clone` operation followed by a `git reset --hard `. + +#### Mitigation + +Require a squash merge strategy for the protected branch. + +To guarantee that only commits representing reviewed diffs are cloned, the SCP must rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) with only a single parent (the revision previously pointed-to by the protected branch). + +It is not acceptable to replay the sequence of commits from the topic branch onto the protected branch. From 2f86109a6a8031b9151acb6963f6f96044d724cd Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 8 Aug 2024 17:12:02 -0400 Subject: [PATCH 31/44] consumable branch clarity? --- docs/spec/draft/source-requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 9b0cbca6e..ad4b9c707 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -61,7 +61,8 @@ Administrators have the ability to expunge (remove) content from a repository an This includes changing files, history, or changing references in git and is used to accommodate legal or privacy compliance requirements. When used as an attack, this is called “repo hijacking” (or “repo-jacking”) and is one of the primary threats source provenance attestations protect against. -On the git VCS, force pushes allow you to remove data from a protected branch and must follow the safe expunging process. +On the git VCS, force pushes allow you to remove data from a branch. +If a branch has been identified as consumable branch, force pushes to that branch must follow the safe expunging process. TODO: Determine how organizations can provide transparency around this process. At a minimum the organization would need to declare why data was removed from the branch. From 834d64c6e19d5d94bc3004492c8ec7a2b571902f Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Fri, 9 Aug 2024 09:20:04 -0400 Subject: [PATCH 32/44] pr comment feedback --- docs/spec/draft/source-requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ad4b9c707..bdda0f39a 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -146,7 +146,8 @@ The change management tool MUST provide at a minimum: ##### Strong Authentication -A strongly-authenticated identity MUST be used for the generation of source provenance attestations. +User accounts that can modify the source or the project's configuration must use multi-factor authentication or its equivalent. +This strongly authenticated identity MUST be used for the generation of source provenance attestations. The SCP MUST declare which forms of identity it considers to be trustworthy for this purpose. For cloud-based SCPs, this will typically be the identity used to push to a git server. From 9b72a775b9413ca1268c305095ca13fa449a6455 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 09:31:15 -0400 Subject: [PATCH 33/44] adding scenarios to the expunging section --- docs/spec/draft/source-requirements.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index bdda0f39a..86a536154 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -67,6 +67,27 @@ If a branch has been identified as consumable branch, force pushes to that branc TODO: Determine how organizations can provide transparency around this process. At a minimum the organization would need to declare why data was removed from the branch. +The goal of this sections is to document that this process is allowed. +Different organizations and tech stacks may have different approaches to the problem. + +Scenarios that need to be addressed: + +### Legal Takedowns + +A DMCA takedown request will be addressed by following an agreed-upon process. +That process should be documented itself and followed. +It may be the case that the specific set of commits targeted by the takedown can be expunged in ways that do not impact revisions. + +### Commit metadata rewrites + +A team may decide that all reachable commits in the history of a revision need to follow a new meta data convention. +In git VCS, compliance with this new policy will require history to be rewritten (commit metadata is included in the computation of the revision id). +Policies in this category include things like commit signatures, author / committer formatting restrictions, closed-issue-linkage, etc. + +### Repository renames + +When a repo is transferred to a new org ("donated"), or if a repo must be renamed or otherwise have its url changed within the same org, attestations for previous revisions of this repo will no longer be matched because the combination of the repository id and the revision id will have changed. + ## Levels ### Level 1: Version controlled From 006a4c1c6e10245a3c1499e6822c1f4f1b8b678e Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 11:10:37 -0400 Subject: [PATCH 34/44] hopefully last rewrite. --- docs/spec/draft/source-requirements.md | 167 ++++++++++++++++++------- 1 file changed, 125 insertions(+), 42 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 86a536154..1ec470c18 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -36,7 +36,7 @@ Consumers can examine the various source provenance attestations to determine if | 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. +| Repository / Repo | 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. Branches may have different security requirements. | Change | A set of modifications to the source in a specific context. Can be proposed and reviewed before being accepted. | Change History | A record of the history of revisions that preceded a specific revision. @@ -80,13 +80,13 @@ It may be the case that the specific set of commits targeted by the takedown can ### Commit metadata rewrites -A team may decide that all reachable commits in the history of a revision need to follow a new meta data convention. +A team may decide that all reachable commits in the history of a revision need to follow a new metadata convention. In git VCS, compliance with this new policy will require history to be rewritten (commit metadata is included in the computation of the revision id). Policies in this category include things like commit signatures, author / committer formatting restrictions, closed-issue-linkage, etc. ### Repository renames -When a repo is transferred to a new org ("donated"), or if a repo must be renamed or otherwise have its url changed within the same org, attestations for previous revisions of this repo will no longer be matched because the combination of the repository id and the revision id will have changed. +When a repo is transferred to a new organization ("donated"), or if a repo must be renamed or otherwise have its url changed within the same org, attestations for previous revisions of this repo will no longer be matched because the combination of the repository id and the revision id will have changed. ## Levels @@ -95,41 +95,90 @@ When a repo is transferred to a new org ("donated"), or if a repo must be rename Summary: The source is stored and managed through a modern version control system. -Intended for: Organizations wanting to easily and quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem without changing their source workflows. +Intended for: Organizations currently storing source in non-standard ways who want to quickly gain some benefits of SLSA and better integrate with the SLSA ecosystem with minimal impact to their current workflows. Benefits: -Version control solves software development challenges ranging from change attribution to effective collaboration. -It is a software development best practice with more benefits than we can discuss here. +Migrating to the appropriate tools is an important first step on the road to operational maturity. + +Requirements: + +#### Use modern tools + +The organization MUST manage the source using tools specifically designed to manage source code. +Tools like Perforce, GitLab, GitHub, Azure Repos are all great examples. -Requirements: The combination of SCP and VCS MUST provide: +Storing revisions as differently-named zips in folders on a laptop does not count. + +Branch protection is not required, nor are there any other constraints on the configuration of the tools. + +#### Canonical location + +The source MUST have a location where the "official" revisions are stored and managed. #### Revisions are immutable and uniquely identifiable -There exists a deterministic way to identify a particular revision. +This requirement ensures that a consumer can determine that the source revision they have is the same as a canonical revision. +The combination of SCP and VCS MUST provide a deterministic way to identify a particular revision. + +Virtually all modern tools provide this guarantee via a combination of the repository ID and revision ID. + +##### Repository IDs + +The repository ID is generated by the SCP and MUST be unique in the context of that instance of the SCP. + +##### Revision IDs -This is usually a combination of the repository ID and revision ID. When the revision ID is a digest of the content of the revision (as in git) nothing more is needed. -When the revision ID is a number or otherwise not a digest, then the SCP MUST document how the immutability of the revision is established. +When the revision ID is a number or otherwise not a digest, then the SCP and VCS MUST document how the immutability of the revision is established. +The same revision ID MAY be present in multiple repositories. See also [Use cases for non-cryptographic, immutable, digests](https://github.com/in-toto/attestation/blob/main/spec/v1/digest_set.md#use-cases-for-non-cryptographic-immutable-digests). -#### Identity Management +### Level 2: Branch History -There exists an identity management system or some other means of identifying actors. -This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom implementation (gittuf, gpg-signatures on commits, etc). -The SCP MUST document how actors are identified for the purposes of attribution. +Summary: +Clarifies which branches in a repo are consumable and guarantees that all changes to protected branches are recorded. -Activities conducted on the SCP SHOULD be attributed to authenticated identities. +Intended for: +All organizations of any size producing software of any kind. + +Benefits: +Version control solves software development challenges ranging from attribution to effective collaboration. +It is a software development best practice with more benefits than we can discuss here. + +Requirements: #### Branches -If the repository supports multiple branches, the organization MUST indicate which branches are intended for consumption. +If the SCP and VCS combination supports multiple branches, the organization MUST indicate which branches are intended for consumption. +This may be implied or explicit. + +For example, an organization may declare that the `default` branch of a repo contains revisions intended for consumption my protected it. + +They may also declare that branches named with the prefix `refs/heads/releases/*` contain revisions held to an even higher standard. + +They may also declare all revisions are intended to be consumed "except those reachable only from branches beginning with `refs/heads/users/*`." +This is a typical setup for teams who leverage code review tools. ##### Continuity -For all branches intended for consumption, it MUST be possible to view the ordered prior states of a source. +For all branches intended for consumption, whenever a branch is updated to point to a new revision, that revision MUST document how it related to the previous revision. Exceptions are allowed via the [safe expunging process](#safe-expunging-process). -### Level 2: Source Provenance Attestations +On VCS like git, the organization MUST enable branch protections that prohibit updating the branch to point to revisions that are not direct descendants of the current revision. +At a minimum, this typically means preventing "force pushes" and "branch deletion." + +It MUST NOT be possible to delete the entire repository (including all branches) and replace it with different source. +Exceptions are allowed via the [safe expunging process](#safe-expunging-process). + +#### Identity Management + +There exists an identity management system or some other means of identifying actors. +This system may be a federated authentication system (AAD, Google, Okta, GitHub, etc) or custom implementation (gittuf, gpg-signatures on commits, etc). +The SCP MUST document how actors are identified for the purposes of attribution. + +Activities conducted on the SCP SHOULD be attributed to authenticated identities. + +### Level 3: Source Provenance Attestations Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. @@ -157,11 +206,7 @@ For example, this would happen if the revision was created on another SCP. #### Change management process The repo must define how the content of a [branch](#definitions) is allowed to change. -It MUST NOT be possible to modify the content of a branch without following the documented process. - -An example of a revision process could be: all proposed changes MUST be pre-approved by code experts before being included on a protected branch in git. - -The revision process MUST specify the branch a contributor is proposing to update. +It MUST NOT be possible to modify the content of a branch without following its documented process. The change management tool MUST provide at a minimum: @@ -178,29 +223,21 @@ These forms of identity are user-provided and not typically verified by the sour See [source roles](#source-roles). -##### Change context - -The change management tool MUST record the "target" context for the change proposal and the previous / current revision in that context. +##### Context -For example, for the git version control system, the attestation MUST record the branch name that will be updated to point to a proposed +The change management tool MUST record the specific code change (a "diff" in git) or instructions to recreate it. +In git, this typically defined to be three revision IDs: the tip of the "topic" branch, the tip of the target branch, and closest shared ancestor between the two (such as determined by `git-merge-base`). -##### Informed Review +The change management tool MUST record the "target" context for the change proposal and the previous / current revision in that context. +For example, for the git version control system, the change management tool MUST record the branch name that was updated. -The change management tool MUST record the specific code change proposal (a "diff" in git) displayed to reviewers (if any) or instructions to recreate it. -The reviewer is able and encouraged to make an informed decision about what they're approving. -The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. -It is not sufficient to indicate that a file changed without showing the contents. +Branches may have differing security postures, and a change can be approved for one context while being unapproved for another. ##### Verified Timestamps The change management tool MUST record timestamps for all contributions and review-related activities. User-provided timestamps MUST NOT be used. -##### Human-readable change description - -The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. -All collected content SHOULD be made immutable if the change is accepted. - ## Choose your own adventure Now that you have a trustworthy way to communicate your security claims, what should you be looking for in those claims? @@ -281,12 +318,13 @@ Requirements: For each configured automatic test, results MUST be collected by t For example, you may configure a "required GitHub Actions workflow" to run your test suites. Only change proposals with a successful workflow run id would be allowed to be submitted. -### Only merge the diff that was reviewed +### Every revision reachable from a branch was approved Summary: -New revisions are created based ONLY on the changes that were reviewed. +New revisions are created based ONLY on the changes that were approved. -Benefits: Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. +Benefits: +Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. Requirements: @@ -302,10 +340,55 @@ When a repo is cloned, all commits _reachable_ from the main branch are fetched This combination of factors allows attacks where the victim performs a `git clone` operation followed by a `git reset --hard `. -#### Mitigation +#### Mitigations + +##### Informed Review + +The reviewer is able and encouraged to make an informed decision about what they're approving. +The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. + +It is not sufficient to indicate that a file changed without showing the contents. + +##### Use only rebase operations on the protected branch Require a squash merge strategy for the protected branch. -To guarantee that only commits representing reviewed diffs are cloned, the SCP must rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) with only a single parent (the revision previously pointed-to by the protected branch). +To guarantee that only commits representing reviewed diffs are cloned, the SCP MUST rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) that has only a single parent (the revision previously pointed-to by the protected branch). +This is different than a standard merge commit strategy which would cause all the user-contributed commits to become reachable from the protected branch via the second parent. It is not acceptable to replay the sequence of commits from the topic branch onto the protected branch. +The intent is to reduce the accepted changes to the exact diffs that were reviewed. +Constituent commits of the topic branch may or may not have been reviewed on an individual basis, and should not become reachable from the protected branch. + +### Immutable Change Discussion + +Summary: +The discussion around a change may often be as important as the change itself. + +Intended for: +Large organizations, or any where discussion is an important part of the change management process. + +Benefits: +From any revision, it's possible for future developers to read through the discussion that ultimately produced it. +This has many educational, forensics, and security auditing benefits. + +Requirements: + +The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. + +The change management tool MUST link this discussion to the revision itself. This is regularly done via commit metadata. + +All collected content SHOULD be made immutable if the change is accepted. +It SHOULD NOT be possible to edit the discussion around a revision after it has been accepted. + +### Fast moving repos and "merge trains" + +Large organizations must keep the number of updates to key protected branches under certain limits to allow time for code review to happen. +For example, if a team tries to merge 60 change requests per hour into the `main` branch, the tip of the `main` branch would only be stable for about 1 minute. +This would effectively leave only 1 minute for a new diff to be both generated and reviewed before it becomes stale again. + +The normal way to work in this environment is to create a buffer branch called a "train" to collect a certain number of approved changes. +The tip of this train branch represents a potential future state of the protected branch. +In this model, the protected branch is updated on a less frequent cadence to point to the tip of the entire train. + +TODO: Explain how attestation claims can be transferred from proposed merge commits to final revisions via a train. \ No newline at end of file From febc191005f9ba199b2a24fde939512735275541 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 11:14:01 -0400 Subject: [PATCH 35/44] update cyoa --- docs/spec/draft/source-requirements.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 1ec470c18..ecb24f649 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -238,10 +238,10 @@ Branches may have differing security postures, and a change can be approved for The change management tool MUST record timestamps for all contributions and review-related activities. User-provided timestamps MUST NOT be used. -## Choose your own adventure +## Choose your own adventure / Typical Source Controls and their Applications Now that you have a trustworthy way to communicate your security claims, what should you be looking for in those claims? -Here are a few extremely common examples. +Here are a few extremely common examples and important implementation details. ### Changes are pre-authorized by two different authorized actors From 6e3f3e3ec7db91b0bddcecb4d7efc9b7f54fdae8 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 10:27:58 -0700 Subject: [PATCH 36/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ecb24f649..1b4c6ce37 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -142,8 +142,7 @@ Intended for: All organizations of any size producing software of any kind. Benefits: -Version control solves software development challenges ranging from attribution to effective collaboration. -It is a software development best practice with more benefits than we can discuss here. +Allows source consumers to track changes to the software over time and attribute those changes to the people that made them. Requirements: From 6c05dc130a4d5355e04224a796671b0e20047b7f Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 17:21:48 -0400 Subject: [PATCH 37/44] move choose your own adventure stuff out. --- docs/spec/draft/source-requirements.md | 155 ------------------ docs/spec/draft/verifying-source.md | 209 +++++++++++++++++++++++++ 2 files changed, 209 insertions(+), 155 deletions(-) create mode 100644 docs/spec/draft/verifying-source.md diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 1b4c6ce37..f0b9a82e1 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -236,158 +236,3 @@ Branches may have differing security postures, and a change can be approved for The change management tool MUST record timestamps for all contributions and review-related activities. User-provided timestamps MUST NOT be used. - -## Choose your own adventure / Typical Source Controls and their Applications - -Now that you have a trustworthy way to communicate your security claims, what should you be looking for in those claims? -Here are a few extremely common examples and important implementation details. - -### Changes are pre-authorized by two different authorized actors - -Summary: All changes to the source are approved by two trusted actors prior to acceptance. - -Intended for: Enterprise repositories and mature open source projects. - -Benefits: A compromise of a single account does not result in compromise of the source. - -Requirements: - -#### Two authorized actors - -All changes to the source are approved by two authorized actors prior to acceptance. -If the proposer is also an authorized actor, the proposer MAY approve their own proposal and count as one of the two required actors. - -#### Different actors - -It MUST NOT be possible for a single actor to control more than one voting accounts. - -Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. -For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). - -#### Post-approval changes allowed - -When performing a review a reviewer may both approve the change and request modifications. Any modifications made need not reset the approval status of the change. To protect against post-approval change see [Review Every Single Revision](#review-every-single-revision). - -### Expert Code Review - -Summary: All changes to the source are pre-approved by experts in those areas. - -Intended for: Enterprise repositories and mature open source projects. - -Benefits: Prevents mistakes made by developers who are unfamiliar with the area. - -Requirements: - -#### Code ownership - -Each part of the source MUST have a clearly identified set of experts. - -#### Approvals from all relevant experts - -For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. -A approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. - -### Review Every Single Revision - -Summary: The final revision was reviewed by all relevant experts prior to submission. - -Intended for: The highest-of-high-security-posture repos. - -Benefits: Provides the maximum chance for experts to spot and reject problems before they ship. - -Requirements: - -#### Reset votes on all changes - -If the proposal is modified after receiving expert approval, all previously granted approvals MUST be revoked. -A new approval MUST be granted from ALL required reviewers. - -The new approval MAY be granted by an actor who approved a previous iteration. - -### Automated testing - -Summary: The final revision was validated against a suite of automated tests. - -Intended for: All organizations and repositories. - -Benefits: Automatic testing has many benefits, including improved accuracy, error prevention and reduced workload on your human developers. - -Requirements: For each configured automatic test, results MUST be collected by the change review tool, recorded in an attestation, and made available for verification. - -For example, you may configure a "required GitHub Actions workflow" to run your test suites. -Only change proposals with a successful workflow run id would be allowed to be submitted. - -### Every revision reachable from a branch was approved - -Summary: -New revisions are created based ONLY on the changes that were approved. - -Benefits: -Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. - -Requirements: - -#### Context - -In many organizations it is normal to review only the "net difference" between the tip of the topic branch and the "best merge base", the closest shared commit between the topic and target branches computed at the time of review. - -The topic branch may contain many commits of which not all were intended to represent a shippable state of the repository. - -If a repository merges branches with a standard merge commit, all those unreviewed commits on the topic branch will become "reachable" from the protected branch by virtue of the multi-parent merge commit. - -When a repo is cloned, all commits _reachable_ from the main branch are fetched and become accessible from the local checkout. - -This combination of factors allows attacks where the victim performs a `git clone` operation followed by a `git reset --hard `. - -#### Mitigations - -##### Informed Review - -The reviewer is able and encouraged to make an informed decision about what they're approving. -The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. - -It is not sufficient to indicate that a file changed without showing the contents. - -##### Use only rebase operations on the protected branch - -Require a squash merge strategy for the protected branch. - -To guarantee that only commits representing reviewed diffs are cloned, the SCP MUST rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) that has only a single parent (the revision previously pointed-to by the protected branch). -This is different than a standard merge commit strategy which would cause all the user-contributed commits to become reachable from the protected branch via the second parent. - -It is not acceptable to replay the sequence of commits from the topic branch onto the protected branch. -The intent is to reduce the accepted changes to the exact diffs that were reviewed. -Constituent commits of the topic branch may or may not have been reviewed on an individual basis, and should not become reachable from the protected branch. - -### Immutable Change Discussion - -Summary: -The discussion around a change may often be as important as the change itself. - -Intended for: -Large organizations, or any where discussion is an important part of the change management process. - -Benefits: -From any revision, it's possible for future developers to read through the discussion that ultimately produced it. -This has many educational, forensics, and security auditing benefits. - -Requirements: - -The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. - -The change management tool MUST link this discussion to the revision itself. This is regularly done via commit metadata. - -All collected content SHOULD be made immutable if the change is accepted. -It SHOULD NOT be possible to edit the discussion around a revision after it has been accepted. - -### Fast moving repos and "merge trains" - -Large organizations must keep the number of updates to key protected branches under certain limits to allow time for code review to happen. -For example, if a team tries to merge 60 change requests per hour into the `main` branch, the tip of the `main` branch would only be stable for about 1 minute. -This would effectively leave only 1 minute for a new diff to be both generated and reviewed before it becomes stale again. - -The normal way to work in this environment is to create a buffer branch called a "train" to collect a certain number of approved changes. -The tip of this train branch represents a potential future state of the protected branch. -In this model, the protected branch is updated on a less frequent cadence to point to the tip of the entire train. - -TODO: Explain how attestation claims can be transferred from proposed merge commits to final revisions via a train. \ No newline at end of file diff --git a/docs/spec/draft/verifying-source.md b/docs/spec/draft/verifying-source.md new file mode 100644 index 000000000..64ecf3180 --- /dev/null +++ b/docs/spec/draft/verifying-source.md @@ -0,0 +1,209 @@ +--- +title: Verifying source +description: SLSA uses attestations to indicate security claims associated with a repository revision, but attestations don't do anything unless somebody inspects them. +SLSA calls that inspection verification, and this page describes how to verify properties of source revisions using their SLSA source provenance attestations. +The intended audience is platform implementers, security engineers, and software consumers. +--- + +SLSA uses attestations to indicate security claims associated with a repository revision, but attestations don't do anything unless somebody inspects them. +SLSA calls that inspection **verification**, and this page describes how to verify properties of source revisions using their SLSA source provenance attestations. + +Source Control Platforms (SCPs) may issue attestations of the process that was used to create specific revisions of a repository. + +A Verification Summary Attestation (VSA) can make verification more efficient by recording the result of prior verifications. +VSA may be issued by a VSA provider to make a SLSA source level determination based on the content of those attestations. + +## How to verify SLSA source level + +TODO: this section needs work. + +### SLSA Level 1 + +Because there is no standardized format, the verification strategy is dependent upon the technologies being used. + +- If you can prove that the revision comes from the expected canonical location for the repository, the source meets level 1. +- If you cannot, it does not meet level 1. + +### SLSA Level 2 + +Because there is no standardized format, the verification strategy is dependent upon the technologies being used. + +- If the repository also has basic history protections, it meets level 2. + +### SLSA Level 3+ + +Repos at this level report their claims in a signed attestation. + +1. For each repository you have, identify the repository id (such as the URL) and the revision id (such as the git commit SHA) +2. Acquire all attestations for that repository id and revision id combination from preconfigured trusted attestation servers. +3. Ensure that the source provenance attestations match the revision id. +4. Ensure that the source provenance attestation documents were signed by a preconfigured root of trust. +5. Ensure that the claims in the revision's provenance attestation meet your expectations for that repository. + +## Common Source Controls and their Applications + +Source attestations provide a trustworthy way to communicate security claims, but what should you be looking for in those claims? +Here are a few extremely common examples and important implementation details. + +In addition to the requirements for SLSA Source L3, most organizations will require multiple of these controls as part of their required branch protections. + +If an organization has indicated that use of these these controls are part of their repository's expectations, consumers SHOULD verify that the process was followed for the revision they are consuming. + +### Changes are pre-authorized by two different authorized actors + +Summary: All changes to the source are approved by two trusted actors prior to acceptance. + +Intended for: Enterprise repositories and mature open source projects. + +Benefits: A compromise of a single account does not result in compromise of the source. + +Requirements: + +#### Two authorized actors + +All changes to the source are approved by two authorized actors prior to acceptance. +If the proposer is also an authorized actor, the proposer MAY approve their own proposal and count as one of the two required actors. + +#### Different actors + +It MUST NOT be possible for a single actor to control more than one voting accounts. + +Should the organization discover that it issued multiple accounts to the same actors, it MUST act to rectify the situation. +For example, it might revoke project privileges for all but one of the accounts and perform retroactive code reviews on any changes where that actors' accounts are the author and/or code reviewer(s). + +#### Post-approval changes allowed + +When performing a review a reviewer may both approve the change and request modifications. Any modifications made need not reset the approval status of the change. To protect against post-approval change see [Review Every Single Revision](#review-every-single-revision). + +### Expert Code Review + +Summary: All changes to the source are pre-approved by experts in those areas. + +Intended for: Enterprise repositories and mature open source projects. + +Benefits: Prevents mistakes made by developers who are unfamiliar with the area. + +Requirements: + +#### Code ownership + +Each part of the source MUST have a clearly identified set of experts. + +#### Approvals from all relevant experts + +For each portion of the source modified by a change proposal, pre-approval MUST be granted by a member of the defined expert set. +A approval from an actor that is a member of multiple expert groups may satisfy the requirement for all groups in which they are a member. + +### Review Every Single Revision + +Summary: The final revision was reviewed by all relevant experts prior to submission. + +Intended for: The highest-of-high-security-posture repos. + +Benefits: Provides the maximum chance for experts to spot and reject problems before they ship. + +Requirements: + +#### Reset votes on all changes + +If the proposal is modified after receiving expert approval, all previously granted approvals MUST be revoked. +A new approval MUST be granted from ALL required reviewers. + +The new approval MAY be granted by an actor who approved a previous iteration. + +### Automated testing + +Summary: +The final revision was validated against a suite of automated tests. + +Intended for: +All organizations and repositories. + +Benefits: +Automatic testing has many benefits, including improved accuracy, error prevention and reduced workload on human developers. + +Requirements: +The organization MUST configure a branch protection rule to require that only revisions with passing test results can be pointed-to by the branch. + +Automatic tests SHOULD be executed in a trustworthy environment (see SLSA build track). + +Results of each test (or an aggregate) MUST be collected by the change review tool and made available for verification. + +Tests SHOULD be run against a revision created for testing by merging the topic branch (containing the proposed changes) into the target branch. + +Use of the proposed merge commit should be preferred to using the tip of the topic branch. + +### Every revision reachable from a branch was approved + +Summary: +New revisions are created based ONLY on the changes that were approved. + +Benefits: +Prevents a large class of internal threat attacks based on hiding a malicious commit in a series of good commits such that the malicious commit does not appear in the reviewed diff. + +Requirements: + +#### Context + +In many organizations it is normal to review only the "net difference" between the tip of the topic branch and the "best merge base", the closest shared commit between the topic and target branches computed at the time of review. + +The topic branch may contain many commits of which not all were intended to represent a shippable state of the repository. + +If a repository merges branches with a standard merge commit, all those unreviewed commits on the topic branch will become "reachable" from the protected branch by virtue of the multi-parent merge commit. + +When a repo is cloned, all commits _reachable_ from the main branch are fetched and become accessible from the local checkout. + +This combination of factors allows attacks where the victim performs a `git clone` operation followed by a `git reset --hard `. + +#### Mitigations + +##### Informed Review + +The reviewer is able and encouraged to make an informed decision about what they're approving. +The reviewer MUST be presented with a full, meaningful content diff between the proposed revision and the previously reviewed revision. + +It is not sufficient to indicate that a file changed without showing the contents. + +##### Use only rebase operations on the protected branch + +Require a squash merge strategy for the protected branch. + +To guarantee that only commits representing reviewed diffs are cloned, the SCP MUST rebase (or "squash") the reviewed diff into a single new commit (the "squashed" commit) that has only a single parent (the revision previously pointed-to by the protected branch). +This is different than a standard merge commit strategy which would cause all the user-contributed commits to become reachable from the protected branch via the second parent. + +It is not acceptable to replay the sequence of commits from the topic branch onto the protected branch. +The intent is to reduce the accepted changes to the exact diffs that were reviewed. +Constituent commits of the topic branch may or may not have been reviewed on an individual basis, and should not become reachable from the protected branch. + +### Immutable Change Discussion + +Summary: +The discussion around a change may often be as important as the change itself. + +Intended for: +Large organizations, or any where discussion is an important part of the change management process. + +Benefits: +From any revision, it's possible for future developers to read through the discussion that ultimately produced it. +This has many educational, forensics, and security auditing benefits. + +Requirements: + +The change management tool SHOULD record a description of the proposed change and all discussions / commentary related to it. + +The change management tool MUST link this discussion to the revision itself. This is regularly done via commit metadata. + +All collected content SHOULD be made immutable if the change is accepted. +It SHOULD NOT be possible to edit the discussion around a revision after it has been accepted. + +### Fast moving repos and "merge trains" + +Large organizations must keep the number of updates to key protected branches under certain limits to allow time for code review to happen. +For example, if a team tries to merge 60 change requests per hour into the `main` branch, the tip of the `main` branch would only be stable for about 1 minute. +This would effectively leave only 1 minute for a new diff to be both generated and reviewed before it becomes stale again. + +The normal way to work in this environment is to create a buffer branch called a "train" to collect a certain number of approved changes. +The tip of this train branch represents a potential future state of the protected branch. +In this model, the protected branch is updated on a less frequent cadence to point to the tip of the entire train. + +TODO: Explain how attestation claims can be transferred from proposed merge commits to final revisions via a train. From 3919badfbfe94be1cf31953ad1b750c4d5a24654 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Mon, 12 Aug 2024 17:57:57 -0400 Subject: [PATCH 38/44] source attestation copy edits --- docs/spec/draft/source-requirements.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index f0b9a82e1..48ddf045b 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -181,7 +181,7 @@ Activities conducted on the SCP SHOULD be attributed to authenticated identities Summary: A consumer can ask the SCP for everything it knows about a specific revision of a repository. -The information is provided in a standardized format. +The information is provided in a documented and tamper-resistant format. Intended for: Organizations that want strong guarantees and auditability of their change management processes. @@ -191,22 +191,27 @@ Provides reliable information to policy enforcement tools. Requirements: -#### Source provenance attestations +#### Source attestations -Source attestations are associated with the revision identifier delivered to consumers. -They are a statement of fact from the perspective of the SCP. -They contain information about how a specific revision was created and how it came to exist in its present context. +A source attestation contains information about how a specific revision was created and how it came to exist in its present context. +They are associated with the revision identifier delivered to consumers and are a statement of fact from the perspective of the SCP. -For example, if a consumer is authorized to access source on a particular branch, they MUST be able to fetch the source attestation documents for revisions in the history of that branch. +If a consumer is authorized to access source on a particular branch, they MUST be able to fetch the source attestation documents for revisions in the history of that branch. -It is possible that an SCP can make no provenance claims about a particular revision. -For example, this would happen if the revision was created on another SCP. +It is possible that an SCP can make no claims about a particular revision. +For example, this would happen if the revision was created on another SCP, or if the revision was not the result of an accepted change management process. #### Change management process The repo must define how the content of a [branch](#definitions) is allowed to change. +This is typically done via the configuration of branch protection rules. It MUST NOT be possible to modify the content of a branch without following its documented process. +SLSA Source Level 2 ensures that all changes are recorded and attributable to an actor. +SLSA Source Level 3 ensures that the documented process was followed. + +The change management tool MUST be able to authoritatively state that each new revision reachable from the protected branch represents only the changes reviewed via the process. + The change management tool MUST provide at a minimum: ##### Strong Authentication @@ -227,7 +232,7 @@ See [source roles](#source-roles). The change management tool MUST record the specific code change (a "diff" in git) or instructions to recreate it. In git, this typically defined to be three revision IDs: the tip of the "topic" branch, the tip of the target branch, and closest shared ancestor between the two (such as determined by `git-merge-base`). -The change management tool MUST record the "target" context for the change proposal and the previous / current revision in that context. +The change management tool MUST record the "target" context for the change proposal and the previous revision in that context. For example, for the git version control system, the change management tool MUST record the branch name that was updated. Branches may have differing security postures, and a change can be approved for one context while being unapproved for another. From cb63de35778a5a8c5723f8125340e68368583946 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Wed, 14 Aug 2024 13:54:05 -0400 Subject: [PATCH 39/44] add disclaimer about use of git VCS --- docs/spec/draft/source-requirements.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 48ddf045b..7ad355747 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -90,6 +90,8 @@ When a repo is transferred to a new organization ("donated"), or if a repo must ## Levels +Many examples in this document use the [git version control system](https://git-scm.com/), but use of git is not a requirement to meet any level on the SLSA source track. + ### Level 1: Version controlled Summary: From f2398a4accaac1a814cfc12497521c490780a3c3 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 15 Aug 2024 10:34:26 -0400 Subject: [PATCH 40/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Tom Hennen Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 7ad355747..747691d7e 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -107,7 +107,7 @@ Requirements: #### Use modern tools The organization MUST manage the source using tools specifically designed to manage source code. -Tools like Perforce, GitLab, GitHub, Azure Repos are all great examples. +Tools like Perforce, GitLab, GitHub, Azure Repos, and self-hosted git _servers_ are all great examples. Storing revisions as differently-named zips in folders on a laptop does not count. From d1219c6e47855049497d4df3a1a153295a948dac Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 15 Aug 2024 10:35:08 -0400 Subject: [PATCH 41/44] Update docs/spec/draft/verifying-source.md Signed-off-by: Zachariah Cox --- docs/spec/draft/verifying-source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/verifying-source.md b/docs/spec/draft/verifying-source.md index 64ecf3180..8eb5cff43 100644 --- a/docs/spec/draft/verifying-source.md +++ b/docs/spec/draft/verifying-source.md @@ -26,7 +26,7 @@ Because there is no standardized format, the verification strategy is dependent ### SLSA Level 2 -Because there is no standardized format, the verification strategy is dependent upon the technologies being used. +Because there is no required attestation document at this level, the verification strategy is dependent upon the technologies being used. - If the repository also has basic history protections, it meets level 2. From 5527616f5acaf78194f8d605330e3aa28caff762 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 15 Aug 2024 10:35:15 -0400 Subject: [PATCH 42/44] Update docs/spec/draft/verifying-source.md Signed-off-by: Zachariah Cox --- docs/spec/draft/verifying-source.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/verifying-source.md b/docs/spec/draft/verifying-source.md index 8eb5cff43..80701d01e 100644 --- a/docs/spec/draft/verifying-source.md +++ b/docs/spec/draft/verifying-source.md @@ -19,7 +19,7 @@ TODO: this section needs work. ### SLSA Level 1 -Because there is no standardized format, the verification strategy is dependent upon the technologies being used. +Because there is no required attestation document at this level, the verification strategy is dependent upon the technologies being used. - If you can prove that the revision comes from the expected canonical location for the repository, the source meets level 1. - If you cannot, it does not meet level 1. From 6df6b33b38531fb57db338f01ead1f6e37267c84 Mon Sep 17 00:00:00 2001 From: Zachariah Cox Date: Thu, 15 Aug 2024 10:52:18 -0400 Subject: [PATCH 43/44] Update docs/spec/draft/source-requirements.md Signed-off-by: Zachariah Cox --- docs/spec/draft/source-requirements.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index 747691d7e..ac1412923 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -107,7 +107,8 @@ Requirements: #### Use modern tools The organization MUST manage the source using tools specifically designed to manage source code. -Tools like Perforce, GitLab, GitHub, Azure Repos, and self-hosted git _servers_ are all great examples. +Tools like git, Perforce, Subversion are great examples. +They may be self-hosted or hosted in the cloud using vendors like GitLab, GitHub, Bitbucket, etc. Storing revisions as differently-named zips in folders on a laptop does not count. From 31d63bacca935428b01d895bf4a940912825b6e5 Mon Sep 17 00:00:00 2001 From: Tom Hennen Date: Thu, 15 Aug 2024 11:53:29 -0300 Subject: [PATCH 44/44] Update docs/spec/draft/source-requirements.md Co-authored-by: Zachariah Cox Signed-off-by: Tom Hennen --- docs/spec/draft/source-requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec/draft/source-requirements.md b/docs/spec/draft/source-requirements.md index ac1412923..89178bacc 100644 --- a/docs/spec/draft/source-requirements.md +++ b/docs/spec/draft/source-requirements.md @@ -110,7 +110,7 @@ The organization MUST manage the source using tools specifically designed to man Tools like git, Perforce, Subversion are great examples. They may be self-hosted or hosted in the cloud using vendors like GitLab, GitHub, Bitbucket, etc. -Storing revisions as differently-named zips in folders on a laptop does not count. +When self-hosting a solution, local, unauthenticated storage is not acceptable. Branch protection is not required, nor are there any other constraints on the configuration of the tools.