From 1a39d3f736fc017d18c60ffdefa9b3d7411a75fd Mon Sep 17 00:00:00 2001
From: Thibault VINCENT <thibault.vincent@enix.fr>
Date: Sat, 2 May 2026 13:48:17 +0200
Subject: [PATCH] docs(chart): link to the hardening guide

---
 CLAUDE.md              |  2 +-
 CONTRIBUTING.md        |  4 ++--
 chart/README.md        | 25 ++++++++++++++-----------
 chart/README.md.gotmpl | 26 +++++++++++++-------------
 4 files changed, 30 insertions(+), 27 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index dfd8eb7..67acc0f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -320,7 +320,7 @@ Registry credentials live on the `release` Environment:
   for images and ghcr.io for the chart, or vice-versa).
 
 Verification commands for downstream consumers are documented in the
-[README](./README.md#-verifying-authenticity).
+[hardening guide](./docs/hardening.md).
 
 ## Renovate
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f45a000..329cc31 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -575,7 +575,7 @@ When the release PR is merged, three things happen automatically:
    the provenance file, and pointers to all signed artifacts
 
 Verification commands for downstream consumers are documented in the
-[main README](./README.md#-verifying-authenticity).
+[hardening guide](./docs/hardening.md).
 
 If you push a tag manually (e.g. to test the Release workflow without
 going through release-please), Chart.yaml's `version`/`appVersion` and
@@ -781,7 +781,7 @@ into implementation.
 - **For the supply-chain story**: the [release workflow](./.github/workflows/release.yaml)
   documents how images are signed (cosign keyless), how SBOMs are attached,
   and how SLSA Level 3 provenance is generated. Verification commands are
-  in [README.md](./README.md#-verifying-authenticity).
+  in [docs/hardening.md](./docs/hardening.md).
 - **For AI-assisted development**: the repository has a [`CLAUDE.md`](./CLAUDE.md)
   giving Claude / Cursor / Aider / similar tools the architectural context
   in a denser, agent-tuned format. Keep it up to date alongside this file
diff --git a/chart/README.md b/chart/README.md
index b414f26..7d0e2fd 100644
--- a/chart/README.md
+++ b/chart/README.md
@@ -109,19 +109,22 @@ helm install x509-certificate-exporter \
   oci://quay.io/enix/charts/x509-certificate-exporter \
   --values x509-certificate-exporter.values.yaml
 
-# Pin to a specific version
-helm install x509-certificate-exporter \
-  oci://quay.io/enix/charts/x509-certificate-exporter \
-  --version 4.1.0 \
-  --values x509-certificate-exporter.values.yaml
+### 🛡️ Supply-chain verification
 
-# Upgrade
-helm upgrade x509-certificate-exporter \
-  oci://quay.io/enix/charts/x509-certificate-exporter \
-  --values x509-certificate-exporter.values.yaml
-```
+Curious how the chart and images are signed, or want to enforce that only
+verified releases run in your cluster? The [hardening guide][hardening]
+covers the territory:
+
+- Immutable image-digest pinning via the chart's `image.digest` value
+- cosign keyless signature verification (sigstore, Fulcio, Rekor)
+- CycloneDX SBOM attestations on container images
+- Strict certificate-identity pinning to the release workflow at a
+  given tag
+- Wiring cosign verification into CI pipelines and cluster admission
+  (sigstore/policy-controller, Kyverno)
+
+[hardening]: https://github.com/enix/x509-certificate-exporter/blob/main/docs/hardening.md
 
-## 📜 Configuring the chart
 
 ### Watching Secrets
 
diff --git a/chart/README.md.gotmpl b/chart/README.md.gotmpl
index 2bbc123..9d0d3df 100644
--- a/chart/README.md.gotmpl
+++ b/chart/README.md.gotmpl
@@ -108,22 +108,22 @@ override into your `values.yaml` and re-run the same command.
 
 ```sh
 # Initial install
-helm install x509-certificate-exporter \
-  oci://quay.io/enix/charts/x509-certificate-exporter \
-  --values x509-certificate-exporter.values.yaml
 
-# Pin to a specific version
-helm install x509-certificate-exporter \
-  oci://quay.io/enix/charts/x509-certificate-exporter \
-  --version 4.1.0 \
-  --values x509-certificate-exporter.values.yaml
+### 🛡️ Supply-chain verification
 
-# Upgrade
-helm upgrade x509-certificate-exporter \
-  oci://quay.io/enix/charts/x509-certificate-exporter \
-  --values x509-certificate-exporter.values.yaml
-```
+Curious how the chart and images are signed, or want to enforce that only
+verified releases run in your cluster? The [hardening guide][hardening]
+covers the territory:
 
+- Immutable image-digest pinning via the chart's `image.digest` value
+- cosign keyless signature verification (sigstore, Fulcio, Rekor)
+- CycloneDX SBOM attestations on container images
+- Strict certificate-identity pinning to the release workflow at a
+  given tag
+- Wiring cosign verification into CI pipelines and cluster admission
+  (sigstore/policy-controller, Kyverno)
+
+[hardening]: https://github.com/enix/x509-certificate-exporter/blob/main/docs/hardening.md
 
 
 ## 📜 Configuring the chart