editorial: Make build environment definitions linkable (#1274)

Fixes #1177 and #1197 .

---------

Signed-off-by: Marcela Melara <marcela.melara@intel.com>

Author: marcelamelara

docs/spec/draft/attested-build-env-levels.md

@@ -5,7 +5,7 @@ description: This page gives an overview of the SLSA Build Environment track and
 
 ## Rationale
 
-Today's hosted build platforms play a central role in an artifact's supply
+Today's hosted [build platforms] play a central role in an artifact's supply
 chain. Whether it's a cloud-hosted service like GitHub Actions or an internal
 enterprise CI/CD system, the build platform has a privileged level of access
 to artifacts and sensitive operations during a build (e.g., access to
@@ -18,15 +18,15 @@ implement and operate fully secure build platforms because they are made up
 of many layers of interconnected components and subsystems.
 
 The SLSA Build Environment track aims to address these issues by making it
-possible to validate the integrity and trace the provenance of core build
+possible to validate the integrity and trace the [provenance] of core build
 platform components.
 
 ## Track overview
 
 The SLSA Build Environment (BuildEnv) track describes increasing levels of
-integrity and trustworthiness of the <dfn>provenance</dfn> of a build's
-execution context. In this track, provenance describes how a [build image]
-was created, how the [hosted] build platform deployed a build image in its
+integrity and trustworthiness of the provenance of a build's
+execution context. In this track, provenance describes how a build image
+was created, how the hosted build platform deployed a build image in its
 environment, and the compute platform they used.
 
 | Track/Level   | Requirements | Focus | Trust Root
@@ -52,23 +52,23 @@ TODO
 ## BuildEnv levels
 
 The primary purpose of the Build Environment (BuildEnv) track is to enable
-auditing that a build was run in the expected execution context.
+auditing that a build was run in the expected [execution context].
 
 The lowest level only requires SLSA [Build L2] Provenance to
-exist for the build image, while higher levels provide increasing
+exist for the [build image], while higher levels provide increasing
 auditability of the build environment's properties and integrity of the
 generated provenance attestations. The highest levels introduce further
-requirements for hardware-assisted hardening aimed at reducing the trusted
-computing base of a build.
+requirements for hardware-assisted hardening of the [compute platform]
+aimed at reducing the trusted computing base of a build.
 
 Software producers and third-party auditors can check attestations generated
-by the build image producer and build platform against the expected
+by the [build image producer] and build platform against the expected
 properties for a given build environment. This enables any party to detect
 [several classes] of supply chain threats originating in the build
 environment.
 
 As in the Build track, the exact implementation of this track is determined
-by the build platform provider, whether they are a commercial CI/CD service
+by the build platform implementer, whether they are a commercial CI/CD service
 or enterprise organization. While this track describes general minimum
 requirements, this track does not dictate the following
 implementation-specific details: the type of build environment, accepted
@@ -110,23 +110,23 @@ n/a
 <dt>Summary<dd>
 
 The build image (i.e., VM or container image) used to instantiate the build
-environment has SLSA provenance showing how the image was built.
+environment has SLSA Build Provenance showing how the image was built.
 
 <dt>Intended for<dd>
 
 Build platforms and organizations wanting to ensure a baseline level of
-integrity for build environments at the time of build image distrbution.
+integrity for build environments at the time of build image distribution.
 
 <dt>Requirements<dd>
 
 -   Build Image Producer:
     -   MUST automatically generate SLSA [Build L2] or higher
     Provenance for created build images (i.e., VM or container images).
-    -   MUST allow independent automatic verification of a build image's SLSA
-    Provenance. If the build image artifact cannot be published, for example
-    due to intellectual property concerns, an attestation asserting the
+    -   MUST allow independent automatic verification of a build image's [SLSA
+    Build Provenance]. If the build image artifact cannot be published, for
+    example due to intellectual property concerns, an attestation asserting the
     expected hash value of the build image MUST be generated and distributed
-    instead (e.g., using [SCAI] or a [Release Attestation]). If the full
+    instead (e.g., using [SCAI] or a [Release Attestation]). If the full Build
     Provenance document cannot be disclosed, a [VSA] asserting the build
     image's SLSA Provenance MUST be distributed instead.
 
@@ -168,14 +168,14 @@ All of [BuildEnv L1], plus:
 -   Build Image Producer:
     -   Build images MUST be created via a SLSA [Build L3] or higher build
     process.
-    -   MUST automatically generate and distribute signed reference values
+    -   MUST automatically generate and distribute signed [reference values]
     for the following build image components: bootloader or equivalent,
-    guest kernel, build agent, build executor, and root filesystem (e.g.,
-    via the image's SLSA Provenance, or [SCAI]).
+    guest kernel, [build agent], and root filesystem (e.g., via the image's
+    SLSA Provenance, or [SCAI]).
     Additional build image components whose initial state is to be checked
     MAY be also measured.
     -   The build agent MUST be capable of:
-        -   Upon completion of the boot process: Automatically interfacing
+        -   Upon completion of the [boot process]: Automatically interfacing
         with the host interface to obtain and transmit a signed quote for the
         build environment's system state.
         -   Upon build dispatch: Automatically generating and distributing
@@ -185,13 +185,13 @@ All of [BuildEnv L1], plus:
 -   Build Platform Requirements:
     -   MUST meet SLSA [Build L3] requirements.
     -   Prior to dispatching a tenant's build to an instantiated environment,
-    a signed quote MUST be automatically requested from the build agent,
-    and the contained measurements verified against their boot process
+    a signed [quote] MUST be automatically requested from the build agent,
+    and the contained [measurements] verified against their boot process
     reference values. A signed attestation to the result of the verification
     MUST be generated and distributed (e.g., via a [VSA]).
 
 -   Compute Platform Requirements:
-    -   The host interface MUST be capable of generating signed quotes for
+    -   The [host interface] MUST be capable of generating signed quotes for
     the build environment's system state.
     In a VM-based environment, this MUST be achieved by enabling a feature
     like [vTPM], or equivalent, in the hypervisor.
@@ -295,10 +295,22 @@ TODO
 [Release Attestation]: https://github.com/in-toto/attestation/blob/main/spec/predicates/release.md
 [SCAI]: https://github.com/in-toto/attestation/blob/main/spec/predicates/scai.md
 [Secure Boot]: https://wiki.debian.org/SecureBoot#What_is_UEFI_Secure_Boot.3F
+[SLSA Build Provenance]: provenance.md
 [TPM]: https://trustedcomputinggroup.org/resource/tpm-library-specification/
 [VSA]: verification_summary.md
-[build image]: terminology.md#build-environment-model
+[build image]: terminology.md#build-image
 [confidential computing]: https://confidentialcomputing.io/wp-content/uploads/sites/10/2023/03/Common-Terminology-for-Confidential-Computing.pdf
+[execution context]: terminology.md#build-environment
 [hosted]: requirements.md#isolation-strength
+[boot process]:  terminology.md#boot-process
+[build agent]: terminology.md#build-agent
+[build image producer]: terminology.md#build-image-producer
+[build platforms]: terminology.md#platform
+[compute platform]: terminology.md#compute-platform
+[host interface]: terminology.md#host-interface
+[measurement]: terminology.md#measurement
+[provenance]: terminology.md#provenance
+[quote]: terminology.md#quote
+[reference values]: terminology.md#reference-value
 [several classes]: #build-environment-threats
 [vTPM]: https://trustedcomputinggroup.org/about/what-is-a-virtual-trusted-platform-module-vtpm/

docs/spec/draft/terminology.md

@@ -99,18 +99,18 @@ of build types](/provenance/v1#index-of-build-types).
 
 | Primary Term | Description
 | --- | ---
-| Platform | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations.
+| <span id="platform">Platform</span> | System that allows tenants to run builds. Technically, it is the transitive closure of software and services that must be trusted to faithfully execute the build. It includes software, hardware, people, and organizations.
 | Admin | A privileged user with administrative access to the platform, potentially allowing them to tamper with builds or the control plane.
 | Tenant | An untrusted user that builds an artifact on the platform. The tenant defines the build steps and external parameters.
 | Control plane | Build platform component that orchestrates each independent build execution and produces provenance. The control plane is managed by an admin and trusted to be outside the tenant's control.
 | Build | Process that converts input sources and dependencies into output artifacts, defined by the tenant and executed within a single build environment on a platform.
 | Steps | The set of actions that comprise a build, defined by the tenant.
-| Build environment | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps.
+| <span id="build-environment">Build environment</span> | The independent execution context in which the build runs, initialized by the control plane. In the case of a distributed build, this is the collection of all such machines/containers/VMs that run steps.
 | Build caches | An intermediate artifact storage managed by the platform that maps intermediate artifacts to their explicit inputs. A build may share build caches with any subsequent build running on the platform.
 | External parameters | The set of top-level, independent inputs to the build, specified by a tenant and used by the control plane to initialize the build.
 | Dependencies | Artifacts fetched during initialization or execution of the build process, such as configuration files, source artifacts, or build tools.
 | Outputs | Collection of artifacts produced by the build.
-| Provenance | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters.
+| <span id="provenance">Provenance</span> | Attestation (metadata) describing how the outputs were produced, including identification of the platform and external parameters.
 
 <details><summary>Ambiguous terms to avoid</summary>
 
@@ -131,46 +131,51 @@ of build types](/provenance/v1#index-of-build-types).
 
 <p align="center"><img src="images/build-env-model.svg" alt="Build Environment Model"></p>
 
-The Build Environment (BuildEnv) track expands upon the [build model](#build-model)
-by explicitily separating the *build image* and *compute platform* from the abstract
-build environment and build platform.
-
-A typical build environment will go through the following lifecycle:
-
-1.  *Build image creation*: A build image producer creates different build
-    images through a dedicated build process. For the SLSA BuildEnv track,
-    the build image producer outputs provenance describing this process.
-2.  *Build environment instantiation*: The hosted build platform calls
-    into the *host interface* to create a new instance of a build environment
-    from a given build image. The *build agent* begins to wait for an incoming
-    build dispatch. For the SLSA BuildEnv track, the host interface in the
-    compute platform attests to the integrity of the environment's *initial
-    state* during its boot process.
-3.  *Build dispatch*: When the tenant dispatches a new build, the hosted
-    build platform assigns the build to a created build environment.
-    For the SLSA BuildEnv track, the build platform
-    attests to the binding between a build environment and *build ID*.
-4.  *Build execution*: Finally, the *build agent* within the
-    environment executes the tenant's build definition.
-
-The BuildEnv track uses the following roles, components, and concepts:
+The Build Environment (BuildEnv) track expands upon the
+[build model](#build-model) by explicitily separating the
+[build image](#build-image) and [compute platform](#compute-platform) from the
+abstract [build environment](#build-environment) and [build platform](#platform).
+Specifically, the BuildEnv track defines the following roles, components, and concepts:
 
 | Primary Term | Description
 | --- | ---
-| Build ID | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution.
-| Build image | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent.
-| Build image producer | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting.
-| Build agent | A build platform-provided program that interfaces with the build platform's control plane from within a running build environment. The build agent is also responsible for executing the tenant’s build definition, i.e., running the build. In practice, the build agent may be loaded into the build environment after instantiation, and may consist of multiple components. All build agent components must be measured along with the build image.
-| Build dispatch | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform.
-| Compute platform | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations.
-| Host interface | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator.
-| Boot process | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform.
-| Measurement | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data.
-| Quote | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata.
-| Reference value | A specific measurement used as the good known value for a given build environment component or state.
+| <span id="build-id">Build ID</span> | An immutable identifier assigned uniquely to a specific execution of a tenant's build. In practice, the build ID may be an identifier, such as a UUID, associated with the build execution.
+| <span id="build-image">Build image</span> | The template for a build environment, such as a VM or container image. Individual components of a build image include the root filesystem, pre-installed guest OS and packages, the build executor, and the build agent.
+| <span id="build-image-producer">Build image producer</span> | The party that creates and distributes build images. In practice, the build image producer may be the hosted build platform or a third party in a bring-your-own (BYO) build image setting.
+| <span id="build-agent">Build agent</span> | A build platform-provided program that interfaces with the build platform's control plane from within a running build environment. The build agent is also responsible for executing the tenant’s build definition, i.e., running the build. In practice, the build agent may be loaded into the build environment after instantiation, and may consist of multiple components. All build agent components must be measured along with the build image.
+| <span id="build-dispatch">Build dispatch</span> | The process of assigning a tenant's build to a pre-deployed build environment on a hosted build platform.
+| <span id="compute-platform">Compute platform</span> | The compute system and infrastructure underlying a build platform, i.e., the host system (hypervisor and/or OS) and hardware. In practice, the compute platform and the build platform may be managed by the same or distinct organizations.
+| <span id="host-interface">Host interface</span> | The component in the compute platform that the hosted build platform uses to request resources for deploying new build environments, i.e., the VMM/hypervisor or container orchestrator.
+| <span id="boot-process">Boot process</span> | In the context of builds, the process of loading and executing the layers of firmware and/or software needed to start up a build environment on the host compute platform.
+| <span id="measurement">Measurement</span> | The cryptographic hash of some component or system state in the build environment, including software binaries, configuration, or initialized run-time data.
+| <span id="quote">Quote</span> | (Virtual) hardware-signed data that contains one or more (virtual) hardware-generated measurements. Quotes may additionally include nonces for replay protection, firmware information, or other platform metadata. (Based on the definition in [section 9.5.3.1](https://trustedcomputinggroup.org/wp-content/uploads/TPM-2.0-1.83-Part-1-Architecture.pdf) of the TPM 2.0 spec)
+| <span id="reference-value">Reference value</span> | A specific measurement used as the good known value for a given build environment component or state.
 
 **TODO:** Disambiguate similar terms (e.g., image, build job, build executor/runner)
 
+#### Build environment lifecycle
+
+A typical build environment will go through the following lifecycle:
+
+1.  *Build image creation*: A [build image producer](#build-image-producer)
+    creates different [build images](#build-image) through a dedicated build
+ process. For the SLSA BuildEnv track, the build image producer outputs
+ [provenance](#provenance) describing this process.
+2.  *Build environment instantiation*: The [hosted build platform](#platform)
+    calls into the [host interface](#host-interface) to create a new instance
+ of a build environment from a given build image. The
+ [build agent](#build-agent) begins to wait for an incoming
+ [build dispatch](#build-dispatch).
+ For the SLSA BuildEnv track, the host interface in the compute platform
+ attests to the integrity of the environment's initial state during its
+ [boot process](#boot-process).
+3.  *Build dispatch*: When the tenant dispatches a new build, the hosted
+    build platform assigns the build to a created build environment.
+    For the SLSA BuildEnv track, the build platform attests to the binding
+ between a build environment and [build ID](#build-id).
+4.  *Build execution*: Finally, the build agent within the environment executes
+    the tenant's build definition.
+
 ### Package model
 
 Software is distributed in identifiable units called <dfn>packages</dfn>