Add Attestations to build and release workflow (#148)

* Attempt at creating a step to build attestations in Actions

* [docs] Added Attestations page; altered numbering of root-level pages.

* [pr build action] Added sha for attestations action

* Added Attestation generation to Release build

* Added mentions of Attestation generation to readmes

* Added mention of the Attestation stuff to the changelog

* Minor version bump

.github/workflows/dotnet.yml

@@ -12,6 +12,8 @@ on:
 
 permissions:
   contents: read
+  id-token: write
+  attestations: write
 
 jobs:
 
@@ -149,6 +151,11 @@ jobs:
     - name: Build NuGet Package
       run: dotnet pack src/OwaspHeaders.Core.csproj --configuration Release
 
+    - name: Generate Attestations
+      uses: actions/attest-build-provenance@963f8a02f24ac90336362e63ca6730cf69ad102e # v2.1.0
+      with:
+        subject-path: ${{ github.workspace }}/**/*.nupkg
+
     - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
       if: ${{ success() }}
       with:

.github/workflows/release.yml

@@ -14,6 +14,8 @@ on:
 
 permissions:
   contents: read
+  id-token: write
+  attestations: write
 
 jobs:
 
@@ -98,6 +100,11 @@ jobs:
     - name: Build NuGet package
       run: dotnet pack src/OwaspHeaders.Core.csproj --configuration Release
 
+    - name: Generate Attestations
+      uses: actions/attest-build-provenance@963f8a02f24ac90336362e63ca6730cf69ad102e # v2.1.0
+      with:
+        subject-path: ${{ github.workspace }}/**/*.nupkg
+
     - name: Push NuGet package
       run: dotnet nuget  push **\*.nupkg --source 'https://api.nuget.org/v3/index.json' --api-key ${{secrets.NUGET_API_KEY}}
       env:

README-NuGet.md

@@ -52,6 +52,12 @@ The source code for this NuGet package can be found at: [https://github.com/GaPr
 
 The documentation for this NuGet package can be found at: [https://gaprogman.github.io/OwaspHeaders.Core/](https://gaprogman.github.io/OwaspHeaders.Core/).
 
+### Attestations
+
+As of [PR 148](https://github.com/GaProgMan/OwaspHeaders.Core/pull/148), OwaspHeaders.Core uses the GitHub provided process for creating attestations per build. This document talks through how to verify those attestations using the [gh CLI](https://cli.github.com/).
+
+See the [Attestations](https://gaprogman.github.io/OwaspHeaders.Core/attestations) page of the documentation to read about how you can verify the attestations for builds from 9.5.0 onward.
+
 ## Issues and Bugs
 
 Please raise any issues and bugs at the above mentioned source code repo.

README.md

@@ -22,6 +22,12 @@ That's it.
 
 The latest documentation for OwaspHeaders.Core can be found at [https://gaprogman.github.io/OwaspHeaders.Core/](https://gaprogman.github.io/OwaspHeaders.Core/).
 
+### Attestations
+
+As of [PR 148](https://github.com/GaProgMan/OwaspHeaders.Core/pull/148), OwaspHeaders.Core uses the GitHub provided process for creating attestations per build. This document talks through how to verify those attestations using the [gh CLI](https://cli.github.com/).
+
+See the [Attestations](https://gaprogman.github.io/OwaspHeaders.Core/attestations) page of the documentation to read about how you can verify the attestations for builds from 9.5.0 onward.
+
 ## Pull Requests
 
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://github.com/GaProgMan/OwaspHeaders.Core/pulls)

changelog.md

@@ -22,11 +22,15 @@ This version dropped support for .NET 6 and .NET 7, as they are no longer suppor
 
 All projects in the [GitHub repo](https://github.com/GaProgMan/OwaspHeaders.Core) now build and run with either .NET 8 or .NET 9, whichever is present (deferring to the highest version number if both are present). As of November 19th, 2024 there are no new features in Version 9, so if you still need to use the NuGet package with .NET 6 or 7 please use Version 8 of the package.
 
+#### Version 9.5.x
+
+This version saw the addition of attestation generation on both a per PR-build and Release basis. See the [Attestations](https://gaprogman.github.io/OwaspHeaders.Core/attestations) page of the documentation to read about how you can verify the attestations per build or release.
+
 #### Version 9.2.x
 
 A number of small optimisations for generating HTTP header values have been made. There are also new Guard clauses in place to protect from a number of null or null/whitespace issues. All using statements have been cleaned up, with a large number placed in relevant global usings files.
 
-**BREAKING CHANGE**: Removal of the X-Powered-By header has been completely removed in this version. The reason for this is that the X-Powered-By header is included by the reverse proxy, which ASP .NET Core has no control over. See the section in the Readme labelled "Server Header: A Warning" for details on how to remove this header.   
+**BREAKING CHANGE**: Removal of the X-Powered-By header has been completely removed in this version. The reason for this is that the X-Powered-By header is included by the reverse proxy, which ASP .NET Core has no control over. See the section in the Readme labelled "Server Header: A Warning" for details on how to remove this header.
 
 #### Version 9.1.x
 

docs/Code-of-Conduct.md

@@ -1,7 +1,7 @@
 ---
 title: Code of Conduct
 layout: page
-nav_order: 4
+nav_order: 5
 ---
 
 # Contributor Covenant Code of Conduct

docs/Contributing.md

@@ -1,7 +1,7 @@
 ---
 title: Contributing
 layout: page
-nav_order: 3
+nav_order: 4
 ---
 
 # Contributing to OwaspHeaders.Core

docs/Minimal-Code-Sample.md

@@ -1,7 +1,7 @@
 ---
 title: Minimal Code Sample
 layout: page
-nav_order: 5
+nav_order: 10
 ---
 
 # Tips For Creating A Minimal Code Sample

docs/attestations.md

@@ -0,0 +1,83 @@
+---
+title: Attestations
+nav_order: 2
+layout: page
+---
+
+As of [PR 148](https://github.com/GaProgMan/OwaspHeaders.Core/pull/148), OwaspHeaders.Core uses the GitHub provided process for creating attestations per build. This document talks through how to verify those attestations using the [gh CLI](https://cli.github.com/).
+
+## PR Build
+
+All PRs are built using the [dotnet.yml](https://github.com/GaProgMan/OwaspHeaders.Core/blob/main/.github/workflows/dotnet.yml) file found in the .github/Workflows directory in the GitHub repo. Attestations for these builds are created in the step labelled "Generate Attestations":
+
+```yml
+# The following yml is correct as of Dec 23rd, 2024
+# For the latest version, please see:
+# https://github.com/GaProgMan/OwaspHeaders.Core/blob/main/.github/workflows/dotnet.yml
+- name: Generate Attestations
+    uses: actions/attest-build-provenance@963f8a02f24ac90336362e63ca6730cf69ad102e # v2.1.0
+    with:
+    subject-path: ${{ github.workspace }}/**/*.nupkg
+```
+
+This step will provide an attestation for the commit which caused the PR build to run.
+
+### Slightly Less Manual Verification
+
+When the build workflow completes, there will be a section in the job summary called "Create the NuGet package for PR-level user testing summary" (see: [this link](https://github.com/GaProgMan/OwaspHeaders.Core/actions/runs/12473647282#summary-34814538093) or the following screenshot for an example)
+
+![](./assets/images/attestations/created.jpg)
+
+Clicking the link under "Attestation created" will take you to the attestation for the particular build of OwaspHeaders.Core.
+
+In the above screenshot, the Attestation link is [https://github.com/GaProgMan/OwaspHeaders.Core/attestations/4097094](https://github.com/GaProgMan/OwaspHeaders.Core/attestations/4097094).
+
+### Manual Verification
+
+In order to manually verify the nupkg file, you will need to download the generated artifact for a given workflow run and follow the steps below.
+
+- Open a workflow run
+  - For example: https://github.com/GaProgMan/OwaspHeaders.Core/actions/runs/12473647282
+- Scroll to the bottom of the workflow run and download the generated artifact
+  - The file will be called "OwaspHeaders.Core"
+  - See the following screenshot:
+
+![](./assets/images/attestations/artifacts.jpg)
+
+- Extract the zip file
+  - You can using your favourite unarchiver
+  - Or you can open the zip file and drag the nupkg file out
+- Open a terminal where you have extracted the nupkg file
+- Run `gh attestation verify --owner GaProgMan OwaspHeaders.Core.x.y.z.nupkg`
+  - Replacing `x.y.z` with the version number of the nupkg file
+
+You should receive output which matches the following:
+
+```bash
+Loaded digest sha256:5e657fed02f84c8072a33a8791e01d6bd45c67863f83ec8542154af08171ed04 for file://OwaspHeaders.Core.9.4.3.nupkg
+Loaded 1 attestation from GitHub API
+
+The following policy criteria will be enforced:
+- OIDC Issuer must match:................... https://token.actions.githubusercontent.com
+- Source Repository Owner URI must match:... https://github.com/GaProgMan
+- Predicate type must match:................ https://slsa.dev/provenance/v1
+- Subject Alternative Name must match regex: (?i)^https://github.com/GaProgMan/
+
+✓ Verification succeeded!
+
+sha256:5e657fed02f84c8072a33a8791e01d6bd45c67863f83ec8542154af08171ed04 was attested by:
+REPO                         PREDICATE_TYPE                  WORKFLOW                                        
+GaProgMan/OwaspHeaders.Core  https://slsa.dev/provenance/v1  .github/workflows/dotnet.yml@refs/pull/148/merge
+```
+
+> [!NOTE] NOTE
+> The above output is specific to the version of OwaspHeaders.Core built using the first workflow run for [PR 148](https://github.com/GaProgMan/OwaspHeaders.Core/pull/148). The output you receive will differ slightly.
+
+## Releases
+
+TBC
+
+## Resources
+
+- [Artifact Attestations is generally available](https://github.blog/changelog/2024-06-25-artifact-attestations-is-generally-available/)
+- [gh CLI](https://cli.github.com/)

docs/changelog.md

@@ -1,7 +1,7 @@
 ---
 title: Changelog
 layout: page
-nav_order: 10
+nav_order: 7
 ---
 
 # Changelog
@@ -28,6 +28,10 @@ This version dropped support for .NET 6 and .NET 7, as they are no longer suppor
 
 All projects in the [GitHub repo](https://github.com/GaProgMan/OwaspHeaders.Core) now build and run with either .NET 8 or .NET 9, whichever is present (deferring to the highest version number if both are present). As of November 19th, 2024 there are no new features in Version 9, so if you still need to use the NuGet package with .NET 6 or 7 please use Version 8 of the package.
 
+#### Version 9.5.x
+
+This version saw the addition of attestation generation on both a per PR-build and Release basis. See the [Attestations](https://gaprogman.github.io/OwaspHeaders.Core/attestations) page of the documentation to read about how you can verify the attestations per build or release.
+
 #### Version 9.2.x
 
 A number of small optimisations for generating HTTP header values have been made. There are also new Guard clauses in place to protect from a number of null or null/whitespace issues. All using statements have been cleaned up, with a large number placed in relevant global usings files.

docs/configuration/index.md

@@ -1,6 +1,6 @@
 ---
 title: Configuration
-nav_order: 2
+nav_order: 3
 layout: page
 ---
 

src/OwaspHeaders.Core.csproj

@@ -8,7 +8,7 @@
 
     <!-- NuGet metadata -->
     <PackageId>OwaspHeaders.Core</PackageId>
-    <Version>9.4.3</Version>
+    <Version>9.5.0</Version>
     <Authors>Jamie Taylor</Authors>
     <Company>RJJ Software Ltd</Company>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>