docs: add user-facing attestation docs

Signed-off-by: Justin Chadwell <me@jedevc.com>

docs/attestations.md

@@ -0,0 +1,76 @@
+# Attestations
+
+<!-- FIXME: this probably belongs as a docker/buildx guide -->
+
+BuildKit supports automatic creation of [in-toto attestations](https://github.com/in-toto/attestation)
+to record various pieces of metadata and information about the build.
+
+When the final output format is a container image, these attestations are
+attached to the image using the [attestation storage](./attestation-storage.md).
+
+## [SBOMs](https://en.wikipedia.org/wiki/Software_supply_chain)
+
+SBOMs are an attestation that records the software components that make up the
+final image. These consist of a list of software packages and the files that
+they own.
+
+They also usually contain metadata about each component, such as software
+licenses, authors, and unique package identifers which can be used for
+vulnerability scanning.
+
+All SBOMs generated by BuildKit are in the [SPDX](https://spdx.dev) JSON
+format. They can be generated using generator images that follow the
+[SBOM generator protocol](./sbom-protocol.md).
+
+To build an image with an attached SBOM (derived using
+[jedevc/buildkit-syft-scanner](https://github.com/jedevc/buildkit-syft-scanner)):
+
+```bash
+buildctl build \
+    --frontend=dockerfile.v0 \
+    --local context=. \
+    --local dockerfile=. \
+    --opt attest:sbom=generator=jedevc/buildkit-syft-scanner
+```
+
+### Dockerfile configuration
+
+If using the dockerfile frontend, you can also set various build arguments in
+your `Dockerfile` to more precisely control the targets that are scanned:
+
+```dockerfile
+# scan the build context using the generator
+ARG SBOM_SCAN_CONTEXT=true
+
+FROM alpine:latest as build
+# scan the the build stage using the generator
+ARG SBOM_SCAN_TARGET=true
+RUN ... # build some software
+
+FROM scratch
+# the final stage is always scanned by default
+COPY --from=build /path/to/software /path/to/software
+```
+
+If the generator image passed as an option in `attest:sbom` supports it, an
+additional SBOM for the build context and each target will be generated in
+addition to an SBOM for the final stage.
+
+You can also directly override these `ARG`s on the command line, by passing
+them as build-arguments.
+
+```bash
+buildctl build \
+    --frontend=dockerfile.v0 \
+    --local context=. \
+    --local dockerfile=. \
+    --opt build-arg:SBOM_SCAN_STAGE=true \
+    --opt build-arg:SBOM_SCAN_CONTEXT=true \
+    --opt attest:sbom=generator=jedevc/buildkit-syft-scanner
+```
+
+## [SLSA provenance](https://slsa.dev/provenance/v0.2)
+
+> **Warning**
+>
+> Work in progress!