StepSecurity is on a mission to secure the open source software supply chain. This blog post is a call to action (pun intended) for all GitHub Action owners to contribute to this mission.
There are over 10,000 Actions in the GitHub Actions Marketplace. If you are the owner of one of these Actions, please contribute to the SecureWorkflows project.
SecureWorkflows is an open-source project maintained by StepSecurity to secure GitHub Actions workflows using automation.
What is the problem we are trying to solve?
GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline.
At the start of each workflow run, GitHub automatically creates a unique GITHUB_TOKEN secret to use in your workflow. By default, the GITHUB_TOKEN has permissions to read and write content, pull requests, packages etc. You can use the permissions key in your workflow file to modify permissions for the GITHUB_TOKEN. This allows you to configure the minimum required permissions for a workflow.
The problem we are trying to solve is to automatically calculate what the minimum permissions should be for a given workflow.
How are we solving this problem?
We are solving this problem by building a knowledge base of permissions needed by each GitHub Action. We then iterate over all the Actions used by a job and figure out the total set of permissions needed.
As an example, the above workflow only has one job, and that job only has one step. The step uses the “actions/labeler” GitHub Action.
In the SecureWorkflows project, we have a YAML file that describes the permissions needed by this Action. This is what the YAML file looks like:
Now, if you try to secure this GitHub Actions workflow using SecureWorkflows, it will set the token permissions using this YAML file (see the fixed workflow below). You can see how the “reason” from the YAML file is added as a comment in the fixed workflow, so the developers know why the permission is needed.
SecureWorkflows adds the “contents: read” permission at the top, so that new jobs added to the workflow are secure by default.
How can you help solving this problem?
If you own a GitHub Action, contribute to the SecureWorkflows project by adding a YAML file describing the permissions your Action needs.
The permissions your Action needs are based on the GitHub API calls your Action makes. As an example, if your GitHub Action is used to comment on a pull request, it needs the “pull-requests: write” permission.
Once you know the API call your Action makes, you can check this the GitHub documentation page for permissions needed for that GitHub API call.
To add information about your Action, you can store the permission information in an “action-security.yml” YAML file specific for your Action and create a pull request in the SecureWorkflows project.
Details on how to create the YAML file are in the Contributing Guide. You can also check out the existing action-security.yml files here.
Looking forward to your contribution to secure the open source software supply chain!
To get updates, follow Step Security on LinkedIn and Twitter.
