From 309612cb8b9ae02f6e73d71c42e7a5160f8de335 Mon Sep 17 00:00:00 2001 From: olivekl <83081275+olivekl@users.noreply.github.com> Date: Tue, 6 Dec 2022 13:03:43 -0500 Subject: [PATCH 1/3] Add section explaining PAT risks --- README.md | 71 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 41 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index dd0902e2..0a489f9d 100644 --- a/README.md +++ b/README.md @@ -45,44 +45,33 @@ The `pull_request` and `workflow_dispatch` triggers are experimental. Running the Scorecard action on a fork repository is not supported. -Private repositories need a Personal Access Token (PAT). - -Public repositories need a PAT to enable the [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) check. Without a PAT, Scorecards will run all checks except the Branch-Protection check. Due to a limitation of the GitHub permission model, the PAT needs [write permisison to the repository](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) through the `repo` scope. **Warning:** the PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) and be accessible by all the workflows and maintainers of a repository. - GitHub Enterprise repositories are not supported. -## Installation -The Scorecards Action is installed by setting up a workflow on the GitHub UI. +## Personal Access Token (PAT) Requirements and Risks -**Private repositories**: Scorecards requires authentication using a Personal Access Token (PAT). If you install Scorecard on a private repository, you must follow the optional Authentication step for Scorecard to run. If you don't, Scorecards will fail to run. **Warning:** the PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) and be accessible by all the workflows and maintainers of a repository. +Certain features require a Personal Access Token (PAT). -**Public repositories**: One Scorecards check ([Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection)) requires authentication using a Personal Access Token (PAT). If you want all Scorecards checks to run on a public repository, you will need to follow the optional Authentication step. If you don't, all checks will run except Branch-Protection. **Warning:** the PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) and be accessible by all the workflows and maintainers of a repository. +- Public repositories need a PAT to enable the + [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) + check. Without a PAT, Scorecards will run all checks except the + Branch-Protection check +- Private repositories need a PAT to use any Scorecard Action functions. -**Optional Authentication**: Create a Personal Access Token (PAT) for authentication and save the token value as a repository secret. (Note: If you have already installed Scorecards on your repository from the command line, you can reuse your existing PAT for the repository secret. If you no longer have access to the PAT, though, simply create a new one.) +Using a PAT introduces risks, however. Due to a limitation of the GitHub +permission model, 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. **The PAT will be stored as a +[GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) +and be accessible by all the workflows and maintainers of a repository. [can we +add one more sentence explaining in plain language what could go wrong +here?]** -**Required**: Set up the workflow via the GitHub UI - see [Workflow Setup](#workflow-setup) +We strongly recommend that you **do not use a PAT** unless you feel that the +risks introduced are outweighed by the functionality they support. -### Authentication with PAT -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: - - 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.) - - Expiration: `No expiration` - - Scopes: - * `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`. - * `admin:org > read:org` Optional: not used in current implementation. - * `admin:repo_hook > read:repo_hook` Optional: needed for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check. - * `write:discussion > read:discussion` Optional: not used in current implementation. - -![image](/images/tokenscopes.png) - -2. Copy the token value. - -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.): - - Name: `SCORECARD_TOKEN` - - Value: the value of the token created in step 1 above. - -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. +## Installation -### Workflow Setup +### Workflow Setup (Required) 1) From your GitHub project's main page, click “Security” in the top ribbon. ![image](/images/install01.png) @@ -107,6 +96,28 @@ Then click "Add More Scanning Tools." ![image](/images/install04.png) +### Authentication with PAT (optional) +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. + +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: + - 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.) + - Expiration: `No expiration` + - Scopes: + * `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`. + * `admin:org > read:org` Optional: not used in current implementation. + * `admin:repo_hook > read:repo_hook` Optional: needed for the experimental [Webhook](https://github.com/ossf/scorecard/blob/main/docs/checks.md#webhooks) check. + * `write:discussion > read:discussion` Optional: not used in current implementation. + +![image](/images/tokenscopes.png) + +2. Copy the token value. + +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.): + - Name: `SCORECARD_TOKEN` + - Value: the value of the token created in step 1 above. + +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. + ## View Results The workflow is preconfigured to run on every repository contribution. After making a code change, you can view the results for the change either through the Scorecard Badge, Code Scanning Alerts or GitHub Workflow Runs. From ee79404eb7dbbcee2c866e4055e6c8e026bc0cdb Mon Sep 17 00:00:00 2001 From: olivekl <83081275+olivekl@users.noreply.github.com> Date: Tue, 6 Dec 2022 13:25:43 -0500 Subject: [PATCH 2/3] Update README.md Update TOC Add plain language explanation of PAT risks --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0a489f9d..769f0034 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,11 @@ If you are using custom steps in the job, it may fail. We understand that this is restrictive, but currently it's necessary to ensure the integrity of the results that we publish, since GitHub workflow steps run in the same environment as the job they belong to. If possible, we will work on making this feature more flexible so we can drop this requirement in the future. ________ +[Personal Access Token (PAT) Requirements and Risks](#personal-access-token-pat-requirements-and-risks) + [Installation](#installation) -- [Authentication](#authentication-with-pat) -- [Workflow Setup](#workflow-setup) +- [Workflow Setup](#workflow-setup-required) +- [Authentication](#authentication-with-pat-optional) [View Results](#view-results) - [REST API](#rest-api) @@ -62,9 +64,8 @@ permission model, 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. **The PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) -and be accessible by all the workflows and maintainers of a repository. [can we -add one more sentence explaining in plain language what could go wrong -here?]** +and be accessible by all the workflows and maintainers of a repository. +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. We strongly recommend that you **do not use a PAT** unless you feel that the risks introduced are outweighed by the functionality they support. @@ -97,7 +98,7 @@ Then click "Add More Scanning Tools." ![image](/images/install04.png) ### Authentication with PAT (optional) -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. +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. 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: - 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.) From 7004fa762786661c6e29bad492234c6291638a51 Mon Sep 17 00:00:00 2001 From: olivekl <83081275+olivekl@users.noreply.github.com> Date: Tue, 6 Dec 2022 13:28:43 -0500 Subject: [PATCH 3/3] Update README.md Fix formatting --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 769f0034..0a537637 100644 --- a/README.md +++ b/README.md @@ -57,18 +57,18 @@ Certain features require a Personal Access Token (PAT). [Branch-Protection](https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection) check. Without a PAT, Scorecards will run all checks except the Branch-Protection check -- Private repositories need a PAT to use any Scorecard Action functions. +- Private repositories need a PAT to use any Scorecard Action functions Using a PAT introduces risks, however. Due to a limitation of the GitHub permission model, 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. **The PAT will be stored as a [GitHub encrypted secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) -and be accessible by all the workflows and maintainers of a repository. +and be accessible by all the workflows and maintainers of a repository.** 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. We strongly recommend that you **do not use a PAT** unless you feel that the -risks introduced are outweighed by the functionality they support. +risks introduced are outweighed by the functionalities they support. ## Installation