diff --git a/create/working-with-pipelines-web-console.adoc b/create/working-with-pipelines-web-console.adoc index 49b0846977a8..055e489ce2ce 100644 --- a/create/working-with-pipelines-web-console.adoc +++ b/create/working-with-pipelines-web-console.adoc @@ -47,3 +47,11 @@ include::modules/op-deleting-pipelines.adoc[leveloffset=+2] // Admin console include::modules/op-creating-pipeline-templates-admin-console.adoc[leveloffset=+1] + +// Both Admin and Developer Console + +include::modules/op-enhanced-pipelinerun-details-view-web-console.adoc[leveloffset=+1] + +include::modules/op-viewing-and-downloading-sboms.adoc[leveloffset=+2] + +include::modules/op-viewing-vulnerabilities.adoc[leveloffset=+2] \ No newline at end of file diff --git a/images/badge.png b/images/badge.png new file mode 100644 index 000000000000..f3df68571f08 Binary files /dev/null and b/images/badge.png differ diff --git a/images/output.png b/images/output.png new file mode 100644 index 000000000000..14856f33b725 Binary files /dev/null and b/images/output.png differ diff --git a/images/pipelinerun_scan.png b/images/pipelinerun_scan.png new file mode 100644 index 000000000000..e71e96e80476 Binary files /dev/null and b/images/pipelinerun_scan.png differ diff --git a/images/sbom.png b/images/sbom.png new file mode 100644 index 000000000000..7469c1ec39a9 Binary files /dev/null and b/images/sbom.png differ diff --git a/images/vulnerabilities_details.png b/images/vulnerabilities_details.png new file mode 100644 index 000000000000..dd1f7bdbd30e Binary files /dev/null and b/images/vulnerabilities_details.png differ diff --git a/images/vulnerabilities_list.png b/images/vulnerabilities_list.png new file mode 100644 index 000000000000..d6b71773bde0 Binary files /dev/null and b/images/vulnerabilities_list.png differ diff --git a/modules/op-enhanced-pipelinerun-details-view-web-console.adoc b/modules/op-enhanced-pipelinerun-details-view-web-console.adoc new file mode 100644 index 000000000000..bf1b8c513b90 --- /dev/null +++ b/modules/op-enhanced-pipelinerun-details-view-web-console.adoc @@ -0,0 +1,31 @@ +// This module is included in the following assemblies: +// * create/working-with-pipelines-web-console.adoc + +:_mod-docs-content-type: CONCEPT +[id="op-enhanced-pipelinerun-details-view-web-console_{context}"] += Enhanced PipelineRun details view in the Web Console + +The PipelineRun details view in the *Developer* or *Administrator* perspective of the web console provides an enhanced visual representation of `PipelinesRuns` within a project. This improved view highlights key Software Supply Chain Security elements within a project. + +The enhanced PipelineRun details view displays: + +* **Security and provenance badge**: Signed badge indicating that Tekton Chains have validated the execution and origin of a PipelineRun. + +* **Output tab**: Dedicated tab for easy access to the PipelineRun results. + +* **Project vulnerabilities**: Visual representation of identified vulnerabilities within a project. + +* **Software Bill of Materials (SBOMs)**: Download or view detailed listing of PipelineRun components. + +== Security and provenance badge +A PipelineRun with a signed badge next to its name signifies that it's secured by Tekton Chains. This badge indicates that the PipelineRun's execution results are cryptographically signed and stored securely, for example within an OCI image. + +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] + +== Output tab + +The PipelineRun details page displays an *Output* tab to view the PipelineRun results. + +image::output.png[] \ No newline at end of file diff --git a/modules/op-viewing-and-downloading-sboms.adoc b/modules/op-viewing-and-downloading-sboms.adoc new file mode 100644 index 000000000000..0b54fb6a6dd5 --- /dev/null +++ b/modules/op-viewing-and-downloading-sboms.adoc @@ -0,0 +1,87 @@ +// This module is included in the following assemblies: +// * create/working-with-pipelines-web-console.adoc + +:_mod-docs-content-type: PROCEDURE +[id="op-viewing-and-downloading-sboms_{context}"] += Viewing and Downloading 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. + +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 # <.> +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//quarkus-demo:v2 --output cyclonedx-json=sbom-image.json + echo 'BEGIN SBOM' + cat sbom-image.json + echo 'END SBOM' + echo 'quay.io/user/workloads//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. +<.> The naming convention of the SBOM task result. A valid naming convention must end with the `LINK_TO_SBOM` string. For example, LINK_TO_SBOM, MY_LINK_TO_SBOM, or ACS_LINK_TO_SBOM. +<.> 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] +---- +... +pipelineSpec: + 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. + + +.Verification + +* Navigate to the PipelineRun details page to view and download the SBOMs using CLI. \ No newline at end of file diff --git a/modules/op-viewing-vulnerabilities.adoc b/modules/op-viewing-vulnerabilities.adoc new file mode 100644 index 000000000000..2291aee157be --- /dev/null +++ b/modules/op-viewing-vulnerabilities.adoc @@ -0,0 +1,114 @@ +// This module is included in the following assemblies: +// * create/working-with-pipelines-web-console.adoc + +:_mod-docs-content-type: PROCEDURE +[id="op-viewing-vulnerabilities_{context}"] += Viewing 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. + +image::vulnerabilities_details.png[] + +You can also review the vulnerabilities in the Vulnerabilities column in the PipelineRuns list view page. + +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. + +.Procedures + +. In the any perspective, switch to the relevant project where you want a visual representation of vulnerabilities. + +. Optional: If you do not have a vulnerability scan task, create one in the following format: + ++ +*Example vulnerability scan task* + ++ +[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: scan # <.> + image: quay.io/your-tool-image # <.> + env: + - name: TOOL_ENV_VAR1 # <.> + valueFrom: + secretKeyRef: + key: tool_var1 + name: tool-secrets + script: | + #!/bin/sh # <.> + + # Tool-specific setup commands + # ... (replace with actual setup commands for your tool) + + # Execute the vulnerability scan, and store the results in a .json file + your-tool-command --output json > scan_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. For example, Roxctl. +<.> 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 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] +---- +jq -rce \ # <1> + '{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 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.