CINXE.COM

<!DOCTYPE html> <html lang="en"><head> <meta charset="utf-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="generator" content="Jekyll v3.9.5" /> <meta property="og:title" content="Provenance" /> <meta property="og:locale" content="en_US" /> <meta name="description" content="Description of SLSA provenance specification for verifying where, when, and how something was produced." /> <meta property="og:description" content="Description of SLSA provenance specification for verifying where, when, and how something was produced." /> <meta property="og:site_name" content="SLSA" /> <meta property="og:image" content="/images/icons/android-chrome-192x192.png" /> <meta property="og:type" content="website" /> <meta name="twitter:card" content="summary_large_image" /> <meta property="twitter:image" content="/images/icons/android-chrome-192x192.png" /> <meta property="twitter:title" content="Provenance" /> <script type="application/ld+json"> {"@context":"https://schema.org","@type":"WebPage","description":"Description of SLSA provenance specification for verifying where, when, and how something was produced.","headline":"Provenance","image":"/images/icons/android-chrome-192x192.png","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/images/icons/android-chrome-512x512.png"}},"url":"/spec/v1.0/provenance"}</script>  <link rel="stylesheet" href="/vendor/tailwindcss-2.2.19/tailwind.min.css"> <link rel="stylesheet" href="/assets/main.css"> <link rel="apple-touch-icon" sizes="180x180" href="/images/icons/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/images/icons/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/images/icons/favicon-16x16.png"> <link rel="icon" type="image/png" sizes="16x16" href="/images/icons/favicon-16x16.png"> <link rel="icon" type="image/x-icon" href="/images/icons/favicon.ico"> <link rel="mask-icon" href="/images/icons/safari-pinned-tab.svg" color="#5bbad5"> <meta name="msapplication-TileColor" content="#da532c" /> <meta name="msapplication-square150x150logo" content="/images/icons/mstile-150x150.png" /> <meta name="theme-color" content="#ffffff" /> <title>SLSA • Provenance</title> <link rel="stylesheet" href="/fonts/inter/inter.css"> <link rel="stylesheet" href="/fonts/ibm_plex/IBMPlexMono-Regular.css"> <link rel="stylesheet" href="/fonts/prodigy/ProdigySans.css"> <script src="/vendor/swiper-6.8.4/swiper-bundle.min.js"></script> <link rel="stylesheet" href="/vendor/swiper-6.8.4/swiper-bundle.min.css"> <script defer src="/vendor/alpinejs-3.10.2/cdn.min.js"></script><link type="application/atom+xml" rel="alternate" href="/feed.xml" title="SLSA" /></head> <body x-data="{navOpen: false}" x-init="$refs.body.style.setProperty('--scrollbar-width', `${window.innerWidth - document.body.offsetWidth}px`)" x-ref="body" ><aside class="site-aside flex flex-col flex-none" :class="{'is-open': navOpen}" > <div class="aside-header p-5 flex justify-between items-center show-laptop"> <a rel="author" href="/" class="logo block"> <img class="logo-white" src="/images/logo.svg" alt="SLSA logo" /> </a> <a class="desktop-github-icon" href="https://github.com/slsa-framework/slsa" target="_blank"> <svg width="22" height="22" viewBox="0 0 22 22" fill="currentColor" xmlns="http://www.w3.org/2000/svg"> <path fill-rule="evenodd" clip-rule="evenodd" d="M11.2344 0.150879C5.28641 0.150879 0.468811 4.96848 0.468811 10.9165C0.468811 15.6803 3.55046 19.7039 7.82978 21.1303C8.36806 21.2245 8.56991 20.9016 8.56991 20.619C8.56991 20.3633 8.55646 19.5155 8.55646 18.6139C5.8516 19.1118 5.15184 17.9545 4.93653 17.3489C4.81541 17.0394 4.29059 16.084 3.83306 15.8283C3.45626 15.6264 2.91798 15.1285 3.8196 15.1151C4.66739 15.1016 5.27295 15.8956 5.47481 16.2185C6.44371 17.8468 7.99126 17.3893 8.61028 17.1067C8.70448 16.4069 8.98708 15.9359 9.29659 15.6668C6.90125 15.3977 4.39825 14.4691 4.39825 10.3513C4.39825 9.18051 4.81541 8.21161 5.50172 7.45802C5.39407 7.18888 5.01727 6.08541 5.60938 4.60514C5.60938 4.60514 6.51099 4.32254 8.56991 5.70861C9.43116 5.46639 10.3462 5.34527 11.2613 5.34527C12.1764 5.34527 13.0914 5.46639 13.9527 5.70861C16.0116 4.30909 16.9132 4.60514 16.9132 4.60514C17.5053 6.08541 17.1285 7.18888 17.0209 7.45802C17.7072 8.21161 18.1244 9.16706 18.1244 10.3513C18.1244 14.4826 15.6079 15.3977 13.2126 15.6668C13.6028 16.0032 13.9392 16.6492 13.9392 17.6584C13.9392 19.0983 13.9258 20.2556 13.9258 20.619C13.9258 20.9016 14.1276 21.238 14.6659 21.1303C16.8031 20.4088 18.6602 19.0353 19.9758 17.2031C21.2915 15.3708 21.9994 13.1721 22 10.9165C22 4.96848 17.1824 0.150879 11.2344 0.150879Z" /> </svg> </a> </div> <div class="aside-content px-5 py-1 flex-1 overflow-auto"> <select id="redirectSelect.show-laptop" class="select-dropdown p-1 mx-1 my-4 text-black opacity-80 show-laptop border-gray-400"> <option value="/spec/v1.1/provenance" class="inline-block">Version 1.1 RC</option> <option selected value="/spec/v1.0/provenance" class="inline-block">Version 1.0</option> <option value="/spec/v0.2/provenance" class="inline-block">Version 0.2</option> <option value="/spec/v0.1/provenance" class="inline-block">Version 0.1</option> <option value="/spec/draft/provenance" class="inline-block">Working Draft</option> </select> <script> var selectEl = document.getElementById('redirectSelect.show-laptop'); selectEl.onchange = function(){ var goto = this.value; window.location = goto; }; </script> <nav class="site-nav"><ul><li> <a class="nav-link" href="/spec/v1.0/"> Overview </a> </li><li> Understanding SLSA <ul><li> <a class="nav-link" href="/spec/v1.0/whats-new"> What's new in v1.0 </a> </li><li> <a class="nav-link" href="/spec/v1.0/about"> About SLSA </a> </li><li> <a class="nav-link" href="/spec/v1.0/threats-overview"> Supply chain threats </a> </li><li> <a class="nav-link" href="/spec/v1.0/use-cases"> Use cases </a> </li><li> <a class="nav-link" href="/spec/v1.0/principles"> Guiding principles </a> </li><li> <a class="nav-link" href="/spec/v1.0/faq"> FAQ </a> </li><li> <a class="nav-link" href="/spec/v1.0/future-directions"> Future directions </a> </li> </ul> </li><li> Core specification <ul><li> <a class="nav-link" href="/spec/v1.0/terminology"> Terminology </a> </li><li> <a class="nav-link" href="/spec/v1.0/levels"> Security levels </a> </li><li> <a class="nav-link" href="/spec/v1.0/requirements"> Producing artifacts </a> </li><li> <a class="nav-link" href="/spec/v1.0/distributing-provenance"> Distributing provenance </a> </li><li> <a class="nav-link" href="/spec/v1.0/verifying-artifacts"> Verifying artifacts </a> </li><li> <a class="nav-link" href="/spec/v1.0/verifying-systems"> Verifying build platforms </a> </li><li> <a class="nav-link" href="/spec/v1.0/threats"> Threats & mitigations </a> </li> </ul> </li><li> Attestation formats <ul><li> <a class="nav-link" href="/attestation-model"> General model </a> </li><li> <a class="nav-link is-active" href="/spec/v1.0/provenance"> Provenance </a> </li><li> <a class="nav-link" href="/spec/v1.0/verification_summary"> Verification Summary </a> </li> </ul> </li><li> How to SLSA <ul><li> <a class="nav-link" href="/get-started"> For developers </a> </li><li> <a class="nav-link" href="/how-to-orgs"> For organizations </a> </li><li> <a class="nav-link" href="/how-to-infra"> For infrastructure providers </a> </li> </ul> </li><li> <a class="nav-link" href="/spec-stages"> Specification stages </a> </li><li> <a class="nav-link" href="/community"> Community </a> </li><li> <a class="nav-link" href="/blog"> Blog </a> </li><li> <a class="nav-link" href="/spec/v1.0/onepage"> Single-page view </a> </li> </ul> </nav> </div> </aside> <div class="site-main"> <header class="site-header flex-none" x-data="{ fixed: false, hidden: false, lastPos: window.scrollY, scrolledPast: false }" x-ref="navbar" x-on:scroll.window=" fixed = window.scrollY > lastPos ? window.scrollY >= $refs.navbar.offsetHeight : window.scrollY > 0; hidden = fixed && window.scrollY > lastPos; if (window.scrollY > $refs.navbar.offsetHeight && !scrolledPast) { setTimeout(() => $refs.navbar.classList.add('is-scrolled-past'), 500); scrolledPast = true; } else if (window.scrollY === 0) { $refs.navbar.classList.remove('is-scrolled-past'); scrolledPast = false; } lastPos = window.scrollY; " x-bind:class="{ 'is-fixed': fixed, 'is-hidden': hidden, 'menu-open': navOpen }" > <div class="site-header-inner h-full flex items-center gap-5" > <button x-on:click="navOpen = !navOpen" :class="{ 'active': navOpen }" class="mobile-menu-button inline-block hide-laptop"> </button> <a rel="author" href="/" class="logo block"> <img class="logo-white" src="/images/logo.svg" alt="SLSA logo" /> </a> <select id="redirectSelect.hide-laptop" class="select-dropdown p-1 mx-1 my-4 text-black opacity-80 hide-laptop border-gray-400"> <option value="/spec/v1.1/provenance" class="inline-block">Version 1.1 RC</option> <option selected value="/spec/v1.0/provenance" class="inline-block">Version 1.0</option> <option value="/spec/v0.2/provenance" class="inline-block">Version 0.2</option> <option value="/spec/v0.1/provenance" class="inline-block">Version 0.1</option> <option value="/spec/draft/provenance" class="inline-block">Working Draft</option> </select> <script> var selectEl = document.getElementById('redirectSelect.hide-laptop'); selectEl.onchange = function(){ var goto = this.value; window.location = goto; }; </script> <a class="desktop-github-icon ml-auto" href="https://github.com/slsa-framework/slsa" target="_blank"> <svg width="22" height="22" viewBox="0 0 22 22" fill="currentColor" xmlns="http://www.w3.org/2000/svg"> <path fill-rule="evenodd" clip-rule="evenodd" d="M11.2344 0.150879C5.28641 0.150879 0.468811 4.96848 0.468811 10.9165C0.468811 15.6803 3.55046 19.7039 7.82978 21.1303C8.36806 21.2245 8.56991 20.9016 8.56991 20.619C8.56991 20.3633 8.55646 19.5155 8.55646 18.6139C5.8516 19.1118 5.15184 17.9545 4.93653 17.3489C4.81541 17.0394 4.29059 16.084 3.83306 15.8283C3.45626 15.6264 2.91798 15.1285 3.8196 15.1151C4.66739 15.1016 5.27295 15.8956 5.47481 16.2185C6.44371 17.8468 7.99126 17.3893 8.61028 17.1067C8.70448 16.4069 8.98708 15.9359 9.29659 15.6668C6.90125 15.3977 4.39825 14.4691 4.39825 10.3513C4.39825 9.18051 4.81541 8.21161 5.50172 7.45802C5.39407 7.18888 5.01727 6.08541 5.60938 4.60514C5.60938 4.60514 6.51099 4.32254 8.56991 5.70861C9.43116 5.46639 10.3462 5.34527 11.2613 5.34527C12.1764 5.34527 13.0914 5.46639 13.9527 5.70861C16.0116 4.30909 16.9132 4.60514 16.9132 4.60514C17.5053 6.08541 17.1285 7.18888 17.0209 7.45802C17.7072 8.21161 18.1244 9.16706 18.1244 10.3513C18.1244 14.4826 15.6079 15.3977 13.2126 15.6668C13.6028 16.0032 13.9392 16.6492 13.9392 17.6584C13.9392 19.0983 13.9258 20.2556 13.9258 20.619C13.9258 20.9016 14.1276 21.238 14.6659 21.1303C16.8031 20.4088 18.6602 19.0353 19.9758 17.2031C21.2915 15.3708 21.9994 13.1721 22 10.9165C22 4.96848 17.1824 0.150879 11.2344 0.150879Z" /> </svg> </a> </div> </header> <main class="site-clamp" aria-label="Content"> <header class="content-header"> <h1 class="mb-16">Provenance</h1> </header> <div class="site-content has-toc"> <aside class="table-of-contents flex flex-col">  <div class="rounded-lg p-4 border border-green-900 mt-4 md:mt-0 mb-4"> Status: <a href="/spec-stages" style="display: inline">Approved</a> </div> <div class="flex-auto rounded-lg p-4 border border-green-900 overflow-auto"> On this page <ul><li><a href="#purpose">Purpose</a></li><li><a href="#model">Model</a></li><li><a href="#parsing-rules">Parsing rules</a></li><li><a href="#schema">Schema</a><ul><li><a href="#provenance">Provenance</a></li><li><a href="#builddefinition">BuildDefinition</a></li><li><a href="#rundetails">RunDetails</a></li><li><a href="#builder">Builder</a></li><li><a href="#buildmetadata">BuildMetadata</a></li><li><a href="#extension-fields">Extension fields</a></li></ul></li><li><a href="#verification">Verification</a></li><li><a href="#index-of-build-types">Index of build types</a></li><li><a href="#migrating-from-02">Migrating from 0.2</a></li><li><a href="#change-history">Change history</a><ul><li><a href="#v10">v1.0</a></li><li><a href="#v02">v0.2</a></li><li><a href="#rename-slsadevprovenance">rename: slsa.dev/provenance</a></li><li><a href="#v011">v0.1.1</a></li><li><a href="#v01">v0.1</a></li></ul></li></ul> </div> </aside> <div class="content main-content"> To trace software back to the source and define the moving parts in a complex supply chain, provenance needs to be there from the very beginning. It’s the verifiable information about software artifacts describing where, when and how something was produced. For higher SLSA levels and more resilient integrity guarantees, provenance requirements are stricter and need a deeper, more technical understanding of the predicate. This document defines the following predicate type within the <a href="https://github.com/in-toto/attestation">in-toto attestation</a> framework: <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>"predicateType": "https://slsa.dev/provenance/v1" </code></pre></div></div> <blockquote> Important: Always use the above string for <code>predicateType</code> rather than what is in the URL bar. The <code>predicateType</code> URI will always resolve to the latest minor version of this specification. See <a href="#parsing-rules">parsing rules</a> for more information. </blockquote> The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in <a href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a>. <h2 id="purpose">Purpose</h2> Describe how an artifact or set of artifacts was produced so that: <ul> <li>Consumers of the provenance can verify that the artifact was built according to expectations.</li> <li>Others can rebuild the artifact, if desired.</li> </ul> This predicate is the RECOMMENDED way to satisfy the SLSA v1.0 <a href="requirements#provenance-generation">provenance requirements</a>. <h2 id="model">Model</h2> Provenance is an attestation that a particular build platform produced a set of software artifacts through execution of the <code>buildDefinition</code>. <img src="/spec/v1.0/images/provenance-model.svg" alt="Build Model" /> The model is as follows: <ul> <li> Each build runs as an independent process on a multi-tenant build platform. The <code>builder.id</code> identifies this platform, representing the transitive closure of all entities that are <a href="/spec/v1.0/principles#trust-systems-verify-artifacts">trusted</a> to faithfully run the build and record the provenance. (Note: The same model can be used for platform-less or single-tenant build platforms.) <ul> <li>The build platform implementer SHOULD define a security model for the build platform in order to clearly identify the platform’s boundaries, actors, and interfaces. This model SHOULD then be used to identify the transitive closure of the trusted build platform for the <code>builder.id</code> as well as the trusted control plane.</li> </ul> </li> <li> The build process is defined by a parameterized template, identified by <code>buildType</code>. This encapsulates the process that ran, regardless of what platform ran it. Often the build type is specific to the build platform because most build platforms have their own unique interfaces. </li> <li> All top-level, independent inputs are captured by the parameters to the template. There are two types of parameters: <ul> <li> <code>externalParameters</code>: the external interface to the build. In SLSA, these values are untrusted; they MUST be included in the provenance and MUST be verified downstream. </li> <li> <code>internalParameters</code>: set internally by the platform. In SLSA, these values are trusted because the platform is trusted; they are OPTIONAL and need not be verified downstream. They MAY be included to enable reproducible builds, debugging, or incident response. </li> </ul> </li> <li> All artifacts fetched during initialization or execution of the build process are considered dependencies, including those referenced directly by parameters. The <code>resolvedDependencies</code> captures these dependencies, if known. For example, a build that takes a git repository URI as a parameter might record the specific git commit that the URI resolved to as a dependency. </li> <li> During execution, the build process might communicate with the build platform’s control plane and/or build caches. This communication is not captured directly in the provenance, but is instead implied by <code>builder.id</code> and subject to <a href="/spec/v1.0/requirements">SLSA Requirements</a>. Such communication SHOULD NOT influence the definition of the build; if it does, it SHOULD go in <code>resolvedDependencies</code> instead. </li> <li> Finally, the build process outputs one or more artifacts, identified by <code>subject</code>. </li> </ul> For concrete examples, see <a href="#index-of-build-types">index of build types</a>. <h2 id="parsing-rules">Parsing rules</h2> This predicate follows the in-toto attestation <a href="https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules">parsing rules</a>. Summary: <ul> <li>Consumers MUST ignore unrecognized fields unless otherwise noted.</li> <li>The <code>predicateType</code> URI includes the major version number and will always change whenever there is a backwards incompatible change.</li> <li>Minor version changes are always backwards compatible and “monotonic.” Such changes do not update the <code>predicateType</code>.</li> <li>Unset, null, and empty field values MUST be interpreted equivalently.</li> </ul> <h2 id="schema">Schema</h2> NOTE: This section describes the fields within <code>predicate</code>. For a description of the other top-level fields, such as <code>subject</code>, see <a href="https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md">Statement</a>.  <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ // Standard attestation fields: "_type": "https://in-toto.io/Statement/v1", "subject": [...], // Predicate: "predicateType": "https://slsa.dev/provenance/v1", "predicate": { "buildDefinition": { "buildType": string, "externalParameters": object, "internalParameters": object, "resolvedDependencies": [ ...#ResourceDescriptor ], }, "runDetails": { "builder": { "id": string, "builderDependencies": [ ...#ResourceDescriptor ], "version": { ...string }, }, "metadata": { "invocationId": string, "startedOn": #Timestamp, "finishedOn": #Timestamp, }, "byproducts": [ ...#ResourceDescriptor ], } } } #ResourceDescriptor: { "uri": string, "digest": { "sha256": string, "sha512": string, "gitCommit": string, [string]: string, }, "name": string, "downloadLocation": string, "mediaType": string, "content": bytes, // base64-encoded "annotations": object, } #Timestamp: string // <YYYY>-<MM>-<DD>T<hh>:<mm>:<ss>Z </code></pre></div></div> <details> <summary>Protocol buffer schema</summary> Link: <a href="/spec/v1.0/schema/provenance.proto">provenance.proto</a> <div class="language-proto highlighter-rouge"><div class="highlight"><pre class="highlight"><code>syntax = "proto3"; package slsa.v1; import "google/protobuf/struct.proto"; import "google/protobuf/timestamp.proto"; // NOTE: While file uses snake_case as per the Protocol Buffers Style Guide, the // provenance is always serialized using JSON with lowerCamelCase. Protobuf // tooling performs this case conversion automatically. message Provenance { BuildDefinition build_definition = 1; RunDetails run_details = 2; } message BuildDefinition { string build_type = 1; google.protobuf.Struct external_parameters = 2; google.protobuf.Struct internal_parameters = 3; repeated ResourceDescriptor resolved_dependencies = 4; } message ResourceDescriptor { string uri = 1; map<string, string> digest = 2; string name = 3; string download_location = 4; string media_type = 5; bytes content = 6; google.protobuf.Struct annotations = 7; } message RunDetails { Builder builder = 1; BuildMetadata metadata = 2; repeated ResourceDescriptor byproducts = 3; } message Builder { string id = 1; map<string, string> version = 2; repeated ResourceDescriptor builder_dependencies = 3; } message BuildMetadata { string invocation_id = 1; google.protobuf.Timestamp started_on = 2; google.protobuf.Timestamp finished_on = 3; } </code></pre></div></div> </details> <h3 id="provenance">Provenance</h3> REQUIRED for SLSA Build L1: <code>buildDefinition</code>, <code>runDetails</code> <table> <tr><th>Field<th>Type<th>Description <tr id="buildDefinition"><td><code>buildDefinition</code> <td><a href="#builddefinition">BuildDefinition</a><td> The input to the build. The accuracy and completeness are implied by <code>runDetails.builder.id</code>. <tr id="runDetails"><td><code>runDetails</code> <td><a href="#rundetails">RunDetails</a><td> Details specific to this particular execution of the build. </table> <h3 id="builddefinition">BuildDefinition</h3> REQUIRED for SLSA Build L1: <code>buildType</code>, <code>externalParameters</code> <table> <tr><th>Field<th>Type<th>Description <tr id="buildType"><td><code>buildType</code> <td>string (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#typeuri">TypeURI</a>)<td> Identifies the template for how to perform the build and interpret the parameters and dependencies. The URI SHOULD resolve to a human-readable specification that includes: overall description of the build type; schema for <code>externalParameters</code> and <code>internalParameters</code>; unambiguous instructions for how to initiate the build given this BuildDefinition, and a complete example. Example: <a href="https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1">https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1</a> <tr id="externalParameters"><td><code>externalParameters</code> <td>object<td> The parameters that are under external control, such as those set by a user or tenant of the build platform. They MUST be complete at SLSA Build L3, meaning that that there is no additional mechanism for an external party to influence the build. (At lower SLSA Build levels, the completeness MAY be best effort.) The build platform SHOULD be designed to minimize the size and complexity of <code>externalParameters</code>, in order to reduce fragility and ease <a href="/spec/v1.0/verifying-artifacts">verification</a>. Consumers SHOULD have an expectation of what “good” looks like; the more information that they need to check, the harder that task becomes. Verifiers SHOULD reject unrecognized or unexpected fields within <code>externalParameters</code>. <tr id="internalParameters"><td><code>internalParameters</code> <td>object<td> The parameters that are under the control of the entity represented by <code>builder.id</code>. The primary intention of this field is for debugging, incident response, and vulnerability management. The values here MAY be necessary for reproducing the build. There is no need to <a href="/spec/v1.0/verifying-artifacts">verify</a> these parameters because the build platform is already trusted, and in many cases it is not practical to do so. <tr id="resolvedDependencies"><td><code>resolvedDependencies</code> <td>array (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md">ResourceDescriptor</a>)<td> Unordered collection of artifacts needed at build time. Completeness is best effort, at least through SLSA Build L3. For example, if the build script fetches and executes “example.com/foo.sh”, which in turn fetches “example.com/bar.tar.gz”, then both “foo.sh” and “bar.tar.gz” SHOULD be listed here. </table> The BuildDefinition describes all of the inputs to the build. It SHOULD contain all the information necessary and sufficient to initialize the build and begin execution. The <code>externalParameters</code> and <code>internalParameters</code> are the top-level inputs to the template, meaning inputs not derived from another input. Each is an arbitrary JSON object, though it is RECOMMENDED to keep the structure simple with string values to aid verification. The same field name SHOULD NOT be used for both <code>externalParameters</code> and <code>internalParameters</code>. The parameters SHOULD only contain the actual values passed in through the interface to the build platform. Metadata about those parameter values, particularly digests of artifacts referenced by those parameters, SHOULD instead go in <code>resolvedDependencies</code>. The documentation for <code>buildType</code> SHOULD explain how to convert from a parameter to the dependency <code>uri</code>. For example: <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code>"externalParameters": { "repository": "https://github.com/octocat/hello-world", "ref": "refs/heads/main" }, "resolvedDependencies": [{ "uri": "git+https://github.com/octocat/hello-world@refs/heads/main", "digest": {"gitCommit": "7fd1a60b01f91b314f59955a4e4d4e80d8edf11d"} }] </code></pre></div></div> Guidelines: <ul> <li> Maximize the amount of information that is implicit from the meaning of <code>buildType</code>. In particular, any value that is boilerplate and the same for every build SHOULD be implicit. </li> <li> Reduce parameters by moving configuration to input artifacts whenever possible. For example, instead of passing in compiler flags via an external parameter that has to be <a href="/spec/v1.0/verifying-artifacts">verified</a> separately, require the flags to live next to the source code or build configuration so that verifying the latter automatically verifies the compiler flags. </li> <li> In some cases, additional external parameters might exist that do not impact the behavior of the build, such as a deadline or priority. These extra parameters SHOULD be excluded from the provenance after careful analysis that they indeed pose no security impact. </li> <li> If possible, architect the build platform to use this definition as its sole top-level input, in order to guarantee that the information is sufficient to run the build. </li> <li> When build configuration is evaluated client-side before being sent to the server, such as transforming version-controlled YAML into ephemeral JSON, some solution is needed to make <a href="/spec/v1.0/verifying-artifacts">verification</a> practical. Consumers need a way to know what configuration is expected and the usual way to do that is to map it back to version control, but that is not possible if the server cannot verify the configuration’s origins. Possible solutions: <ul> <li> (RECOMMENDED) Rearchitect the build platform to read configuration directly from version control, recording the server-verified URI in <code>externalParameters</code> and the digest in <code>resolvedDependencies</code>. </li> <li> Record the digest in the provenance<a href="#fn1" id="fnref1">1</a> and use a separate provenance attestation to link that digest back to version control. In this solution, the client-side evaluation is considered a separate “build” that SHOULD be independently secured using SLSA, though securing it can be difficult since it usually runs on an untrusted workstation. </li> </ul> </li> <li> The purpose of <code>resolvedDependencies</code> is to facilitate recursive analysis of the software supply chain. Where practical, it is valuable to record the URI and digest of artifacts that, if compromised, could impact the build. At SLSA Build L3, completeness is considered “best effort”. </li> </ul> <h3 id="rundetails">RunDetails</h3> REQUIRED for SLSA Build L1: <code>builder</code> <table> <tr><th>Field<th>Type<th>Description <tr id="builder"><td><code>builder</code> <td><a href="#builder">Builder</a><td> Identifies the build platform that executed the invocation, which is trusted to have correctly performed the operation and populated this provenance. <tr id="metadata"><td><code>metadata</code> <td><a href="#buildmetadata">BuildMetadata</a><td> Metadata about this particular execution of the build. <tr id="byproducts"><td><code>byproducts</code> <td>array (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md">ResourceDescriptor</a>)<td> Additional artifacts generated during the build that are not considered the “output” of the build but that might be needed during debugging or incident response. For example, this might reference logs generated during the build and/or a digest of the fully evaluated build configuration. In most cases, this SHOULD NOT contain all intermediate files generated during the build. Instead, this SHOULD only contain files that are likely to be useful later and that cannot be easily reproduced. </table> <h3 id="builder">Builder</h3> REQUIRED for SLSA Build L1: <code>id</code> <table> <tr><th>Field<th>Type<th>Description <tr id="builder.id"><td><code>id</code> <td>string (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#typeuri">TypeURI</a>)<td> URI indicating the transitive closure of the trusted build platform. This is <a href="/spec/v1.0/verifying-artifacts#step-1-check-slsa-build-level">intended</a> to be the sole determiner of the SLSA Build level. If a build platform has multiple modes of operations that have differing security attributes or SLSA Build levels, each mode MUST have a different <code>builder.id</code> and SHOULD have a different signer identity. This is to minimize the risk that a less secure mode compromises a more secure one. The <code>builder.id</code> URI SHOULD resolve to documentation explaining: <ul> <li>The scope of what this ID represents.</li> <li>The claimed SLSA Build level.</li> <li>The accuracy and completeness guarantees of the fields in the provenance.</li> <li>Any fields that are generated by the tenant-controlled build process and not verified by the trusted control plane, except for the <code>subject</code>.</li> <li>The interpretation of any extension fields.</li> </ul> <tr id="builderDependencies"><td><code>builderDependencies</code> <td>array (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/resource_descriptor.md">ResourceDescriptor</a>)<td> Dependencies used by the orchestrator that are not run within the workload and that do not affect the build, but might affect the provenance generation or security guarantees. <tr id="builder.version"><td><code>version</code> <td>map (string→string)<td> Map of names of components of the build platform to their version. </table> The build platform, or <dfn>builder</dfn> for short, represents the transitive closure of all the entities that are, by necessity, <a href="/spec/v1.0/principles#trust-systems-verify-artifacts">trusted</a> to faithfully run the build and record the provenance. This includes not only the software but the hardware and people involved in running the service. For example, a particular instance of <a href="https://tekton.dev/">Tekton</a> could be a build platform, while Tekton itself is not. For more info, see <a href="/spec/v1.0/terminology#build-model">Build model</a>. The <code>id</code> MUST reflect the trust base that consumers care about. How detailed to be is a judgement call. For example, GitHub Actions supports both GitHub-hosted runners and self-hosted runners. The GitHub-hosted runner might be a single identity because it’s all GitHub from the consumer’s perspective. Meanwhile, each self-hosted runner might have its own identity because not all runners are trusted by all consumers. Consumers MUST accept only specific signer-builder pairs. For example, “GitHub” can sign provenance for the “GitHub Actions” builder, and “Google” can sign provenance for the “Google Cloud Build” builder, but “GitHub” cannot sign for the “Google Cloud Build” builder. Design rationale: The builder is distinct from the signer in order to support the case where one signer generates attestations for more than one builder, as in the GitHub Actions example above. The field is REQUIRED, even if it is implicit from the signer, to aid readability and debugging. It is an object to allow additional fields in the future, in case one URI is not sufficient. <h3 id="buildmetadata">BuildMetadata</h3> REQUIRED: (none) <table> <tr><th>Field<th>Type<th>Description <tr id="invocationId"><td><code>invocationId</code> <td>string<td> Identifies this particular build invocation, which can be useful for finding associated logs or other ad-hoc analysis. The exact meaning and format is defined by <code>builder.id</code>; by default it is treated as opaque and case-sensitive. The value SHOULD be globally unique. <tr id="startedOn"><td><code>startedOn</code> <td>string (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#timestamp">Timestamp</a>)<td> The timestamp of when the build started. <tr id="finishedOn"><td><code>finishedOn</code> <td>string (<a href="https://github.com/in-toto/attestation/blob/main/spec/v1/field_types.md#timestamp">Timestamp</a>)<td> The timestamp of when the build completed. </table> <h3 id="extension-fields">Extension fields</h3> Implementations MAY add extension fields to any JSON object to describe information that is not captured in a standard field. Guidelines: <ul> <li>Extension fields SHOULD use names of the form <code><vendor>_<fieldname></code>, e.g. <code>examplebuilder_isCodeReviewed</code>. This practice avoids field name collisions by namespacing each vendor. Non-extension field names never contain an underscore.</li> <li>Extension fields MUST NOT alter the meaning of any other field. In other words, an attestation with an absent extension field MUST be interpreted identically to an attestation with an unrecognized (and thus ignored) extension field.</li> <li>Extension fields SHOULD follow the <a href="https://github.com/in-toto/attestation/blob/main/spec/v1/README.md#parsing-rules">monotonic principle</a>, meaning that deleting or ignoring the extension SHOULD NOT turn a DENY decision into an ALLOW.</li> </ul> <h2 id="verification">Verification</h2> Please see <a href="/spec/v1.0/verifying-artifacts">Verifying Artifacts</a> for a detailed discussion of provenance verification. <h2 id="index-of-build-types">Index of build types</h2> The following is a partial index of build type definitions. Each contains a complete example predicate.  <ul> <li><a href="https://slsa-framework.github.io/github-actions-buildtypes/workflow/v1">GitHub Actions Workflow (community-maintained)</a></li> <li><a href="https://slsa-framework.github.io/gcb-buildtypes/triggered-build/v1">Google Cloud Build (community-maintained)</a></li> </ul> To add an entry here, please send a pull request on GitHub. <h2 id="migrating-from-02">Migrating from 0.2</h2> To migrate from <a href="/provenance/v0.2">version 0.2</a> (<code>old</code>), use the following pseudocode. The meaning of each field is unchanged unless otherwise noted. <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>{ "buildDefinition": { // The `buildType` MUST be updated for v1.0 to describe how to // interpret `inputArtifacts`. "buildType": /* updated version of */ old.buildType, "externalParameters": old.invocation.parameters + { // It is RECOMMENDED to rename "entryPoint" to something more // descriptive. "entryPoint": old.invocation.configSource.entryPoint, // It is OPTIONAL to rename "source" to something more descriptive, // especially if "source" is ambiguous or confusing. "source": old.invocation.configSource.uri, }, "internalParameters": old.invocation.environment, "resolvedDependencies": old.materials + [ { "uri": old.invocation.configSource.uri, "digest": old.invocation.configSource.digest, } ] }, "runDetails": { "builder": { "id": old.builder.id, "builderDependencies": null, // not in v0.2 "version": null, // not in v0.2 }, "metadata": { "invocationId": old.metadata.buildInvocationId, "startedOn": old.metadata.buildStartedOn, "finishedOn": old.metadata.buildFinishedOn, }, "byproducts": null, // not in v0.2 }, } </code></pre></div></div> The following fields from v0.2 are no longer present in v1.0: <ul> <li><code>entryPoint</code>: Use <code>externalParameters[<name>]</code> instead.</li> <li><code>buildConfig</code>: No longer inlined into the provenance. Instead, either: <ul> <li>If the configuration is a top-level input, record its digest in <code>externalParameters["config"]</code>.</li> <li>Else if there is a known use case for knowing the exact resolved build configuration, record its digest in <code>byproducts</code>. An example use case might be someone who wishes to parse the configuration to look for bad patterns, such as <code>curl | bash</code>.</li> <li>Else omit it.</li> </ul> </li> <li><code>metadata.completeness</code>: Now implicit from <code>builder.id</code>.</li> <li><code>metadata.reproducible</code>: Now implicit from <code>builder.id</code>.</li> </ul> <h2 id="change-history">Change history</h2> <h3 id="v10">v1.0</h3> Major refactor to reduce misinterpretation, including a minor change in model. <ul> <li>Significantly expanded all documentation.</li> <li>Altered the model slightly to better align with real-world build platforms, align with reproducible builds, and make verification easier.</li> <li>Grouped fields into <code>buildDefinition</code> vs <code>runDetails</code>.</li> <li>Renamed: <ul> <li><code>parameters</code> -> <code>externalParameters</code> (slight change in semantics)</li> <li><code>environment</code> -> <code>internalParameters</code> (slight change in semantics)</li> <li><code>materials</code> -> <code>resolvedDependencies</code> (slight change in semantics)</li> <li><code>buildInvocationId</code> -> <code>invocationId</code></li> <li><code>buildStartedOn</code> -> <code>startedOn</code></li> <li><code>buildFinishedOn</code> -> <code>finishedOn</code></li> </ul> </li> <li>Removed: <ul> <li><code>configSource</code>: No longer special-cased. Now represented as <code>externalParameters</code> + <code>resolvedDependencies</code>.</li> <li><code>buildConfig</code>: No longer inlined into the provenance. Can be replaced with a reference in <code>externalParameters</code> or <code>byproducts</code>, depending on the semantics, or omitted if not needed.</li> <li><code>completeness</code> and <code>reproducible</code>: Now implied by <code>builder.id</code>.</li> </ul> </li> <li>Added: <ul> <li>ResourceDescriptor: <code>annotations</code>, <code>content</code>, <code>downloadLocation</code>, <code>mediaType</code>, <code>name</code></li> <li>Builder: <code>builderDependencies</code> and <code>version</code></li> <li><code>byproducts</code></li> </ul> </li> <li>Changed naming convention for extension fields.</li> </ul> Differences from RC1 and RC2: <ul> <li>Renamed <code>systemParameters</code> (RC1 + RC2) -> <code>internalParameters</code> (final).</li> <li>Changed naming convention for extension fields (in RC2).</li> <li>Renamed <code>localName</code> (RC1) -> <code>name</code> (RC2).</li> <li>Added <code>annotations</code> and <code>content</code> (in RC2).</li> </ul> <h3 id="v02">v0.2</h3> Refactored to aid clarity and added <code>buildConfig</code>. The model is unchanged. <ul> <li>Replaced <code>definedInMaterial</code> and <code>entryPoint</code> with <code>configSource</code>.</li> <li>Renamed <code>recipe</code> to <code>invocation</code>.</li> <li>Moved <code>invocation.type</code> to top-level <code>buildType</code>.</li> <li>Renamed <code>arguments</code> to <code>parameters</code>.</li> <li>Added <code>buildConfig</code>, which can be used as an alternative to <code>configSource</code> to validate the configuration.</li> </ul> <h3 id="rename-slsadevprovenance">rename: slsa.dev/provenance</h3> Renamed to “slsa.dev/provenance”. <h3 id="v011">v0.1.1</h3> <ul> <li>Added <code>metadata.buildInvocationId</code>.</li> </ul> <h3 id="v01">v0.1</h3> Initial version, named “in-toto.io/Provenance” <section class="footnotes"> <ol> <li id="fn1"> The <code>externalParameters</code> SHOULD reflect reality. If clients send the evaluated configuration object directly to the build server, record the digest directly in <code>externalParameters</code>. If clients upload the configuration object to a temporary storage location and send that location to the build server, record the location in <code>externalParameters</code> as a URI and record the <code>uri</code> and <code>digest</code> in <code>resolvedDependencies</code>. <a href="#fnref1" class="footnote-backref">↩</a> </li> </ol> </section> <div class="mt-10 pt-10 border-t flex flex-col sm:flex-row space-between gap-5"> <a href="/spec/v1.0/threats" class="border rounded px-4 py-2 text-left">&lsaquo; Threats & mitigations</a> <a href="/spec/v1.0/verification_summary" class="sm:ml-auto border rounded px-4 py-2 text-right">Verification Summary &rsaquo;</a> </div> </div> </div> </main><footer class="site-footer flex-none h-card text-white"> <div class="site-clamp py-4 flex flex-wrap items-start justify-between w-full"> <div class="w-full md:w-1/3 mb-8 md:mb-0"> SLSA is a cross-industry collaboration. © 2024 The Linux Foundation, under the terms of the <a href="https://github.com/slsa-framework/governance">Community Specification License 1.0</a> </div> <div class="w-full md:w-1/3 mb-8 md:mb-0"> Privacy statement We use <a href="https://goatcounter.com">GoatCounter</a> to help us improve our website by collecting and reporting information on how it's used. We do not store advertising or tracking cookies. The information we collect does not identify anyone and does not track an individual's use of the site. </div> <div class="w-full md:w-1/4 mb-8 md:mb-0 flex md:justify-end"> <a href="https://github.com/slsa-framework/slsa/blob/089d120f336c9acf4d16af1fd889a26b0d7c372a/docs/spec/v1.0/provenance.md?plain=1" target="_blank" class="flex gap-4 h5 font-normal"> View source on GitHub <svg width="22" height="22" viewBox="0 0 22 22" fill="none" xmlns="http://www.w3.org/2000/svg"> <path fill-rule="evenodd" clip-rule="evenodd" d="M11.2344 0.150879C5.28641 0.150879 0.468811 4.96848 0.468811 10.9165C0.468811 15.6803 3.55046 19.7039 7.82978 21.1303C8.36806 21.2245 8.56991 20.9016 8.56991 20.619C8.56991 20.3633 8.55646 19.5155 8.55646 18.6139C5.8516 19.1118 5.15184 17.9545 4.93653 17.3489C4.81541 17.0394 4.29059 16.084 3.83306 15.8283C3.45626 15.6264 2.91798 15.1285 3.8196 15.1151C4.66739 15.1016 5.27295 15.8956 5.47481 16.2185C6.44371 17.8468 7.99126 17.3893 8.61028 17.1067C8.70448 16.4069 8.98708 15.9359 9.29659 15.6668C6.90125 15.3977 4.39825 14.4691 4.39825 10.3513C4.39825 9.18051 4.81541 8.21161 5.50172 7.45802C5.39407 7.18888 5.01727 6.08541 5.60938 4.60514C5.60938 4.60514 6.51099 4.32254 8.56991 5.70861C9.43116 5.46639 10.3462 5.34527 11.2613 5.34527C12.1764 5.34527 13.0914 5.46639 13.9527 5.70861C16.0116 4.30909 16.9132 4.60514 16.9132 4.60514C17.5053 6.08541 17.1285 7.18888 17.0209 7.45802C17.7072 8.21161 18.1244 9.16706 18.1244 10.3513C18.1244 14.4826 15.6079 15.3977 13.2126 15.6668C13.6028 16.0032 13.9392 16.6492 13.9392 17.6584C13.9392 19.0983 13.9258 20.2556 13.9258 20.619C13.9258 20.9016 14.1276 21.238 14.6659 21.1303C16.8031 20.4088 18.6602 19.0353 19.9758 17.2031C21.2915 15.3708 21.9994 13.1721 22 10.9165C22 4.96848 17.1824 0.150879 11.2344 0.150879Z" fill="white"/> </svg> </a> This site is powered by <a href="https://www.netlify.com">Netlify</a> </div> </div> <div class="site-clamp py-4 flex items-start justify-between w-full mb-16 md:mb-0"> <a rel="author" href="/"><img src="/images/logo.svg" alt="SLSA logo" /></a> </div> </footer> </div> </body> </html>