diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 2e0c4267cdb1..319ee4647830 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 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/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-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..46090b4ac0d4 --- /dev/null +++ b/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//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. +<.> (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 -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:" +---- + +. 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:" +---- + +.. (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: > 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 ", + "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..b46407e16d25 --- /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 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. 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..13543a580d78 --- /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 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] \ No newline at end of file