Skip to content

Latest commit

 

History

History
155 lines (123 loc) · 4.41 KB

reference.md

File metadata and controls

155 lines (123 loc) · 4.41 KB
Raw

Predicate type: Reference

Type URI: https://in-toto.io/attestation/reference/v0.1

Version: v0.1.0

Purpose

The reference attestation references a set of documents that are relevant to some resource. It is used to point to and sign metadata that is not provided in-band.

Use Cases

One use case is to provide an SBOM of an artifact without needing to sign the entire SBOM and transmit it in-band. A consumer, such as GUAC, retrieves the SBOM, verifies the digest, and uses it for vulnerability management, compliance, analysis, or any other purpose.

Another use case is to provide evidence for a policy such as "deny unless a reference to an SBOM is provided".

There is encodability overlap with the SCAI predicate, but it is not the best fit because it doesn't support standardizing an attribute (which would be desired here), the use case is distinct, and it is a larger prequisite. A more opinionated predicate will increase usability and encourage adoption.

Prerequisites

The in-toto Attestation Framework and an SBOM specification such as SPDX.

Model

This predicate is intended to be generated and consumed throughout the software supply chain. In addition, it is intended to be used in the analysis of it as a whole.

Schema

{
  // Standard attestation fields:
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{ ... }],

  // Predicate:
  "predicateType": "https://in-toto.io/attestation/reference/v0.1",
  "predicate": {
    "attester": {
      "id": "<TypeUri>"
    },
    "references": ["<ResourceDescriptor>", ...]
  }
}

Parsing Rules

This predicate follows the in-toto Attestation Framework's parsing rules.

The references field is repeated as an optimization: multiple references SHOULD be treated as if each reference was represented in its own attestation with all other content unchanged.

The reference(s) are associated with the set of subjects as a whole, instead of being independently associated with each subject. See the example with two subjects.

Fields

attester.id: string (TypeUri), required

An identifier for the system that provides the document.

references array of ResourceDescriptor objects, required

The referred documents. The downloadLocation and mediaType MUST be provided for each. If the file type is unknown, application/octet-stream SHOULD be used.

Examples

Reference to an SBOM for an image

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{
    "name": "registry.example.com/my-project/my-image",
    "digest": {
      "sha256": "886a77e9b9c993e221d1843e3af5b1fbeea26d8962995e8562174a6aba0c7cc9"
    }
  }],
  "predicateType": "https://in-toto.io/attestation/reference/v0.1",
  "predicate": {
    "attester": {
      "id": "https://my-builder.com/v1"
    },
    "references": [{
      "downloadLocation": "https://cloud.com/my-sboms/sbom.spdx.json",
      "digest": {
        "sha256": "3b0d19b348f1e46a571c6e9df32897637c20dd9803261c2fc9cbe38b0c8422c4"
      },
      "mediaType": "application/spdx+json"
    }]
  }
}

Reference to an SBOM for multiple artifacts

In this example, a single SBOM was generated for a set of build outputs by scanning the source file system. Per the parsing rules, this attestation SHOULD be interpreted to mean that the SBOM was generated for both subjects -- it will list dependencies of both foo and bar.

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "foo.deb",
      "digest": {
        "sha256": "f1847f7e67aa18d0063fda3cbde8b61f84384fbf35c3dd4cfa8c4822400b5a64"
      }
    },
    {
      "name": "bar.deb",
      "digest": {
        "sha256": "680177210742d53016820ec118b6d7dd0be62758ad6d7f503e96927ced4809b4"
      }
    }
  ],
  "predicateType": "https://in-toto.io/attestation/reference/v0.1",
  "predicate": {
    "attester": {
      "id": "https://my-builder.com/v1"
    },
    "references": [{
      "downloadLocation": "https://cloud.com/my-sboms/sbom.spdx.json",
      "digest": {
        "sha256": "3b0d19b348f1e46a571c6e9df32897637c20dd9803261c2fc9cbe38b0c8422c4"
      },
      "mediaType": "application/spdx+json"
    }]
  }
}

Changelog and Migrations

None yet.