Official GitHub Action for OSSF Scorecards.
The Scorecards GitHub Action is free for all public repositories. Private repositories are supported if they have GitHub Advanced Security. Private repositories without GitHub Advanced Security can run Scorecards from the command line by following the standard installation instructions.
Starting from scorecard-action:v2, GITHUB_TOKEN permissions or job permissions needs to include
id-token: write for publish_results: true. This is needed to access GitHub's
OIDC token which verifies the authenticity of the result when publishing it.
scorecard-action:v2 has a new requirement for the job running the ossf/scorecard-action step. The step running this job must belong to this approved list of GitHub actions:
- "actions/checkout"
- "actions/upload-artifact"
- "github/codeql-action/upload-sarif"
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.
The following GitHub triggers are supported: push, schedule (default branch only).
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 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 through the repo scope. Warning: the PAT will be stored as a GitHub encrypted secret and be accessible by all the workflows and maintainers of a repository.
GitHub Enterprise repositories are not supported.
The Scorecards Action is installed by setting up a workflow on the GitHub UI.
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 and be accessible by all the workflows and maintainers of a repository.
Public repositories: One Scorecards check (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 and be accessible by all the workflows and maintainers of a repository.
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.)
Required: Set up the workflow via the GitHub UI - see Workflow Setup
- Create a Personal Access Token with the following read permissions:
- Note:
Token for OSSF Scorecard Action - myorg/myrepo(Note: replacemyorg/myrepowith the names of your organization and repository so you can keep track of your tokens.) - Expiration:
No expiration - Scopes:
repo > public_repoRequired to read Branch-Protection settings. Note: for private repositories, you need scoperepo.admin:org > read:orgOptional: not used in current implementation.admin:repo_hook > read:repo_hookOptional: needed for the experimental Webhook check.write:discussion > read:discussionOptional: not used in current implementation.
- Note:
-
Copy the token value.
-
Create a new repository secret with the following settings (Warning: GitHub 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.
- Name:
-
(Optional) If you install Scorecard on a repository owned by an organization that uses SAML SSO, be sure to enable SSO for your PAT token.
- From your GitHub project's main page, click “Security” in the top ribbon.
- Click “Set up Code Scanning.”
Note: if you have already 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.
Then click "Add More Scanning Tools."
- Choose the "OSSF Scorecards supply-chain security analysis" from the list of workflows, and then click “set up this workflow.”
- Commit the changes.
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.
Starting with scorecard-action:v2, users can use a REST API to query their latest run results. This requires setting publish_results: true for the action and enabling id-token: write permission for the job (needed to access GitHub OIDC token). The API is available here: https://api.securityscorecards.dev.
Starting with scorecard-action:v2, users can add a Scorecard Badge to their README to display the latest status of their Scorecard results. This requires setting publish_results: true for the action and enabling id-token: write permission for the job (needed to access GitHub OIDC token). The badge is updated on every run of scorecard-action and points to the latest result. To add a badge to your README, copy and paste the below lines:
[![OpenSSF Scorecard]
(https://api.securityscorecards.dev/projects/github.com/{org}/{repo}/badge)]
(https://api.securityscorecards.dev/projects/github.com/{org}/{repo})
Once this badge is added, clicking on the badge will take users to the latest run result of Scorecard.
A list of results is accessible by going in the Security tab and clicking "Code Scanning Alerts" (it can take a couple minutes for the run to complete and the results to show up). Click on the individual alerts for more information, including remediation instructions. You will need to click "Show more" to expand the full remediation instructions.
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. This tab will also show the logs, which can help you troubleshoot if the run failed.
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). In addition, provide the repo scope to your PAT. (The repo > public_repo scope only provides access to public repositories).
If you install Scorecards on a repository owned by an organization that uses SAML SSO or if you see 403 Resource protected by organization SAML enforcement in the logs, be sure to enable SSO for your PAT token (see Authentication).
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 and reset to the default values if necessary.
If you prefer to manually set up the Scorecards GitHub Action, you will need to set up a workflow file.
First, create a new file in this location: [yourrepo]/.github/workflows/scorecards.yml. Then use the input values below.
| 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 |
no | PAT token with write repository access. Follow these steps 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. |
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.
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 also needed to enable badges on the repository (release scheduled for Q2'22).
The Scorecards Action uses the artifact uploader action to upload results in SARIF format to the Actions tab. These results are available to anybody for five days after the run to help with debugging. To disable the upload, comment out the Upload Artifact value in the Workflow Example.
Note: if you disable this option, the results of the Scorecards Action run will be available only to maintainers (on the Security tab scanning dashboard).
name: Scorecards supply-chain security
on:
# Only the default branch is supported.
branch_protection_rule:
schedule:
# Weekly on Saturdays.
- cron: '30 1 * * 6'
push:
branches: [ main, master ]
# Declare default permissions as read only.
permissions: read-all
jobs:
analysis:
name: Scorecards analysis
runs-on: ubuntu-latest
permissions:
# Needed to upload the results to code-scanning dashboard.
security-events: write
# Used to receive a badge. (Upcoming feature)
id-token: write
actions: read
contents: read
steps:
- name: "Checkout code"
uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846 # tag=v3.0.0
with:
persist-credentials: false
- name: "Run analysis"
uses: ossf/scorecard-action@3e15ea8318eee9b333819ec77a36aca8d39df13e # tag=v1.1.1
with:
results_file: results.sarif
results_format: sarif
# (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
# - you want to enable the Branch-Protection check on a *public* repository, or
# - you are installing Scorecards on a *private* repository
# To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
# 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). Commenting out will disable uploads of run results in SARIF
# format to the repository Actions tab.
- name: "Upload artifact"
uses: actions/upload-artifact@6673cd052c4cd6fcf4b4e6e60ea986c889389535 # tag=v3.0.0
with:
name: SARIF file
path: results.sarif
retention-days: 5
# Upload the results to GitHub's code scanning dashboard.
- name: "Upload to code-scanning"
uses: github/codeql-action/upload-sarif@5f532563584d71fdef14ee64d17bafb34f751ce5 # tag=v1.0.26
with:
sarif_file: results.sarif