From 593d703021d5667fe1b971bd61c4c8bb743d6370 Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Thu, 20 Mar 2025 15:51:06 +0000 Subject: [PATCH 1/4] adding guidance on best practices for GitHub Actions --- practices/actions-best-practices.md | 227 ++++++++++++++++++++++++++++ practices/security.md | 1 + 2 files changed, 228 insertions(+) create mode 100644 practices/actions-best-practices.md diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md new file mode 100644 index 00000000..ce325a60 --- /dev/null +++ b/practices/actions-best-practices.md @@ -0,0 +1,227 @@ +# GitHub Actions Security Best Practices + +## Introduction + +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. + +This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks. + +## Table of Contents +- [Secrets Management](#secrets-management) +- [Limiting Permissions](#limiting-permissions) +- [Third-Party Actions](#third-party-actions) +- [Dependency Management](#dependency-management) +- [Runner Security](#runner-security) +- [Pull Request Workflows](#pull-request-workflows) +- [OIDC Integration](#oidc-integration) +- [Audit and Monitoring](#audit-and-monitoring) + +## Secrets Management + +### Use GitHub Secrets + +- Store sensitive data (API tokens, credentials, etc.) as [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) +- Never hardcode sensitive values in your workflow files +- Do not use structured data as a secret - this can cause GitHubs secret redaction in logs to fail +- Rotate secrets regularly +- Use environment-specific secrets when possible +- Ensure a secret scanner is deployed as part of your workflows +- Public repositories should enable GitHub Secret Scanner and Push Protection + +### Minimize Secret Scope +```yaml +# Good practice - limiting secret to specific environment +jobs: + deploy: + environment: production + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Deploy + env: + API_TOKEN: ${{ secrets.API_TOKEN }} + run: ./deploy.sh +``` + +### Avoid Exposing Secrets in Logs + +- Don't echo or print secrets in workflow steps +- Set debug to false when using secrets +- Use masking for any dynamically generated secrets + +## Limiting Permissions + +### Use Least Privilege Principle + +Limit the GitHub token permissions to only what's necessary: +```yaml +permissions: + contents: read + pull-requests: write + issues: write +``` + +### Use Fine-Grained Tokens + +- Create custom GitHub Apps with limited scopes when possible +- Use repository-scoped tokens instead of organization-wide tokens + +## Third-Party Actions + +While third-party actions can significantly enhance the functionality and efficiency of your workflows, they also introduce potential security risks: + +- *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. +- *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. +- *Dependency Vulnerabilities*: Third-party actions may rely on outdated or insecure dependencies, which could expose your workflows to known vulnerabilities. +- *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. +- *Excessive Permissions*: Third-party actions may request more permissions than necessary, potentially exposing sensitive data or allowing unauthorized access to your repository. + +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. + +### Pin Actions to Specific Versions + +Always use specific commit SHAs instead of tags or branches: + +```yaml +# Not secure - can change unexpectedly +- uses: actions/checkout@v3 +# Better - using a specific version tag +- uses: actions/checkout@v3.1.0 +# Best - using a specific commit SHA +- uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b +``` + +### Verify Third-Party Actions + +- Only use trusted actions from the GitHub Marketplace +- Review the source code of third-party actions before using them +- Consider forking and maintaining your own copy of critical actions + +### Use Actions Security Best Practices + +- Enable Dependabot alerts for GitHub Actions +- Set up a workflow that regularly checks for outdated actions + +## Dependency Management + +### Scan Dependencies + +- Use dependency scanning tools like GitHub's Dependabot + +### Keep Dependencies Updated + +- Implement automated dependency updates +- Regularly review and update dependencies with security patches + +## Runner Security + +### Self-hosted Runner Security + +If using self-hosted runners: + +- Run them in isolated environments (containers/VMs) +- Regularly update and patch runner machines- Implement proper network isolation- Use ephemeral runners when possible + +```yaml +jobs: + build: + runs-on: [self-hosted, isolated] + steps: + # Your workflow steps here +``` + +### GitHub-hosted Runner Security + +- Be aware that GitHub-hosted runners are reset after each job +- Clean up any sensitive data before job completion +- Don't store persistent sensitive data in the runner's environment + +## Pull Request Workflows + +### Secure Pull Request Workflows + +- Don't expose secrets to pull request workflows from forks +- Use `pull_request_target` carefully with read-only permissions + +```yaml +# Safer approach for PR workflows +on: + pull_request: +jobs: + test: + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@v3 + - name: Run tests + run: npm test +``` + +### Implement Required Reviews + +- Enforce branch protection rules +- Require code reviews before merging +- Use status checks to enforce security scans + +## OIDC Integration + +### Use OpenID Connect for Cloud Providers + +Instead of storing long-lived cloud credentials, use GitHub's OIDC provider: + +```yaml +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + id-token: write + contents: read + steps: + - uses: actions/checkout@v3 + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@v1 + with: + role-to-assume: arn:aws:iam::123456789012:role/github-actions + aws-region: eu-west-2 +``` + +### Limit OIDC Token Claims + +- Set specific subject claims in your cloud provider +- Implement additional claim conditions (repository, branch, environment) + +## Audit and Monitoring + +### Enable Audit Logging + +- Monitor GitHub Actions usage via audit logs +- Set up alerts for suspicious activity + +### Review Workflow Changes + +- Enforce code reviews for workflow file changes +- Use CODEOWNERS to restrict who can modify workflow files + +``` +# CODEOWNERS file/.github/workflows/ @security-team +``` + +### Regular Security Reviews + +- Conduct regular reviews of all workflows +- Update security practices based on emerging threats +- Monitor GitHub security advisories + +## Additional Resources + +- [GitHub Actions Security Hardening Guide](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions) +- [GitHub Security Lab](https://securitylab.github.com/) +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [Security for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions) + +## Conclusion + +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. + +Remember that security is an ongoing process - regularly review and update your security practices to adapt to new threats and challenges. diff --git a/practices/security.md b/practices/security.md index b8043bac..421e8fd4 100644 --- a/practices/security.md +++ b/practices/security.md @@ -137,6 +137,7 @@ The remainder of this page gives more detailed and specific recommendations to b - Secure **CI/CD** - Robust authentication and minimum privileges - Prefer ambient IAM credentials over retrieving credentials from secrets management. Do not store credentials in the plain. + - If using GitHub Actions follow the [Best Practices outlined here](./actions-best-practices.md) - **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))
Example IAM policy fragment to prevent unencrypted RDS databases (click to expand) From d5b5bda84c83bbd12f01363e2cb44c78deddfba2 Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Thu, 20 Mar 2025 17:07:12 +0000 Subject: [PATCH 2/4] resolving formatting issues --- practices/actions-best-practices.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index ce325a60..92602c83 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -7,6 +7,7 @@ GitHub Actions is a powerful automation tool that enables CI/CD workflows direct This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks. ## Table of Contents + - [Secrets Management](#secrets-management) - [Limiting Permissions](#limiting-permissions) - [Third-Party Actions](#third-party-actions) @@ -28,7 +29,8 @@ This guide outlines best practices for securing your GitHub Actions workflows an - Ensure a secret scanner is deployed as part of your workflows - Public repositories should enable GitHub Secret Scanner and Push Protection -### Minimize Secret Scope +### Minimize Secret Scope + ```yaml # Good practice - limiting secret to specific environment jobs: @@ -53,7 +55,8 @@ jobs: ### Use Least Privilege Principle -Limit the GitHub token permissions to only what's necessary: +Limit the GitHub token permissions to only what's necessary: + ```yaml permissions: contents: read @@ -80,7 +83,7 @@ To mitigate these risks, always follow best practices, such as pinning actions t ### Pin Actions to Specific Versions -Always use specific commit SHAs instead of tags or branches: +Always use specific commit SHAs instead of tags or branches: ```yaml # Not secure - can change unexpectedly @@ -203,7 +206,7 @@ jobs: - Enforce code reviews for workflow file changes - Use CODEOWNERS to restrict who can modify workflow files -``` +```plaintext # CODEOWNERS file/.github/workflows/ @security-team ``` From 00c7ced61c8f69bf10faeb57e62ed347aab05543 Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Mon, 24 Mar 2025 08:06:03 +0000 Subject: [PATCH 3/4] updating guidance, to include account id as a secret, splitting out list further and adding guidance around due diligence when using GitHub actions --- practices/actions-best-practices.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index 92602c83..162506fd 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -83,7 +83,7 @@ To mitigate these risks, always follow best practices, such as pinning actions t ### Pin Actions to Specific Versions -Always use specific commit SHAs instead of tags or branches: +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: ```yaml # Not secure - can change unexpectedly @@ -91,7 +91,7 @@ Always use specific commit SHAs instead of tags or branches: # Better - using a specific version tag - uses: actions/checkout@v3.1.0 # Best - using a specific commit SHA -- uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b +- uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.1.0 ``` ### Verify Third-Party Actions @@ -123,7 +123,9 @@ Always use specific commit SHAs instead of tags or branches: If using self-hosted runners: - Run them in isolated environments (containers/VMs) -- Regularly update and patch runner machines- Implement proper network isolation- Use ephemeral runners when possible +- Regularly update and patch runner machines +- Implement proper network isolation +- Use ephemeral runners when possible ```yaml jobs: @@ -185,7 +187,7 @@ jobs: - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v1 with: - role-to-assume: arn:aws:iam::123456789012:role/github-actions + role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions aws-region: eu-west-2 ``` From b19ab4fd7603a7b481c548cee830f848e9f8a5ed Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Tue, 25 Mar 2025 09:12:16 +0000 Subject: [PATCH 4/4] extending guidance following review --- practices/actions-best-practices.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index 162506fd..350203e4 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -19,6 +19,8 @@ This guide outlines best practices for securing your GitHub Actions workflows an ## Secrets Management +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. + ### Use GitHub Secrets - Store sensitive data (API tokens, credentials, etc.) as [GitHub Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) @@ -55,7 +57,7 @@ jobs: ### Use Least Privilege Principle -Limit the GitHub token permissions to only what's necessary: +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: ```yaml permissions: @@ -66,6 +68,8 @@ permissions: ### Use Fine-Grained Tokens +Fine grained tokens *must* only be used if the GitHub token can not be used. + - Create custom GitHub Apps with limited scopes when possible - Use repository-scoped tokens instead of organization-wide tokens @@ -83,7 +87,7 @@ To mitigate these risks, always follow best practices, such as pinning actions t ### Pin Actions to Specific Versions -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: +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: ```yaml # Not secure - can change unexpectedly @@ -96,6 +100,8 @@ When including a GitHub Action within your workflow you should perform due dilig ### Verify Third-Party Actions +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: + - Only use trusted actions from the GitHub Marketplace - Review the source code of third-party actions before using them - Consider forking and maintaining your own copy of critical actions @@ -120,7 +126,7 @@ When including a GitHub Action within your workflow you should perform due dilig ### Self-hosted Runner Security -If using self-hosted runners: +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: - Run them in isolated environments (containers/VMs) - Regularly update and patch runner machines