From e0ee462c72bd9cde1341be37c04443ba8c8509ef Mon Sep 17 00:00:00 2001 From: Shivani Rana Date: Wed, 29 Apr 2026 15:35:23 +0100 Subject: [PATCH 1/3] Review GitHub Actions against CCOE guidance --- .../github-actions-best-practices.md | 96 +++++++++++++++++++ docs/github-actions-opus-prompt.md | 27 ++++++ 2 files changed, 123 insertions(+) create mode 100644 .github/instructions/github-actions-best-practices.md create mode 100644 docs/github-actions-opus-prompt.md diff --git a/.github/instructions/github-actions-best-practices.md b/.github/instructions/github-actions-best-practices.md new file mode 100644 index 000000000..3c8017a6b --- /dev/null +++ b/.github/instructions/github-actions-best-practices.md @@ -0,0 +1,96 @@ +# GitHub Actions Security Best Practices (NHSDigital) + +This file is a direct copy of the guidance from the NHSDigital Software Engineering Quality Framework: +https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/actions-best-practices.md + +_Last updated: 27 April 2026_ + +--- + +# 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. All actions used in committed workflow definitions must be pinned to a full-length commit SHA. + +## Table of Contents +- Secrets Management +- Limiting Permissions +- Third-Party Actions +- Dependency Management +- Runner Security +- Pull Request Workflows +- OIDC Integration +- Audit and Monitoring + +## Secrets Management +- Store sensitive data (API tokens, credentials, etc.) as GitHub Secrets +- Never hardcode sensitive values in your workflow files +- Do not use structured data as a secret - this can cause GitHub's 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 (limit to specific environments/jobs) +- Avoid exposing secrets in logs (don't echo/print secrets, set debug to false, use masking for dynamic secrets) +- Use robust secrets management tools (Azure Key Vault, AWS Secrets Manager) + +## Limiting Permissions +- Use least privilege principle for GITHUB_TOKEN +- Use fine-grained tokens only if GITHUB_TOKEN cannot be used +- Create custom GitHub Apps with limited scopes when possible +- Use repository-scoped tokens instead of org-wide tokens + +## Third-Party Actions +- Pin all actions to a commit SHA (with inline tag/version comment) +- Do not use tags or branch references in committed workflow definitions +- Review third-party actions before adoption +- Minimize use of third-party actions; prefer native/reusable/org actions +- Document rationale for third-party actions in docs/ADRs.md or similar +- Prefer actions with clear maintenance history, minimal permissions, and narrow scope +- Only use trusted actions from the GitHub Marketplace +- Consider forking/maintaining your own copy of critical actions +- Keep a record of approval/version reviewed +- Enable Dependabot alerts for GitHub Actions +- Set up a workflow to check for outdated actions + +## Dependency Management +- Use dependency scanning tools (e.g., Dependabot) +- Implement automated dependency updates +- Regularly review and update dependencies with security patches + +## Runner Security +- Self-hosted runners: use only with private repos, run in isolated environments, update/patch regularly, use network isolation, prefer ephemeral runners +- GitHub-hosted runners: be aware they are reset after each job, clean up sensitive data before job completion, don't store persistent sensitive data in runner env + +## Pull Request Workflows +- Don't expose secrets to PR workflows from forks +- Use pull_request_target carefully with read-only permissions +- 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 long-lived credentials +- Limit OIDC token claims (set specific subject claims, implement additional claim conditions) + +## Audit and Monitoring +- Enable audit logging for GitHub Actions usage +- Set up alerts for suspicious activity +- Enforce code reviews for workflow file changes +- Use CODEOWNERS to restrict workflow file modification +- 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. + +Security is an ongoing process—regularly review and update your security practices to adapt to new threats and challenges. diff --git a/docs/github-actions-opus-prompt.md b/docs/github-actions-opus-prompt.md new file mode 100644 index 000000000..f8d90e3df --- /dev/null +++ b/docs/github-actions-opus-prompt.md @@ -0,0 +1,27 @@ +# Opus 4.6 Assessment Prompt: GitHub Actions Security Best Practices + +Use this prompt with Opus 4.6 to assess your GitHub Actions workflows for compliance with NHSDigital best practices. + +--- + +**Prompt:** + +Please assess our GitHub Actions workflows for compliance with the NHSDigital GitHub Actions Security Best Practices (see docs/github-actions-best-practices.md). + +- Review all workflow files in .github/workflows/ (*.yml, *.yaml). +- Identify any gaps or violations, including but not limited to: + - Actions not pinned to commit SHAs + - Missing or overly broad permissions blocks + - Use of third-party actions without documentation or justification + - Secrets handling issues (e.g., secrets exposed, not using GitHub Secrets) + - Missing dependency scanning or update automation + - Runner security issues + - Pull request workflow security (e.g., secrets exposed to forks) + - OIDC integration and claim limitations + - Missing audit, monitoring, or CODEOWNERS controls + +Please provide: +1. An investigation writeup summarizing the current state and any risks. +2. A list of remediation tickets for each gap found, with suggested actions. + +--- From 03fc9a0b64e47889c4c1be4d7037d274f1944e84 Mon Sep 17 00:00:00 2001 From: Shivani Rana Date: Wed, 29 Apr 2026 16:55:20 +0100 Subject: [PATCH 2/3] fix check markdown failure --- .../github-actions-best-practices.md | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/.github/instructions/github-actions-best-practices.md b/.github/instructions/github-actions-best-practices.md index 3c8017a6b..d4ccdac4d 100644 --- a/.github/instructions/github-actions-best-practices.md +++ b/.github/instructions/github-actions-best-practices.md @@ -1,20 +1,17 @@ # GitHub Actions Security Best Practices (NHSDigital) -This file is a direct copy of the guidance from the NHSDigital Software Engineering Quality Framework: -https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/actions-best-practices.md - -_Last updated: 27 April 2026_ +This file is a direct copy of the guidance from the NHSDigital Software Engineering Quality Framework: [NHSDigital Actions Best Practices](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/actions-best-practices.md) +Last updated: 27 April 2026 --- -# 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. +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. All actions used in committed workflow definitions must be pinned to a full-length commit SHA. ## Table of Contents + - Secrets Management - Limiting Permissions - Third-Party Actions @@ -25,8 +22,9 @@ This guide outlines best practices for securing your GitHub Actions workflows an - Audit and Monitoring ## Secrets Management + - Store sensitive data (API tokens, credentials, etc.) as GitHub Secrets -- Never hardcode sensitive values in your workflow files +- Never hard-code sensitive values in your workflow files - Do not use structured data as a secret - this can cause GitHub's secret redaction in logs to fail - Rotate secrets regularly - Use environment-specific secrets when possible @@ -37,12 +35,14 @@ This guide outlines best practices for securing your GitHub Actions workflows an - Use robust secrets management tools (Azure Key Vault, AWS Secrets Manager) ## Limiting Permissions + - Use least privilege principle for GITHUB_TOKEN - Use fine-grained tokens only if GITHUB_TOKEN cannot be used - Create custom GitHub Apps with limited scopes when possible - Use repository-scoped tokens instead of org-wide tokens ## Third-Party Actions + - Pin all actions to a commit SHA (with inline tag/version comment) - Do not use tags or branch references in committed workflow definitions - Review third-party actions before adoption @@ -56,15 +56,18 @@ This guide outlines best practices for securing your GitHub Actions workflows an - Set up a workflow to check for outdated actions ## Dependency Management + - Use dependency scanning tools (e.g., Dependabot) - Implement automated dependency updates - Regularly review and update dependencies with security patches ## Runner Security + - Self-hosted runners: use only with private repos, run in isolated environments, update/patch regularly, use network isolation, prefer ephemeral runners -- GitHub-hosted runners: be aware they are reset after each job, clean up sensitive data before job completion, don't store persistent sensitive data in runner env +- GitHub-hosted runners: be aware they are reset after each job, clean up sensitive data before job completion, don't store persistent sensitive data in runner environment ## Pull Request Workflows + - Don't expose secrets to PR workflows from forks - Use pull_request_target carefully with read-only permissions - Enforce branch protection rules @@ -72,10 +75,12 @@ This guide outlines best practices for securing your GitHub Actions workflows an - Use status checks to enforce security scans ## OIDC Integration + - Use OpenID Connect for cloud providers instead of long-lived credentials - Limit OIDC token claims (set specific subject claims, implement additional claim conditions) ## Audit and Monitoring + - Enable audit logging for GitHub Actions usage - Set up alerts for suspicious activity - Enforce code reviews for workflow file changes @@ -85,12 +90,13 @@ This guide outlines best practices for securing your GitHub Actions workflows an - 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. +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. Security is an ongoing process—regularly review and update your security practices to adapt to new threats and challenges. From 07f5ec0cfce34fa6e90380b9d60e2c7dc43ea2b8 Mon Sep 17 00:00:00 2001 From: Shivani Rana Date: Wed, 29 Apr 2026 17:09:09 +0100 Subject: [PATCH 3/3] fix check markdown failure for opus prompt md --- docs/github-actions-opus-prompt.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/github-actions-opus-prompt.md b/docs/github-actions-opus-prompt.md index f8d90e3df..f39c28390 100644 --- a/docs/github-actions-opus-prompt.md +++ b/docs/github-actions-opus-prompt.md @@ -8,7 +8,7 @@ Use this prompt with Opus 4.6 to assess your GitHub Actions workflows for compli Please assess our GitHub Actions workflows for compliance with the NHSDigital GitHub Actions Security Best Practices (see docs/github-actions-best-practices.md). -- Review all workflow files in .github/workflows/ (*.yml, *.yaml). +- Review all workflow files in .github/workflows/ (`*.yml`, `*.yaml`). - Identify any gaps or violations, including but not limited to: - Actions not pinned to commit SHAs - Missing or overly broad permissions blocks @@ -21,6 +21,7 @@ Please assess our GitHub Actions workflows for compliance with the NHSDigital Gi - Missing audit, monitoring, or CODEOWNERS controls Please provide: + 1. An investigation writeup summarizing the current state and any risks. 2. A list of remediation tickets for each gap found, with suggested actions.