|
| 1 | +# GitHub Actions Use Policy for InstructLab |
| 2 | + |
| 3 | +This document describes the use policy for GitHub Actions (actions) in workflows for all repositories in the [InstructLab](https://github.com/instructlab) organization. |
| 4 | + |
| 5 | +## Background |
| 6 | + |
| 7 | +GitHub Actions are an important tool for CI/CD use within the repositories of the InstructLab project. |
| 8 | +One of the main values is to verify the quality of pull requests for things like tests passing, spelling checks, well-formedness of files, etc. |
| 9 | +Repositories may also use actions to build and publish releases for the project. |
| 10 | + |
| 11 | +Since actions play a critical role in the project, care must be taken in how they are used due to their place in the security of the software supply chain of the project. |
| 12 | + |
| 13 | +## Dependabot |
| 14 | + |
| 15 | +Each repository using GitHub Actions must configure Dependabot to manage the action dependencies. |
| 16 | +The repository must contain a `.github/dependabot.yml` file with the following minimum configuration: |
| 17 | + |
| 18 | +```yaml |
| 19 | +version: 2 |
| 20 | +updates: |
| 21 | + # Maintain dependencies for GitHub Actions |
| 22 | + - package-ecosystem: "github-actions" |
| 23 | + directory: "/" |
| 24 | + schedule: |
| 25 | + interval: "daily" |
| 26 | +``` |
| 27 | +
|
| 28 | +Repository maintainers must review and respond to all pull requests submitted by Dependabot in a timely manner. |
| 29 | +
|
| 30 | +## SHAs instead of tags |
| 31 | +
|
| 32 | +GitHub Actions must be referenced using SHA values for a specific commit. |
| 33 | +Use of other reference types such as tag or branch names is not permitted. |
| 34 | +
|
| 35 | +```yaml |
| 36 | +- name: Git Checkout |
| 37 | + uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4.1.4 |
| 38 | +``` |
| 39 | +
|
| 40 | +instead of |
| 41 | +
|
| 42 | +```yaml |
| 43 | +- name: Git Checkout |
| 44 | + uses: actions/checkout@v4 |
| 45 | +``` |
| 46 | +
|
| 47 | +The use of SHAs can avoid security issues if the tag or branch of the action is moved to a malicious commit. |
| 48 | +We also gain build repeatability for future builds by referring to a precise revision of the action. |
| 49 | +
|
| 50 | +Since we use Dependabot to manage our action dependencies, Dependabot will handle the chore of using the proper SHA values in the submitted pull requests when action dependencies are updated. |
| 51 | +
|
| 52 | +## Trusted Providers of GitHub Actions |
| 53 | +
|
| 54 | +There are many GitHub Actions available in GitHub. |
| 55 | +Not all can be necessarily trusted. |
| 56 | +The InstructLab project must maintain [a list of allowed providers and a list of denied providers](github-actions-providers.md). |
| 57 | +
|
| 58 | +Allowed providers will include all GitHub created actions (`actions/*`) as well as other official actions such as Python Packaging actions (`pypa/*`). |
| 59 | + |
| 60 | +The InstructLab organization's Settings->Actions->General must be configured to allow select actions including actions created by GitHub along with the allowed providers. |
| 61 | + |
| 62 | +Adding actions to the allowed providers or denied providers lists will require approval by the organization maintainers along with updating the organization's settings. This can be done by submitting a Pull Request to modify [`github-actions-providers.md`](github-actions-providers.md). |
| 63 | + |
| 64 | +## Harden the GitHub Action runner |
| 65 | + |
| 66 | +To further increase security, the first step of each job in a workflow must be the [`step-security/harden-runner`](https://github.com/step-security/harden-runner) action. |
| 67 | +This action hardens the action runner by implementing network egress control and some infrastructure security. |
| 68 | + |
| 69 | +```yaml |
| 70 | +- name: "Harden Runner" |
| 71 | + uses: step-security/harden-runner@a4aa98b93cab29d9b1101a6143fb8bce00e2eac4 # v2.7.1 |
| 72 | + with: |
| 73 | + egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs |
| 74 | +``` |
| 75 | + |
| 76 | +Each execution of the workflow job will produce a report showing endpoints accessed by the job and possible source file overwrites. |
| 77 | +The report will also suggest modifications to the harden-runner action's configuration to further increase security. |
| 78 | + |
| 79 | +```yaml |
| 80 | +- name: "Harden Runner" |
| 81 | + uses: step-security/harden-runner@a4aa98b93cab29d9b1101a6143fb8bce00e2eac4 # v2.7.1 |
| 82 | + with: |
| 83 | + disable-sudo: true |
| 84 | + egress-policy: block |
| 85 | + allowed-endpoints: > |
| 86 | + github.com:443 |
| 87 | +``` |
| 88 | + |
| 89 | +Hardening the action runner like this can prevent malicious or misbehaving actions or the misuse of actions from exfiltrating secrets. |
| 90 | +The article [Harden-Runner Defends Against Arbitrary Command Execution in `tj-actions/changed-files` GitHub Action](https://www.stepsecurity.io/blog/defend-against-arbitrary-command-execution-in-tj-actions-changed-files) shows how the misuse of an action could allow an attacker with a well-crafted pull request to exfiltrate secrets. |
0 commit comments