Skip to content

Commit

Permalink
Merge pull request #81 from konflux-ci/revert-80-build-metadata-rework
Browse files Browse the repository at this point in the history 
Revert "Rework supply chain metadata documentation"
  • Loading branch information
@arewm
arewm authored Jul 2, 2024
2 parents c7b74d6 + 27daed8 commit 9ecf99c
Show file tree
Hide file tree
Showing 6 changed files with 55 additions and 202 deletions.
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/how-tos/_nav.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
72 changes: 1 addition & 71 deletions docs/modules/ROOT/pages/how-tos/creating.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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 <component name> -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:<output omitted>
--
72 changes: 1 addition & 71 deletions docs/modules/ROOT/pages/how-tos/metadata/index.adoc
View file
Original file line number Diff line number Diff line change
@@ -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:<output omitted>
--

+
. 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:<sha-digest>
└── 📦 SBOMs for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-<sha-digest>.sbom
└── 🍒 sha256:<sbom-sha-digest>
└── 💾 Attestations for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-<sha-digest>.att
└── 🍒 sha256:<attestation-sha-digest>
└── 🔐 Signatures for an image tag: quay.io/redhat-user-workload/workspace-tenant/application/component:sha256-<sha-digest>.sig
└── 🍒 sha256:<signature-sha-digest>
--

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].
= Inspecting provenance and attestations
61 changes: 9 additions & 52 deletions .../pages/how-tos/metadata/attestations.adoc → ...OT/pages/how-tos/metadata/provenance.adoc
View file
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -152,6 +107,11 @@ Example output:
"payloadType",
"signatures"
]
[
"payload",
"payloadType",
"signatures"
]
--
+
Expand All @@ -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::<output omitted>
└── 💾 Attestations for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.att
├── 🍒 sha256::<output omitted>
└── 🍒 sha256::<output omitted>
└── 🔐 Signatures for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.sig
└── 🍒 sha256::<output omitted>
└── 📦 SBOMs for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.sbom
└── 🍒 sha256:<output omitted>
--
== 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].
45 changes: 39 additions & 6 deletions docs/modules/ROOT/pages/how-tos/metadata/sboms.adoc
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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 <component name> -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:<sha-digest>"
----

. 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:<sha-digest>
----

+
Expand All @@ -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:<sha-digest> > sbom.txt
----

== Reading the SBOM
Expand Down
5 changes: 4 additions & 1 deletion docs/modules/ROOT/pages/index.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 9ecf99c

Please sign in to comment.