Add predicates for human reviews

Signed-off-by: Aditya Sirish <aditya@saky.in>

spec/predicates/README.md

@@ -24,6 +24,12 @@ our [vetting process], and may be of general interest:
 -   [SPDX]: SPDX-formatted BOM for software artifacts.
 -   [CycloneDX]: CycloneDX BOM for software artifacts.
 -   [Test Results]: A generic schema to express results of any type of tests.
+-   [Human Review]: To describe findings of human reviews such as code reviews,
+    dependency audits, and more.
+-   [VCS Code Review]: To describe code review approvals for review and version
+    control systems.
+-   [Crev]: To describe community reviews as part of the Crev project for
+    software dependencies.
 
 [CycloneDX]: https://cyclonedx.org/
 [Link]: link.md
@@ -36,3 +42,6 @@ our [vetting process], and may be of general interest:
 [Test Results]: test-results.md
 [in-toto 0.9]: https://github.com/in-toto/docs/blob/master/in-toto-spec.md#44-file-formats-namekeyid-prefixlink
 [vetting process]: ../../docs/new_predicate_guidelines.md#vetting-process
+[Human Review]: human-review.md
+[VCS Code Review]: human-review-vcs.md
+[Crev]: human-review-crev.md

spec/predicates/human-review-crev.md

@@ -0,0 +1,123 @@
+# 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",
+        "timestamp": "<TIMESTAMP>",
+        "reviewer": {
+            "idType": "crev",
+            "id": "",
+            "url": "<URL>"        
+        },
+        "thoroughness": "high|medium|low",
+        "understanding": "high|medium|low",
+        "comment": "<STRING>"
+    }
+}
+```
+
+### Parsing Rules
+
+This predicate follows the
+[in-toto Attestation Framework's parsing rules](../v1/README.md#parsing-rules).
+
+### Fields
+
+The subject of this predicate type is a specific package and its version in some
+ecosystem.
+
+`result`, _enum_, _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`.
+The `url` is a reference to the reviewer's crev-proofs repository.
+
+`timestamp` _Timestamp_, _required_
+
+Indicates time of review creation.
+
+`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/v1",
+    "subject": [
+        {
+            "name": "in-toto",
+            "uri": "purl+pkg:pypi/in-toto@1.3.2",
+            "digest": {
+                "sha256": "aa12e63298425cfc4773ed03febd68a384c63b2690959dd788f8c4511ea97bbe"
+            },
+            "downloadLocation": "https://github.com/in-toto/in-toto/releases/download/v1.3.2/in_toto-1.3.2-py3-none-any.whl"
+        },
+    ],
+    "predicateType": "https://in-toto.io/attestation/human-review/crev/v0.1",
+    "predicate": {
+        "result": "positive",
+        "timestamp": "2023-03-16T00:09:27Z",
+        "reviewer": {
+            "idType": "github",
+            "id": "adityasaky",
+            "url": "https://github.com/adityasaky/crev-proofs"
+        },
+        "thoroughness": "high",
+        "understanding": "high",
+        "comment": "This dependency is well written and can be used safely."
+    }
+}
+```

spec/predicates/human-review-vcs.md

@@ -0,0 +1,100 @@
+# 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.
+
+As this attestation is generated by a version control service or code review
+service, the signatures are from the service rather than the specific users
+issuing the review.
+
+## Schema
+
+```json
+{
+    "_type": "https://in-toto.io/Statement/v1",
+    "subject": [
+        {
+            "name": "<REPO>",
+            "digest": { "gitCommit": "<HASH>" },
+            "uri": "<LINK TO REPO>"
+        },
+    ],
+    "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1",
+    "predicate": {
+        "reviewer": ["<STRING>", ...],
+        "reviewLink": "<LINK TO REVIEW>",
+        "timestamp": "<TIMESTAMP>"
+    }
+}
+```
+
+### Parsing Rules
+
+This predicate follows the
+[in-toto Attestation Framework's parsing rules](../v1/README.md#parsing-rules).
+
+### Fields
+
+`reviewer` _array of strings_, _required_
+
+Indicates the identity of one or more reviewers. MUST NOT be used over the
+attestation's signature to validate the source of the attestation. This field
+supports scenarios where the attestation is issued and signed by the VCS system.
+
+`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": [{
+        "name": "in-toto-python",
+        "digest": {
+            "gitCommit": "b0bd8ecab5607e174fa403e002c74a666e7edd51"
+        },
+        "uri": "https://github.com/in-toto/in-toto"
+    }],
+    "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1",
+    "predicate": {
+        "reviewer": ["https://github.com/lukpueh"],
+        "reviewLink": "https://github.com/in-toto/in-toto/pull/503#pullrequestreview-1341209941",
+        "timestamp": "2023-03-15T11:05:00Z"
+    }
+}
+```

spec/predicates/human-review.md

@@ -0,0 +1,90 @@
+# 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.
+
+## 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": "<URL>",
+        "timestamp": "<TIMESTAMP>"
+    }
+}
+```
+
+### Parsing Rules
+
+This predicate follows the
+[in-toto Attestation Framework's parsing rules](../v1/README.md#parsing-rules).
+
+### Fields
+
+`result` _enum_, _optional_
+
+Indicates the result of the review. For example, it may have the values "pass"
+or "fail".
+
+`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"
+    }
+}
+```