sigrev/docs/spec.md

# SigRev Spec [DRAFT]

Version: 0.0

## Table of Contents

- [SigRev Specification](#SigRev-spec)
  - [Table of Contents](#table-of-contents)
  - [1 Introduction](#1-introduction)

## 1. Introduction

## 1.1 Scope

This document describes the SigRev specification. A sigrev is a signed document
in an specified format attesting to the either human or automated review of
repositories of code in a software supply chain.

It is intended to be agnostic to any particular VCS or code distribution
method, however references to such systems where available will be defined
as possible to assist in making it easier for people to find reviews via
a range of distribution and search tools and databases which are out of scope
for this document.

VCS Support

* Git -- `git+`
* Mercurial -- `hg+`
* Subversion -- `svn+`

## Format

| Field Name | Decription | Required |
| :--- | :--- | :---: |
| version | The version of the schema | yes |
| reviewer | RFC5322 name-addr format (eg. John Doe <johndoe@example.com>) | yes |
| treehash | sha256sum of treehashes | yes |
| paths | a list of filepaths reviewed or reproduced, can include globs | yes |
| artifcts | a list of built artificats with hashes if relevant | no |
| vcs-ref | VCS ref | yes |
| type | The type of review. Allowed values are: function, security, readability, reproducibility | yes |
| confidence | How confident are you in the type of review you did: `low,medium,high` | yes |
| system.platform | The platform used to build `amd64,arm64,etc` | yes |
| system.cpu | Information about the CPU used | no |
| system.cores | Number of cores in CPU | no |
| system.location | location of machine(mostly for reproducibility, if in 'the cloud' include the region e.g AWS:us-east-1, could also be ISO 3166-2) | no |
| comments | freeform text | no |

### Security Review Example

```
version: 0.1
reviewer: John Doe <jdoe@example.com>
treehash: 9cc0641a294d3ee359ae474aef1a9a6a6657aeb2
paths:
- ./*
vcs-ref: git+https://reposite.com/example-user/example-repo
type: "security",
confidence: "high"
system:
  platform: amd64
  location: "ISO3166-2:US-CA"
comments: |
  Very Secure, much wow
```

### Reproducible Build Example(s)

```
version: 0.1
reviewer: Reproduction Bot <repro-bot@example.com>
treehash: a5fc98c3950d7bb6bf083d5e7c08a91ffef990af
paths:
- ./*
vcs-ref: git+https://example.com/public/some-repo
type: "reproducibility",
confidence: "high"
system:
  platform: amd64
  location: "AWS:us-east-1"
```