Skip to content

Commit 0facdb6

Browse files
walteckwalteck
authored
adding guidance on best practices for GitHub Actions (#344)
1 parent fc57a17 commit 0facdb6

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎practices/actions-best-practices.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# GitHub Actions Security Best Practices
2+
3+
## Introduction
4+
5+
GitHub Actions is a powerful automation tool that enables CI/CD workflows directly within your GitHub repository. Securing your GitHub Actions workflows is crucial to protect your code, secrets, and infrastructure from potential security threats.
6+
7+
This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks.
8+
9+
## Table of Contents
10+
11+
- [Secrets Management](#secrets-management)
12+
- [Limiting Permissions](#limiting-permissions)
13+
- [Third-Party Actions](#third-party-actions)
14+
- [Dependency Management](#dependency-management)
15+
- [Runner Security](#runner-security)
16+
- [Pull Request Workflows](#pull-request-workflows)
17+
- [OIDC Integration](#oidc-integration)
18+
- [Audit and Monitoring](#audit-and-monitoring)
19+
20+
## Secrets Management
21+
22+
This section describes how secrets in GitHub Actions should be managed, teams should ensure that they are using robust secrets management tools such as Azure Key Vault and AWS Secrets Manager for securely storing secrets.
23+
24+
### Use GitHub Secrets
25+
26+
- Store sensitive data (API tokens, credentials, etc.) as [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
27+
- Never hardcode sensitive values in your workflow files
28+
- Do not use structured data as a secret - this can cause GitHubs secret redaction in logs to fail
29+
- Rotate secrets regularly
30+
- Use environment-specific secrets when possible
31+
- Ensure a secret scanner is deployed as part of your workflows
32+
- Public repositories should enable GitHub Secret Scanner and Push Protection
33+
34+
### Minimize Secret Scope
35+
36+
```yaml
37+
# Good practice - limiting secret to specific environment
38+
jobs:
39+
deploy:
40+
environment: production
41+
runs-on: ubuntu-latest
42+
steps:
43+
- uses: actions/checkout@v3
44+
- name: Deploy
45+
env:
46+
API_TOKEN: ${{ secrets.API_TOKEN }}
47+
run: ./deploy.sh
48+
```
49+
50+
### Avoid Exposing Secrets in Logs
51+
52+
- Don't echo or print secrets in workflow steps
53+
- Set debug to false when using secrets
54+
- Use masking for any dynamically generated secrets
55+
56+
## Limiting Permissions
57+
58+
### Use Least Privilege Principle
59+
60+
Limit the GitHub token permissions to only what's necessary please [see here](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for details on the default permissions that the github token is given when the permissions block is not used:
61+
62+
```yaml
63+
permissions:
64+
contents: read
65+
pull-requests: write
66+
issues: write
67+
```
68+
69+
### Use Fine-Grained Tokens
70+
71+
Fine grained tokens *must* only be used if the GitHub token can not be used.
72+
73+
- Create custom GitHub Apps with limited scopes when possible
74+
- Use repository-scoped tokens instead of organization-wide tokens
75+
76+
## Third-Party Actions
77+
78+
While third-party actions can significantly enhance the functionality and efficiency of your workflows, they also introduce potential security risks:
79+
80+
- *Untrusted Code*: Third-party actions are often maintained by external developers. If the code is not reviewed or vetted, it may contain vulnerabilities or malicious code that could compromise your repository or infrastructure.
81+
- *Version Drift*: Using tags like @latest or branch references (e.g., @main) can lead to unexpected changes in behavior if the action is updated. This could introduce breaking changes or vulnerabilities into your workflows.
82+
- *Dependency Vulnerabilities*: Third-party actions may rely on outdated or insecure dependencies, which could expose your workflows to known vulnerabilities.
83+
- *Lack of Maintenance*: Some third-party actions may not be actively maintained, leaving them vulnerable to security issues or compatibility problems with newer GitHub Actions features.
84+
- *Excessive Permissions*: Third-party actions may request more permissions than necessary, potentially exposing sensitive data or allowing unauthorized access to your repository.
85+
86+
To mitigate these risks, always follow best practices, such as pinning actions to specific commit SHAs, reviewing the source code of actions, and using only trusted actions from reputable sources.
87+
88+
### Pin Actions to Specific Versions
89+
90+
When including a GitHub Action within your workflow you should perform due diligence checks to ensure that the action achieves the aims you are intending it to, and that it doesn't do anything unintended, this would include performing a code review of the GitHub action code. To prevent the underlying code being changed without your awareness always use specific commit SHAs instead of tags or branches as tags can be modified if the upstream repository is compromised:
91+
92+
```yaml
93+
# Not secure - can change unexpectedly
94+
- uses: actions/checkout@v3
95+
# Better - using a specific version tag
96+
- uses: actions/[email protected]
97+
# Best - using a specific commit SHA
98+
- uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.1.0
99+
```
100+
101+
### Verify Third-Party Actions
102+
103+
When including a GitHub Action within your workflow consider alternatives, is there an existing mechanism you can use? Would this be something that could be reused and you could create your own action within the organisation that other teams could benefit from? If you can only achieve your goal with a third-party action then:
104+
105+
- Only use trusted actions from the GitHub Marketplace
106+
- Review the source code of third-party actions before using them
107+
- Consider forking and maintaining your own copy of critical actions
108+
109+
### Use Actions Security Best Practices
110+
111+
- Enable Dependabot alerts for GitHub Actions
112+
- Set up a workflow that regularly checks for outdated actions
113+
114+
## Dependency Management
115+
116+
### Scan Dependencies
117+
118+
- Use dependency scanning tools like GitHub's Dependabot
119+
120+
### Keep Dependencies Updated
121+
122+
- Implement automated dependency updates
123+
- Regularly review and update dependencies with security patches
124+
125+
## Runner Security
126+
127+
### Self-hosted Runner Security
128+
129+
Self-hosted runners *must* only be [used with private repositories](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). If using self-hosted runners:
130+
131+
- Run them in isolated environments (containers/VMs)
132+
- Regularly update and patch runner machines
133+
- Implement proper network isolation
134+
- Use ephemeral runners when possible
135+
136+
```yaml
137+
jobs:
138+
build:
139+
runs-on: [self-hosted, isolated]
140+
steps:
141+
# Your workflow steps here
142+
```
143+
144+
### GitHub-hosted Runner Security
145+
146+
- Be aware that GitHub-hosted runners are reset after each job
147+
- Clean up any sensitive data before job completion
148+
- Don't store persistent sensitive data in the runner's environment
149+
150+
## Pull Request Workflows
151+
152+
### Secure Pull Request Workflows
153+
154+
- Don't expose secrets to pull request workflows from forks
155+
- Use `pull_request_target` carefully with read-only permissions
156+
157+
```yaml
158+
# Safer approach for PR workflows
159+
on:
160+
pull_request:
161+
jobs:
162+
test:
163+
runs-on: ubuntu-latest
164+
permissions:
165+
contents: read
166+
steps:
167+
- uses: actions/checkout@v3
168+
- name: Run tests
169+
run: npm test
170+
```
171+
172+
### Implement Required Reviews
173+
174+
- Enforce branch protection rules
175+
- Require code reviews before merging
176+
- Use status checks to enforce security scans
177+
178+
## OIDC Integration
179+
180+
### Use OpenID Connect for Cloud Providers
181+
182+
Instead of storing long-lived cloud credentials, use GitHub's OIDC provider:
183+
184+
```yaml
185+
jobs:
186+
deploy:
187+
runs-on: ubuntu-latest
188+
permissions:
189+
id-token: write
190+
contents: read
191+
steps:
192+
- uses: actions/checkout@v3
193+
- name: Configure AWS credentials
194+
uses: aws-actions/configure-aws-credentials@v1
195+
with:
196+
role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions
197+
aws-region: eu-west-2
198+
```
199+
200+
### Limit OIDC Token Claims
201+
202+
- Set specific subject claims in your cloud provider
203+
- Implement additional claim conditions (repository, branch, environment)
204+
205+
## Audit and Monitoring
206+
207+
### Enable Audit Logging
208+
209+
- Monitor GitHub Actions usage via audit logs
210+
- Set up alerts for suspicious activity
211+
212+
### Review Workflow Changes
213+
214+
- Enforce code reviews for workflow file changes
215+
- Use CODEOWNERS to restrict who can modify workflow files
216+
217+
```plaintext
218+
# CODEOWNERS file/.github/workflows/ @security-team
219+
```
220+
221+
### Regular Security Reviews
222+
223+
- Conduct regular reviews of all workflows
224+
- Update security practices based on emerging threats
225+
- Monitor GitHub security advisories
226+
227+
## Additional Resources
228+
229+
- [GitHub Actions Security Hardening Guide](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
230+
- [GitHub Security Lab](https://securitylab.github.com/)
231+
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
232+
- [Security for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions)
233+
234+
## Conclusion
235+
236+
Securing GitHub Actions requires a multi-layered approach focusing on secrets management, permissions, third-party action vetting, and proper configuration. By following these best practices, you can significantly reduce security risks while still enjoying the full benefits of GitHub Actions automation.
237+
238+
Remember that security is an ongoing process - regularly review and update your security practices to adapt to new threats and challenges.

‎practices/security.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ The remainder of this page gives more detailed and specific recommendations to b
137137
- Secure **CI/CD**
138138
- Robust authentication and minimum privileges
139139
- Prefer ambient IAM credentials over retrieving credentials from secrets management. Do not store credentials in the plain.
140+
- If using GitHub Actions follow the [Best Practices outlined here](./actions-best-practices.md)
140141
- **Enforce** infrastructure security (e.g. [Azure Policy](https://docs.microsoft.com/en-us/azure/governance/policy/overview), [AWS Config](https://aws.amazon.com/config/)) and validate it (e.g. [ScoutSuite](https://github.com/nccgroup/ScoutSuite/blob/master/README.md))
141142

142143
<details><summary>Example IAM policy fragment to prevent unencrypted RDS databases (click to expand)</summary>

0 commit comments

Comments
 (0)