Skip to main content

Automatically restrict permissions for the GITHUB_TOKEN

Manually calculating the minimum permissions for each job in a workflow is a chore. Step Security GitHub app analyzes the workflow file and suggests minimum permissions using a pull request

What risk does this mitigate?#

As per the security hardening for GitHub Actions, 3rd party GitHub actions can use the GITHUB_TOKEN by accessing it from the github.token context. You should therefore make sure that the GITHUB_TOKEN is granted the minimum required permissions.

In the Codecov breach, an attacker modified the bash uploader to steal credentials from pipelines. Customers using the Codecov GitHub action could have had their GITHUB_TOKEN stolen. This is a real example of the risk.

An adversary who gets hold of the GITHUB_TOKEN can use the GitHub API to modify repository content, including releases, if the assigned permissions of the token are not restricted. This can happen if an action (e.g. a third-party action) used in the workflow is compromised, or if the runner is compromised.

How does it work?#

The App is triggered as a result of certain events.

  1. When the App is first installed on an organization or repository,
  2. When a new repository is added to the installation, or
  3. when a pull request is created that modifies a workflow file.

The App receives a webhook from GitHub with information about the repository or the pull request. It fetches the workflow files from the .github/workflows/ folder in the repository, parses the YAML files, and analyzes them for the minimum required permissions.

The App then modifies the workflow files and adds the minimum permissions using the permissions key. It then creates a pull request with the changes. You can review the changes, and if all looks good, merge the changes into the base branch.

Limitations#

The App does not suggest permissions in certain scenarios:

  1. When a run step in a job uses the GITHUB_TOKEN. The App does not currently analyze the code that uses the token.
  2. If your workflow uses a GitHub action for which the App does not have permission information.
  3. If the job or a workflow already has permissions defined, the App does not modify them.