Harden your project
A project created from Scaffold ships with a security policy, a security audit workflow and release workflows that attest their assets. The Open Source Security Foundation (OpenSSF) rates projects with Scorecard and the Best Practices badge. Part of each rating needs the project's owner. This page is for the owner of a public Scaffold project on GitHub. Follow it after the first push to main to check the Scorecard result, decide on required reviews, earn the Best Practices badge and publish a release that Scorecard can score.
Before you begin
Make sure you have the following:
- A public GitHub repository, configured with the
githubcommand ofinstall.sh. GitHub repository setup describes the command. - The
Auditworkflow in.github/workflows/audit.yml, which Audit describes.
Check the Scorecard result
OpenSSF Scorecard scores the repository's security practices with a list of checks, each from 0 to 10. The Audit workflow publishes the result after each run on main.
To read the result, open https://scorecard.dev/viewer/?uri=github.com/OWNER/REPO. Replace OWNER and REPO with your repository's owner and name. Until the Audit workflow has run once on main, the viewer reports that the repository isn't found.
Most checks score the files and settings that Scaffold and install.sh github set up. The Code-Review, Branch-Protection and Signed-Releases checks need you, as the next sections describe.
Decide on required reviews
Scorecard's Code-Review and Branch-Protection checks want a second person to approve each change:
- Code-Review scores about the 30 most recent commits. Each change merged without an approval lowers the score.
- Branch-Protection scores the default branch's protection in 5 tiers. Each tier counts only after every lower tier is met in full. The
default-branchruleset thatinstall.sh githubapplies blocks force pushes and deleting the branch, which meets the first tier. The second tier needs at least 1 required approval. Until the ruleset requires an approval, its required status checks earn no points.
A maintainer can't approve their own pull request. Pick the option that fits your project:
- With 1 maintainer, keep the ruleset as it is and accept the lower Code-Review and Branch-Protection scores.
- With 2 or more maintainers, require an approval on every pull request.
To require an approval on every pull request:
- On your repository, open Settings > Rules > Rulesets and click
default-branch. - Turn on Require a pull request before merging and set Required approvals to 1.
- Click Save changes.
A later run of install.sh github keeps this rule, because it replaces only the deletion, force-push and required status checks rules. install.sh also lets the admin repository role bypass the ruleset, so an administrator can still merge without an approval.
Earn the OpenSSF Best Practices badge
The OpenSSF Best Practices badge shows that a project meets a list of open source practices, called criteria. You answer each criterion on the badge's site, and in most answers you link a file in the repository as evidence. The badge has 3 levels, and this section covers the first, passing. The project earns it after it meets every criterion of that level that applies to it.
To earn the badge:
- Sign in at bestpractices.dev with your GitHub account.
- Add the project with your repository's URL.
- Answer every passing criterion. The first of the following tables lists the evidence to link, and the second lists the criteria that need your own answer.
- In
README.md, find the commented-out OpenSSF Best Practices badge. ReplacePROJECT_IDin it with the number in the project's bestpractices.dev URL. - Move the badge out of the comment and delete the comment. Confirm that the badge on your repository's page reads passing. Before the project meets every criterion, the badge shows its progress.
Criteria the template covers
A project created from Scaffold already holds the evidence for the following criteria. Link the file in each criterion's answer:
| Criteria | Evidence to link |
|---|---|
interact, contribution | README.md and CONTRIBUTING.md |
contribution_requirements, test_policy, tests_documented_added | The "Submit a change" section of CONTRIBUTING.md |
floss_license, floss_license_osi, license_location | LICENSE, which holds the GPL-3.0 license |
sites_https, discussion, repo_public, repo_track, repo_interim, repo_distributed, report_process, report_tracker, report_archive | The GitHub repository and its issues |
version_unique, version_semver, version_tags | The Releases page and RELEASING.md. The release workflows start only on a version tag, as Release describes. |
release_notes | The Releases page. Release Drafter, which install.sh adds by default, drafts the notes. |
vulnerability_report_process, vulnerability_report_private | SECURITY.md |
build, build_common_tools, build_floss_tools, test, test_invocation, warnings, warnings_strict | The commands for each stack in CONTRIBUTING.md |
test_continuous_integration | The test-*.yml workflows in .github/workflows |
static_analysis, static_analysis_common_vulnerabilities, static_analysis_often | .github/workflows/audit.yml, whose CodeQL and Semgrep scans run on every pull request and push to main |
delivery_mitm, delivery_unsigned | The GitHub release assets, which GitHub serves over HTTPS |
When you replace one of these files, such as LICENSE, update the answers that link it.
Criteria only you can answer
The following criteria depend on the project's own code, history or people:
| Criteria | What to answer |
|---|---|
description_good, documentation_basics, documentation_interface | Replace the placeholder features and usage in README.md with your project's, then link README.md |
maintained, report_responses, enhancement_responses | Your response times to issues and pull requests |
vulnerability_report_response | Your response time to vulnerability reports in the last 6 months. In SECURITY.md, the project commits to a reply within 14 days. |
release_notes_vulns | Whether each release's notes name the vulnerabilities it fixes |
tests_are_added, warnings_fixed, static_analysis_fixed, dynamic_analysis_fixed | Whether your recent changes added tests and fixed what the linters and scans found |
vulnerabilities_fixed_60_days, vulnerabilities_critical_fixed | Your time to fix known vulnerabilities. Renovate raises the dependency updates. |
no_leaked_credentials | Whether the repository holds valid credentials. The secret scanning that install.sh github turns on lists the credentials it finds on the Security tab. Revoke each one before you answer. |
know_secure_design, know_common_errors | Whether a developer on the project knows secure design and the common errors for its kind of software |
crypto_published, crypto_call, crypto_floss, crypto_keylength, crypto_working, crypto_weaknesses, crypto_pfs, crypto_password_storage, crypto_random | Any cryptography the project adds. Answer N/A when it adds none. |
dynamic_analysis, dynamic_analysis_unsafe, dynamic_analysis_enable_assertions | Any dynamic analysis you run, such as fuzzing |
Cut an attested release
Scorecard's Signed-Releases check looks for a build provenance file in the assets of the project's recent releases. A provenance file records the workflow run that built each asset. The check scores 10 when each of those releases has an .intoto.jsonl file.
The Release PHP and Release Node.js workflows attach REPO-STACK-TAG.intoto.jsonl to each release. REPO is the repository name, STACK is php or nodejs and TAG is the release's tag. To give the check a release to score, publish a release:
- For a PHP command app with a PHAR, or a single-file PHP script, follow PHP release.
- For a Node.js project, follow Node.js release.
A PHP class library and a PHP command app without a PHAR have no release workflow. Release Docker publishes an image and attaches nothing to the release. On those projects, Signed-Releases has nothing to score.
The next Audit run scores the new release. That run starts on the next push to main, or on Monday's scheduled run.