Add predicates for human reviews

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

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": "<URL>",
+        "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 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."
+    }
+}
+```

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": "<URL>",
+        "timestamp": "<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"
+    }
+}
+```

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": "<HASH>" }
+        },
+    ],
+    "predicateType": "http://in-toto.io/attestation/human-review/vcs/v0.1",
+    "predicate": {
+        "result": "approved/changes-required/comment",
+        "reviewLink": "https://github.com/<>",
+        "timestamp": "<TIMESTAMP>"
+        "reviewer": "<STRING>"
+    }
+}
+```
+
+### 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"
+    }
+}
+```