diff --git a/docs/eigencompute/concepts/verifiable-builds.md b/docs/eigencompute/concepts/verifiable-builds.md new file mode 100644 index 00000000..a1c8d6db --- /dev/null +++ b/docs/eigencompute/concepts/verifiable-builds.md @@ -0,0 +1,49 @@ +--- +title: Verifiable Builds +sidebar_position: 5 +--- + +Verifiable builds provide cryptographic proof linking the source code and build process for EigenCompute applications. EigenCompute verifiable builds +enable users to cryptographically verify that a running container was built from a specific GitHub commit. + +EigenCompute uses the [Google Cloud Build SLSA provenance system](https://cloud.google.com/build/docs/securing-builds/generate-validate-build-provenance/) +to provide the build digest that is cryptographically signed by Google Cloud Build and includes: + +* Git repository URL +* Exact commit SHA +* Dockerfile path and build context +* All dependency image digests +* Build timestamp. + +Verifiably built containers are stored publicly in [Docker Hub](https://hub.docker.com/r/eigenlayer/eigencloud-containers). + +The [Verifiability Dashboard](https://verify.eigencloud.xyz/) displays the status of source code verification for applications. + +For information on how to build verifiably, see [Build from verfiable source](../howto/build/verifiable-builds/build-from-verifiable-source.md). + +## Dependencies + +For an application to be verifiably built, every layer of the application stack must be verifiably built. You cannot include +unverified code in a verifiable build. + +When you submit a build with dependencies, each dependency: + +1. Must be a previously verifiably built image. +2. Must have valid SLSA provenance. +3. Must have it's digest recorded in your build's provenance. + +When submitting a build with dependencies, provenance is validated and dependency digests are recorded in the build's SLSA provenance. + +The [EigenCompute TLS and KMS clients are prebuilt](https://github.com/Layr-Labs/eigencompute-containers) and the digests included in all EigenCompute applications. + +EigenCompute applications with dependencies other than the TLS and KMS clients must submit those verifiable builds and include +the dependency's image digest when verifiably building the application. + +## Guarantees + +| Property | Guarantee | +|-----------------------|---------------------------------------------------------| +| Source Verification | Every line of code traces back to a specific git commit | +| Build Reproducibility | Same inputs always produce same provenance | +| Dependency Integrity | No unverified code can be injected | +| Tamper Evidence | Any modification breaks the cryptographic chain | diff --git a/docs/eigencompute/howto/build/verifiable-builds/_category_.json b/docs/eigencompute/howto/build/verifiable-builds/_category_.json new file mode 100644 index 00000000..a6c6904a --- /dev/null +++ b/docs/eigencompute/howto/build/verifiable-builds/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 4, + "label": "Verifiable Builds", + "collapsible": true, + "collapsed": false, +} \ No newline at end of file diff --git a/docs/eigencompute/howto/build/verifiable-builds/build-from-verifiable-source.md b/docs/eigencompute/howto/build/verifiable-builds/build-from-verifiable-source.md new file mode 100644 index 00000000..c81ea1b6 --- /dev/null +++ b/docs/eigencompute/howto/build/verifiable-builds/build-from-verifiable-source.md @@ -0,0 +1,53 @@ +--- +title: Build from verifiable source +sidebar_position: 1 +--- + +To build from a verifiable source, options are: + +1. Use the `ecloud compute build submit` command to submit a verifiable build from a GitHub source. +2. Specify the `--verifiable` option or select `Yes` when prompted when deploying or upgrading using the `ecloud compute deploy` or `upgrade` commands.. + +## Submit from GitHub source + +To submit a verifiable build from a GitHub source, specify the required options or supply when prompted: + +* `--repo` (`ECLOUD_BUILD_REPO`) +* `--commit` (`ECLOUD_BUILD_COMMIT`) +* `--dockerfile` (`ECLOUD_BUILD_DOCKERFILE`, default is `Dockerfile`) +* `--context` (`ECLOUD_BUILD_CONTEXT`, default is `.`) +* `--dependencies sha256:...` (repeatable; prompt supports comma-separated) +* `--build-caddyfile` (`ECLOUD_BUILD_CADDYFILE`) (optional) +* `--no-follow` +* `--json` + +For example: +``` +ecloud compute build submit --repo https://github.com/myorg/myapp --commit abc123... + +ecloud compute build submit --repo https://github.com/myorg/myapp --commit abc123... --dependencies sha256:def456... + +ecloud compute build submit --repo https://github.com/myorg/myapp --commit abc123... --build-caddyfile Caddyfile + +ecloud compute build submit --repo https://github.com/myorg/myapp --commit abc123... --no-follow +``` + +Once built and verified, the image can be specified as a prebuilt image when deploying or upgrading. + +## Submit when deploying or upgrading + +To submit when deploying or upgrading, specify the `--verifiable` option for the `ecloud compute app` command, or select +`Yes` when prompted. + +When deploying or upgrading, specify a GitHub source using the `--build-context`, `--build-dependencies`, and `--build-dockerfile` options, +or specify a prebuilt verifiable image using the `--image-ref` option. + +## Submitting builds with dependencies + +To specify prebuilt dependencies to include in a verifiable build, use the `--dependencies` option for `ecloud compute build`, +`ecloud compute app deploy` or `ecloud compute app upgrade`. + +The EigenCompute TLS and KMS clients do not need to be specified as dependencies because they are [prebuilt](https://github.com/Layr-Labs/eigencompute-containers) +and the digests included in all EigenCompute applications. + +For more information on dependencies in verifiable builds, refer to [Verifiable Builds](../../../concepts/verifiable-builds.md). \ No newline at end of file