diff --git a/check-version-pinning/README.md b/check-version-pinning/README.md index 1626855..1138fd1 100644 --- a/check-version-pinning/README.md +++ b/check-version-pinning/README.md @@ -1,32 +1,87 @@ # Check Version Pinning GitHub Action -This Action scans your workflow files for untrusted GitHub Actions that are pinned to a version (`@v`) rather than a SHA hash. +This GitHub Action scans your workflow files to ensure all GitHub Actions are securely pinned to a SHA hash, rather than a version tag (`@v`). Using SHA pinning aligns with best practices to protect against unintended changes in third-party actions. + +## Purpose + +According to GitHub's security guidance, third-party actions should be pinned to a commit hash rather than a version tag for enhanced security. For instance, prefer this format: +```yaml +uses: oxsecurity/megalinter/flavors/python@32c1b3827a334c80026c654f31ee1b4801ad8798 +``` +over: +```yaml +uses: oxsecurity/megalinter/flavors/python@v1 +``` + +This Action inspects workflows to detect and report any actions that are not SHA-pinned, helping to secure your CI/CD pipeline. + +## Features + +- Simple SHA Check: This Action scans workflows based on the string after the @ symbol to verify SHA pinning. + +- Targeted Organisations: No organisations are treated as implicitly trusted, ensuring that all third-party actions must be SHA-pinned without exceptions. + +- Customisable Scanning Modes: Run a full scan of your repository or focus on changes within a pull request. + ## Inputs -### `workflow_directory` -The directory to scan for workflow files. Default is `.github/workflows`. +`workflow_directory` + +Specifies the directory to scan for workflow files. Defaults to .github/workflows if not set. + +`scan_mode` + +Defines the scope of the scan: -### `scan_mode` -The type of scan you wish to undertake: -- full = the whole repository. -- pr_changes = only changes in a pr. +- full: Scans all workflows in the specified directory. +- pr_changes: Scans only changes within a pull request (PR). ## Outputs -### `found_unpinned_actions` -A boolean indicating if any unpinned actions were found. +Provides a list of any unpinned actions detected in the repository. -## Example usage +## Example Usage + +Here's a typical workflow setup that uses this Action to enforce SHA pinning on actions: ```yaml +name: 🧪 Check Version Pinning + +on: + push: + branches: + - main + pull_request: + workflow_dispatch: + jobs: check-version-pinning: runs-on: ubuntu-latest + steps: - - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 0 # Disable shallow clones for a more comprehensive scan + - name: Check for unpinned Actions - uses: ministryofjustice/check-version-pinning-action@6b42224f41ee5dfe5395e27c8b2746f1f9955030 # v1.0.0 + uses: ministryofjustice/github-actions/check-version-pinning@ccf9e3a4a828df1ec741f6c8e6ed9d0acaef3490 # v18.5.0 with: workflow_directory: ".github/workflows" - scan_mode: "pr_changes" # Use "full" for a full repo scan + scan_mode: "full" ``` + +## Why This Action? + +We initially considered using actionlint but found it too restrictive for our use case. This Action is lightweight and focuses solely on verifying SHA pinning for third-party actions, making it simpler and more tailored to specific security needs. + +## Notes + +This Action will: + +- Flag any action with a version tag (e.g., @v1) rather than a SHA. + +- Not detect cases where third-party actions do not use semantic versioning or the v prefix in version tags. + +- Require all actions to be SHA-pinned, without any implicit trust for specific organisations like ministryofjustice or actions. + +By adding this Action to your workflows, you can ensure a more secure CI/CD setup that prevents accidental usage of unpinned or untrusted actions.