Merge pull request #76 from LogFlames/document_sigstore

Add documentation for signing Maven releases with sigstore

Author: monperrus

index.md

@@ -94,6 +94,7 @@ See [https://github.com/chains-project/](https://github.com/orgs/chains-project/
 - [Software supply chain attacks on crypto infrastructure](software-supply-chain-attacks-crypto.md)
 - [NIX and the supply chain, debrief of NixCon 2022](nixcon-2022.md)
 - [SBOMs for your GitHub Releases](sbom-github.md)
+- [Sigstore Attestations for your GitHub Releases](maven-sigstore.md)
 - [Software suply chain CWEs](cwe-software-supplu-chain.md)
 - [CHAINS checklist](chains-repo-checklist.md)
 

maven-sigstore.md

@@ -0,0 +1,63 @@
+---
+title: Pushing Sigstore Attestations to Maven Central on Release
+---
+
+# Pushing Sigstore Attestations to Maven Central on Release
+
+## Requirements
+
+You need a project, a GitHub repository, and releases done with GitHub Actions. You also need a sigstore plugin that supports your build system.
+Here we show how to do it with maven and sigstore-maven-plugin.
+
+## Steps
+
+1. Add a plugin to your pom.xml. If you have a different build system, you can find the appropriate plugin here: [https://docs.sigstore.dev/language_clients/language_client_overview/](https://docs.sigstore.dev/language_clients/language_client_overview/).
+
+   ```xml
+   <properties>
+     <sigstore.skip>true</sigstore.skip>
+   </properties>
+   ```
+
+   ```xml
+   <build>
+     <plugins>
+       <plugin>
+         <groupId>dev.sigstore</groupId>
+         <artifactId>sigstore-maven-plugin</artifactId>
+         <version>1.3.0</version>
+         <configuration>
+           <skip>${sigstore.skip}</skip>
+         </configuration>
+         <executions>
+           <execution>
+             <id>sign</id>
+             <goals>
+               <goal>sign</goal>
+             </goals>
+           </execution>
+         </executions>
+       </plugin>
+     </plugins>
+   </build>
+   ```
+
+   This will create a `<filename>.sigstore.json` with the attestation during the `sign` build step. We add the optional property `sigstore.skip` to make the default to not sign (for easier local development). Signing is then enabled during deployment builds using the maven argument: `-Dsigstore.skip=false`.
+
+2. (GitHub) Add the `id-token` permission to your release job in GitHub Actions.
+
+   ```yaml
+   jobs:
+     build:
+       name: Build and release
+       permissions:
+         id-token: write
+       [...]
+   ```
+
+   This enables OIDC authentication for the release job, which is required for signing artifacts with sigstore. For additional details, see the documentation for [sigstore-maven-plugin](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin).
+
+3. (Maven Central) JReleaser automatically uploads the `<filename>.sigstore.json` files to Maven Central.
+
+4. Make a release :) The final result looks like this on Maven Central: https://repo1.maven.org/maven2/io/github/chains-project/maven-lockfile/5.8.2/.
+

sbom-github.md

@@ -26,7 +26,7 @@ By the end of this post, you will clearly understand how to add SBOMs to your so
 
 ## Steps
 
-1. Add a plugin to your pom.xml. If you have a different build system, you can find the appropriate plugin here: https://cyclonedx.org/docs/bom-tools/
+1. Add a plugin to your pom.xml. If you have a different build system, you can find the appropriate plugin here: [https://cyclonedx.org/docs/bom-tools/](https://cyclonedx.org/docs/bom-tools/)
 
    ```xml
    <build>
@@ -69,17 +69,17 @@ By the end of this post, you will clearly understand how to add SBOMs to your so
 
    ```yml
      - name: Run JReleaser
-       uses: jreleaser/release-action@f69e545b05f149483cecb2fb81866247992694b8
+       uses: jreleaser/release-action@ad73772277e63d9f2bbf4f24a7bb1300388334d7 # 2.4.3
        with:
-         version: 1.15.0
+         version: 1.20.0
          arguments: full-release 
        env:
          JRELEASER_GITHUB_TOKEN: ${{ secrets.JRELEASER_GITHUB_TOKEN }}
          [...]
    ```
 
 4. Make a release  :)
-   The final result looks like this on GitHub: https://github.com/chains-project/maven-lockfile/releases/tag/v5.3.5 and like this on Maven Central: https://repo1.maven.org/maven2/io/github/chains-project/maven-lockfile/5.3.5/.
+   The final result looks like this on GitHub: https://github.com/chains-project/maven-lockfile/releases/tag/v5.8.2 and like this on Maven Central: https://repo1.maven.org/maven2/io/github/chains-project/maven-lockfile/5.8.2/.
 
 ## Conclusion
 In conclusion, adding SBOMs to your GitHub and Maven Central releases is a simple and effective way to improve the security and integrity of your software products. Following the steps outlined in this blog post, you can easily generate and add an SBOM to your GitHub and Maven Central release using Maven and JReleaser. With an SBOM, you can identify and remediate vulnerabilities in your software products on time, reducing the risk of security breaches and ensuring the trust of your users. We hope this post has helped guide you through adding SBOMs to your GitHub and Maven Central releases, and we encourage you to continue exploring ways to improve the security and quality of your software products.