Secure Supply Chain docs for layered-zero-trust

Author: gaurav-nelson

content/patterns/layered-zero-trust/_index.adoc

@@ -97,7 +97,7 @@ The pattern consists of the following key components:
 ** Provides a management control plane in multi-cluster scenarios.
 
 * link:https://docs.redhat.com/en/documentation/red_hat_quay/3.15[Red{nbsp}Hat Quay]
-** Enables a private repository for OCI images within our environment.
+** Enables a private repository for OCI images within the environment.
 
 * link:https://docs.redhat.com/en/documentation/red_hat_openshift_container_storage/4.8/html/managing_hybrid_and_multicloud_resources/index[Multicloud Object Gateway]
 ** Provides an object storage service for {ocp}.
@@ -106,7 +106,7 @@ The pattern consists of the following key components:
 ** Provides cryptographic signing and verification of software artifacts and container images.
 
 * link:https://docs.redhat.com/es/documentation/red_hat_trusted_profile_analyzer/2.2[Red{nbsp}Hat Trusted Profile Analyzer (RHTPA)]
-** Provides the storage and management means for _Software Bills of Materials_ (SBOMs), with cross-referencing capabilities between SBOMs and CVEs/Security Advisories.
+** Provides the storage and management means for _Software Bill of Materials_ (SBOMs), with cross-referencing capabilities between SBOMs and CVEs/Security Advisories.
 
 [id="sidecar-pattern"]
 ==== Sidecar pattern
@@ -141,7 +141,7 @@ The following technologies are used in this solution:
 * *Compliance Operator*: Provides ability to scan and remediate cluster hardening based on profiles
 * *QTodo application*: Serves as a sample Quarkus-based application to show zero trust principles.
 * *PostgreSQL database*: Provides the backend database for the demonstration application.
-* *Multicloud Object Gateway*: Lightweight object storage service for {ocp}. Used as storage by Quay.
+* *Multicloud Object Gateway*: Lightweight object storage service for {ocp}. Used by Quay for the storage of binary blobs.
 * *Red{nbsp}Hat Quay*: Private registry for OCI images.
-* *Red{nbsp}Hat Trusted Artifact Signer*: Facilitates signing and verification of binary objects in the cluster.
+* *Red{nbsp}Hat Trusted Artifact Signer*: Facilitates signing and verification of software artifacts.
 * *Red{nbsp}Hat Trusted Profile Analyzer*: Enables SBOM file analysis and vulnerability detection.

content/patterns/layered-zero-trust/lzt-secure-supply-chain.adoc

@@ -13,7 +13,7 @@ include::modules/comm-attributes.adoc[]
 = Use case: Secure supply chain
 
 [role="_abstract"]
-This use case outlines the process of building, signing, and verifying artifacts and images within the Zero Trust Validated Pattern (ZTVP) using the Red{nbsp}Hat Trusted Artifact Signer (RHTAS) and the Red{nbsp}Hat Trusted Profile Analyzer (RHTPA).
+A key objective of ZTVP is the comprehensive security of both the platform and the applications deployed on it. This use case outlines the process of building, signing, and verifying artifacts and images within the Zero Trust Validated Pattern (ZTVP) using the Red{nbsp}Hat Trusted Artifact Signer (RHTAS) and the Red{nbsp}Hat Trusted Profile Analyzer (RHTPA). Through the implementation of this supply chain, we can establish a chain of trust and integrity for applications.
 
 [id="clone-app-source"]
 == Cloning the app source code
@@ -33,7 +33,7 @@ $ git clone https://github.com/validatedpatterns-demos/qtodo.git
 [id="build-app-artifact"]
 == Building the app artifact
 
-The application requires *Java 17+* and *maven 3.8.x+* to compile.
+The application requires *Java 17+* and *Maven 3.8.x+* to compile.
 However, you can use containers and the Makefile that is already present in the repository.
 
 .Procedure
@@ -49,23 +49,23 @@ The artifact is built in the `target/` directory.
 
 .Verification
 
-* List the contents of the `target/` directory to verify that the generated JAR file:
+* List the contents of the `target/` directory to verify the generated JAR file:
 +
 [source,terminal]
 ----
 $ ls -lh target/
 total 46M
--rw-r--r-- 1 user user 46M Nov 19 13:42 qtodo-1.0.0-SNAPSHOT-runner.jar
+-rw-r--r-- 1 user user 46M Nov 19 13:42 qtodo-1.0.0-runner.jar
 ----
 
 [id="build-image"]
 == Building the image
 
-To create an image that has the JAR file that you built, you can use `make` command.
+To create an image that has the JAR file that you built, use the `make` command.
 
 .Procedure
 
-* Run the following command to build the container image:
+* Run the following commands to set details related to the qtodo application and then build the container image:
 +
 [source,terminal]
 ----
@@ -76,7 +76,7 @@ $ make build-image-binary
 
 .Verification
 
-* The resulting image is available in the local image store. You can verify its presence by listing the images.
+* The resulting image is available in the local image store. Verify its presence by listing the images.
 +
 [source,terminal]
 ----
@@ -123,7 +123,7 @@ $ podman push "${IMAGE}"  # --tls-verify=false
 
 To ensure the security and integrity of the qtodo artifact within the supply chain, sign the artifact file (binary) by using *RHTAS*.
 
-RHTAS relies on the `Sigstore` open source project standards. It comprises three core services that work together to provide keyless signing, transparency, and verification:
+RHTAS uses the `Sigstore` open source project standards. It consists of three core services that work together to provide keyless signing, transparency, and verification:
 
 * `Fulcio` (Certificate Authority)
 * `Rekor` (Transparency Log)
@@ -140,11 +140,11 @@ For more information about these products, see the following documentation topic
 [id="download-cosign"]
 === Downloading cosign
 
-Install the cosign binary that is provided by the RHTAS solution, which is accessible within the `cli-server` pod.
+Install the `cosign` binary that RHTAS provides. This binary is accessible within the `cli-server` pod.
 
 .Procedure
 
-. Get the cli-server hostname by using the `oc` client:
+. Obtain the hostname of the cli-server by using the `oc` client  which contains the CLI tools provided by RHTAS:
 +
 [source,terminal]
 ----
@@ -156,7 +156,7 @@ $ export CLI_SERVER_URL="https://$(oc get route -n trusted-artifact-signer -l ap
 Using disparate versions of `cosign` might lead to incompatibility issues with the RHTAS services. To ensure compatibility, always download the `cosign` binary directly from the `cli-server` pod of your specific RHTAS deployment.
 ====
 
-. Set the appropriate operating system and architecture and download the `cosign` binary:
+. Specify the appropriate operating system and architecture and download the `cosign` binary:
 +
 [source,terminal]
 ----
@@ -186,7 +186,7 @@ Configure `cosign` to use the TUF root of your RHTAS instance before signing any
 
 .Procedure
 
-. Get the TUF root:
+. Obtain the URL of the TUF instance:
 +
 [source,terminal]
 ----
@@ -215,9 +215,9 @@ $ cosign initialize \
 ----
 
 [id="oidc-credentials"]
-=== OIDC credentials
+=== OpenID Connect credentials
 
-Signing requires an OIDC identity issuer and the URLs for the Fulcio and Rekor services. This configuration uses *Keycloak*; however, you can substitute this component based on your specific environment.
+Signing requires an OpenID Connect (OIDC) identity issuer and the URLs for the Fulcio and Rekor services. This configuration uses *Keycloak*; however, you can substitute this component based on your specific environment.
 
 The following example illustrates the procedure for obtaining an identification token by using Keycloak.
 
@@ -256,31 +256,36 @@ $ export OIDC_TOKEN="$(curl -sk ${OIDC_TOKEN_URL} \
   --data-urlencode 'scope=openid email profile' \
   | jq -r .access_token)"
 ----
++
+[NOTE]
+====
+OIDC tokens have a limited lifespan and might expire during this procedure. If you encounter authentication errors in subsequent steps, re-run this command to get a fresh token.
+====
 
 [id="create-signature-bundle"]
 === Creating a signature bundle
 
-Run the signing command. This generates a `.bundle` file that has the signature and the transparency log entry.
+Run the signing command. This command generates a `.bundle` file that has the signature and the transparency log entry.
 
 .Procedure
 
-. Get the Fulcio service hostname:
+. Obtain the URL of the Fulcio service:
 +
 [source,terminal]
 ----
 # Get Fulcio service hostname
 $ export FULCIO_URL="https://$(oc get route -n trusted-artifact-signer -l app.kubernetes.io/component=fulcio -o jsonpath='{.items[0].spec.host}')"
 ----
 
-. Get the Rekor service hostname:
+. Obtain the URL Rekor service:
 +
 [source,terminal]
 ----
 # Get Rekor service hostname
 $ export REKOR_URL="https://$(oc get route -n trusted-artifact-signer -l app.kubernetes.io/component=rekor-server -o jsonpath='{.items[0].spec.host}')"
 ----
 
-. Set the path to the artifact:
+. Set the path to the previously created artifact (JAR):
 +
 [source,terminal]
 ----
@@ -302,7 +307,7 @@ $ cosign sign-blob "${ARTIFACT_PATH}" \
 
 .Verification
 
-To verify the signed artifact, you can use the generated bundle and the artifact itself. Ensure `cosign` still points to the RHTAS TUF root.
+To verify the signed artifact, you can use the generated bundle and the artifact itself.
 
 * Verify the artifact by using the following command:
 +
@@ -321,17 +326,17 @@ Beyond command-line verification, you can locate the record by using the Rekor s
 You can get the URL for the Rekor Search UI by using the following command:
 [source,terminal]
 ----
-$ oc get route -n trusted-artifact-signer -l app.kubernetes.io/component=rekor-ui -o jsonpath='{.items[0].spec.host}'
+$ echo https://$(oc get route -n trusted-artifact-signer -l app.kubernetes.io/component=rekor-ui -o jsonpath='{.items[0].spec.host}')
 ----
 
 image::/images/layered-zero-trust/rekor-web-ui.png[Rekor's Search UI]
 
 [id="sign-container-image"]
 == Signing the image
 
-To sign the image, use RHTAS services again. For this step, you must also be logged in to the Quay service, because you write the digital signature to the repository.
+To sign the image, use RHTAS services again. For this step, you must also be logged in to the Quay service as the digital signature is published to the repository.
 
-To reference the image you intend to sign, you must use its digest rather than its tag. You can obtain the digest of the image by using `skopeo` or by checking the Quay repository.
+To reference the image you intend to sign, you must use its digest rather than its tag. Get the digest of the image by using `skopeo` or by checking the Quay repository.
 
 .Procedure
 
@@ -367,7 +372,7 @@ $ cosign sign "${IMAGE_REF}" \
 
 .Verification
 
-To verify the image, you can use `cosign` and check the output to see if it matches your identity and OIDC.
+To verify the image signature, you can use `cosign` and check the output to see if it matches your identity and OIDC issuer.
 
 * Verify the image by using the following command:
 
@@ -411,7 +416,7 @@ $ syft scan registry:"${IMAGE}" -o spdx-json=qtodo-sbom.json
 [id="attach-sbom"]
 == Attaching the SBOM to the image
 
-You must attach the generated SBOM file to the image, which enables verification by third parties if required. For this task, use the `cosign` tool again.
+You must attach the generated SBOM file to the image which enables verification by third parties if required. For this task, use the `cosign` tool again.
 
 Although direct attachment of the SBOM to the image is feasible, the recommended approach involves encapsulating the SBOM within a signed envelope, thereby generating an attestation. This method ensures the integrity of the SBOM, guaranteeing its provenance and confirming that it has not been subjected to unauthorized modifications.
 
@@ -429,32 +434,23 @@ $ cosign attest \
   --type spdxjson \
   --fulcio-url="${FULCIO_URL}" \
   --rekor-url="${REKOR_URL}" \
+  --identity-token "${OIDC_TOKEN}" \
   --oidc-client-id="${RHTAS_CLIENT_ID}" \
-  --oidc-issuer "${OIDC_ISSUER_URL}" \
   --yes \
   "${IMAGE}"
 ----
 
 [id="upload-sbom-rhtpa"]
 == Uploading the SBOM to RHTPA
 
-To analyze the SBOM and detect Common Vulnerabilities and Exposures (CVEs) in the image, use RHTPA.
+To analyze the SBOM and detect Common Vulnerabilities and Exposures (CVEs) in the image, use Red Hat Trusted Profile Analyzer (RHTPA).
 
 The RHTPA system provides an API that enables the direct upload of the SBOM by an HTTP request. To use this API, you need a token authorized by the OIDC.
 
 This following commands illustrates the process for obtaining the token when using Keycloak, which serves as the default OIDC for the Zero Trust Validated Pattern (ZTVP).
 
 .Procedure
 
-. Get the OIDC Issuer URL from Keycloak and set the token URL:
-+
-[source,terminal]
-----
-# Get the OIDC Issuer URL from Keycloak route
-$ export OIDC_ISSUER_URL="https://$(oc get route -n keycloak-system -l app=keycloak -o jsonpath='{.items[0].spec.host}')/realms/ztvp"
-$ export OIDC_TOKEN_URL="${OIDC_ISSUER_URL}/protocol/openid-connect/token"
-----
-
 . Obtain the client secret for the RHTPA OIDC client:
 +
 [source,terminal]
@@ -463,7 +459,7 @@ $ export OIDC_TOKEN_URL="${OIDC_ISSUER_URL}/protocol/openid-connect/token"
 $ export RHTPA_CLIENT_SECRET="$(oc get secret rhtpa-oidc-cli-secret -n trusted-profile-analyzer -o jsonpath='{.data.client-secret}' | base64 -d)"
 ----
 
-. Set the client ID:
+. Set the Client ID associated with RHTPA:
 +
 [source,terminal]
 ----
@@ -484,11 +480,11 @@ $ export RHTPA_TOKEN=$(curl -sSfk -X POST "${OIDC_TOKEN_URL}" \
   -d "client_secret=${RHTPA_CLIENT_SECRET}" | jq -r .access_token)
 ----
 
-. Get the RHTPA API URL:
+. Obtain the RHTPA API URL:
 +
 [source,terminal]
 ----
-# Get the RHTPA API hostname
+# Get the RHTPA API URL
 $ export RHTPA_URL="https://$(oc get route -n trusted-profile-analyzer -l app.kubernetes.io/name=server -o jsonpath='{.items[0].spec.host}')"
 ----
 . Upload the SBOM to RHTPA using the API with the Keycloak token:
@@ -503,7 +499,7 @@ $ curl -sk -X POST \
   "${RHTPA_URL}/api/v2/sbom"
 ----
 
-Upon publication, you can view the SBOM on the RHTPA web UI. The access URL is same as the one used for the API. Similar to the API, the RHTPA web UI uses OIDC for user authentication. In our specific deployment, you can view the RHTPA web UI by logging in with the credentials. Use the following commands to get the username and password:
+Once the SBOM has been published, it can be viewed within the RHTPA web UI. The URL is same as the value obtained previously for the RHTPA API. Similar to the API, the RHTPA web UI uses OIDC for user authentication. In our specific deployment, you can view the RHTPA web UI by logging in with the credentials associated with the user. Use the following commands to obtain the username and password:
 
 [source,terminal]
 ----
@@ -516,12 +512,15 @@ $ oc get secret keycloak-users -n keycloak-system \
   base64 -d
 ----
 
+To review the newly generated SBOM within the web UI, navigate to the "SBOMs" section via the left-hand menu, and select the entry corresponding to the name of the container image from the list of available SBOMs.
+
 image::/images/layered-zero-trust/rhtpa-web-ui.png[RHTPA Web UI]
 
 [id="validate-sbom"]
 == Validating the SBOM
 
-To verify the integrity and provenance of the SBOM file, specifically confirming that its signature originates from a trusted source and was securely generated, use the `ec` tool.
+To verify the integrity and provenance of the SBOM file, specifically confirming that its signature originates from a trusted source and was securely generated, use the `ec` tool. Beyond the verification of attestation and container signatures, Enterprise Contract (`ec`) offers additional capabilities for monitoring supply chain security. Comprehensive details are available within link:https://docs.redhat.com/en/documentation/red_hat_trusted_artifact_signer/1.3/html-single/deployment_guide/index#verifying-signatures-on-container-images-with-conforma-openshift_deploy[Red{nbsp}Hat Trusted Artifact Signer Deployment Guide].
+
 
 You can install the `ec` tool by directly downloading it from the `cli-server` pod.
 
@@ -555,3 +554,8 @@ $ ec validate image \
   --rekor-url "${REKOR_URL}" \
   --show-successes
 ----
+
+[id="conclusion"]
+== Conclusion
+
+This concludes our implementation of a Secure Supply Chain leveraging Red{nbsp}Hat Trusted Artifact Signer (RHTAS) and the Red{nbsp}Hat Trusted Profile Analyzer (RHTPA). We have demonstrated the complete process, which encompasses building an application from source code, generating a container image, cryptographically signing the resulting binaries, and subsequently verifying that these binaries have been signed by an authorized entity. Future work may focus on the automation of this process and its integration into a Continuous Integration/Continuous Delivery (CI/CD) solution.