Merge pull request #70231 from gtrivedi88/HACDOCS-713

HACDOCS-698: Updated the content for the Enhanced PipelineRun details view in the Web Console

_topic_maps/_topic_map.yml

@@ -102,6 +102,8 @@ Distros: openshift-pipelines
 Topics:
 - Name: Using Tekton Chains for OpenShift Pipelines supply chain security
   File: using-tekton-chains-for-openshift-pipelines-supply-chain-security
+- Name: Setting up Openshift Pipelines in the web console to view Software Supply Chain Security elements
+  File: setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements
 - Name: Configuring the security context for pods
   File: configuring-security-context-for-pods
 - Name: Securing webhooks with event listeners

modules/op-setting-up-openshift-pipelines-to-download-or-view-sboms.adoc

@@ -0,0 +1,185 @@
+// This module is included in the following assemblies:
+// * secure/setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="op-setting-up-openshift-pipelines-to-download-or-view-sboms_{context}"]
+= Setting up {pipelines-shortname} to download or view SBOMs
+
+The `PipelineRun` details page provides an option to download or view Software Bill of Materials (SBOMs), enhancing transparency and control within your supply chain. SBOMs lists all the software libraries that a component uses. Those libraries can enable specific functionality or facilitate development.
+
+You can use an SBOM to better understand the composition of your software, identify vulnerabilities, and assess the potential impact of any security issues that might arise.
+
+.Options to download or view SBOMs
+image::sbom.png[]
+
+.Prerequisites
+
+* You have link:https://docs.openshift.com/container-platform/4.14/web_console/web-console.html#web-console[logged in to the web console].
+
+* You have the appropriate link:https://docs.openshift.com/container-platform/4.14/authentication/using-rbac.html#default-roles_using-rbac[roles and permissions] in a project to create applications and other workloads in OpenShift Container Platform.
+
+.Procedure
+
+. In the *Developer* or *Administrator* perspective, switch to the relevant project where you want a visual representation of SBOMs.
+
+. Add a task in the following format to view or download the SBOM information:
+
++
+.Example SBOM task
+
++
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: sbom-task # <1>
+  annotations:
+    task.output.location: results  # <2>
+    task.results.format: application/text
+    task.results.key: LINK_TO_SBOM  # <3>
+    task.results.type: external-link  # <4>
+spec:
+  results:
+    - description: Contains the SBOM link  # <5>
+      name: LINK_TO_SBOM
+  steps:
+    - name: print-sbom-results
+      image: quay.io/image  # <6>
+      script: | # <7>
+        #!/bin/sh
+        syft version
+        syft quay.io/<username>/quarkus-demo:v2 --output cyclonedx-json=sbom-image.json
+        echo 'BEGIN SBOM'
+        cat sbom-image.json
+        echo 'END SBOM'
+        echo 'quay.io/user/workloads/<namespace>/node-express/node-express:build-8e536-1692702836' | tee $(results.LINK_TO_SBOM.path) # <8>
+----
+<1> The name of your task.
+<2> The location for storing the task outputs.
+<3> The SBOM task result name. Do not change the name of the SBOM result task.
+<4> (Optional) Set to open the SBOM in a new tab.
+<5> The description of the result.
+<6> The image that generates the SBOM.
+<7> The script that generates the SBOM image.
+<8> The SBOM image along with the path name.
+
+. Update the Pipeline to reference the newly created SBOM task.
+
++
+[source,yaml]
+----
+...
+spec:
+  tasks:
+    - name: sbom-task  
+      taskRef: 
+        name: sbom-task # <1>
+  results:
+    - name: IMAGE_URL  # <2>
+      description: url
+      value: <oci_image_registry_url> # <3>
+----
+<1> The same name as created in Step 2.
+<2> The name of the result.
+<3> The OCI image repository URL which contains the `.sbom` images.
+
+. Rerun the affected OpenShift Pipeline.
+
+
+== Viewing an SBOM in the web UI
+
+.Prerequisites
+
+* You have set up {pipelines-shortname} to download or view SBOMs.
+
+.Procedure
+
+. Navigate to the Activity -> PipelineRuns tab.
+
+. For the project whose SBOM you want to view, select its most recent pipeline run.
+
+. On the `PipelineRun` details page, select *View SBOM*.
+
+.. You can use your web browser to immediately search the SBOM for terms that indicate vulnerabilities in your software supply chain. For example, try searching for `log4j`.
+
+.. You can select *Download* to download the SBOM, or *Expand* to view it full-screen.
+
+== Downloading an SBOM in the CLI
+
+.Prerequisites
+
+* You have installed the link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/how-to-guides/Secure-your-supply-chain/proc_inspect_sbom/[Cosign] CLI tool.
+
+* You have set up {pipelines-shortname} to download or view SBOMs.
+
+.Procedure
+
+. Open terminal, log in to *Developer* or *Administrator* perspective, and then switch to the relevant project.
+
+. From the OpenShift web console, copy the `download sbom` command and run it on your terminal.
++
+.Example cosign command
++
+[source,terminal]
+----
+$ cosign download sbom quay.io/<workspace>/user-workload@sha256
+----
+
+.. (Optional) To view the full SBOM in a searchable format, run the following command to redirect the output:
++
+.Example cosign command
++
+[source,terminal]
+----
+$ cosign download sbom quay.io/<workspace>/user-workload@sha256 > sbom.txt
+----
+
+== Reading the SBOM
+
+In the SBOM, as the following sample excerpt shows, you can see four characteristics of each library that a project uses:
+
+* Its author or publisher
+
+* Its name
+
+* Its version
+
+* Its licenses
+
+This information helps you verify that individual libraries are safely-sourced, updated, and compliant.
+
+.Example SBOM
+
+[source,terminal]
+----
+{
+    "bomFormat": "CycloneDX",
+    "specVersion": "1.4",
+    "serialNumber": "urn:uuid:89146fc4-342f-496b-9cc9-07a6a1554220",
+    "version": 1,
+    "metadata": {
+        ...
+    },
+    "components": [
+        {
+            "bom-ref": "pkg:pypi/flask@2.1.0?package-id=d6ad7ed5aac04a8",
+            "type": "library",
+            "author": "Armin Ronacher <armin.ronacher@active-4.com>",
+            "name": "Flask",
+            "version": "2.1.0",
+            "licenses": [
+                {
+                    "license": {
+                        "id": "BSD-3-Clause"
+                    }
+                }
+            ],
+            "cpe": "cpe:2.3:a:armin-ronacher:python-Flask:2.1.0:*:*:*:*:*:*:*",
+            "purl": "pkg:pypi/Flask@2.1.0",
+            "properties": [
+                {
+                    "name": "syft:package:foundBy",
+                    "value": "python-package-cataloger"
+                    ...
+----

modules/op-setting-up-openshift-pipelines-to-view-project-vulnerabilities.adoc

@@ -0,0 +1,137 @@
+// This module is included in the following assemblies:
+// * secure/setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="op-setting-up-openshift-pipelines-to-view-project-vulnerabilities_{context}"]
+= Setting up {pipelines-shortname} to view project vulnerabilities 
+
+The PipelineRun details page provides a visual representation of identified vulnerabilities,  categorized by the severity (critical, high, medium, and low). This streamlined view facilitates prioritization and remediation efforts.
+
+.Viewing vulnerabilities on the `PipelineRun` details page
+image::vulnerabilities_details.png[]
+
+You can also review the vulnerabilities in the *Vulnerabilities* column in the pipeline run list view page.
+
+.Viewing vulnerabilities on the `PipelineRun` list view
+image::vulnerabilities_list.png[]
+
+.Prerequisites
+
+* You have link:https://docs.openshift.com/container-platform/4.14/web_console/web-console.html#web-console[logged in to the web console].
+
+* You have the appropriate link:https://docs.openshift.com/container-platform/4.14/authentication/using-rbac.html#default-roles_using-rbac[roles and permissions] in a project to create applications and other workloads in OpenShift Container Platform.
+
+* You have an existing vulnerability scan task.
+
+.Procedures
+
+. In the *Developer* or *Administrator* perspective, switch to the relevant project where you want a visual representation of vulnerabilities.
+
+. Update your existing vulnerability scan task to ensure that it stores the output in the .json file and then extracts the vulnerability summary in the following format:
+
++
+[source,yaml]
+----
+# The format to extract vulnerability summary (adjust the jq command for different JSON structures).
+jq -rce \ 
+    '{vulnerabilities:{
+      critical: (.result.summary.CRITICAL),
+      high: (.result.summary.IMPORTANT),
+      medium: (.result.summary.MODERATE),
+      low: (.result.summary.LOW)
+      }}' scan_output.json | tee $(results.SCAN_OUTPUT.path)
+
+----
++
+[NOTE]
+====
+You might need to adjust the link:https://jqlang.github.io/jq/download/[jq] command for different JSON structures.
+====
+
+.. (Optional) If you do not have a vulnerability scan task, create one in the following format:
++
+*Example vulnerability scan task using Roxctl*
++
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: vulnerability-scan  # <1>
+  annotations:
+    task.output.location: results  # <2>
+    task.results.format: application/json
+    task.results.key: SCAN_OUTPUT  # <3>
+spec:
+  results:
+    - description: CVE result format  # <4>
+      name: SCAN_OUTPUT
+      type: string
+  steps:
+    - name: roxctl  # <5>
+      image: quay.io/roxctl-tool-image  # <6>
+      env:
+        - name: ENV_VAR_NAME_1  # <7>
+          valueFrom:
+            secretKeyRef:
+              key: secret_key_1            
+              name: secret_name_1
+      env:
+        - name: ENV_VAR_NAME_2
+          valueFrom:
+            secretKeyRef:
+              key: secret_key_2            
+              name: secret_name_2
+      script: | # <8>
+        #!/bin/sh
+        # Sample shell script
+        echo "ENV_VAR_NAME_1: " $ENV_VAR_NAME_1
+        echo "ENV_VAR_NAME_2: " $ENV_VAR_NAME_2
+        jq --version (adjust the jq command for different JSON structures)
+        curl -k -L -H "Authorization: Bearer $ENV_VAR_NAME_1" https://$ENV_VAR_NAME_2/api/cli/download/roxctl-linux --output ./roxctl
+        chmod +x ./roxctl 
+        echo "roxctl version"
+        ./roxctl version
+        echo "image from pipeline: " 
+
+        # Replace the following line with your dynamic image logic
+        DYNAMIC_IMAGE=$(get_dynamic_image_logic_here)
+        echo "Dynamic image: $DYNAMIC_IMAGE"
+        ./roxctl image scan --insecure-skip-tls-verify -e $ENV_VAR_NAME_2 --image $DYNAMIC_IMAGE --output json  > roxctl_output.json
+        more roxctl_output.json
+        jq -rce \  # <9>
+          '{vulnerabilities:{
+          critical: (.result.summary.CRITICAL),
+          high: (.result.summary.IMPORTANT),
+          medium: (.result.summary.MODERATE),
+          low: (.result.summary.LOW)
+            }}' scan_output.json | tee $(results.SCAN_OUTPUT.path)
+----
+<1> The name of your task.
+<2> The location for storing the task outputs.
+<3> The naming convention of the scan task result. A valid naming convention must end with the `SCAN_OUTPUT` string. For example, SCAN_OUTPUT, MY_CUSTOM_SCAN_OUTPUT, or ACS_SCAN_OUTPUT.
+<4> The description of the result.
+<5> The name of the vulnerability scanning tool that you have used. 
+<6> The location of the actual image containing the scan tool.
+<7> The tool-specific environment variables.
+<8> The shell script to be executed with json output. For example, scan_output.json.
+<9> The format to extract vulnerability summary (adjust `jq` command for different JSON structures).
+
+. Update an appropriate Pipeline to add vulnerabilities specifications in the following format:
+
++
+[source,yaml]
+----
+...
+spec:
+  results:
+    - description: The common vulnerabilities and exposures (CVE) result
+      name: SCAN_OUTPUT
+      type: $(tasks.vulnerability-scan.results.SCAN_OUTPUT)
+----
+
+.Verification
+
+* Navigate to the `PipelineRun` details page and review the *Vulnerabilities* row for a visual representation of identified vulnerabilities.
+
+* Alternatively, you can navigate to the `PipelineRun` list view page, and review the *Vulnerabilities* column.

secure/setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements.adoc

@@ -0,0 +1,33 @@
+:_mod-docs-content-type: ASSEMBLY
+include::_attributes/common-attributes.adoc[]
+[id="setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements"]
+= Setting up {pipelines-shortname} in the web console to view Software Supply Chain Security elements
+:context: setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements
+
+toc::[]
+
+[role="_abstract"]
+Use the *Developer* or *Administrator* perspective to create or modify a pipeline and view key Software Supply Chain Security elements within a project.
+
+Set up {pipelines-shortname} to view:
+
+* **Project vulnerabilities**: Visual representation of identified vulnerabilities within a project.
+
+* **Software Bill of Materials (SBOMs)**: Download or view detailed listing of PipelineRun components.
+
+Additionally, PipelineRuns that meet {tekton-chains} requirement displays signed badges next to their names. This badge indicates that the pipeline run execution results are cryptographically signed and stored securely, for example within an OCI image.
+
+.The signed badge
+image::badge.png[]
+
+The PipelineRun displays the signed badge next to its name only if you have configured {tekton-chains}. For information on configuring Tekton Chains, see link:https://docs.openshift.com/pipelines/1.13/secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.html[Using Tekton Chains for OpenShift Pipelines supply chain security].
+
+
+include::modules/op-setting-up-openshift-pipelines-to-view-project-vulnerabilities.adoc[leveloffset=+1]
+
+include::modules/op-setting-up-openshift-pipelines-to-download-or-view-sboms.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+== Additional resources
+
+* xref:../create/working-with-pipelines-web-console.html#additional-resources_working-with-pipelines-web-console[Working with Red Hat OpenShift Pipelines in the web console]