diff --git a/README.md b/README.md index 3d53e79b..14c765c8 100644 --- a/README.md +++ b/README.md @@ -2,41 +2,92 @@ [![CodeQL](https://github.com/ossf/scorecard-action/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/ossf/scorecard-action/actions/workflows/codeql-analysis.yml) > Official GitHub Action for [OSSF scorecard](https://github.com/ossf/scorecard). -## Installation -The simplest and quickest way to install Scorecards's GitHub action is from the [GitHub's marketplace](https://github.com/marketplace/actions/ossf-scorecard-action). -**WARNING**: the action does *not* support private repositories. +The Scorecards GitHub Action is free for all public repositories. Private repositories are supported if they have [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security). Private repositories without GitHub Advanced Security can run Scorecards from the command line by following the [standard installation instructions](https://github.com/ossf/scorecard#installation). -### Inputs +## Installation +To install the Scorecards GitHub Action, you need to: -| Name | Required | Description | -| ----- | -------- | ----------- | -| `result_file` | yes | The file that contains the results. | -| `result_format` | yes | The format in which to store the results [json \| sarif]. For GitHub's scanning dashboard, select `sarif`. | -| `repo_token` | yes | PAT token with read-only access. Follow [these steps](#pat-token-creation) to create it. | -| `publish_results` | recommended | This will allow you to display a badge on your repository to show off your hard work (release scheduled for Q2'22). See details [here](#publishing-results).| +1) 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.) + +3) Set up the workflow via the GitHub UI -### PAT token creation -1. Create a PAT token [here](https://github.com/settings/tokens/new) with the following read permissions: - - Note: `Read-only token for OSSF Scorecard Action` +### Authentication +1. [Create a Personal Access Token](https://github.com/settings/tokens/new) with the following read permissions: + - Note: `Read-only 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` * `admin:org > read:org` * `admin:repo_hook > read:repo_hook` * `write:discussion > read:discussion` - - Create and copy the token. -2. Create a new repository secret at `https://github.com///settings/secrets/actions/new` with the following settings: - - Name: `SCORECARD_TOKEN` +![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: + - Name: `SCORECARD_READ_TOKEN` - Value: the value of the token created in step 1 above. +### Workflow Setup +1) From your GitHub project's main page, click “Security” in the top ribbon. + +![image](/images/install01.png) + +2) Click “Set up Code Scanning.” + +![image](/images/install02.png) + +Note: if you have aleady configured other code scanning tools, your UI will look different than shown above. Instead, click "Code Scanning Alerts" on the left side of the page. + +![image](/images/installb1.png) + +Then click "Add More Scanning Tools." + +![image](/images/installb2.png) + +3) Choose the "OSSF Scorecards supply-chain security analysis" from the list of workflows, and then click “set up this workflow.” + +![image](/images/install03.png) + +4) Commit the changes. + +![image](/images/install04.png) + +## Verify Runs and View Results +The workflow is preconfigured to run on every repository contribution. + +To verify that the Action is running successfully, click the repository's Actions tab to see the status of all recent workflow runs. + +![image](/images/actionconfirm.png) + +To view a list of results from each Scorecards Action run, go to the Security tab and click "Code Scanning Alerts." Click on the individual alerts for more information, including remediation instructions. You will need to click "Show more" to expand the full remediation instructions. + +![image](/images/remediation.png) + + +## Manual Action Set Up + +If you prefer to manually set up the Scorecards GitHub Action, use the following values. + +### Inputs + +| Name | Required | Description | +| ----- | -------- | ----------- | +| `result_file` | yes | The file that contains the results. | +| `result_format` | yes | The format in which to store the results [json \| sarif]. For GitHub's scanning dashboard, select `sarif`. | +| `repo_token` | yes | PAT token with read-only access. Follow [these steps](#pat-token-creation) to create it. | +| `publish_results` | recommended | This will allow you to display a badge on your repository to show off your hard work (release scheduled for Q2'22). See details [here](#publishing-results).| + ### Publishing results The Scorecard team runs a weekly scan of public GitHub repositories in order to track -the overall security health of the open source ecosystem. The results of the scans are publicly -available as described [here](https://github.com/ossf/scorecard#public-data). -Setting `publish_results: true` replaces the results of the team's weelky scans, +the overall security health of the open source ecosystem. The results of the scans are [publicly +available](https://github.com/ossf/scorecard#public-data). +Setting `publish_results: true` replaces the results of the team's weekly scans with your own scan results, helping us scale by cutting down on repeated workflows and GitHub API requests. -This option is needed to enable badges on the repository (release scheduled for Q2'22). +This option is also needed to enable badges on the repository (release scheduled for Q2'22). ### Full example @@ -77,9 +128,11 @@ jobs: results_format: sarif # Read-only PAT token. To create it, # follow the steps in https://github.com/ossf/scorecard-action#pat-token-creation. - repo_token: ${{ secrets.SCORECARD_READ_TOKEN }} - # Publish the results to enable scorecard badges. For more details, see - # https://github.com/ossf/scorecard-action#publishing-results. + repo_token: ${{ secrets.SCORECARD_TOKEN }} + # Publish the results for public repositories to enable scorecard badges. For more details, see + # https://github.com/ossf/scorecard-action#publishing-results. + # For private repositories, `publish_results` will automatically be set to `false`, regardless + # of the value entered here. publish_results: true # Upload the results as artifacts (optional). diff --git a/images/actionconfirm.png b/images/actionconfirm.png new file mode 100644 index 00000000..93db524e Binary files /dev/null and b/images/actionconfirm.png differ diff --git a/images/install01.png b/images/install01.png new file mode 100644 index 00000000..1a692d6f Binary files /dev/null and b/images/install01.png differ diff --git a/images/install02.png b/images/install02.png new file mode 100644 index 00000000..b36d25b1 Binary files /dev/null and b/images/install02.png differ diff --git a/images/install03.png b/images/install03.png new file mode 100644 index 00000000..0ecd00d4 Binary files /dev/null and b/images/install03.png differ diff --git a/images/install04.png b/images/install04.png new file mode 100644 index 00000000..772a2aa6 Binary files /dev/null and b/images/install04.png differ diff --git a/images/installb1.png b/images/installb1.png new file mode 100644 index 00000000..8da2aa72 Binary files /dev/null and b/images/installb1.png differ diff --git a/images/installb2.png b/images/installb2.png new file mode 100644 index 00000000..171bcbcc Binary files /dev/null and b/images/installb2.png differ diff --git a/images/remediation.png b/images/remediation.png new file mode 100644 index 00000000..c545a661 Binary files /dev/null and b/images/remediation.png differ diff --git a/images/tokenscopes.png b/images/tokenscopes.png new file mode 100644 index 00000000..473c5ec6 Binary files /dev/null and b/images/tokenscopes.png differ