diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 2e0c4267cdb1..848a692270ef 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 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/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..a70ffef7b43a 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-setting-up-openshift-pipelines-to-download-or-view-sboms.adoc b/modules/op-setting-up-openshift-pipelines-to-download-or-view-sboms.adoc new file mode 100644 index 000000000000..f2ca5c7fc68b --- /dev/null +++ b/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//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) # <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: # <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//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//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 ", + "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" + ... +---- \ No newline at end of file diff --git a/modules/op-setting-up-openshift-pipelines-to-view-project-vulnerabilities.adoc b/modules/op-setting-up-openshift-pipelines-to-view-project-vulnerabilities.adoc new file mode 100644 index 000000000000..25a2b606747a --- /dev/null +++ b/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. diff --git a/secure/setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements.adoc b/secure/setting-up-openshift-pipelines-to-view-software-supply-chain-security-elements.adoc new file mode 100644 index 000000000000..81b07eb0f4d4 --- /dev/null +++ b/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] \ No newline at end of file