Skip to main content

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 github command of install.sh. GitHub repository setup describes the command.
  • The Audit workflow 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-branch ruleset that install.sh github applies 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:

  1. On your repository, open Settings > Rules > Rulesets and click default-branch.
  2. Turn on Require a pull request before merging and set Required approvals to 1.
  3. 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:

  1. Sign in at bestpractices.dev with your GitHub account.
  2. Add the project with your repository's URL.
  3. 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.
  4. In README.md, find the commented-out OpenSSF Best Practices badge. Replace PROJECT_ID in it with the number in the project's bestpractices.dev URL.
  5. 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:

CriteriaEvidence to link
interact, contributionREADME.md and CONTRIBUTING.md
contribution_requirements, test_policy, tests_documented_addedThe "Submit a change" section of CONTRIBUTING.md
floss_license, floss_license_osi, license_locationLICENSE, which holds the GPL-3.0 license
sites_https, discussion, repo_public, repo_track, repo_interim, repo_distributed, report_process, report_tracker, report_archiveThe GitHub repository and its issues
version_unique, version_semver, version_tagsThe Releases page and RELEASING.md. The release workflows start only on a version tag, as Release describes.
release_notesThe Releases page. Release Drafter, which install.sh adds by default, drafts the notes.
vulnerability_report_process, vulnerability_report_privateSECURITY.md
build, build_common_tools, build_floss_tools, test, test_invocation, warnings, warnings_strictThe commands for each stack in CONTRIBUTING.md
test_continuous_integrationThe 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_unsignedThe 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:

CriteriaWhat to answer
description_good, documentation_basics, documentation_interfaceReplace the placeholder features and usage in README.md with your project's, then link README.md
maintained, report_responses, enhancement_responsesYour response times to issues and pull requests
vulnerability_report_responseYour response time to vulnerability reports in the last 6 months. In SECURITY.md, the project commits to a reply within 14 days.
release_notes_vulnsWhether each release's notes name the vulnerabilities it fixes
tests_are_added, warnings_fixed, static_analysis_fixed, dynamic_analysis_fixedWhether your recent changes added tests and fixed what the linters and scans found
vulnerabilities_fixed_60_days, vulnerabilities_critical_fixedYour time to fix known vulnerabilities. Renovate raises the dependency updates.
no_leaked_credentialsWhether 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_errorsWhether 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_randomAny cryptography the project adds. Answer N/A when it adds none.
dynamic_analysis, dynamic_analysis_unsafe, dynamic_analysis_enable_assertionsAny 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.