-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Aditya Sirish <aditya@saky.in>
- Loading branch information
1 parent
065aec2
commit 2af4cac
Showing
3 changed files
with
336 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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." | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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" | ||
} | ||
} | ||
``` |