Skip to content
This repository was archived by the owner on Nov 5, 2024. It is now read-only.

Commit 5e3af4c

Browse files
Chr1st1anSearsChr1st1anSears
authored
Merge pull request #111 from Chr1st1anSears/slsa-doc
Concept and procedure docs for SLSA
2 parents 5bb5ab2 + 69172ff commit 5e3af4c

File tree

4 files changed

+290
-0
lines changed

4 files changed

+290
-0
lines changed

‎docs/modules/ROOT/nav-concepts.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
* Concepts
2+
** xref:concepts/slsa/con_slsa-conformity.adoc[Supply chain security through SLSA conformity]
23
** xref:concepts/java-build-service/java-build-service.adoc[Java build service]
34
** xref:concepts/java-build-service/java-build-service-components.adoc[Java build service components]
45

‎docs/modules/ROOT/nav-how-to-guides.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
*** xref:how-to-guides/testing_applications/surface-level_tests.adoc[Surface-level test]
66
** Securing your supply chain
77
*** xref:how-to-guides/Secure-your-supply-chain/proc_inspect_sbom.adoc[Inspecting SBOMs]
8+
*** xref:how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc[Downloading your SLSA provenance]
89
*** xref:how-to-guides/Secure-your-supply-chain/proc_java_dependencies.adoc[Configuring dependencies rebuild for Java apps in the CLI]
910
** xref:how-to-guides/proc_creating_your_own_environment.adoc[Creating your own environment]
1011
** xref:how-to-guides/creating_a_custom_application_test_with_test_pipelines.adoc[Creating a custom application test with test pipelines]

‎docs/modules/ROOT/pages/concepts/slsa/con_slsa-conformity.adoc‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
= Supply chain security through SLSA conformity
2+
3+
4+
== Supply-chain Levels for Software Artifacts (SLSA)
5+
6+
Supply-chain Levels for Software Artifacts (SLSA) is a security framework produced through industry collaboration. We use this framework as a guide for reinforcing the build process we use for your applications, to better secure your software supply chain.
7+
8+
SLSA assigns two primary responsibilities to build platforms like {ProductName}:
9+
10+
* Provenance to describe how the platform built each software artifact
11+
* Build isolation to prevent tampering with the build process
12+
13+
SLSA also includes three Build Levels, which provide you with increasing guarantees about how build platforms fulfill these responsibilities. Any build platform that generates provenance conforms to the SLSA framework’s Build Level 1 (L1) specifications. Build platforms produce artifacts with higher Build Levels by hardening provenance against forgery and by isolating the build process. As of the v1.0 specification, Build Level 3 (L3) is the highest Build Level. {ProductName} produces Build L3 artifacts.
14+
15+
The rest of this document further explains our key responsibilities, provenance and build isolation, and how we fulfill those responsibilities. It concludes with a table summarizing how {ProductName} meets the requirements for SLSA Build L3.
16+
17+
18+
== SLSA Provenance
19+
20+
In the context of its framework, SLSA defines provenance as “the verifiable information about software artifacts describing where, when and how something was produced.” SLSA provenance is expressed through attestation, and for higher Build Levels, build platforms must sign that attestation.
21+
22+
=== Attestation
23+
24+
Attestation is the fundamental component of provenance, and you can think of it like a recipe. A recipe tells you how someone made a certain dish, and attestation tells you how a build platform created a software artifact. Our SLSA attestation specifically includes a subject that tells you which artifact the attestation belongs to, and a predicate that explains how {ProductName} built each artifact, including relevant links.
25+
26+
=== Signing the attestation
27+
28+
At higher Build Levels, SLSA directs build platforms to harden their provenance by signing each attestation. With the signature, you can verify that no one tampered with the attestation for your artifacts. Currently, {ProductName} signs attestations using a private key.
29+
30+
=== Evaluating provenance
31+
32+
In its Build Levels, SLSA evaluates provenance based on three questions:
33+
34+
* Completeness: Does the provenance fully explain how the artifact was built?
35+
* Authenticity: How certain are you that the provenance came from the builder?
36+
* Accuracy: How difficult is it to tamper with provenance during the build process?
37+
38+
Completeness of provenance comes from its attestation, and authenticity derives from the signature.
39+
40+
Accuracy is where provenance and build isolation intersect. To generate unforgeable provenance, build platforms must store those secret materials in a secure management system that platform users cannot access. In {ProductName}, only Tekton Chains, which generates and signs provenance, has access to the private key.
41+
42+
43+
== Build isolation
44+
45+
According to the SLSA framework, our other primary responsibility is to guarantee that we build your software correctly, without external influence, by isolating the builds. For Build L2, SLSA directs build platforms to run builds in a hosted environment, and for Build L3, they direct us to make builds internally isolated within that hosted environment.
46+
47+
=== Hosted
48+
49+
If builds run on an individual’s workstation, they become inconsistent. This inconsistency can cause mundane technical issues, but it also introduces security risks. What if undetected malware is lurking on that person’s machine?
50+
51+
To shrink the attack plane, SLSA dicates that builds should execute “using a hosted build platform on shared or dedicated infrastructure, not on an individual’s workstation.” By using an environment that comes from a known, auditable state, build platforms can largely ensure that they generate artifacts in the same way every time.
52+
53+
{ProductName} is a hosted build platform. We execute builds on Amazon Web Services (AWS) through Red Hat OpenShift Service on AWS (ROSA).
54+
55+
56+
=== Internally isolated
57+
58+
Running builds in a hosted environment can protect your builds from malware installed on an individual’s workstation. But an attacker could gain access to your instance of a hosted build platform. What if they inject a malicious payload into one of your artifacts during the build process, and falsify the provenance to cover their tracks? Or what if they use one build to poison an environment that another build uses?
59+
60+
To mitigate these threats, and others, SLSA instructs build platforms to execute builds in an environment that, within the larger hosted environment, is internally isolated from other builds, users, and the control plane. The only external influence that is permissible is influence that the build itself requests, such as dependencies.
61+
62+
{ProductName} internally isolates builds within ROSA using several different tactics. For example, Tekton Chains generates and signs provenance in its own namespace, separate from the one that runs user-defined build steps, so attackers cannot forge provenance. And builds themselves run in their own ephemeral pods, so they cannot persist or influence the build environment of subsequent builds.
63+
64+
65+
== How we meet the requirements for SLSA Build L3
66+
67+
The following table summarizes how {ProductName} conforms to the specification for producing SLSA Build L3 software artifacts.
68+
69+
[cols="1,1, 1"]
70+
|===
71+
|Build level |Requirements |How we meet them
72+
73+
3+^|_For provenance_
74+
75+
|L1: Provenance exists
76+
a|Provenance is:
77+
78+
* Automatically generated
79+
* Formatted per SLSA guidelines, or contains equivalent information
80+
* Complete as possible
81+
82+
a|Provenance in {ProductName} is:
83+
84+
* Generated for each software artifact
85+
* Formatted according to SLSA guidelines
86+
* Complete
87+
88+
89+
|L2: Hosted build platform
90+
a|Provenance is complete and authentic:
91+
92+
* Users can validate provenance.
93+
* The control plane, not tenants, generates provenance.
94+
* Provenance is complete.
95+
96+
a|{ProductName}:
97+
98+
* Signs attestations with a private key
99+
* Generates provenance itself using Tekton Chains
100+
* Generates complete attestations
101+
102+
|L3: Hardened builds
103+
a|Provenance is complete, authentic, and accurate:
104+
105+
* Secret material used to authenticate provenance is stored in a secure management system.
106+
* Secret material is not accessible to the environment running user-defined build steps.
107+
* Provenance is complete, including fully enumerated external parameters.
108+
109+
a|{ProductName}:
110+
111+
* Stores secret materials in Tekton Chains, which is a secure management system
112+
* Uses Tekton Chains in a separate namespace
113+
* Enumerates external parameters in its provenance
114+
115+
116+
3+^|_For build isolation_
117+
118+
|L1: Provenance exists
119+
|None
120+
|N/A
121+
122+
|L2: Hosted build platform
123+
|All build steps run using a hosted build platform on shared or dedicated infrastructure, not on an individual’s workstation.
124+
|{ProductName} is hosted through ROSA.
125+
126+
|L3: Hardened builds
127+
a|Builds run in an isolated environment:
128+
129+
* Builds cannot access secrets of the platform.
130+
* Two builds cannot influence one another.
131+
* Builds cannot persist or influence environment of other builds.
132+
* Builds cannot inject false entries into a cache used by another build.
133+
* Services allowing remote influence must be listed as external parameters in provenance.
134+
135+
a|In {ProductName}:
136+
137+
* Only Tekton Chains can access secret materials.
138+
* Builds run in ephemeral pods.
139+
* ServiceAccounts (API objects that are shared within projects) have reduced permissions.
140+
* Tekton Chains generates and signs provenance outside users’ workspaces.
141+
* External parameters are fully enumerated in provenance.
142+
143+
|===
144+
145+
== Additional resources
146+
147+
* Learn xref:../how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc[how to inspect the SLSA] provenance for your components.
148+
* 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.

‎docs/modules/ROOT/pages/how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
= Downloading your SLSA provenance
2+
3+
The Supply-chain Levels for Software Artifacts (SLSA) website states: “To make an external claim of meeting a SLSA level…there needs to be a way for external users to consume and verify your provenance.” Since we claim to meet SLSA Build Level 3, we have provided the following procedure for you to download the SLSA provenace that {ProductName} generates for each of your xref:../glossary/index.adoc#component[components], including both the attestation and its signature.
4+
5+
.Prerequisites
6+
7+
* xref:../getting-started/getting_started_in_cli.adoc[Login] to {ProductName} in your CLI
8+
* link:https://stedolan.github.io/jq/download/[Install] the `jq` command line utility
9+
* link:https://docs.sigstore.dev/cosign/installation/[Install] the `cosign` command line utility
10+
11+
.Procedure
12+
13+
First you need to get the image path for the component whose attestation you want to download. Then, you can use `cosign` to download the provenance.
14+
15+
. List your components:
16+
17+
+
18+
[source]
19+
--
20+
oc get components
21+
--
22+
23+
+
24+
Example output:
25+
+
26+
[source]
27+
--
28+
NAME AGE STATUS REASON TYPE
29+
partner-catalog-build-ucmg 24d True OK Updated
30+
partner-catalog-ec-pz7b 18d True OK Updated
31+
--
32+
33+
. Choose a component and get its image path:
34+
+
35+
[source]
36+
--
37+
oc get component <component name> -ojson | jq ‘.status.containerImage’
38+
--
39+
40+
+
41+
Example:
42+
+
43+
[source]
44+
--
45+
`oc get component partner-catalog-build-ucmg -ojson | jq ‘.status.containerImage’
46+
--
47+
48+
. For convenience, save the image path to a local variable:
49+
50+
+
51+
[source]
52+
--
53+
IMAGE=quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg@sha256:<output omitted>
54+
--
55+
56+
57+
. Use `cosign` to download the attestation, and use `jq` to put it in a human-readable format:
58+
+
59+
[source]
60+
--
61+
cosign download attestation $IMAGE | jq '.payload|@base64d|fromjson'
62+
--
63+
64+
+
65+
Example output:
66+
+
67+
[source]
68+
--
69+
{
70+
"_type": "https://in-toto.io/Statement/v0.1",
71+
"predicateType": "https://slsa.dev/provenance/v0.2",
72+
"subject": [
73+
{
74+
"name": "quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg",
75+
"digest": {
76+
"sha256": "<output omitted>"
77+
}
78+
}
79+
],
80+
"predicate": {
81+
"builder": {
82+
"id": "https://tekton.dev/chains/v2"
83+
},
84+
"buildType": "tekton.dev/v1beta1/TaskRun",
85+
"invocation": {
86+
<remaining output omitted>
87+
--
88+
89+
. Use the same tools to download the attestation signature:
90+
91+
+
92+
[source]
93+
--
94+
cosign download attestation $IMAGE | jq '.|keys'
95+
--
96+
97+
+
98+
Example output:
99+
+
100+
[source]
101+
--
102+
[
103+
"payload",
104+
"payloadType",
105+
"signatures"
106+
]
107+
[
108+
"payload",
109+
"payloadType",
110+
"signatures"
111+
]
112+
--
113+
114+
+
115+
. (Optional) You can also print a high-level overview of the provenance-related artifacts that {ProductName} has created for a component:
116+
117+
+
118+
[source]
119+
--
120+
cosign tree $IMAGE
121+
--
122+
+
123+
Example output:
124+
+
125+
[source]
126+
--
127+
📦 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>
128+
└── 💾 Attestations for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.att
129+
├── 🍒 sha256::<output omitted>
130+
└── 🍒 sha256::<output omitted>
131+
└── 🔐 Signatures for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.sig
132+
└── 🍒 sha256::<output omitted>
133+
└── 📦 SBOMs for an image tag: quay.io/redhat-user-workloads/rhn-support-csears-tenant/demo-build/partner-catalog-build-ucmg:sha256-:<output omitted>.sbom
134+
└── 🍒 sha256:<output omitted>
135+
--
136+
137+
== Additional resources
138+
* Learn about the SLSA framework and xref:../concepts/slsa/con_slsa-conformity.adoc[how {ProductName} meets the requirements of SLSA Build Level 3].
139+
* 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/posts/introducing-the-enterprise-contract/[this page] to learn how to use the EC CLI tool to verify your provenance.
140+

0 commit comments

Comments
 (0)