Most of us probably spend more time reading restaurant reviews than we spend evaluating the security of a new open source dependency. Yet the stakes riding on our codebases are so much higher than a bad meal. Software supply chain attacks have seen a 742% annual increase as attackers target vulnerabilities in dependencies earlier in the supply chain as a way of multiplying the impact of their attacks.
Open source consumers need knowledge about the projects they rely on to help protect their projects from the next big supply chain attack. Are the dependencies you bring into your project safe? What’s happening under the surface in the projects you depend on?
Enter Open Source Security Foundation’s (OpenSSF) Scorecard project, an automated way to judge a software project’s security practices—and with them, the project’s risks. According to a recent report by Sonatype, Scorecard ratings are one of the best indicators of whether a project has known vulnerabilities. If you’re looking to start improving your software supply chain security, adopting Scorecard is a great first step to understanding what’s in your software. And if you’re a project owner, we’ll explain how you can use Scorecard to track and improve your project’s security practices, helping protect and build trust in your project.
In this Guide, you will learn about:
Using the Scorecard API to automatically look-up scores for all of your dependencies.
Using the Scorecard GitHub Action to keep tabs on your own score.
Ways to improve your Scorecard rating and, by extension, the security of your project.
What is OpenSSF Scorecard?
In short, Scorecard is a set of benchmarks used to generate an aggregated project score (0-10) that gives you a sense of how highly a project prioritizes security. This is essential for identifying vulnerable points in your supply chain: A dependency that doesn’t meet your own internal security standards might well be the weakest link in your software.
A closer look at the individual scores for the 19 different Scorecard metrics (“checks”) will tell you whether a project’s maintainers follow the practices that are the most important to you:
Do they require code review when contributors make changes?
Do they protect branches against unauthorized deletion or changes?
Do they pin their dependencies, so compromised version updates can’t be pushed without review?
The granularity of scoring individual best practices means that for consumers, Scorecards can be like a good restaurant review: They help answer the question “do I want to eat here?” And beyond just that, Scorecards also give maintainers an actionable checklist of steps you can take to improve your security.
How do I use Scorecard?
Lots of ways! It depends on whether you’re evaluating someone else’s software or improving your own, and how much time you have.
To evaluate an open source project
In five minutes:
To quickly see the Scorecard for a project, visit Open Source Insights (OSI) and search for the project. More than 1.25M projects are indexed. When available, Scorecards are shown alongside the individual project page. Here’s the listing for the Scorecard project itself:
If a project isn’t indexed, you can use the Scorecard CLI to run a scan on it, or any other project.
To scale your evaluations
To scale up your approach to evaluating software dependencies, try adding the API to your build system or ingestion process. The Scorecard scan results are available via an HTTP REST Endpoint and a BigQuery dataset.
You can use this data to automate the human process of judging software. For example, you can:
Feed information about checks you value into your policy engine to automate the decision of whether to allow the project to build.
Run regular scans, such as checking daily that the scores of your dependencies haven’t dropped below a certain threshold or that projects haven’t been abandoned.
Leverage the data wherever you have a critical decision point in your development process.
To improve an open source project
In 10 minutes:
To use Scorecard with your own project, you can add the Scorecard GitHub Action in less than 10 minutes. The action runs a Scorecard scan after any repository change, so you get immediate feedback if a PR causes a regression in your project’s security. The act of installing the action will trigger its first run, giving you a snapshot of your current situation, available in the GitHub security dashboard.
Each result comes with remediation tips and an indication of severity, so you can choose where to start to raise your score—and secure your project.
If you want to get in some quick wins, start by:
Enabling Branch Protection, so you can ensure that nobody makes unauthorized changes to your main branch
Adding a Security Policy, so users who discover a vulnerability know how to report it to you in a secure way
If you want to start with the checks that give you the most bang for your buck, check out Code Review, Binary Artifacts, and Pinned Dependencies. According to Sonatype’s State of the Software Supply Chain, these checks correlated most strongly with whether a project contained a known vulnerability.
Once you’ve made a dent in improving your score, be sure to add a badge to show off your hard work!
What’s next
Of course, these checks are just one part of making open source software more secure for everyone. Keeping tabs on the results of the tests and, crucially, acting on the information, is an ongoing endeavor. But we hope we can make your security journey easier. We’d love to hear what you think. To share your thoughts, or get involved with Scorecard, reach out to us through our contact section.
