From 2af4cac625b4c87e0f23c554a680b3512d90398f Mon Sep 17 00:00:00 2001 From: Aditya Sirish Date: Thu, 30 Jun 2022 13:38:56 -0400 Subject: [PATCH] Add predicates for human reviews Signed-off-by: Aditya Sirish --- spec/predicates/crev.md | 127 ++++++++++++++++++++++++++++++++ spec/predicates/human-review.md | 106 ++++++++++++++++++++++++++ spec/predicates/vcs.md | 103 ++++++++++++++++++++++++++ 3 files changed, 336 insertions(+) create mode 100644 spec/predicates/crev.md create mode 100644 spec/predicates/human-review.md create mode 100644 spec/predicates/vcs.md diff --git a/spec/predicates/crev.md b/spec/predicates/crev.md new file mode 100644 index 00000000..9b9031c8 --- /dev/null +++ b/spec/predicates/crev.md @@ -0,0 +1,127 @@ +# Predicate type: Dependency Reviews (crev) + +Type URI: (tentative) https://in-toto.io/attestation/human-review/crev/v0.1 + +Version: Do we use Crev's versioning? Currently -1? What about their URI? + +## Purpose + +This attestation type is used to describe the results of human review of +dependency source code. The format is based on the +[crev project](https://github.com/crev-dev/crev). + +## Use Cases + +As noted above, crev enables social review of popular open source software +dependencies. A crev review includes information such as the thoroughness of +the review, understanding of the source code, and a final rating. + +## Prerequisite + +Understanding of the +[in-toto attestation specification](https://github.com/in-toto/attestation). + +## Model + +Most modern software have external dependencies. Dependency review is the +process of reviewing and verifying the source code of a particular +dependency, and can be performed by one or more of several actors in the supply +chain. The developer importing a new dependency can perform the review or a +dedicated security team can be tasked with it. + +## Schema + +```json +{ + "_type": "https://in-toto.io/Statement/v1", + "subject": [{...}], + "predicateType": "https://in-toto.io/attestation/human-review/crev/v0.1", + "predicate": { + "result": "positive/negative", + "reviewLink": "", + "timestamp": "", + "reviewer": { + "idType": "crev", + "id": "", + "url": "" + }, + "thoroughness": "high/medium/low", + "understanding": "high/medium/low", + "comment": "" + } +} +``` + +### Parsing Rules + +This predicate follows the in-toto attestation parsing rules. Summary: + +- Consumers MUST ignore unrecognized fields. +- The `predicateType` URI includes the major version number and will always + change whenever there is a backwards incompatible change. +- Minor version changes are always backwards compatible and “monotonic.” Such + changes do not update the `predicateType`. +- Producers MAY add extension fields using field names that are unlikely to + collide with names used by other producers. Field names SHOULD avoid using + characters like `.` and `$`. +- Fields marked _optional_ MAY be unset or null, and should be treated + equivalently. Both are equivalent to empty for object or array values. + +### Fields + +Extends: [human-review](./human-review.md). + +`result`, _boolean_, _required_ + +Specifies if the overall rating of the dependency is `positive` or `negative`. + +`reviewer` _object_, _required_ + +Identifies the reviewer. This has some meaning for crev's trust proliferation +aspects, but the identity of the reviewer can also be mapped based on in-toto's +functionary handling. `idType` is used to determine the contents of `reviewer`. + +`thoroughness` _enum_, _required_ + +Describes how thorough the reviewer was. Must be set to one of `low`, `medium`, +or `high`. + +`understanding` _enum_, _required_ + +Describes the reviewer's understanding of the dependency code. Must be set to +one of `low`, `medium`, or `high`. + +`comment` _string_, _optional_ + +Optional field with any other comments a reviewer may have about the +dependency. + +## Example + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "subject": [ + { + "name": "purl+pkg:pypi/in-toto@1.3.2", + "digest": { + "sha256": "aa12e63298425cfc4773ed03febd68a384c63b2690959dd788f8c4511ea97bbe" + }, + "downloadLocation": "https://github.com/in-toto/in-toto/releases/tag/v1.3.2" + }, + ], + "predicateType": "https://in-toto.io/attestation/human-review/crev/v0.1", + "predicate": { + "result": "positive", + "reviewLink": "https://github.com/adityasaky/crev-proofs", + "timestamp": "2023-03-16T00:09:27Z", + "reviewer": { + "idType": "github", + "id": "adityasaky" + }, + "thoroughness": "high", + "understanding": "high", + "comment": "This dependency is well written and can be used safely." + } +} +``` diff --git a/spec/predicates/human-review.md b/spec/predicates/human-review.md new file mode 100644 index 00000000..d0f785d3 --- /dev/null +++ b/spec/predicates/human-review.md @@ -0,0 +1,106 @@ +# Predicate type: Human Reviews + +Type URI: https://in-toto.io/attestation/human-review/v0.1 + +Version: 0.1.0 + +Authors: + +## Purpose + +This is a generic predicate type used to describe human reviews of software +artifacts. For example, this predicate (or a derivative) can be used to wrap +results of code reviews, software audits, and dependency reviews such as the +crev project. + +This predicate type, meant to be extended by specific systems that emit review +results. However, those extensions will have a distinct `predicateType` value +that builds off of the URI in this document. + +## Use Cases + +Software supply chains encompass many types of human reviews. Best practices +including standards like SLSA recommend two or multi-party review for source +code. Another example is the crev project where open source software +dependencies are socially reviewed. + +## Prerequisites + +Understanding of the +[in-toto attestation specification](https://github.com/in-toto/attestation). + +## Model + +This predicate type includes one compulsory field, `result`, that describes the +result of the review. Derivatives of this predicate may include other contextual +fields pertaining to different code review systems or use cases. The predicate +includes an optional `reviewLink` field that can be used to find the full +review. In the general case, the subject of a code review attestation must +identify the software artifacts the review applies to. + +## Schema + +```json +{ + "_type": "https://in-toto.io/Statement/v1", + "subject": [{...}], + "predicateType": "https://in-toto.io/attestation/human-review/v0.1", + "predicate": { + "result": "pass/fail", + "reviewLink": "", + "timestamp": "" + } +} +``` + +### Parsing Rules + +This predicate follows the in-toto attestation parsing rules. Summary: + +- Consumers MUST ignore unrecognized fields. +- The `predicateType` URI includes the major version number and will always + change whenever there is a backwards incompatible change. +- Minor version changes are always backwards compatible and “monotonic.” Such + changes do not update the `predicateType`. +- Producers MAY add extension fields using field names that are unlikely to + collide with names used by other producers. Field names SHOULD avoid using + characters like `.` and `$`. +- Fields marked _optional_ MAY be unset or null, and should be treated + equivalently. Both are equivalent to empty for object or array values. + +### Fields + +`result` _interface_, _required_ + +TODO: what type should this specify? For extensibility, should we have an +"interface" type? + +Indicates the result of the review. + +`reviewLink` _URI_, _optional_ + +Contains a link to the full review. Useful to point to information that cannot +be captured in the attestation. + +`timestamp` _Timestamp_, _optional_ + +Indicates time of review creation. + +## Example + +```json +{ + "_type": "https://in-toto.io/Statement/v1", + "subject": [{ + "digest": { + "gitCommit": "b0bd8ecab5607e174fa403e002c74a666e7edd51" + } + }], + "predicateType": "https://in-toto.io/attestation/human-review/v0.1", + "predicate": { + "result": "pass", + "reviewLink": "https://github.com/in-toto/in-toto/pull/503#pullrequestreview-1341209941", + "timestamp": "2023-03-15T11:05:00Z" + } +} +``` diff --git a/spec/predicates/vcs.md b/spec/predicates/vcs.md new file mode 100644 index 00000000..52edff2c --- /dev/null +++ b/spec/predicates/vcs.md @@ -0,0 +1,103 @@ +# Predicate type: VCS Code Reviews + +Type URI: (tentative) https://in-toto.io/attestation/human-review/vcs/v0.1 + +Version: 0.1.0 + +## Purpose + +This attestation type is used to describe code review approvals of the simplest +kind. The general expectation is that reviews are tied to specific changes in a +version control system (VCS) such as Git. + +## Use Cases + +Changes to source code are reviewed by other members of the development team. +The review may be performed using systems like Gerrit or via reviewing +mechanisms built into version control forges such as GitHub and GitLab. + +## Prerequisite + +Understanding of the +[in-toto attestation specification](https://github.com/in-toto/attestation). + +## Model + +Typically, software development processes incorporate some type of code review. +Other members of the development team are expected to study the changes +proposed and approve them, confirming they meet various expectations pertaining +to code quality, functionality, and so on. Therefore, the general expectation +is that this attestation is generated as a confirmation, an approval of some +specific change, and is performed by developers in the supply chain who have +code review responsibilities. + +## Schema + +```json +{ + "_type": "https://in-toto.io/Statement/v1", + "subject": [ + { + "digest": { "gitCommit": "" } + }, + ], + "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1", + "predicate": { + "result": "approved/changes-required/comment", + "reviewLink": "https://github.com/<>", + "timestamp": "" + "reviewer": "" + } +} +``` + +### Parsing Rules + +This predicate follows the in-toto attestation parsing rules. Summary: + +- Consumers MUST ignore unrecognized fields. +- The `predicateType` URI includes the major version number and will always + change whenever there is a backwards incompatible change. +- Minor version changes are always backwards compatible and “monotonic.” Such + changes do not update the `predicateType`. +- Producers MAY add extension fields using field names that are unlikely to + collide with names used by other producers. Field names SHOULD avoid using + characters like `.` and `$`. +- Fields marked _optional_ MAY be unset or null, and should be treated + equivalently. Both are equivalent to empty for object or array values. + +### Fields + +Extends: [human-review](./human-review.md#fields). + +`result` _enum_, _required_ + +One of `approved`, `changes-requested`, or `comment`. TODO: This is inspired by +GitHub. Should `vcs` be extended further for GitHub, GitLab etc? Gerrit uses a +numeric scale. + +`reviewer` _string_, _optional_ + +Indicates the identity of the reviewer. MUST NOT be used over the attestation's +signature to validate the identity of the reviewer. + +## Example + +```json +{ + "_type": "https://in-toto.io/Statement/v0.1", + "subject": [{ + "name": "in-toto-python", + "digest": { + "gitCommit": "b0bd8ecab5607e174fa403e002c74a666e7edd51" + } + }], + "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1", + "predicate": { + "result": "approved", + "reviewLink": "https://github.com/in-toto/in-toto/pull/503#pullrequestreview-1341209941", + "timestamp": "2023-03-15T11:05:00Z", + "reviewer": "https://github.com/lukpueh" + } +} +```