merge pull request #87 from zackbradys/main

updated `validating images` docs and upgraded to `docusaurus v3`
rancherfederal · Mar 6, 2024 · 11af74d · 11af74d
2 parents 3f47ac3 + 5ba462c
commit 11af74d
Show file tree

Hide file tree

Showing 19 changed files with 11,578 additions and 8,416 deletions.
diff --git a/docs/airgapped-docs/introduction.md b/docs/airgapped-docs/introduction.md
@@ -8,7 +8,7 @@ As our product is still at Initial Operation Capability (IOC), there are some ex
 
 - Installation and packaging is still in progress and improving.
 
-If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-charts/issues/).
+If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-charts/issues).
 
 ## What is this?
 

diff --git a/docs/intro.md b/docs/intro.md
@@ -8,10 +8,10 @@ Carbide is Rancher Government's hardened distribution of the SUSE Rancher produc
 
 Rancher Carbide is tactically built with the following enhancements over the community version:
 
-- [SLSA 3 compliant](https://slsa.dev/) secure build process hosted on Azure Government
+- [SLSA 3 compliant](https://slsa.dev) secure build process hosted on Azure Government
 - Digitally Signed Container Images. Every container hosted in our registry has been digitally [signed](https://rancherfederal.github.io/carbide-docs/docs/registry-docs/validating-images) by Rancher Government Solutions. Verifiable trust is baked into everything we do.
 - [Software Bill of Materials](https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=&cad=rja&uact=8&ved=2ahUKEwiW0KSchfL5AhWPkIkEHf6QASQQFnoECAkQAQ&url=https%3A%2F%2Fwww.cisa.gov%2Fsbom&usg=AOvVaw2_RntIRhhNuizqtvNQxmyP) (SBOM) support in every container image
-- Container [Attestations](https://www.testifysec.com/blog/what-is-a-supply-chain-attestation/)
+- [Container Attestations](https://www.testifysec.com/blog/what-is-a-supply-chain-attestation)
 - Container Vulnerability Scans
 - Authenticated Registry hosted on Azure Government Container Registry
 - STIGATRON: Day 2 security operator powered by Rancher Government's DISA STIGs

diff --git a/docs/registry-docs/enforcement.md b/docs/registry-docs/enforcement.md
@@ -65,7 +65,7 @@ hauler store save --filename kubewarden-policy.tar.zst
 
 ### Loading Policy Artifact to a Registry (Airgaped Environments)
 
-To move the Policy Artifact into your registry, use the following script and the resulting TAR from the [Saving Policy](enforcement.md#saving-the-policy-artifact).
+Use the below script, substituting your registry, to load the policy artifact:
 
 ```bash
 # load the content from the tarball to the hauler store

diff --git a/docs/registry-docs/introduction.md b/docs/registry-docs/introduction.md
@@ -9,7 +9,7 @@ As our product is still in the IOC phase, there are some expectations to level-s
 
 **DISCLAIMER**:  The Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used as the primary registry for running Kubernetes clusters. It is only intended as the acquisition point to obtain the Carbide secured images. Customers should seed their own private OCI registries, and use that registry for their Kubernetes clusters.
 
-If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-docs/issues/).
+If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-docs/issues).
 
 ## What is this?
 Here at Rancher Government Solutions, we take the security of our products seriously.  Products like `rke2` are tailor built to address the "secure by default" needs of the federal government, while still maintaining the same ease of deployments that our users have come to love from Rancher products.

diff --git a/docs/registry-docs/prereqs.md b/docs/registry-docs/prereqs.md
@@ -17,7 +17,7 @@ The Carbide Secured Registry (rgcrprod.azurecr.us) is _not_ intended to be used
 curl -sfL https://get.hauler.dev | bash
 ```
 
-**Supply Chain Tool: [cosign](https://docs.sigstore.dev/)**
+**Supply Chain Tool: [cosign](https://docs.sigstore.dev)**
 
 ```bash
 # example installation steps
@@ -28,7 +28,7 @@ sudo mv cosign-linux-amd64 /usr/local/bin/cosign
 sudo chmod 755 /usr/local/bin/cosign
 ```
 
-**Container Tool: [helm](https://helm.sh/docs/)**
+**Container Tool: [helm](https://helm.sh/docs)**
 
 ```bash
 # example installation steps

diff --git a/docs/registry-docs/rancher-config.md b/docs/registry-docs/rancher-config.md
@@ -118,7 +118,7 @@ configs:
 
 ### Usage with `Rancher`
 
-Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.5/en/installation/install-rancher-on-k8s/), adding in the following steps to use our [Carbide Helm Chart](https://github.com/rancherfederal/carbide-charts) and the `helm install` command.
+Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.5/en/installation/install-rancher-on-k8s), adding in the following steps to use our [Carbide Helm Chart](https://github.com/rancherfederal/carbide-charts) and the `helm install` command.
 
 When installing Rancher, to utilize the private registry, you'll need to set the following values in your Helm values:
 

diff --git a/docs/registry-docs/uninstall-rancher.md b/docs/registry-docs/uninstall-rancher.md
@@ -62,7 +62,7 @@ See the [RKE2/K3s Uninstall](uninstall-kubernetes.md) documentation.
 
 ### Reverting `Rancher` Chart
 
-Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.7/en/installation/install-rancher-on-k8s/), you can revert to using DockerHub images by removing values from the Helm upgrade command.
+Follow Rancher's [Installation Guide](https://rancher.com/docs/rancher/v2.7/en/installation/install-rancher-on-k8s), you can revert to using DockerHub images by removing values from the Helm upgrade command.
 
 ```bash
 helm upgrade rancher rancher-latest/rancher \

diff --git a/docs/registry-docs/validating-images.md b/docs/registry-docs/validating-images.md
@@ -19,37 +19,114 @@ tCAZva7CLlk/6gxvCM0QkIKznfaGTRMMYTaHMdQSau6yulDLlpokA++i8Q==
 
 ## Secure Supply Chain
 
-## Checking the Digital Signature In A Registry
+Before pulling images or even after images have been pushed to a registry, you should always verify those images against the carbide public key. Below are the instructions for using `cosign` directly from a registry.
 
-Before pulling images, or after images have been pushed to a registry, you should verify those images against the carbide public key. These instructions are for verifying images directly from a registry.
+**NOTE:** You'll need to substitute `rgcrprod.azurecr.us` with your own registry domain, if verifying images in your own registry.
 
-**NOTE:** You'll need to substitute `rgcrprod.azurecr.us` with your own registry domain if verifying in your own registry.
+<details open>
+<summary><b>Carbide Images v2</b> (Starting 03/2024)</summary>
+
+In Carbide Images v2 (or Cosign v2), the attachment of supply chain artifacts to the top layer of an image has been deprecated. In order for us to maintain interoperability, we have migrated our images and supply chain artifacts to be attached at the individual layer for a specific platform or architecture of an image.
+
+If you would like to see more information, please see the noticed posted [here](https://github.com/sigstore/cosign/blob/main/specs/SBOM_SPEC.md)!
+
+## Display Supply Chain Artifacts
+
+```bash
+# display supply chain related artifacts for an image
+cosign tree rgcrprod.azurecr.us/carbide/carbide-docs:0.1.4
+📦 Supply Chain Security Related artifacts for an image: rgcrprod.azurecr.us/carbide/carbide-docs:0.1.4
+└── 🔐 Signatures for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-9f4251c8cb5161b7a1670788d4e716e735779804933e4db7698a625a2c762a44.sig
+   └── 🍒 sha256:9e1b59dc650801d4d088c7b816a34f2fb9d8e53a040615750bc45d9202b522b0
+```
+
+```bash
+# display supply chain related artifacts for an image
+# example image digest for carbide-docs:0.1.4 for linux/amd64
+cosign tree rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91
+📦 Supply Chain Security Related artifacts for an image: rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91
+└── 💾 Attestations for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91.att
+   ├── 🍒 sha256:dfa305431fecc7148b2975285295701a4e7e2f314bda41efa1fe4fb31758dc68
+   └── 🍒 sha256:133e5c020fe7fd20ae4453a9193a3b2a5e36a0447aa9d322ba83494bfde912d4
+└── 🔐 Signatures for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91.sig
+   └── 🍒 sha256:f8cf6aea22f450991fc1800bc0b1440377a40833a94ff51c850210218fd5ad4d
+```
+
+### Verifying the Digital Signature
 
 ```bash
 # verify the image's attestation by validating the supplied signature
-cosign verify --key carbide-key.pub rgcrprod.azurecr.us/rancher/rancher:v2.8.2
+cosign verify --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs:0.1.4 | jq
+```
+
+### Viewing the Software Bill of Materials
+
+```bash
+# verify the image's sbom attestation by validating the supplied signature
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91 --type spdxjson | jq
+
+# view the image's sbom
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91 --type spdxjson | jq -r '.payload' | base64 -d | jq
 ```
 
-### Software Bill of Materials
+### Viewing the Vulnerability Scan Results
+
+```bash
+# verify the image's vulnerability attestation by validating the supplied signature
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91 --type vuln | jq
+
+# view the image's vulnerability scan results
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs@sha256:9cfda4875822b37f1e899c962e9bae5bb709235a1794834a839eaa74f429eb91 --type vuln | jq -r '.payload' | base64 -d | jq
+```
+
+</details>
+
+<details>
+<summary><b>Carbide v1</b> (Before 03/2024)</summary>
+
+## Display Supply Chain Artifacts
+
+```bash
+# display supply chain related artifacts for an image
+cosign tree rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3
+📦 Supply Chain Security Related artifacts for an image: rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3
+└── 💾 Attestations for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-4d8b3e7e6e1a7640ca5f4ea833a5aef7a6f031947093e3e7625c8c949c1c8839.att
+   └── 🍒 sha256:8890d36772569483c9295be31a779770af0a61b51c6ba83cecc699fc724b9fd7
+└── 🔐 Signatures for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-4d8b3e7e6e1a7640ca5f4ea833a5aef7a6f031947093e3e7625c8c949c1c8839.sig
+   └── 🍒 sha256:a28126ae0a4bb23f71787e912125c25232677f6948812d937fd8feb9fe03ac6f
+└── 📦 SBOMs for an image tag: rgcrprod.azurecr.us/carbide/carbide-docs:sha256-4d8b3e7e6e1a7640ca5f4ea833a5aef7a6f031947093e3e7625c8c949c1c8839.sbom
+   └── 🍒 sha256:970fc626b7075bd4822083cebc26d2e7cfcc1d5f1bfbcf9c3d0b3543a769be99
+```
+
+### Verifying the Digital Signature
+
+```bash
+# verify the image's attestation by validating the supplied signature
+cosign verify --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3
+```
+
+### Viewing the Software Bill of Materials
 
 ```bash
 # verify the image's SBOM attestation by validating the supplied signature
-cosign verify --key carbide-key.pub rgcrprod.azurecr.us/rancher/rancher:v2.8.2 --attachment sbom
+cosign verify --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3 --attachment sbom
 
 # view the image's SBOM
-cosign download sbom rgcrprod.azurecr.us/rancher/rancher:v2.8.2
+cosign download sbom rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3
 ```
 
-### Vulnerability Scan Results
+### Viewing the Vulnerability Scan Results
 
 ```bash
 # verify the image's SBOM attestation by validating the supplied signature
-cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/rancher/rancher:v2.8.2 --type vuln > /dev/null
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3 --type vuln | jq
 
 # view the image's vulnerability scan results
-cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/rancher/rancher:v2.8.2 --type vuln | jq -r '.payload' | base64 -d | jq
+cosign verify-attestation --key carbide-key.pub rgcrprod.azurecr.us/carbide/carbide-docs:0.1.3 --type vuln | jq -r '.payload' | base64 -d | jq
 ```
 
+</details>
+
 ### Resources
 
-For more information on `cosign`, check out [Chainguard Academy](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-verify-file-signatures-with-cosign/).
+For more information on `cosign`, check out the [Chainguard Academy](https://edu.chainguard.dev/open-source/sigstore/cosign/how-to-verify-file-signatures-with-cosign).
diff --git a/docs/stigatron-docs/introduction.md b/docs/stigatron-docs/introduction.md
@@ -8,7 +8,7 @@ As our product is still at Initial Operation Capability (IOC), there are some ex
 
 - Installation and packaging is still in progress and improving.
 
-If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-charts/issues/).
+If you see issues and areas for improvement, please submit Github issues [here](https://github.com/rancherfederal/carbide-charts/issues).
 
 ## What is this?
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -1,8 +1,8 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+const lightCodeTheme = require('prism-react-renderer').themes.github;
+const darkCodeTheme = require('prism-react-renderer').themes.dracula;
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -28,12 +28,13 @@ const config = {
   },
 
   plugins: [
-    [
-      require.resolve("@cmfcmf/docusaurus-search-local"),
+    [ require.resolve('docusaurus-lunr-search'),
       {
-        // Options here
-      },
-    ],
+        languages: ['en'],
+        indexBaseUrl: true,
+        highlightResult: true
+      }
+    ]
   ],
 
   presets: [