Introduction
The GITHUB_TOKEN is an automatically generated secret used to authenticate to GitHub APIs from GitHub Actions workflows. It allows for secure interactions with the GitHub API, enabling tasks such as cloning repositories, pushing code, and accessing GitHub's features without using personal access tokens (PATs). Determining the minimum required permissions for this GITHUB_TOKEN is challenging. This complexity arises because different workflows and actions might require varying access levels, and overly permissive tokens increase the risk of accidental or malicious misuse. Calculating the least privilege permissions ensures that workflows have enough access to perform their tasks, minimizing the risk of security incidents.
How StepSecurity Harden-Runner Calculates Minimum GITHUB_TOKEN Permissions
StepSecurity Harden-Runner provides network egress control and CI/CD infrastructure security for GitHub-hosted and self-hosted runners. It is used by Microsoft, Google, CISA, DataDog, Intel, and hundreds of other organizations to enhance their GitHub Actions security.
Harden-Runner can not only monitor outbound network traffic but can also monitor outbound HTTPS requests using eBPF! This means it can monitor the VERBs (e.g., GET, POST) and PATHs (e.g., /repos/owner/repo/issues) for calls made to the GitHub APIs from the runner.
Why Use eBPF Over MITM SSL?
Using eBPF to monitor HTTPS requests offers advantages over traditional Man-in-the-Middle (MITM) SSL techniques. MITM SSL requires self-signed certificates, which can be cumbersome to manage and ineffective when certificates are pinned. In contrast, eBPF allows monitoring SSL write calls directly at the kernel level, bypassing the need for self-signed certificates. This approach enables secure, unobtrusive analysis of HTTPS requests.
Mapping GitHub API Calls to GITHUB_TOKEN Permissions
Each GitHub Actions API call requires a corresponding GITHUB_TOKEN permission. For instance, a GET request to the /repos/org/repo/info/refs?service=git-upload-pack endpoint requires the "contents: read" permission. Harden-Runner uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for each job in your workflow. Harden-Runner analyzes multiple runs of a given job, allowing the recommendations to improve over time as more runs are analyzed. This is particularly useful since some runs may not call certain APIs, and analyzing more runs ensures comprehensive permission recommendations.
Illustrative Examples
Let us look at three examples of how StepSecurity Harden-Runner helps determine the precise GITHUB_TOKEN permissions by monitoring outbound HTTPS requests using eBPF.
Example 1: Job where security scanner uploads scan results to GitHub
The screenshot below shows the outbound HTTPS requests in a GitHub Actions workflow that uses a security scanner and uploads scanning results to GitHub.
- The GET request to the /repos/org/repo/info/refs?service=git-upload-pack endpoint requires the "contents: read" permission.
- The GET request to the /repos/org/repo/actions endpoint requires the "actions: read" permission.
- The PUT request to the /repos/org/repo/code-scanning endpoint requires the "security-events: write" permission.
StepSecurity uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for this job correctly.
Example 2: Job where “actions/github-script” Action is used to call GitHub APIs
The screenshot below shows the outbound HTTPS requests in a GitHub Actions workflow that uses “actions/github-script” Action to fetch all issues, pull requests, and branches.
- The GET request to the /repos/step-security/token-perms-test/issues?state=all endpoint requires the "issues: read" permission.
- The GET request to the /repos/step-security/token-perms-test/pulls?state=all endpoint requires the "pull-requests: read" permission.
- The GET request to the /repos/step-security/token-perms-test/branches endpoint requires the "content: read" permission.
StepSecurity uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for this job correctly.
Example 3: Job where “peter-evans/create-pull-request” Action is used to create a pull request
The screenshot below shows the outbound HTTPS requests in a GitHub Actions workflow that uses “peter-evans/create-pull-request” Action to create a pull request
- The GET request to the /step-security/token-perms-test/info/refs?service=git-receive-pack endpoint is used to push code and requires the "contents: write" permission.
- The POST request to the /repos/step-security/token-perms-test/pulls endpoint requires the "pull-requests: write" permission.
- The PATCH request to the /repos/step-security/token-perms-test/pulls/1 endpoint also requires the "pull-requests: write" permission.
StepSecurity uses the PATHs and VERBs of these HTTPS calls to recommend the minimum GITHUB_TOKEN permissions for this job correctly.
Summary
To get started and understand what minimum GITHUB_TOKEN permissions your workflows need, add the Harden-Runner GitHub Action to your workflow files. By leveraging Harden-Runner, you can ensure that your GitHub Actions workflows adhere to the principle of least privilege, thereby enhancing the security of your CI/CD pipelines.
This feature is included in the StepSecurity enterprise tier, providing additional benefits and support to ensure your workflows are secure and efficient.
Ready to enhance your GitHub Actions security? Add Harden-Runner to your workflow and upgrade to the StepSecurity enterprise tier for advanced features and priority support!
