HACDOCS-698: Added the content for the Enhanced PipelineRun details v…

…iew 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 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,210 @@
+// 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 Openshift Pipelines to download or view SBOMs
+
+The PipelineRun details page provides an option to download or view 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 may 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 any perspective, switch to the relevant project where you want a visual representation of SBOMs.
+
+. Add a task to create the SBOM link in the following format:
+
++
+*Example SBOM link task*
+
++
+[source,yaml]
+----
+apiVersion: tekton.dev/v1
+kind: Task
+metadata:
+  name: sbom-task # <.>
+  annotations:
+    task.output.location: results  # <.>
+    task.results.format: application/text
+    task.results.key: LINK_TO_SBOM  # <.>
+    task.results.type: external-link  # <.>
+spec:
+  results:
+    - description: Contains the SBOM link  # <.>
+      name: LINK_TO_SBOM
+  steps:
+    - name: print-sbom-results
+      image: quay.io/image  # <.>
+      script: | # <.>
+        #!/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) # <.>
+----
+<.> The name of your task.
+<.> The location for storing the task outputs.
+<.> (Optional) Set to open the SBOM in a new tab. 
+<.> The SBOM task result name. Do not change the name of the SBOM result task.
+<.> The description of the result.
+<.> The image that generates the SBOM.
+<.> The script that generates the SBOM image.
+<.> 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
+  results:
+    - name: IMAGE_URL  # <.>
+      description: url
+      value: $(tasks.sbom-task.results.LINK_TO_SBOM) # <.>
+----
+<.> The same name as created in Step 2.
+<.> The result for the OCI image repository URL.
+<.> The variable that references and retrieves the generated  SBOM link from a specific task within a pipeline.
+
+
+== Viewing an SBOM in the web UI
+
+.Prerequisites
+
+* You set up Openshift Pipelines to download or view SBOMs.
+
+.Procedure
+
+. Navigate to the Activity > PipelineRuns tab.
+
+. For the component 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
+
+* Install 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.
+
+* Install the link:https://jqlang.github.io/jq/download/[jq] CLI tool.
+
+* You set up Openshift Pipelines to download or view SBOMs.
+
+.Procedure
+
+. Open terminal and list your components.
++
+[source,terminal]
+----
+$ oc get components
+----
++
+*Example output*
++
+[source,terminal]
+----
+NAME                               AGE   STATUS   REASON   TYPE
+devfile-sample-go-basic-8wqt       8m54s True     OK       Updated
+devfile-sample-python-basic-ikch   20d   True     OK       Updated
+----
+
+. Choose which component’s SBOM you want to download. Then use `oc` get and the `jq` CLI tool to get the component image path.
++
+[source,terminal]
+----
+$ oc get component <component name> -ojson | jq '.status.containerImage'
+----
++
+*Example*
++
+[source,terminal]
+----
+$ oc get component devfile-sample-python-basic-ikch -ojson | jq '.status.containerImage'
+    "quay.io/redhat-appstudio/user-workload@sha256:<output omitted>"
+----
+
+. Use Cosign to download the SBOM. From the output of the last command, pass the image path as an argument into Cosign’s `download sbom` command. Be sure to delete any quotation marks around the image path.
++
+Example
++
+[source,terminal]
+----
+$ cosign download sbom quay.io/redhat-appstudio/user-workload@sha256:<output omitted>"
+----
+
+.. (Optional) To view the full SBOM in a searchable format, you can redirect the output:
++
+[source,terminal]
+----
+$ cosign download sbom quay.io/redhat-appstudio/user-workload@sha256:<output omitted> > sbom.txt
+----
+
+== Reading the SBOM
+
+In the SBOM, as the following sample excerpt shows, you can see four characteristics of each library that a component 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.
+
+[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 Openshift pipelines to view project vulnerabilities
+
+The PipelineRun details view 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 view
+image::vulnerabilities_details.png[]
+
+You can also review the vulnerabilities in the Vulnerabilities column in the PipelineRuns list view page.
+
+.Viewing vulnerabilities on the PipelineRuns 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 any 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 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 may 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  # <.>
+  annotations:
+    task.output.location: results  # <.>
+    task.results.format: application/json
+    task.results.key: SCAN_OUTPUT  # <.>
+spec:
+  results:
+    - description: CVE result format  # <.>
+      name: SCAN_OUTPUT
+      type: string
+  steps:
+    - name: roxctl  # <.>
+      image: quay.io/roxctl-tool-image  # <.>
+      env:
+        - name: ENV_VAR_NAME_1  # <.>
+          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: | # <.>
+        #!/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
+        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 \  # <.>
+          '{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)
+----
+<.> The name of your task.
+<.> The location for storing the task outputs.
+<.> 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.
+<.> The description of the result.
+<.> The name of the vulnerability scanning tool that you have used. 
+<.> The location of the actual image containing the scan tool.
+<.> The tool-specific environment variables.
+<.> The shell script to be executed with json output. For example, scan_output.json.
+<.> 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 PipelineRuns 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 Openshift Pipelines 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 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' requirements display a signed badge next to its name. This badge indicates that the PipelineRun's 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]