diff --git a/docs/_posts/2023-08-07-bring-your-own-builder-github.md b/docs/_posts/2023-08-07-bring-your-own-builder-github.md index dee206c53..ffc4e9889 100644 --- a/docs/_posts/2023-08-07-bring-your-own-builder-github.md +++ b/docs/_posts/2023-08-07-bring-your-own-builder-github.md @@ -4,7 +4,7 @@ author: "Andres Almiray (JReleaser), Adam Korczynski (AdaLogics), Philip Harriso is_guest_post: false --- -It has been an exciting quarter for supply chain security and SLSA, with the release of the [SLSA v1.0 specification](2023-04-19-slsa-v1-final.md), [SLSA provenance support for npm](https://github.blog/2023-04-19-introducing-npm-package-provenance/), and the announcement of new SLSA Level 3 builders for [Node.js](2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md) and [containers](2023-06-13-slsa-github-worfklows-container-based.md)! +It has been an exciting quarter for supply chain security and SLSA, with the release of the [SLSA v1.0 specification](2023-04-19-slsa-v1-final.md), [SLSA provenance support for npm](https://github.blog/2023-04-19-introducing-npm-package-provenance/), and the announcement of new SLSA Level 3 builders for [Node.js](2023-05-11-bringing-improved-supply-chain-security-to-the-nodejs-ecosystem.md) and [containers](2023-06-13-slsa-github-worfklows-container-based.md)! SLSA now provides and maintains official builders for [Go](2022/06/slsa-github-workflows), [Node.js](2023/05/bringing-improved-supply-chain-security-to-the-nodejs-ecosystem) and [Container](2023/06/slsa-github-worfklows-container-based) based projects. But what if you don't use any of these languages or use custom tooling that isn't supported by the official builders? @@ -19,12 +19,12 @@ To demonstrate the flexibility of this framework, we are also announcing three S The BYOB framework benefits both GitHub Action maintainers and GitHub Action users: -1. For Action maintainers, it makes it easy to meet the [SLSA Build L3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements. -1. For Action users, it makes it easy to adopt SLSA by trusting the BYOB project and the Action code - without worrying about which machine runs the Action. +1. For Action maintainers, it makes it easy to meet the [SLSA Build L3](https://slsa.dev/spec/v1.0/levels#build-l3) requirements. +2. For Action users, it makes it easy to adopt SLSA by trusting the BYOB project and the Action code - without worrying about which machine runs the Action. The BYOB framework provides a set of GitHub Actions and workflows that helps builder authors generate provenance. -The high-level architecture is depicted in the diagram below. The `builder_workflow.yml` represents the builder being created. The BYOB framework, on the right of the diagram, acts as an orchestrator. +The high-level architecture is depicted in the diagram below. The `builder_workflow.yml` represents the builder being created. The BYOB framework, on the right of the diagram, acts as an orchestrator. ![BYOB architecture](https://github.com/slsa-framework/slsa/assets/64505099/51c796e3-754e-4cd8-b2ea-dd8c23662411) @@ -40,7 +40,7 @@ uses: slsa-framework/slsa-github-generator/actions/delegator/setup-generic@v1.8. ... slsa-runner-label: "ubuntu-latest" slsa-build-action-path: "./internal/callback_action" - slsa-workflow-inputs: {% raw %} ${{ toJson(inputs) }} {% endraw %} + slsa-workflow-inputs: {% raw %}${{ toJson(inputs) }}{% endraw %} ``` The second step is to run the BYOB framework with the initialized "slsa-token": @@ -48,10 +48,10 @@ The second step is to run the BYOB framework with the initialized "slsa-token": ```yaml uses: slsa-framework/slsa-github-generator/.github/workflows/delegator_generic_slsa3.yml@v1.8.0 with: - slsa-token: {% raw %} ${{ needs.slsa-setup.outputs.slsa-token }} {% endraw %} + slsa-token: {% raw %}${{ needs.slsa-setup.outputs.slsa-token }}{% endraw %} secrets: - secret1: {% raw %} ${{ inputs.password }} {% endraw %} - secret2: {% raw %} ${{ inputs.token }} {% endraw %} + secret1: {% raw %}${{ inputs.password }}{% endraw %} + secret2: {% raw %}${{ inputs.token }}{% endraw %} ``` When the run completes, the BYOB framework will generate a list of attestations for the artifacts indicated by the builder. More information is available in our [documentation](https://github.com/slsa-framework/slsa-github-generator/blob/main/BYOB.md#generation-of-metadata-layout-file). @@ -60,11 +60,11 @@ When the run completes, the BYOB framework will generate a list of attestations To validate the design of the BYOB framework and demonstrate its flexibility, we have partnered with new contributors to create three new builders for the [Java ecosystems](https://github.com/slsa-framework/slsa-github-generator/blob/main/README.md#builder-creation): -1. A [JReleaser](https://github.com/jreleaser/release-action/tree/java#slsa-builder) Java builder which wraps the existing [GitHub Action for JReleaser](https://github.com/jreleaser/release-action) into a SLSA3-compliant builder. The integration was done by [aalmiray@](https://github.com/aalmiray), the maintainer of the [JReleaser](https://jreleaser.org) project. The resulting builder is hosted in the same repository as its original [Action](https://github.com/jreleaser/release-action/blob/java/.github/workflows/builder_slsa3.yml), so that JReleaser users can continue using the repositories they are already accustomed to. +1. A [JReleaser](https://github.com/jreleaser/release-action/tree/java#slsa-builder) Java builder which wraps the existing [GitHub Action for JReleaser](https://github.com/jreleaser/release-action) into a SLSA3-compliant builder. The integration was done by [aalmiray@](https://github.com/aalmiray), the maintainer of the [JReleaser](https://jreleaser.org) project. The resulting builder is hosted in the same repository as its original [Action](https://github.com/jreleaser/release-action/blob/java/.github/workflows/builder_slsa3.yml), so that JReleaser users can continue using the repositories they are already accustomed to. -2. A [Maven builder](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/maven#readme), contributed by [AdaLogics](https://adalogics.com). This builder is currently hosted in the OpenSSF SLSA repository. +2. A [Maven builder](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/maven#readme), contributed by [AdaLogics](https://adalogics.com). This builder is currently hosted in the OpenSSF SLSA repository. -3. A [Gradle builder](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/gradle#readme), contributed by [AdaLogics](https://adalogics.com). This builder is currently hosted in the OpenSSF SLSA repository. +3. A [Gradle builder](https://github.com/slsa-framework/slsa-github-generator/tree/main/internal/builders/gradle#readme), contributed by [AdaLogics](https://adalogics.com). This builder is currently hosted in the OpenSSF SLSA repository. These Java builders can publish provenance attestation on Maven central. Additionally, the JReleaser SLSA builder can provide attestation for artifacts published as GitHub release assets and/or uploaded to cloud storage such as AWS S3. Like other builders released by the SLSA Tooling SIG, the provenance can be verified using the [slsa-verifier](https://github.com/slsa-framework/slsa-verifier). @@ -79,25 +79,25 @@ Maven Central allows you to browse the files of each release, and from there you Once you have the link to the artifact, you can verify it as follows: ```shell -$ ARTIFACT=test-artifact-0.1.0-jar -$ ARTIFACT_URL="https://repo1.maven.org/maven2/path/to/${ARTFACT}" -$ PROVENANCE_URL="${ARTIFACT_URL}".build.slsa -$ wget "${ARTIFACT_URL}" && wget "${PROVENANCE_URL}" -$ slsa-verifier verify-artifact "${ARTIFACT}" --provenance-path="${ARTIFACT}.build.slsa" --source-uri github.com/org/repo +ARTIFACT=test-artifact-0.1.0-jar +ARTIFACT_URL="https://repo1.maven.org/maven2/path/to/${ARTFACT}" +PROVENANCE_URL="${ARTIFACT_URL}".build.slsa +wget "${ARTIFACT_URL}" && wget "${PROVENANCE_URL}" +slsa-verifier verify-artifact "${ARTIFACT}" --provenance-path="${ARTIFACT}.build.slsa" --source-uri github.com/org/repo ``` ### Verification for your dependencies A Java project contains not only the main application code, but also its dependencies consumed as "packages". We can therefore recursively verify each dependency's provenance. To this end, we're releasing an [experimental Maven plugin](https://github.com/slsa-framework/slsa-verifier/tree/main/experimental/maven-plugin). The plugin resolves all dependencies of a given project and checks if they have provenance attestations along with their releases. When the plugin finds a dependency that has a provenance statement, it verifies it against the dependency. -The plugin automatically performs the verification when configured in the ["pom.xml"](TODO:link to doc). Or it may be run [manually](TODO:link to doc). See our [documentation](https://github.com/slsa-framework/slsa-verifier/tree/main/experimental/maven-plugin). +The plugin automatically performs the verification when configured in the ["pom.xml"](https://github.com/slsa-framework/slsa-verifier/tree/main/experimental/maven-plugin#integrating-it-into-your-maven-build-cycle). Or it may be run [manually](https://github.com/slsa-framework/slsa-verifier/tree/main/experimental/maven-plugin#using-the-maven-verification-plugin). See our [documentation](https://github.com/slsa-framework/slsa-verifier/tree/main/experimental/maven-plugin). The plugin is still a proof-of-concept, but it demonstrates what's possible with and likely to come from the BYOB Framework. With the framework producing L3 provenance for GitHub Actions users, and the plugin automatically verifying Maven packages, you can build an end-to-end solution for an entire ecosystem. ## Conclusion -Thanks to the BYOB framework, it's now possible for maintainers of existing GitHub Actions to start producing SLSA Level 3 provenance attestations! +Thanks to the BYOB framework, it's now possible for maintainers of existing GitHub Actions to start producing SLSA Level 3 provenance attestations! -If you are a maintainer of an existing GitHub Action, try it out by following the [BYOB documentation](https://github.com/slsa-framework/slsa-github-generator/tree/main#build-your-own-builder) and don't hesitate to report issues or ask questions on the [slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator/issues) repository. +If you are a maintainer of an existing GitHub Action, try it out by following the [BYOB documentation](https://github.com/slsa-framework/slsa-github-generator/tree/main#build-your-own-builder) and don't hesitate to report issues or ask questions on the [slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator/issues) repository. **Special thanks**: Zach Steindler (GitHub), Ian Lewis, Asra Ali, Appu Goundan (Google) for the help landing this feature (design, reviews, implementation, etc)!