Recently I’ve started to add the OSSF scorecard action to my (action) repositories. This is a GitHub action that will run the OSSF scorecard checks against your repository to see if you are following best practices, like having a security policy, using a code scanning tool, etc. Using this badge can give your users a quick overview of the security of your repository. OSSF stands for ‘Open Source Security Foundation’ and is an initiative to improve the security of open source repositories.
The scorecard action will do three things (if you use the default settings):
The action checks your repository against several checks and then calculates a score for each check on a scale of 0 to 10. Based on the risk for that check, the score is then multiplied with a weight. The final score is the average of all the weighted scores. The higher the score, the better.
Some of the checks that are executed are:
Setting is up is as easy as going to the OSSF scorecard action repo and copy the workflow example. Add that to you a new workflow file in your repo and run it from the default branch (usually
main). After the first run, you can add a link to your README.md file to show the badge.
The result will be a badge showing the latest score:
The default workflow also uploads the check results as a SARIF file to the Code Scanning Alerts that you can find on the Security tab of your repository. Each check can give one or more results, so you will get an alert for each result. That way you can fix the issues one by one.
Even better is that most of these alerts will give you actionable suggestions on how to fix the issue. For example, the alert above will give you a link to the Step Security Application that can analyze your repository and give you a pull request with the changes to fix the issue. They focus on three things:
One of the best practices is to always indicate what permissions you want to allow for the GitHub token that will be used in your workflow. The default setting is to permissive: it is
write for everything in your repo. I’ve been advocating that people always make this read-only at the organization level.
Since you cannot see what the organization permissions are, it’s a best practice to always specify the rights. You can add it to the top of your workflow file:
And now you can override it at the job level if you need to. For example, if you need to push to a branch, you can add
write to the
jobs: build: permissions: contents: write runs-on: ubuntu-latest steps: # etc
This setting is something I want to look into more. It seems that you can add a security agent to your GitHub hosted runner (available only for Ubuntu). It’s an extra product from Step Security which is available for free. It will analyze the network traffic in the job and log that in their system. After a couple of runs they know what kind of traffic is to be expected, and then you can convert that to basically a firewall rule. Any violations will then be logged and blocked. This can give you a better perimeter defense (as by default all traffic is allowed).
Definitely something to look into more!
The last option is to pin your actions to a full SHA hash. This is a best practice that I’ve been advocating for a while. It’s a bit more work, but it will make sure that your workflow will not be affected by a malicious actor pushing a new version of an action. What I really like is that this setting will analyze your workflow file (either pasted in or just all workflows in your public repo) and then suggest the SHA hashes of the actions, by looking at their latest version! Even better, they store the latest version in the comment next to the SHA hash, so you can understand where the hash comes from. Even Dependabot understands that comment and will update it in their version update PRs!