diff --git a/docs/modules/ROOT/pages/how-tos/_nav.adoc b/docs/modules/ROOT/pages/how-tos/_nav.adoc index 3debc071..076ba648 100644 --- a/docs/modules/ROOT/pages/how-tos/_nav.adoc +++ b/docs/modules/ROOT/pages/how-tos/_nav.adoc @@ -19,5 +19,5 @@ **** xref:how-tos/testing/integration/creatingoverridesnapshot.adoc[Creating an override snapshot] ** xref:how-tos/metadata/index.adoc[Inspecting provenance and attestations] *** xref:how-tos/metadata/sboms.adoc[Inspecting SBOMs] -*** xref:how-tos/metadata/attestations.adoc[Inspecting artifact attestations] +*** xref:how-tos/metadata/provenance.adoc[Downloading the SLSA provenance] ** xref:how-tos/deleting.adoc[Deleting applications and components] diff --git a/docs/modules/ROOT/pages/how-tos/creating.adoc b/docs/modules/ROOT/pages/how-tos/creating.adoc index 337f2f0d..bd5769ac 100644 --- a/docs/modules/ROOT/pages/how-tos/creating.adoc +++ b/docs/modules/ROOT/pages/how-tos/creating.adoc @@ -40,7 +40,7 @@ kubectl -n pipelines-as-code create secret generic pipelines-as-code-secret \ . Still in the context of your {ProductName} repository, run `kubectl create -f smee/smee-client`. . Now, you can trigger your application’s first build pipeline. In the git repository for your application, using your preferred text editor, open a pull request against the `/.tekton/pull-request.yaml` file. .. Specifically, replace any existing value for the `git-url` field with the git URL for your application’s repository. (This is the URL you would use to clone the repository locally; it ends with `.git`.) -. Once the PR is made, a build pipeline should start. You can track its progress in the {ProductName} UI or you can see the final status in GitHub after the pipeline completes. If the pipeline is successful, you can merge the PR. +. Once the PR is made, a build pipeline should start. You can track its progress on GitHub, or in the {ProductName} UI. If the pipeline is successful, you can merge the PR. == Example YAML file for multiple components @@ -111,73 +111,3 @@ metadata: spec: url: "https://github.com/konflux-ci/anothertestrepo" -- - -== Finding the built image - -After a pipeline completes with a built artifact, you may want to test the resulting image to ensure that it works properly. The `IMAGE_URL` Tekton result will be set to the pullspec for the image. This can be discovered using the UI or the CLI. - -+ -NOTE: Images build from pull request pipelines will be automatically deleted 5 days after they are built. This parameter can be changed by xref:/how-tos/configuring/customizing-the-build.adoc[customizing the build]. - -=== With the UI - -All build PipelineRuns are visible in the {ProductName} UI. The location of these images in the OCI registry is reported on the *Activity* page. - -.Procedure - -In the console, complete the following steps to find the image pullspec for a completed PipelineRun: - -. Navigate to the *Activity* > *Pipeline runs* tab. - -. For the component whose SBOM you want to view, select its most recent pipeline run. - -. Find the *Results* section at the bottom of the page and look for the `IMAGE_URL` row. It should resemble `quay.io/redhat-user-workloads/workspace-tenant/application/component:tag`. The `IMAGE_DIGEST` provided can be used as an alternative mechanism for referencing the image. You will - -=== With the CLI - -After the build PipelineRuns are completed from git push events, the Components are updated with the location of the artifact in the OCI registry. - -The CLI - -.Prerequisites - -* xref:/getting-started/cli.adoc[Login] to {ProductName}. - -* Install the link:https://stedolan.github.io/jq/download/[jq] CLI tool. - -.Procedure - -In the CLI, complete the following steps to find the latest pullspec for a component: - -. List your components. -+ -[source] ----- -$ oc get components ----- -+ -.Example output -+ -[source] ----- -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 image you want to discover. Then use `oc get` and the `jq` CLI tool to get the component image path. - -+ -[source] ----- -$ oc get component -o json | jq '.status.containerImage' ----- - -. For convenience, you may want to save the image path to a local variable. -+ -Example: -+ -[source] --- -IMAGE=quay.io/redhat-user-workloads/workspace-tenant/application/component@sha256: --- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/metadata/index.adoc b/docs/modules/ROOT/pages/how-tos/metadata/index.adoc index ec2b9cf4..2135310e 100644 --- a/docs/modules/ROOT/pages/how-tos/metadata/index.adoc +++ b/docs/modules/ROOT/pages/how-tos/metadata/index.adoc @@ -1,71 +1 @@ -= Inspecting provenance and attestations - -We are committed to providing exceptional security with {ProductName} by hardening the build platform and providing transparency into the build process and artifact's composition. By hardening the build platform, we enable multiple builds to run on a shared platform while preventing tampering from other running builds (link:https://slsa.dev/spec/v1.1/threats-overview[threats to the build process]). By providing transparency, we enable xref:/advanced-how-tos/managing-compliance-with-ec.adoc[policy evaluation] and auditability on the actual build process (link:https://slsa.dev/spec/v1.1/threats-overview[threats to the package selection]). This commitment means that {ProductName} conforms to the link:https://slsa.dev/spec/v1.0/levels#build-l3[SLSA Build Level 3] requirements. - -Don't take our word on the transparency -- you can download and inspect these artifacts yourself! {ProductName} generates and pushes build metadata as OCI artifacts to the container registry alongside your software's build using the link:https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md[referrers API]. - -== Discovering the associated metadata - -.Prerequisites - -* Install the link:https://docs.sigstore.dev/cosign/installation/[Cosign] CLI tool. - -* Install the link:https://stedolan.github.io/jq/download/[jq] CLI tool. - -* xref:/getting-started/cli.adoc[Login] to {ProductName}. - -.Procedure - -In the CLI, complete the following steps to discover the associated metadata a component: - -. Find the image for a xref:/how-tos/creating.adoc#finding-the-built-image[recently completed build pipeline] and export the value to the `IMAGE` environment variable -+ -Example: -+ -[source] --- -IMAGE=quay.io/redhat-user-workloads/workspace-tenant/application/component@sha256: --- - -+ -. Print a high-level overview of the artifact's metadata that {ProductName} has created for a component: - -+ -[source] --- -cosign tree $IMAGE --- -+ -Example output: -+ -[source] --- -πŸ“¦ Supply Chain Security Related artifacts for an image: quay.io/redhat-user-workload/workspace-tenant/application/component@sha256: -└── πŸ“¦ SBOMs for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-.sbom - └── πŸ’ sha256: -└── πŸ’Ύ Attestations for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-.att - └── πŸ’ sha256: -└── πŸ” Signatures for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-.sig - └── πŸ’ sha256: --- - -The `cosign tree` command will show all metadata associated to the artifact via the referrers API. The SBOM artifact contains the Software Bill of MaterialsWe have provided further procedures for you to view and inspect the xref:/how-tos/metadata/attestations.adoc[attestations] and xref:/how-tos/metadata/sboms.adoc[SBOMs] by {ProductName}. - -== Downloading the attestations - -In order to enable the software artifacts' build processes to be audited, . As part of that commitment, {ProductName} conforms to This includes providing transparency into when and how all artifacts are built by generating link:https://slsa.dev/spec/v1.0/provenance[SLSA provenance] with Tekton Chains. - -The pipeline provenance generated by link:https://tekton.dev/docs/concepts/supply-chain-security/[Tekton Chains] contains information from the PipelineRun that generated the attested artifact including input parameters for the Tasks as well as Task results. - -We have provided the procedures for you to link:/how-tos/metadata/provenance/downloading.adoc[download] and link:/how-tos/metadata/provenance/inspect.adoc[inspect] the SLSA provenace that {ProductName} generates for each of your xref:../glossary/index.adoc#component[components]. - -The SLSA provenance is stored as an OCI artifact alongside the images that are pushed to the container registry. The provenance is associated with the artifact by the link:https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md[referrers API] and can be retrieved from the OCI registry using a command line tool `cosign`. - -A software bill of materials (SBOM) provides greater transparency for your software supply chain. {ProductName} provides link:https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf[build SBOMs], which list 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. In particular, you can use various tools to scan your SBOM and determine if any of your dependencies have known vulnerabilities. Furthermore, to comply with cybersecurity regulations, your organization might need to provide its customers with the SBOM for your application's components. For example, in the United States, the link:https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/[Executive Order on Improving the Nation's Cybersecurity] requires vendors to provide SBOMs, and in Europe, the link:https://www.cisa.gov/sites/default/files/2023-09/EU%20Commission%20SBOM%20Work_508c.pdf[Cyber Resilience Act] does the same. - - -== Additional resources -* Learn about the SLSA framework and xref:/index.adoc#supply-chain-security-through-slsa-conformity[how {ProductName} meets the requirements of SLSA Build Level 3]. -* Red Hat's Enterprise Contract (EC) is a powerful tool that you can also use to verify your SLSA provenance; visit link:https://enterprisecontract.dev/docs/user-guide/main/cli.html#_validating_an_image[this page] to learn how to use the EC CLI tool to verify your provenance. You will need the public key used by Tekton Chains, which you can find by following link:https://enterprisecontract.dev/docs/user-guide/main/cli.html#_finding_the_public_key[these instructions]. \ No newline at end of file += Inspecting provenance and attestations \ No newline at end of file diff --git a/docs/modules/ROOT/pages/how-tos/metadata/attestations.adoc b/docs/modules/ROOT/pages/how-tos/metadata/provenance.adoc similarity index 57% rename from docs/modules/ROOT/pages/how-tos/metadata/attestations.adoc rename to docs/modules/ROOT/pages/how-tos/metadata/provenance.adoc index d246bf1f..b8e8406a 100644 --- a/docs/modules/ROOT/pages/how-tos/metadata/attestations.adoc +++ b/docs/modules/ROOT/pages/how-tos/metadata/provenance.adoc @@ -1,53 +1,8 @@ -= Inspecting artifact attestations += Downloading the SLSA provenance -Generally speaking, link:https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec[attestations] are authenticated metadata about software artifacts. An identity (and their private cryptographic key) are required to create an attestation for a software artifact. The primary attestation that {ProductName} generates is the SLSA provenance which is produced by link:https://tekton.dev/docs/concepts/supply-chain-security/[Tekton Chains]. This provenance contains information from the PipelineRun that generated the attested artifact including input parameters for the Tasks as well as Task results. +We are committed to providing exceptional build-time security with {ProductName}. As part of that commitment, {ProductName} conforms to the link:https://slsa.dev/spec/v1.0/levels#build-l3[SLSA Build Level 3] requirements. This includes providing transparency into the steps taken for all artifact builds by generating link:https://slsa.dev/spec/v1.0/provenance[SLSA provenance]. -After you have found the image for a xref:/how-tos/creating.adoc#finding-the-built-image[recently completed build pipeline] and exported the value to the `IMAGE` environment variable, you are ready to start exploring the information stored in the attestations. - -== Inspect the SLSA provenance - -Tekton Chains produces a very detailed SLSA provenance. If we were to look at the output from the following provenance, we would find that it is over 2800 lines long! - -[source] --- -$ cosign download attestation $IMAGE | jq -r '.payload | @base64d | fromjson' | head -{ - "_type": "https://in-toto.io/Statement/v0.1", - "predicateType": "https://slsa.dev/provenance/v0.2", - "subject": [ - { - "name": "quay.io/redhat-user-workloads/rhtap-integration-tenant/oras-container/oras-container", - "digest": { - "sha256": "5d0a8a5535fcc4ba467264cacbdeab2fb8662a538a61cb7fc8b3155e3f20fa39" - } - }, --- - -Therefore, it will likely be convenient to use tools like `jq` to further filter the provenance to identify smaller sets of relevant information. - -=== Identify the build parameters - -Since the SLSA provenance includes metadata about the input parameters, we can use it to view the parameters for the Tekton PipelineRun including its source repository! - -[source] --- -$ cosign download attestation $IMAGE | jq -r '.payload | @base64d | fromjson | .predicate.invocation.parameters' -{ - "build-args-file": "", - "build-source-image": "false", - "dockerfile": "Containerfile", - "git-url": "https://github.com/konflux-ci/oras-container", - "hermetic": "false", - "image-expires-after": "", - "java": "false", - "output-image": "quay.io/redhat-user-workloads/rhtap-integration-tenant/oras-container/oras-container:477ee20f7e6d146ea203c4aaa0507f4d1e925a53", - "path-context": ".", - "prefetch-input": "", - "rebuild": "false", - "revision": "477ee20f7e6d146ea203c4aaa0507f4d1e925a53", - "skip-checks": "false" -} --- +We have also provided the following procedure for you to actually access the SLSA provenace that {ProductName} generates for each of your xref:../glossary/index.adoc#component[components]. Follow the instructions below to download your SLSA provenance. .Prerequisites @@ -152,6 +107,11 @@ Example output: "payloadType", "signatures" ] +[ + "payload", + "payloadType", + "signatures" +] -- + @@ -170,16 +130,13 @@ Example output: πŸ“¦ Supply Chain Security Related artifacts for an image: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg@sha256:: └── πŸ’Ύ Attestations for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:.att β”œβ”€β”€ πŸ’ sha256:: + └── πŸ’ sha256:: └── πŸ” Signatures for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:.sig └── πŸ’ sha256:: └── πŸ“¦ SBOMs for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:.sbom └── πŸ’ sha256: -- -== Inspecting the downloaded provenance - -The generated provenance includes information from the Tekton PipelineRun that generated the attested artifact. It - == Additional resources * Learn about the SLSA framework and xref:/index.adoc#supply-chain-security-through-slsa-conformity[how {ProductName} meets the requirements of SLSA Build Level 3]. * Red Hat's Enterprise Contract (EC) is a powerful tool that you can also use to verify your SLSA provenance; visit link:https://enterprisecontract.dev/docs/user-guide/main/cli.html#_validating_an_image[this page] to learn how to use the EC CLI tool to verify your provenance. You will need the public key used by Tekton Chains, which you can find by following link:https://enterprisecontract.dev/docs/user-guide/main/cli.html#_finding_the_public_key[these instructions]. diff --git a/docs/modules/ROOT/pages/how-tos/metadata/sboms.adoc b/docs/modules/ROOT/pages/how-tos/metadata/sboms.adoc index 6c96d3d7..f1a30dae 100644 --- a/docs/modules/ROOT/pages/how-tos/metadata/sboms.adoc +++ b/docs/modules/ROOT/pages/how-tos/metadata/sboms.adoc @@ -1,5 +1,6 @@ -= Inspecting artifact SBOMs += Inspecting SBOMs +== Software bill of materials A software bill of materials (SBOM) provides greater transparency for your software supply chain. {ProductName} provides link:https://www.cisa.gov/sites/default/files/2023-04/sbom-types-document-508c.pdf[build SBOMs], which list 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. In particular, you can use various tools to scan your SBOM and determine if any of your dependencies have known vulnerabilities. Furthermore, to comply with cybersecurity regulations, your organization might need to provide its customers with the SBOM for your application's components. For example, in the United States, the link:https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/[Executive Order on Improving the Nation's Cybersecurity] requires vendors to provide SBOMs, and in Europe, the link:https://www.cisa.gov/sites/default/files/2023-09/EU%20Commission%20SBOM%20Work_508c.pdf[Cyber Resilience Act] does the same. @@ -37,20 +38,52 @@ The SBOM is unsigned so there is no way to verify whether it has been tampered w * xref:/getting-started/cli.adoc[Login] to {ProductName}. -* You have found the image for a xref:/how-tos/creating.adoc#finding-the-built-image[recently completed build pipeline] and exported the value to the `IMAGE` environment variable. - .Procedure In the CLI, complete the following steps to download the SBOM for a component: -. Use Cosign to download the SBOM. Pass the IMAGE environment variable as an argument into Cosign's `download sbom` command. +. List your components. ++ +[source] +---- +$ oc get components +---- ++ +.Example output ++ +[source] +---- +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] +---- +$ oc get component -ojson | jq '.status.containerImage' +---- + ++ +.Example + ++ +[source] +---- +$ 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] ---- -$ cosign download sbom $IMAGE +$ cosign download sbom quay.io/redhat-appstudio/user-workload@sha256: ---- + @@ -59,7 +92,7 @@ $ cosign download sbom $IMAGE + [source] ---- -$ cosign download sbom $IMAGE > sbom.txt +$ cosign download sbom quay.io/redhat-appstudio/user-workload@sha256: > sbom.txt ---- == Reading the SBOM diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 5de91ae9..d600306a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -190,5 +190,8 @@ a|In {ProductName}: == Additional resources -* Learn xref:../how-tos/metadata/index.adoc[how to inspect the SLSA] provenance for your components. +* Learn xref:../how-tos/metadata/provenance.adoc[how to inspect the SLSA] provenance for your components. * Visit the link:https://slsa.dev/spec/v1.0/[SLSA overview page], the link:https://slsa.dev/spec/v1.0/levels[Build Levels] page, or the link:https://slsa.dev/spec/v1.0/verifying-systems[verifying build platforms] page. + +//xref to be double-checked before the release +//OLD * Learn xref:../how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc[how to inspect the SLSA] provenance for your components.