Skip to content

Commit

Permalink
docs: slsa editorial fixes
Browse files Browse the repository at this point in the history 
Signed-off-by: David Karlsson <[email protected]>
  • Loading branch information
@dvdksn @jedevc
dvdksn authored and jedevc committed Jan 4, 2023
1 parent 9c212c2 commit 066091a
Showing 1 changed file with 101 additions and 47 deletions.
148 changes: 101 additions & 47 deletions docs/slsa.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,23 @@

BuildKit supports automatic creation of [SLSA Provenance](https://slsa.dev/provenance)
attestations for the build process. Provenance attestations record information describing
how your build was performed and is important for tracking the security of your build pipeline.
how a build was created, and is important for tracking the security of your software
artifacts.

For example, provenance attestations created by BuildKit include details such as:
Provenance attestations created by BuildKit include details such as:

- Build parameters and environment.
- Build timestamps.
- Version control metadata for your build sources.
- Build dependencies with their immutable checksums. For example, base images or external URLs used by the build.
- Descriptions of all build steps, with their source and layer mappings.

All provenance generated by BuildKit is wrapped inside [in-toto attestations](https://github.com/in-toto/attestation)
Provenance generated by BuildKit is wrapped inside [in-toto attestations](https://github.com/in-toto/attestation)
in the [SLSA Provenance format](https://slsa.dev/provenance/v0.2).

## Build with provenance attestations

To build an image with attached provenance with `buildctl`, use the `attest:provenance` option:
To build an image with provenance attestations using `buildctl`, use the `attest:provenance` option:

```bash
buildctl build \
Expand All @@ -26,7 +28,7 @@ buildctl build \
--opt attest:provenance=
```

You can also specify custom parameters for the provenance:
You can also customize the attestations using parameters:

```bash
buildctl build \
Expand All @@ -36,13 +38,13 @@ buildctl build \
--opt attest:provenance=mode=min,inline-only=true
```

Provenance attestations can be attached to build results from all BuildKit exporters.
When the final output format is a container image(`image` or `oci` exporter), provenance is attached
to the image using the [attestation storage](./attestation-storage.md) specification. When creating a
multi-platform image, every single-platform subimage will have its own provenance.
All BuildKit exporters support attaching attestations to build results.
When the final output format is a container image (`image` or `oci` exporter), provenance is attached
to the image using the format described in the [attestation storage specification](./attestation-storage.md).
When creating a multi-platform image, each platform version of the image gets its own provenance.

When using the `local` or `tar` exporter, the provenance will be written to a file named `provenance.json`
and exported with your build result.
If you use the `local` or `tar` exporter, the provenance will be written to a file named `provenance.json`
and exported with your build result, in the root directory.

## Parameters

Expand Down Expand Up @@ -99,20 +101,27 @@ filesystems, you may not want to include the provenance in these cases.

The provenance format generated by BuildKit is defined by the [SLSA Provenance format](https://slsa.dev/provenance/v0.2).

The following is a selection of fields filled in by BuildKit:
This section describes how BuildKit populate each field, and whether the
field gets included when you generate attestations `mode=min` and `mode=max`.

### `builder.id` [(SLSA)](https://slsa.dev/provenance/v0.2#builder.id)

The `builder.id` field is set to the URL of the build, if available. This is value can be set with `builder-id` attestation parameter.
Included with `mode=min`.

The `builder.id` field is set to the URL of the build, if available.

```
"builder": {
"id": "https://github.com/docker/buildx/actions/runs/3709599520"
},
```

This value can be set using the `builder-id` attestation parameter.

### `buildType` [(SLSA)](https://slsa.dev/provenance/v0.2#buildType)

Included with `mode=min`.

The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be used to determine the structure of the provenance content.

```
Expand All @@ -121,6 +130,8 @@ The `buildType` field is set to "https://mobyproject.org/buildkit@v1" can be use

### `invocation.configSource` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.configSource)

Included with `mode=min`.

Describes the config that initialized the build.

```
Expand All @@ -134,12 +145,15 @@ Describes the config that initialized the build.
},
```

For builds that were initialized from a remote context like Git URL or HTTP URL, this structure
defines to URL to the context and its immutable digest. For frontend builds, the `entryPoint` field
defines the path for the Dockerfile that initialized the build (`filename` frontend option).
For builds that were initialized from a remote context, like a Git or HTTP URL, this object
defines to URL to the context and its immutable digest. For builds using a local frontend,
such as a Dockerfile, the `entryPoint` field defines the path for the frontend file that
initialized the build (`filename` frontend option).

### `invocation.parameters` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.parameters)

Partially included with `mode=min`.

Describes build inputs that were passed to the build.

```
Expand All @@ -164,18 +178,26 @@ Describes build inputs that were passed to the build.
"locals": [],
```

- `frontend` defines BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`.
The following properties are included with both `mode=min` and `mode=max`:

- `locals` lists any local sources used in the build, including the build context and frontend file.
- `frontend` defines type of BuildKit frontend used for the build. Currently, this can be `dockerfile.v0` or `gateway.v0`.
- `args` defines the build arguments passed to the BuildKit frontend. This maps to the `--opt` flag in `buildctl`.
The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes are
used for build arguments and labels, and `target` key defines the target stage that was built.
The `source` key defines the source image for the Gateway frontend, if used.
- `secrets` defines the secrets that were used to the build. Note that the actual secret values are not included.

The keys are specific to the frontend the build used. For example, in Dockerfile `build-arg:` and `label:` prefixes
are used for build arguments and labels, and `target` key defines the target stage that was built. The `source` key
defines the source image for the Gateway frontend, if used.

The following properties are only included with `mode=max`:

- `secrets` defines what secrets were used to the build. Note that actual secret values are not included.
- `ssh` defines the ssh forwards that were used to the build.
- `locals` defines if the build used any local sources.


### `invocation.environment` [(SLSA)](https://slsa.dev/provenance/v0.2#invocation.environment)

Included with `mode=min`.

```
"environment": {
"platform": "linux/amd64"
Expand All @@ -188,10 +210,15 @@ necessarily the platform of the build result that can be determined from the `in

### `materials` [(SLSA)](https://slsa.dev/provenance/v0.2#materials)

Defines all the external artifacts that were part of the build. These will be URLs to Git repositories
where the source code is coming from, HTTP URLs if you are building from a remote tarball or that you use
with `ADD` command in Dockerfile, or any Docker images that were used during the build. The URLs to
the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format.
Included with `mode=min`.

Defines all the external artifacts that were part of the build. The value depends on the type of artifact:

- The URL of Git repositories containing source code for the image
- HTTP URLs if you are building from a remote tarball, or that was included using an `ADD` command in Dockerfile
- Any Docker images that were used during the build

The URLs to the Docker images will be in [Package URL](https://github.com/package-url/purl-spec) format.

All the build materials will include the immutable checksum of the artifact. When building from a
mutable tag, you can use the digest information to determine if the artifact has been updated compared
Expand All @@ -217,7 +244,9 @@ to when the build ran.

### `buildConfig` [(SLSA)](https://slsa.dev/provenance/v0.2#buildConfig)

Describes all the build steps performed during the build.
Only included with `mode=max`.

Defines the build steps performed during the build.

BuildKit internally uses LLB definition to execute the build steps. The LLB definition of the build steps
is defined in `buildConfig.llbDefinition` field.
Expand Down Expand Up @@ -259,10 +288,12 @@ The dependencies for a vertex in the LLB graph can be found in the `inputs` fiel
...
```

### `metadata.buildIncocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId)
### `metadata.buildInvocationId` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildIncocationId)

Included with `mode=min`.

Unique identifier for the build invocation. Then building a multi-platform image with a single build request,
this value will be the same for all the single-platform subimages.
Unique identifier for the build invocation. When building a multi-platform image with a single build request,
this value will be the shared by all the platform versions of the image.

```
"metadata": {
Expand All @@ -271,6 +302,8 @@ this value will be the same for all the single-platform subimages.

### `metadata.buildStartedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildStartedOn)

Included with `mode=min`.

Timestamp when the build started.

```
Expand All @@ -279,6 +312,8 @@ Timestamp when the build started.

### `metadata.buildFinishedOn` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.buildFinishedOn)

Included with `mode=min`.

Timestamp when the build finished.

```
Expand All @@ -287,6 +322,8 @@ Timestamp when the build finished.

### `metadata.completeness` [(SLSA)](https://slsa.dev/provenance/v0.2#metadata.completeness)

Included with `mode=min`.

Defines if the provenance information is complete.

`completeness.parameters` is true if all the build arguments are included in the `invocation.parameters` field.
Expand Down Expand Up @@ -321,6 +358,8 @@ user with the `reproducible=true` attestation parameter.

### `metadata.https://mobyproject.org/buildkit@v1#hermetic`

Included with `mode=min`.

This extension field is set to true if the build was hermetic and did not access the network.
In Dockerfiles, a build is hermetic if it does not use `RUN` commands or disables
network with `--network=none` flag.
Expand All @@ -333,24 +372,39 @@ network with `--network=none` flag.

### `metadata.https://mobyproject.org/buildkit@v1#metadata`

Partially included with `mode=min`.

This extension field defines BuildKit-specific additional metadata that is not part of the SLSA provenance spec.

`source` defines the source mapping of LLB build steps defined in `buildConfig.llbDefinition` to their
original source code (for example Dockerfile commands). `source.locations` contains the ranges of all the
Dockerfile commands that were executed by a LLB step. `source.infos` array contains the source code itself.
This mapping is present if the BuildKit frontend provided it when creating the LLB definition.
#### `source`

`layers` defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the
Only included with `mode=max`.

Defines a source mapping of LLB build steps, defined in the `buildConfig.llbDefinition` field, to their
original source code (for example, Dockerfile commands). The `source.locations` field contains the ranges
of all the Dockerfile commands that were executed in an LLB step. `source.infos` array contains the source
code itself. This mapping is present if the BuildKit frontend provided it when creating the LLB definition.

#### `layers`

Only included with `mode=max`.

Defines the layer mapping of LLB build step mounts defined in `buildConfig.llbDefinition` to the
OCI descriptors of equivalent layers. This mapping is present if the layer data was available, usually
when attestation is for an image or if the build step pulled in image data as part of the build.

`vcs` defines the optional metadata for the version control system that was used for the build. If a build
uses a remote context from Git repository, BuildKit can extract the details of the version control system
automatically and present it in the `invocation.configSource` field. But if the build uses a source from a
local directory, the VCS information is lost even if the directory contained a Git repository. In this case,
the build client can send additional `vcs:source` and `vcs:revision` build options and BuildKit will add
them to the provenance attestations as extra metadata. Note that contrary to the `invocation.configSource`
field, these values were not verified by BuildKit and should not be trusted other than for a metadata hint.
#### `vcs`

Included with both `mode=min` and `mode=max`.

Defines optional metadata for the version control system used for the build. If a build uses a
remote context from Git repository, BuildKit extracts the details of the version control
system automatically and displays it in the `invocation.configSource` field. But if the build
uses a source from a local directory, the VCS information is lost even if the directory contained
a Git repository. In this case, the build client can send additional `vcs:source` and
`vcs:revision` build options and BuildKit will add them to the provenance attestations as extra
metadata. Note that, contrary to the `invocation.configSource` field, BuildKit doesn't verify the
`vcs` values, and as such they can't be trusted and should only be used as a metadata hint.

```bash
buildctl build \
Expand All @@ -365,12 +419,12 @@ buildctl build \
## Output

To inspect the provenance that was generated and attached to a container
image, you can use the `docker buildx imagetools` command to explore the
resulting image in your registry, following the format described in the
[attestation storage](./attestation-storage.md).
image, you can use the `docker buildx imagetools` command to inspect the
image in a registry. Inspecting the attestation displays the format described
in the [attestation storage specification](./attestation-storage.md).

For example, for a simple Docker image based on `alpine:latest`, we might get
the following provenance for a `mode=min` build:
For example, inspecting a simple Docker image based on `alpine:latest` results
in a provenance attestation similar to the following, for a `mode=min` build:

```json
{
Expand Down

0 comments on commit 066091a

Please sign in to comment.