- Notifications
You must be signed in to change notification settings - Fork0
OpenSSF Scorecard - Security health metrics for Open Source
License
nokia/scorecard
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
- Default Scorecard Checks
- Detailed Check Documentation (Scoring Criteria, Risks, andRemediation)
- Report Problems
- Code of Conduct
- Contribute to Scorecard
- Add a New Check
- Connect with the Scorecard Community
- Report a Security Issue
We created Scorecard to help open source maintainers improve their securitybest practices and to help open source consumers judge whether their dependenciesare safe.
Scorecard is an automated tool that assesses a number of important heuristics("checks") associated with software security and assignseach check a score of 0-10. You can use these scores to understand specificareas to improve in order to strengthen the security posture of your project.You can also assess the risks that dependencies introduce, and make informeddecisions about accepting these risks, evaluating alternative solutions, orworking with the maintainers to make improvements.
The inspiration for Scorecard’s logo:"You passed! All D's ... and an A!"
Automate analysis and trust decisions on the security posture of open sourceprojects.
Use this data to proactively improve the security posture of the criticalprojects the world depends on.
Scorecard has been run on thousands of projects to monitor and track securitymetrics. Prominent projects that use Scorecard include:
We run a weekly Scorecard scan of the 1 million most critical open sourceprojects judged by their direct dependencies and publish the results in aBigQuery public dataset.
This data is available in the public BigQuery datasetopenssf:scorecardcron.scorecard-v2. The latest results are available in theBigQuery viewopenssf:scorecardcron.scorecard-v2_latest.
You can query the data usingBigQuery Explorer by navigating to Add Data > Star a project by name > 'openssf'.For example, you may be interested in how a project's score has changed over time:
SELECTdate, scoreFROM`openssf.scorecardcron.scorecard-v2`WHERErepo.name="github.com/ossf/scorecard"ORDER BYdateASC
You can extract the latest results to Google Cloud storage in JSON format usingthebq tool:
# Get the latest PARTITION_IDbq query --nouse_legacy_sql 'SELECT partition_id FROMopenssf.scorecardcron.INFORMATION_SCHEMA.PARTITIONS WHERE table_name="scorecard-v2"AND partition_id!="__NULL__" ORDER BY partition_id DESCLIMIT 1'# Extract to GCSbq extract --destination_format=NEWLINE_DELIMITED_JSON'openssf:scorecardcron.scorecard-v2$<partition_id>' gs://bucket-name/filename-*.jsonThe list of projects that are checked is available in thecron/internal/data/projects.csvfile in this repository. If you would like us to track more, please feel free tosend a Pull Request with others. Currently, this list is derived fromprojectshosted on GitHub ONLY. We do plan to expand them in near future to account forprojects hosted on other source control systems.
The easiest way to use Scorecard on GitHub projects you own is with theScorecard GitHub Action. The Actionruns on any repository change and issues alerts that maintainers can view in therepository’s Security tab. For more information, see the Scorecard GitHubActioninstallation instructions.
To query pre-calculated scores of OSS projects, use theREST API.
To enable your project to be available on the REST API, setpublish_results: truein the Scorecard GitHub Action setting.
Enablingpublish_results: truein Scorecard GitHub Actions also allows maintainers to display a Scorecard badge on their repository to show off theirhard work. This badge also auto-updates for every change made to the repository. See more details onthis OSSF blogpost.
To include a badge on your project's repository, simply add the following markdown to your README:
[](https://securityscorecards.dev/viewer/?uri=github.com/{owner}/{repo})To run a Scorecard scan on projects you do not own, use the command lineinterface installation option.
Platforms: Currently, Scorecard supports OSX and Linux platforms. If you areusing a Windows OS you may experience issues. Contributions towards supportingWindows are welcome.
Language: You must have GoLang installed to run Scorecard(https://golang.org/doc/install)
scorecard is available as a Docker container:
docker pull gcr.io/openssf/scorecard:stable
To use a specific scorecard version (e.g., v3.2.1), run:
docker pull gcr.io/openssf/scorecard:v3.2.1
To install Scorecard as a standalone:
Visit our latestrelease page anddownload the correct zip file for your operating system.
Add the binary to yourGOPATH/bin directory (usego env GOPATH to identify your directory if necessary).
We generateSLSA3 signatures using the OpenSSF'sslsa-framework/slsa-github-generator during the release process. To verify a release binary:
- Install the verification tool fromslsa-framework/slsa-verifier#installation.
- Download the signature file
attestation.intoto.jsonlfrom theGitHub releases page. - Run the verifier:
slsa-verifier -artifact-path<the-zip> -provenance attestation.intoto.jsonl -source github.com/ossf/scorecard -tag<the-tag>
| Package Manager | Supported Distribution | Command |
|---|---|---|
| Nix | NixOS | nix-shell -p nixpkgs.scorecard |
| AUR helper | Arch Linux | Use your AUR helper to installscorecard |
| Homebrew | macOS or Linux | brew install scorecard |
GitHub imposesapi rate limitson unauthenticated requests. To avoid these limits, you must authenticate yourrequests before running Scorecard. There are two ways to authenticate yourrequests: either create a GitHub personal access token, or create a GitHub AppInstallation.
- Create a classic GitHub personal access token.When creating the personal access token, we suggest you choose the
public_reposcope. Set the token in an environment variable calledGITHUB_AUTH_TOKEN,GITHUB_TOKEN,GH_AUTH_TOKENorGH_TOKENusing thecommands below according to your platform.
# For posix platforms, e.g. linux, mac:export GITHUB_AUTH_TOKEN=<your access token># Multiple tokens can be provided separated by comma to be utilized# in a round robin fashion.export GITHUB_AUTH_TOKEN=<your access token1>,<your access token2># For windows:set GITHUB_AUTH_TOKEN=<your access token>set GITHUB_AUTH_TOKEN=<your access token1>,<your access token2>
OR
- Create a GitHub App Installationfor higher rate-limit quotas. If you have an installed GitHub App and keyfile, you can use the three environment variables below, following thecommands (
setorexport) shown above for your platform.
GITHUB_APP_KEY_PATH=<path to the key file on disk>GITHUB_APP_INSTALLATION_ID=<installation id>GITHUB_APP_ID=<app id>These variables can be obtained from the GitHubdeveloper settings page.
Scorecard can run using just one argument, the URL of the target repo:
$ scorecard --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2eStarting [CII-Best-Practices]Starting [Fuzzing]Starting [Pinned-Dependencies]Starting [CI-Tests]Starting [Maintained]Starting [Packaging]Starting [SAST]Starting [Dependency-Update-Tool]Starting [Token-Permissions]Starting [Security-Policy]Starting [Signed-Releases]Starting [Binary-Artifacts]Starting [Branch-Protection]Starting [Code-Review]Starting [Contributors]Starting [Vulnerabilities]Finished [CI-Tests]Finished [Maintained]Finished [Packaging]Finished [SAST]Finished [Signed-Releases]Finished [Binary-Artifacts]Finished [Branch-Protection]Finished [Code-Review]Finished [Contributors]Finished [Dependency-Update-Tool]Finished [Token-Permissions]Finished [Security-Policy]Finished [Vulnerabilities]Finished [CII-Best-Practices]Finished [Fuzzing]Finished [Pinned-Dependencies]RESULTS-------Aggregate score: 7.9 / 10Check scores:|---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| SCORE| NAME| REASON| DOCUMENTATION/REMEDIATION||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 10 / 10| Binary-Artifacts| no binaries foundin the repo| github.com/ossf/scorecard/blob/main/docs/checks.md#binary-artifacts||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 9 / 10| Branch-Protection| branch protection is not| github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection|||| maximal on development and all||||| release branches|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------||?| CI-Tests| no pull request found| github.com/ossf/scorecard/blob/main/docs/checks.md#ci-tests||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| CII-Best-Practices| no badge found| github.com/ossf/scorecard/blob/main/docs/checks.md#cii-best-practices||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 10 / 10| Code-Review| branch protectionfor default| github.com/ossf/scorecard/blob/main/docs/checks.md#code-review|||| branch is enabled|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| Contributors| 0 different companies found --| github.com/ossf/scorecard/blob/main/docs/checks.md#contributors|||| score normalized to 0|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| Dependency-Update-Tool| no update tool detected| github.com/ossf/scorecard/blob/main/docs/checks.md#dependency-update-tool||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| Fuzzing| project is not fuzzedin| github.com/ossf/scorecard/blob/main/docs/checks.md#fuzzing|||| OSS-Fuzz|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 1 / 10| Maintained| 2 commit(s) foundin the last| github.com/ossf/scorecard/blob/main/docs/checks.md#maintained|||| 90 days -- score normalized to||||| 1|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------||?| Packaging| no published package detected| github.com/ossf/scorecard/blob/main/docs/checks.md#packaging||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 8 / 10| Pinned-Dependencies| unpinned dependencies detected| github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies|||| -- score normalized to 8|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| SAST| no SAST tool detected| github.com/ossf/scorecard/blob/main/docs/checks.md#sast||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 0 / 10| Security-Policy| security policy file not| github.com/ossf/scorecard/blob/main/docs/checks.md#security-policy|||| detected|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------||?| Signed-Releases| no releases found| github.com/ossf/scorecard/blob/main/docs/checks.md#signed-releases||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 10 / 10| Token-Permissions| tokens are read-onlyin GitHub| github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions|||| workflows|||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|| 10 / 10| Vulnerabilities| no vulnerabilities detected| github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities||---------|------------------------|--------------------------------|---------------------------------------------------------------------------|
TheGITHUB_AUTH_TOKEN has to be set to a validtoken
docker run -e GITHUB_AUTH_TOKEN=token gcr.io/openssf/scorecard:stable --show-details --repo=https://github.com/ossf/scorecard
To use a specific scorecard version (e.g., v3.2.1), run:
docker run -e GITHUB_AUTH_TOKEN=token gcr.io/openssf/scorecard:v3.2.1 --show-details --repo=https://github.com/ossf/scorecard
For more details about why a check fails, use the--show-details option:
./scorecard --repo=github.com/ossf-tests/scorecard-check-branch-protection-e2e --checks Branch-Protection --show-detailsStarting [Pinned-Dependencies]Finished [Pinned-Dependencies]RESULTS-------|---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------|| SCORE | NAME | REASON | DETAILS | DOCUMENTATION/REMEDIATION ||---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------|| 9 / 10 | Branch-Protection | branch protection is not | Info: 'force pushes' disabled | github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection || | | maximal on development and all | on branch 'main' Info: 'allow | || | | release branches | deletion' disabled on branch | || | | | 'main' Info: linear history | || | | | enabled on branch 'main' Info: | || | | | strict status check enabled | || | | | on branch 'main' Warn: status | || | | | checks for merging have no | || | | | specific status to check on | || | | | branch 'main' Info: number | || | | | of required reviewers is 2 | || | | | on branch 'main' Info: Stale | || | | | review dismissal enabled on | || | | | branch 'main' Info: Owner | || | | | review required on branch | || | | | 'main' Info: 'admininistrator' | || | | | PRs need reviews before being | || | | | merged on branch 'main' | ||---------|------------------------|--------------------------------|--------------------------------|---------------------------------------------------------------------------|To use a GitHub Enterprise hostgithub.corp.com, use theGH_HOST environment variable.
# Set the GitHub Enterprise host without https prefix or slash with relevant authentication tokenexport GH_HOST=github.corp.comexport GITHUB_AUTH_TOKEN=tokenscorecard --repo=github.corp.com/org/repo# OR without github host urlscorecard --repo=org/repo
For projects in the--npm,--pypi,--rubygems, or--nuget ecosystems, you have theoption to run Scorecard using a package manager. Provide the package name torun the checks on the corresponding GitHub source code.
For example,--npm=angular.
To run only specific check(s), add the--checks argument with a list of checknames.
For example,--checks=CI-Tests,Code-Review.
The currently supported formats aredefault (text) andjson.
These may be specified with the--format flag. For example,--format=json.
The following checks are all run against the target project by default:
| Name | Description | Risk Level | Token Required | GitLab Support | Note |
|---|---|---|---|---|---|
| Binary-Artifacts | Is the project free of checked-in binaries? | High | PAT, GITHUB_TOKEN | Supported | |
| Branch-Protection | Does the project useBranch Protection ? | High | PAT (repo orrepo> public_repo), GITHUB_TOKEN | Supported (see notes) | certain settings are only supported with a maintainer PAT |
| CI-Tests | Does the project run tests in CI, e.g.GitHub Actions,Prow? | Low | PAT, GITHUB_TOKEN | Supported | |
| CII-Best-Practices | Has the project earned anOpenSSF (formerly CII) Best Practices Badge at the passing, silver, or gold level? | Low | PAT, GITHUB_TOKEN | Validating | |
| Code-Review | Does the project practice code review before code is merged? | High | PAT, GITHUB_TOKEN | Validating | |
| Contributors | Does the project have contributors from at least two different organizations? | Low | PAT, GITHUB_TOKEN | Validating | |
| Dangerous-Workflow | Does the project avoid dangerous coding patterns in GitHub Action workflows? | Critical | PAT, GITHUB_TOKEN | Unsupported | |
| Dependency-Update-Tool | Does the project use tools to help update its dependencies? | High | PAT, GITHUB_TOKEN | Unsupported | |
| Fuzzing | Does the project use fuzzing tools, e.g.OSS-Fuzz,QuickCheck orfast-check? | Medium | PAT, GITHUB_TOKEN | Validating | |
| License | Does the project declare a license? | Low | PAT, GITHUB_TOKEN | Validating | |
| Maintained | Is the project at least 90 days old, and maintained? | High | PAT, GITHUB_TOKEN | Validating | |
| Pinned-Dependencies | Does the project declare and pindependencies? | Medium | PAT, GITHUB_TOKEN | Validating | |
| Packaging | Does the project build and publish official packages from CI/CD, e.g.GitHub Publishing ? | Medium | PAT, GITHUB_TOKEN | Validating | |
| SAST | Does the project use static code analysis tools, e.g.CodeQL,LGTM (deprecated),SonarCloud? | Medium | PAT, GITHUB_TOKEN | Unsupported | |
| Security-Policy | Does the project contain asecurity policy? | Medium | PAT, GITHUB_TOKEN | Validating | |
| Signed-Releases | Does the project cryptographicallysign releases? | High | PAT, GITHUB_TOKEN | Validating | |
| Token-Permissions | Does the project declare GitHub workflow tokens asread only? | High | PAT, GITHUB_TOKEN | Unsupported | |
| Vulnerabilities | Does the project have unfixed vulnerabilities? Uses theOSV service. | High | PAT, GITHUB_TOKEN | Validating | |
| Webhooks | Does the webhook defined in the repository have a token configured to authenticate the origins of requests? | Critical | maintainer PAT (admin: repo_hook oradmin> read:repo_hookdoc | EXPERIMENTAL |
To see detailed information about each check, its scoring criteria, andremediation steps, check out thechecks documentation page.
Two-factor Authentication (2FA) adds an extra layer of security when logging into websites or apps. 2FA protects your account if your password is compromised by requiring a second form of authentication, such as codes sent via SMS or authentication app, or touching a physical security key.
We strongly recommend that you enable 2FA on GitHub and any important account where it is available. 2FA is not a Scorecard check because GitHub does not make that data about user accounts public. Arguably, this data should always remain private, since accounts without 2FA are so vulnerable to attack.
Though it is not an official check, we urge all project maintainers to enable 2FA to protect their projects from compromise.
Follow the steps described atConfiguring two-factor authentication
If possible, use either:
- physical security key (preferred), such as Titan or Yubikey
- recovery codes, stored in an access protected and encrypted vault
As a last option, use SMS. Beware: 2FA using SMS is vulnerable toSIM swap attack.
Each individual check returns a score of 0 to 10, with 10 representing the bestpossible score. Scorecard also produces an aggregate score, which is aweight-based average of the individual checks weighted by risk.
- “Critical” risk checks are weighted at 10
- “High” risk checks are weighted at 7.5
- “Medium” risk checks are weighted at 5
- “Low” risk checks are weighted at 2.5
See thelist of current Scorecard checks for each check'srisk level.
If you have what looks like a bug, please use theGithub issue tracking system. Beforeyou file an issue, please search existing issues to see if your issue is alreadycovered.
Before contributing, please follow ourCode of Conduct.
See theContributing documentation for guidance on how tocontribute to the project.
If you'd like to add a check, please see guidancehere.
If you want to get involved in the Scorecard community or have ideas you'd liketo chat about, we discuss this project in theOSSF Best Practices Working Groupmeetings.
| Artifact | Link |
|---|---|
| Scorecard Dev Forum | ossf-scorecard-dev@ |
| Scorecard Announcements Forum | ossf-scorecard-announce@ |
| Community Meeting VC | Link to z o o m meeting |
| Community Meeting Calendar | Biweekly Thursdays, 1:00pm-2:00pm PST Calendar |
| Meeting Notes | Notes |
| Slack Channel | #security_scorecards |
Maintainers are listed in theCODEOWNERS file.
To report a security issue, please follow instructionshere.
We meet every other Thursday - 4p ET on thiszoom link.
You can see theagenda and meeting notes here.
See theFAQ for answers to Frequently Asked Questions about Scorecard.
About
OpenSSF Scorecard - Security health metrics for Open Source
Resources
License
Code of conduct
Security policy
Stars
Watchers
Forks
Languages
- Go98.2%
- Makefile1.2%
- Other0.6%