Skip to content

Commit e7d44dd

Browse files
puercopuerco
authored
Update getting started doc (#315)
* Update getting started doc Signed-off-by: Adolfo Garcia Veytia (puerco) <[email protected]> * Link to image files Signed-off-by: Adolfo Garcia Veytia (puerco) <[email protected]> --------- Signed-off-by: Adolfo Garcia Veytia (puerco) <[email protected]>
1 parent 204a470 commit e7d44dd

11 files changed

+247
-60
lines changed

‎GETTING_STARTED.md‎

Lines changed: 247 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,279 @@
1-
# Getting Started
1+
# SLSA Source Tool: Getting Started
22

3-
These instructions assume you want to achieve the highest SLSA Source Level.
4-
If not you may have to modify the steps somewhat.
3+
This guide provides a detailed outline to harden a repository and start producing
4+
signed evidence to prove its security controls are in place, protecting code
5+
revisions as they land in the codebase.
56

6-
## Enable Controls
7+
## TL;DR
78

8-
First, enable continuity controls within the target GitHub repo.
9+
If you want to skip [the big read](#onboarding-guide), these instructions should
10+
work for most repositories. If you run into any problems, read on or open an
11+
issue on [github.com/slsa-framework/source-tool](http://github.com/slsa-framework/source-tool).
912

10-
1. Go to the GitHub repo
11-
2. Click the 'Settings' option
12-
3. Click 'Rules -> Rulesets'
13-
4. Click 'New Ruleset -> Import a ruleset'
14-
5. Upload [docs/rulesets/source_level_3_basic.json](docs/rulesets/source_level_3_basic.json)
15-
6. Click 'Create'
13+
### Shortest Onboarding (GitHub)
1614

17-
## Enable Source PoC workflow
15+
The following examples use `http://github.com/yourorg/yourepo` as a
16+
repository, please substitute it for your repository. You can use the full repo
17+
URL or short identifiers as shown in the examples.
1818

19-
Now, enable a workflow that will evaluate the SLSA level, create provenance, etc...
19+
#### Prerequisites
2020

21-
1. Create a clean checkout of the target repo
22-
2. Create a new file named `.github/workflows/compute_slsa_source.yml`
23-
3. Add the following content
21+
1. Download the sourcetool binary from the
22+
[project releases](https://github.com/slsa-framework/source-tool/releases/latest).
2423

25-
```yaml
26-
name: SLSA Source
27-
on:
28-
push:
29-
branches: [ "main" ]
30-
31-
jobs:
32-
# Whenever new source is pushed recompute the slsa source information.
33-
check-change:
34-
permissions:
35-
contents: write # needed for storing the vsa in the repo.
36-
id-token: write
37-
uses: slsa-framework/slsa-source-poc/.github/workflows/compute_slsa_source.yml@main
24+
#### Enable SLSA Controls
25+
26+
1. **Authorize the sourcetool app**
27+
Run the following command and follow the instructions:
28+
29+
```bash
30+
sourcetool auth login
31+
```
32+
33+
2. **Enable all the SLSA controls**
34+
Execute setup subcommand with your repository:
35+
36+
```bash
37+
sourcetool setup repo youorg/yourepo
38+
```
39+
40+
This will open a pull request on the repository you want to
41+
protect, make sure it is merged before continuing.
42+
43+
3. **Create the repository policy**
44+
This command will create your repository policy and open a pull
45+
request in the community repo:
46+
47+
```bash
48+
sourcetool policy create yourorg/yourrepo
49+
```
50+
51+
#### Check Onboarding Status
52+
53+
At any point you can check the progress of the repository onboarding by running:
54+
55+
```bash
56+
sourcetool status
57+
```
58+
59+
Sourcetool will let you know if there are any outstanding steps to follow and
60+
show the current applicable SLSA Source level.
61+
62+
#### Verify Commits
63+
64+
Once the policy merges on the community repo, you should be able to verify
65+
commits using the embedded attestations stored in git notes in your git repository.
66+
To verify the latest commit, run:
67+
68+
```bash
69+
sourcetool verifycommit yourorg/yourrepo
70+
```
71+
72+
## Onboarding Guide
73+
74+
This is the detailed guide to onboard repos to protect them with SLSA Source. For
75+
the short version, check the [TL;DR section](#TL;DR) at the beginning of this
76+
document for 5 minute instructions.
77+
78+
### Introduction
79+
80+
This guide documents the instructions to use sourcetool to enable SLSA Source
81+
Level 3 controls in a repository. Onboarding a repository involves configuring the
82+
required controls, start generating provenance attestations and creating a source
83+
policy in the community repository.
84+
85+
After onboarding, your repository will start producing unforgeable evidence that
86+
prove branches and tags are (and have been) hardened when revisions are pushed to
87+
your branches, meaning that no commit has merged unsupervised.
88+
89+
## Prerequisites
90+
91+
Before onboarding a new repository to the SLSA Source Track, please ensure you have done the following:
92+
93+
#### 1. Make sure you have access to the repository
94+
95+
Make sure you have proper permissions on the repository you want to protect to
96+
configure rules and push feature branches. You need to have admin access or have
97+
a custom role with the "edit repository rules" permission. Provenance generation
98+
will be enabled through a regular pull request.
99+
100+
#### 2. Download sourcetool
101+
102+
Download the `sourcetool` binary for your local architecture from the [GitHub
103+
releases page](https://github.com/slsa-framework/slsa-source-poc/releases/latest).
104+
105+
## Authorize Sourcetool to Access your Repositories
106+
107+
Log in to grant sourcetool access to your repositories. We have an easy,
108+
interactive flow in the CLI. Run the following command and follow the instructions:
109+
110+
```bash
111+
sourcetool auth login
112+
```
113+
114+
That command will display an eight character code and open your browser to
115+
authorize the sourcetool app:
116+
117+
![](docs/media/image01-login.png )
118+
119+
On the displayed webpage, enter the eight characters as displayed on your terminal:
120+
121+
![](docs/media/image02-code.png )
38122

123+
Follow the instructions, you will be presented with a list of repositories you
124+
want to grant access to. You choose all your repos or just let sourcetool work
125+
on a select few.
126+
127+
### Verify Access
128+
129+
Once done, you can verify that sourcetool is correctly logged in by running the
130+
following:
131+
132+
```
133+
sourcetool auth whoami
134+
```
135+
136+
![](docs/media/image03-logged-as.png )
137+
138+
All’s set, you can now start securing your repos.
139+
140+
## Checking Onboarding Status
141+
142+
Once you are logged in, you can check the onboarding status of a repository
143+
using the `status` subcommand:
144+
145+
```bash
146+
sourcetool status yourorg/yourrepo
39147
```
40148

41-
4. Submit the change to your main branch
149+
The status subcommand will show the control implementation status, if a policy
150+
was found and the current SLSA level of the repository:
42151

43-
## Validate Source PoC workflow
152+
![](docs/media/image04-status.png)
44153

45-
Let's verify that everything is working
154+
## One-shot Repository Set Up
46155

47-
1. Note the digest of **merged** commit that added the workflow above
48-
2. Run the verification command
156+
The quickest way to set up a repository is to use sourcetool’s one-shot set up
157+
mode. This will enable all controls at once. If you want more granular control
158+
enabling each control, see the Step By Step guide below.
49159

50-
`go run github.com/slsa-framework/slsa-source-poc/sourcetool@latest verifycommit --commit <commit digest> --owner <YOUR REPO'S ORG> --repo <YOUR REPO'S NAME> --branch main`
160+
### Set up all Controls
161+
162+
To enable all the SLSA recommended protections, run the `setup repo` subcommand:
163+
164+
```bash
165+
sourcetool setup repo yourorg/yourrepo
166+
```
167+
168+
Sourcetool will confirm the actions it will perform before modifying anything.
169+
Type `yes` to proceed.
170+
171+
![](docs/media/image05-setup-repo.png)
172+
173+
## Step-by-step Control Setup
174+
175+
To have more granular enabling each of the SLSA protections in the repo, use
176+
`sourcetool setup control`. This subcommand lets you enable individual
177+
protections in the repo if the all-at-once approach is too scary.
178+
179+
The `setup control` subcommand takes a configuration label and enables only that
180+
specific control. For example, to enable tag protection on `yourorg/yourrepo`, run:
181+
182+
```bash
183+
sourcetool setup controls --config=CONFIG_TAG_RULES yourorg/yourrepo
184+
```
51185

52-
3. You should see the message
53-
`SUCCESS: commit <commit digest> verified with [SLSA_SOURCE_LEVEL_1]`
186+
![](docs/media/image06-confirm-controls.png)
54187

55-
Move to the next section to get to `SLSA_SOURCE_LEVEL_3`.
188+
Again, sourcetool confirms before modifying anything. Type yes to proceed.
56189

57-
## Create a policy file
190+
Configuration Labels
191+
Each configuration label enables a control configuration of those that sourcetool
192+
can manage. The following are the supported labels and their effects:
58193

59-
Now let's create the policy file that will upgrade your SLSA level to level 3.
194+
| Configuration Label | Description |
195+
| :---- | :---- |
196+
| `CONFIG_BRANCH_RULES` | Configures push and delete branch protection in the repository, required to reach SLSA source level 2+. |
197+
| `CONFIG_TAG_RULES` | Configures update, push and delete protection for all tags in the repository, This is required to reach SLSA source level 2+. |
198+
| `CONFIG_GEN_PROVENANCE` | Opens a pull request in the repository to add the provenance generation workflow after every push. |
199+
| `CONFIG_POLICY` | Opens a pull request on the SLSA policy repository to check in a SLSA Source policy for the repository. |
60200

61-
1. Create a fork of https://github.com/slsa-framework/slsa-source-poc
62-
2. Within that fork create a new branch for your policy
63-
3. Within a clean working directory run
201+
You can view these with `sourcetool setup controls --help`
64202

65-
`go run github.com/slsa-framework/slsa-source-poc/sourcetool@latest createpolicy --owner <YOUR REPO'S ORG> --repo <YOUR REPO'S NAME> --branch main`
203+
Note that the source policy (`CONFIG_POLICY`) is not one of the SLSA controls but
204+
the policy creation is abstracted as another control configuration to simplify
205+
using sourcetool when scripting.
66206

67-
e.g.
207+
## Creating the Source Policy
68208

69-
`go run github.com/slsa-framework/slsa-source-poc/sourcetool@latest createpolicy --owner TomHennen --repo wrangle --branch main`
209+
The repository policy is guarded at the community repository and informs
210+
verifying tools the time periods when branches have been protected under their
211+
current SLSA level.
70212

71-
4. Edit the created policy file to set the `canonical_repo` field to the canonical repo for this source
213+
sourcetool can automatically create the repository policy by checking the
214+
enabled protections. You can create the policy at any time but it is recommended
215+
to do it once you finish setting up the desired controls in the repo.
72216

73-
(TODO: see if we can remove this annoyance at some point)
217+
To create the policy, use the `sourcetool policy create` subcommand. Sourcetool
218+
will look at the implemented controls and issue the policy according to the
219+
achieved SLSA level:
74220

75-
e.g. `"canonical_repo": "https://github.com/TomHennen/wrangle",`
221+
![](docs/media/image07-confirm-pr.png )
76222

77-
5. Add & commit the created policy file.
78-
6. Send a PR with the change to https://github.com/slsa-framework/slsa-source-poc
79-
7. Once it's approved you'll be at SLSA Source Level 3 for your next change.
223+
Typing `yes` will create the policy JSON and open a pull request on the SLSA
224+
source policies community repo (`slsa-framework/source-policies`). If you want
225+
to open the PR manually, you can pass the `--pr=false` flag. Sourcetool will only
226+
print the policy and you can open the pull request manually:
227+
228+
![](docs/media/image08-policy.png)
229+
230+
### Viewing a Repository Policy
231+
232+
To retrieve and display a repository policy, use the `sourcetool policy view`
233+
subcommand:
234+
235+
```bash
236+
sourcetool policy view yourorg/yourrepo
237+
```
238+
239+
![](docs/media/image09-policy.png )
240+
241+
## Verifying Commits
242+
243+
Once the SLSA controls are in place, each commit pushed into the repository will
244+
generate source provenance metadata and store it in git notes by default. These
245+
attestations and VSAs can be used to verify the SLSA level of the repository.
246+
247+
To verify a commit, use the `verifycommit` subcommand. Pass it a commit locator
248+
like this:
249+
250+
```bash
251+
sourcetool verifycommit slsa-framework/slsa-source-poc@fc0f59a9332e7873bb146b95cc4b39232eada7d2
252+
```
253+
254+
![](docs/media/image10-pcy-json.png)
255+
256+
If you omit the commit SHA, sourcetool will verify the last commit in the branch.
257+
258+
## Troubleshooting
259+
260+
### Workflow Errors
261+
262+
commit xxx has more than one parent \[...\] which is not supported
263+
This error happens when your repository uses merge commits. While not officially supported, you can enable the experimental support in sourcetool by enabling the `allow-merge-commits` option in the `.github/workflows/compute_slsa_source.yaml` workflow in your repo:
264+
265+
```yaml
266+
uses: slsa-framework/source-actions/.github/workflows/compute\_slsa\_source.yml@main
267+
with:
268+
allow-merge-commits: true
269+
```
80270
81-
## Validate Source Level 3 workflow
271+
### Sourcetool CLI Error Messages
82272
83-
Let's verify that everything is working
273+
**Repository is empty**
84274
85-
1. Make and merge a change to the protected branch (`main`) in **your** repo.
86-
2. Note the digest of **merged** commit
87-
3. Run the verification command
275+
If you initialize a new repo and it does not have any commits yet, onboarding will fail as there are no commits to look for existing provenance. This error should go away after the first push.
88276
89-
`go run github.com/slsa-framework/slsa-source-poc/sourcetool@latest verifycommit --commit <commit digest> --owner <YOUR REPO'S ORG> --repo <YOUR REPO'S NAME> --branch main`
277+
**503 No server is currently available to service your request.**
90278
91-
4. You should see the message
92-
`SUCCESS: commit <commit digest> verified with [SLSA_SOURCE_LEVEL_3]`
279+
This error usually means there is a disruption with GitHub services, usually waiting and retrying should make it go away, optionally check [https://www.githubstatus.com/](https://www.githubstatus.com/) to check for service outages.

‎docs/media/image01-login.png‎

520 KB
Loading

‎docs/media/image02-code.png‎

141 KB
Loading

‎docs/media/image03-logged-as.png‎

32.4 KB
Loading

‎docs/media/image04-status.png‎

371 KB
Loading

‎docs/media/image05-setup-repo.png‎

179 KB
Loading

‎docs/media/image06-confirm-controls.png‎

100 KB
Loading

‎docs/media/image07-confirm-pr.png‎

210 KB
Loading

‎docs/media/image08-policy.png‎

166 KB
Loading

‎docs/media/image09-policy.png‎

310 KB
Loading

0 commit comments

Comments
 (0)