You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
📖 Update README to accept fine-grained tokens (#1175)
* Update README for fine-grained tokens
- Removed "Personal Access Token (PAT) Requirements and Risks" section, which
doesn't apply to fine-grained tokens
- In "Authentication with PAT (Optional)"
- Updated settings for fine-grained permissions
- Removed comment about SAML SSO, which doesn't apply to fine-grained tokens
- In "Troubleshooting", removed items on private repositories and SAML SSO.
- Updated "Workflow example"
Signed-off-by: Pedro Kaj Kjellerup Nacht <[email protected]>
* Add info on classic PATs and risks of Administration
Signed-off-by: Pedro Kaj Kjellerup Nacht <[email protected]>
* Remove comment on deploy keys
Signed-off-by: Pedro Kaj Kjellerup Nacht <[email protected]>
* Permissions only used for branch protection and webhooks
Signed-off-by: Pedro Kaj Kjellerup Nacht <[email protected]>
---------
Signed-off-by: Pedro Kaj Kjellerup Nacht <[email protected]>
Copy file name to clipboardExpand all lines: README.md
+51-43Lines changed: 51 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,11 +14,9 @@ OIDC token which verifies the authenticity of the result when publishing it. See
14
14
15
15
If publishing results, scorecard-action:v2 also imposes new requirements on both the workflow and the job running the `ossf/scorecard-action` step. For full details see [here](#workflow-restrictions).
16
16
________
17
-
[Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks)
and be accessible by all the workflows and maintainers of a repository.**
62
-
This means another maintainer on your project could potentially use the token to impersonate you. If there is an exploitable bug in a workflow with write permissions, an external contributor could potentially exploit it to extract the PAT.
63
-
64
-
We recommend that you **do not use a PAT** unless you feel that the
65
-
risks introduced are outweighed by the functionalities they support.
66
-
67
46
## Installation
68
47
69
48
### Workflow Setup (Required)
@@ -87,27 +66,43 @@ risks introduced are outweighed by the functionalities they support.
87
66
88
67
89
68
90
-
### Authentication with PAT (optional)
91
-
Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret. Review [Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks) before using a PAT.
69
+
### Authentication with Fine-grained PAT (optional)
70
+
Scorecard can run successfully with the workflow's default `GITHUB_TOKEN`.
71
+
However, the `Branch-Protection` and (experimental) `Webhooks` checks require additional data that isn't accessible with that token.
92
72
93
-
1.[Create a Personal Access Token](https://github.com/settings/tokens/new?scopes=public_repo,read:org,read:repo_hook,read:discussion) with the following read permissions:
94
-
- Note: `Token for OSSF Scorecard Action - myorg/myrepo` (Note: replace `myorg/myrepo` with the names of your organization and repository so you can keep track of your tokens.)
95
-
- Expiration: `No expiration`
96
-
- Scopes:
97
-
*`repo > public_repo` Required to read [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) settings. **Note**: for private repositories, you need scope `repo`.
98
-
*`admin:org > read:org` Optional: not used in current implementation.
99
-
*`admin:repo_hook > read:repo_hook` Optional: needed for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check.
100
-
*`write:discussion > read:discussion` Optional: not used in current implementation.
73
+
We therefore suggest you create a fine-grained Personal Access Token (PAT) that Scorecard may use for authentication.
101
74
102
-
75
+
1.[Create a fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with the following settings:
(Note: replace `$USER_NAME/$REPO_NAME` with the names of your organization and repository so you can keep track of your tokens.)
78
+
- Expiration: Set `Custom` and then set the date to exactly a year in the future (the maximum allowed)
79
+
- Repository Access: `Only select repositories` and select the desired repository.
80
+
Alternatively, set `All repositories` if you wish to use the same token for all your repositories.
81
+
- Repository Permissions:
82
+
*`Administration: Read-only`: Required to read [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) settings.
83
+
*`Metadata: Read-only` will be automatically set when you set `Administration`
84
+
*`Webhooks: Read-only`: (Optional) required for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check.
85
+
86
+
**Disclaimer:** Scorecard uses these permissions solely to learn about the project's branch protection rules and webhooks.
87
+
However, the token can read many of the project's settings
88
+
(for a full list, see the queries marked `(read)` in [GitHub's documentation](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2022-11-28#administration)).
89
+
90
+
"Classic" tokens with `repo` scope also work.
91
+
However, these carry significantly higher risks compared to fine-grained PATs
92
+
(see ["Classic" Personal Access Token (PAT) Requirements and Risks](#classic-personal-access-token-pat-requirements-and-risks))
93
+
and are therefore strongly discouraged.
94
+
95
+
103
96
104
97
2. Copy the token value.
105
98
106
99
3.[Create a new repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) with the following settings (**Warning:**[GitHub encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) are accessible by all the workflows and maintainers of a repository.):
107
100
- Name: `SCORECARD_TOKEN`
108
101
- Value: the value of the token created in step 1 above.
109
102
110
-
4. (Optional) If you install Scorecard on a repository owned by an organization that uses [SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on), be sure to [enable SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for your PAT token.
103
+
Note that fine-grained tokens expire after one year. You'll receive an email from GitHub when your token is about to expire, at which point you must regenerate it. Make sure to update the token string in your repository's secrets.
104
+
105
+
4. When you call the `ossf/scorecard-action` in your workflow, pass the token as `repo-token: ${{ secrets.SCORECARD_TOKEN }}`.
111
106
112
107
## View Results
113
108
@@ -142,11 +137,9 @@ To verify that the Action is running successfully, click the repository's Action
142
137
143
138
144
139
### Troubleshooting
145
-
If the run has failed, the most likely reason is an authentication failure. If you are running Scorecards on a private repository, confirm that the Personal Access Token is saved as an encrypted secret within the same repository (see [Authentication](#authentication)). In addition, provide the `repo` scope to your PAT. (The `repo > public_repo` scope only provides access to public repositories).
140
+
If the run has failed, the most likely reason is an authentication failure. Confirm that the Personal Access Token is saved as an encrypted secret within the same repository (see [Authentication](#authentication)). Also confirm that the PAT is still valid and hasn't expired or been revoked.
146
141
147
-
If you install Scorecards on a repository owned by an organization that uses [SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/about-authentication-with-saml-single-sign-on) or if you see `403 Resource protected by organization SAML enforcement` in the logs, be sure to [enable SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) for your PAT token (see [Authentication](#authentication)).
148
-
149
-
If you use a PAT saved as an encrypted secret and the run is still failing, confirm that you have not made any changes to the workflow yaml file that affected the syntax. Review the [workflow example](#workflow-example) and reset to the default values if necessary.
142
+
If you have a valid PAT saved as an encrypted secret and the run is still failing, confirm that you have not made any changes to the workflow yaml file that affected the syntax. Review the [workflow example](#workflow-example) and reset to the default values if necessary.
150
143
151
144
## Manual Action Setup
152
145
@@ -237,10 +230,9 @@ jobs:
237
230
with:
238
231
results_file: results.sarif
239
232
results_format: sarif
240
-
# (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
233
+
# (Optional) fine-grained personal access token. Uncomment the `repo_token` line below if:
241
234
# - you want to enable the Branch-Protection check on a *public* repository, or
242
-
# - you are installing Scorecards on a *private* repository
243
-
# To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
235
+
# To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-fine-grained-pat-optional.
244
236
# repo_token: ${{ secrets.SCORECARD_TOKEN }}
245
237
246
238
# Publish the results for public repositories to enable scorecard badges. For more details, see
@@ -264,3 +256,19 @@ jobs:
264
256
with:
265
257
sarif_file: results.sarif
266
258
```
259
+
260
+
## "Classic" Personal Access Token (PAT) Requirements and Risks
261
+
Certain features require a Personal Access Token (PAT).
262
+
We recommend you use a fine-grained token as described in [Authentication](#authentication-with-fine-grained-pat-optional).
263
+
A "classic" PAT also works, but we strongly discourage its use.
264
+
265
+
Due to a limitation of the "classic" tokens' permission model,
266
+
the PAT needs [write permission to the repository](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) through the `repo` scope.
267
+
**The PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
268
+
and be accessible by all of the repository's workflows and maintainers.**
269
+
This means another maintainer on your project could potentially use the token to impersonate you.
270
+
If there is an exploitable bug in a workflow with write permissions,
271
+
an external contributor could potentially exploit it to extract the PAT.
272
+
273
+
The only benefit of a "classic" PAT is that it can be set to never expire.
274
+
However, we believe this does not outweigh the significantly higher risk of "classic" PATs compared to fine-grained PATs.
0 commit comments