Merge branch 'main' into feature/CCM-21880_Workflow_Perms_for_Repo_Sync

Author: jamesthompson26-nhs

.github/actions/build-docs/action.yml

@@ -16,6 +16,10 @@ inputs:
     description: "Additional pnpm workspace filters passed to pnpm install"
     required: false
     default: ""
+  GITHUB_TOKEN:
+    description: "Token for access to github package registry"
+    required: false
+    default: ""
 runs:
   using: "composite"
   steps:
@@ -29,6 +33,13 @@ runs:
     - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
       with:
         node-version: ${{ inputs.node_version }}
+    - name: "Configure pnpm for GitHub Packages"
+      if: ${{ inputs.GITHUB_TOKEN != '' }}
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.GITHUB_TOKEN }}
+      run: |
+        scripts/set-github-token.sh
     - name: Install pnpm dependencies
       run: pnpm install --frozen-lockfile --filter ./docs ${{ inputs.pnpm_filters }}
       shell: bash

.github/actions/scan-dependencies/action.yaml

@@ -20,7 +20,7 @@ inputs:
     description: "IDP AWS report upload endpoint to upload the report to"
     required: false
   skip_if_pr_has_label:
-    description: "Skip dependency scanning when the triggering PR has this label"
+    description: "Skip failing the dependency scan when the triggering PR has this label"
     required: false
     default: "skip-dependencies-check"
 runs:
@@ -68,40 +68,32 @@ runs:
         fi
 
         echo "should_skip=${SHOULD_SKIP}" >> "$GITHUB_OUTPUT"
-    - name: "Skip dependency scan"
-      if: steps.skip-check.outputs.should_skip == 'true'
-      shell: bash
-      run: |
-        echo "Dependency scan skipped because PR has label '${{ inputs.skip_if_pr_has_label }}'."
     - name: "Generate SBOM"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: |
         ACTION_ROOT="$(cd "${GITHUB_ACTION_PATH}/../../.." && pwd)"
         export TOOLING_ROOT="${ACTION_ROOT}"
         export BUILD_DATETIME=${{ inputs.build_datetime }}
         "${ACTION_ROOT}/scripts/reports/create-sbom-report.sh"
     - name: "Compress SBOM report"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: zip sbom-repository-report.json.zip sbom-repository-report.json
     - name: "Upload SBOM report as an artefact"
-      if: ${{ !env.ACT && steps.skip-check.outputs.should_skip != 'true' }}
+      if: ${{ !env.ACT }}
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
       with:
         name: sbom-repository-report.json.zip
         path: ./sbom-repository-report.json.zip
         retention-days: 21
     - name: "Scan vulnerabilities"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: |
         ACTION_ROOT="$(cd "${GITHUB_ACTION_PATH}/../../.." && pwd)"
         export TOOLING_ROOT="${ACTION_ROOT}"
         export BUILD_DATETIME=${{ inputs.build_datetime }}
+        export SCAN_FAIL_ON_SEVERITY=none
         "${ACTION_ROOT}/scripts/reports/scan-vulnerabilities.sh"
     - name: "Generate vulnerabilities summary"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: |
         ACTION_ROOT="$(cd "${GITHUB_ACTION_PATH}/../../.." && pwd)"
@@ -110,48 +102,49 @@ runs:
           cat vulnerabilities-summary.md >> "$GITHUB_STEP_SUMMARY"
         fi
     - name: "Compress vulnerabilities report"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: zip vulnerabilities-repository-report.json.zip vulnerabilities-repository-report.json
     - name: "Upload vulnerabilities report as an artefact"
-      if: ${{ !env.ACT && steps.skip-check.outputs.should_skip != 'true' }}
+      if: ${{ !env.ACT }}
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
       with:
         name: vulnerabilities-repository-report.json.zip
         path: ./vulnerabilities-repository-report.json.zip
         retention-days: 21
     - name: "Upload vulnerabilities summary as an artefact"
-      if: ${{ !env.ACT && steps.skip-check.outputs.should_skip != 'true' }}
+      if: ${{ !env.ACT }}
       uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
       with:
         name: vulnerabilities-summary.md
         path: ./vulnerabilities-summary.md
         retention-days: 21
     - name: "Fail if Critical or High vulnerabilities found"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       run: |
         CRITICAL_COUNT=$(jq '[.matches[] | select(.vulnerability.severity == "Critical") | {id: .vulnerability.id, package: .artifact.name, version: .artifact.version}] | unique_by([.id, .package, .version]) | length' vulnerabilities-repository-report.json)
         HIGH_COUNT=$(jq '[.matches[] | select(.vulnerability.severity == "High") | {id: .vulnerability.id, package: .artifact.name, version: .artifact.version}] | unique_by([.id, .package, .version]) | length' vulnerabilities-repository-report.json)
         echo "Critical: $CRITICAL_COUNT, High: $HIGH_COUNT"
         if [[ "$CRITICAL_COUNT" -gt 0 || "$HIGH_COUNT" -gt 0 ]]; then
-          echo "::error::Found $CRITICAL_COUNT Critical and $HIGH_COUNT High severity vulnerabilities"
-          exit 1
+          if [[ "${{ steps.skip-check.outputs.should_skip }}" == "true" ]]; then
+            echo "Bypassing blocking dependency scan failure because PR has label '${{ inputs.skip_if_pr_has_label }}'."
+          else
+            echo "::error::Found $CRITICAL_COUNT Critical and $HIGH_COUNT High severity vulnerabilities"
+            exit 1
+          fi
         fi
     - name: "Check prerequisites for sending the reports"
-      if: steps.skip-check.outputs.should_skip != 'true'
       shell: bash
       id: check
       run: echo "secrets_exist=${{ inputs.idp_aws_report_upload_role_name != '' && inputs.idp_aws_report_upload_bucket_endpoint != '' }}" >> $GITHUB_OUTPUT
     - name: "Authenticate to send the reports"
-      if: steps.skip-check.outputs.should_skip != 'true' && steps.check.outputs.secrets_exist == 'true'
+      if: steps.check.outputs.secrets_exist == 'true'
       uses: aws-actions/configure-aws-credentials@acca2b1b2070338fb9fd1ca27ecee81d687e58e5 # v6.1.2
       with:
         role-to-assume: arn:aws:iam::${{ inputs.idp_aws_report_upload_account_id }}:role/${{ inputs.idp_aws_report_upload_role_name }}
         aws-region: ${{ inputs.idp_aws_report_upload_region }}
     - name: "Send the SBOM and vulnerabilities reports to the central location"
       shell: bash
-      if: steps.skip-check.outputs.should_skip != 'true' && steps.check.outputs.secrets_exist == 'true'
+      if: steps.check.outputs.secrets_exist == 'true'
       run: |
         aws s3 cp \
           ./sbom-repository-report.json.zip \

.pre-commit-hooks.yaml

@@ -51,3 +51,10 @@
   entry: .github/actions/check-todo-usage/check-todos.sh
   language: script
   pass_filenames: false
+
+- id: scan-dependencies
+  name: Scan dependencies
+  entry: scripts/githooks/scan-dependencies.sh
+  language: script
+  pass_filenames: false
+  stages: [manual]

.tool-versions

@@ -9,6 +9,7 @@ terraform-docs 0.19.0
 trivy 0.69.2
 vale 3.6.0
 python 3.13.5
+ruby 3.2.0
 
 # ==============================================================================
 # The section below is reserved for Docker image versions.

docs/github-actions/scan-dependencies.md

@@ -13,23 +13,50 @@ Scans project dependencies for known vulnerabilities.
 ### Description
 
 This composite action scans project dependencies to identify known security vulnerabilities.
+It always produces the SBOM, raw Grype JSON report, and markdown summary, and it fails the workflow when High or Critical vulnerabilities are present unless the triggering PR carries a configured skip label.
 
 ### Usage
 
 ```yaml
 jobs:
   scan-deps:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
     steps:
       - uses: actions/checkout@v4
 
       - name: Scan dependencies
         uses: NHSDigital/nhs-notify-shared-modules/.github/actions/scan-dependencies@v1.0.0
+        with:
+          build_datetime: "${{ needs.metadata.outputs.build_datetime }}"
+          build_timestamp: "${{ needs.metadata.outputs.build_timestamp }}"
+          skip_if_pr_has_label: grype-ignore-high-and-critical
 ```
 
 ### Details
 
 - Scans: npm packages, Ruby gems, Python packages
-- Checks: Known vulnerabilities (CVEs)
-- Reports: Security advisories
-- Alerts: High-risk dependencies
+- Checks: Known vulnerabilities or CVE findings
+- Reports: SBOM JSON, Grype JSON, and markdown summary
+- Alerts: High and Critical vulnerabilities fail by default
+
+### Ignore File
+
+If a repository contains a file at `scripts/config/grype.yaml`, each non-comment line is treated as a Grype vulnerability ID to suppress. For example:
+
+```text
+CVE-2026-25128 # Ticket to review: CCM-14317
+GHSA-xxxx-yyyy-zzzz
+```
+
+### Skip Label
+
+Set `skip_if_pr_has_label` to a PR label name if you need to skip the blocking failure for known High or Critical findings that are already being handled elsewhere.
+
+- The scan still runs.
+- Reports and summaries are still uploaded.
+- Only the final blocking failure is skipped when the label is present.
+
+The default label is `skip-dependencies-check`.

docs/pre-commit-hooks.md

@@ -115,6 +115,25 @@ Validates TODO comments follow the required format with Jira ticket IDs.
     - id: check-todo-usage
 ```
 
+#### scan-dependencies
+
+Runs the same SBOM and Grype dependency scan used in CI and prints the markdown vulnerability summary locally.
+
+**Usage:**
+
+```yaml
+- repo: https://github.com/NHSDigital/nhs-notify-shared-modules
+  rev: vX.Y.Z
+  hooks:
+    - id: scan-dependencies
+```
+
+Run it manually when needed:
+
+```bash
+pre-commit run --config scripts/config/pre-commit.yaml --hook-stage manual scan-dependencies
+```
+
 ## Setup in Your Repository
 
 Add to your `.pre-commit-config.yaml`:
@@ -128,6 +147,7 @@ repos:
       - id: check-file-format
       - id: check-markdown-format
       - id: lint-terraform
+      - id: scan-dependencies
       # Add other hooks as needed
 ```
 
@@ -142,3 +162,4 @@ pre-commit install
 - All hooks run with `pass_filenames: false` - they operate on the entire repository
 - The `scan-secrets` hook checks the entire Git history for security
 - Hooks reference scripts in either `scripts/githooks/` or `.github/actions/`
+- `scan-dependencies` uses the same Grype-based workflow as CI, respects `scripts/config/grype.yaml` when present, and is configured as a manual-only hook

scripts/config/pre-commit.yaml

@@ -70,3 +70,11 @@ repos:
         entry: /usr/bin/env check=branch ./.github/actions/check-todo-usage/check-todos.sh
         language: script
         pass_filenames: false
+  - repo: local
+    hooks:
+      - id: scan-dependencies
+        name: Scan dependencies
+        entry: ./scripts/githooks/scan-dependencies.sh
+        language: script
+        pass_filenames: false
+        stages: [manual]

scripts/config/syft.yaml

@@ -4,6 +4,8 @@
 #   - "./out/**/*.json"
 exclude:
   - ./.git/**
+  - ./**/terraform/**/.terraform/**
+  - ./**/terraform/plugin-cache/**
 
 # maximum number of workers used to process the list of package catalogers in parallel
 parallelism: 3

scripts/githooks/scan-dependencies.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TOOLING_ROOT="${TOOLING_ROOT:-$(cd "${SCRIPT_DIR}/../.." && pwd)}"
+
+cd "$(git rev-parse --show-toplevel)"
+
+export BUILD_DATETIME="${BUILD_DATETIME:-$(date -u +'%Y-%m-%dT%H:%M:%S%z')}"
+export SCAN_FAIL_ON_SEVERITY="${SCAN_FAIL_ON_SEVERITY:-none}"
+
+echo "Step 1: Creating SBOM..."
+"${TOOLING_ROOT}/scripts/reports/create-sbom-report.sh" > /dev/null 2>&1
+[[ -f sbom-repository-report.json ]] && echo "  ✓ SBOM created" || echo "  ✗ SBOM not found"
+
+echo "Step 2: Scanning vulnerabilities..."
+"${TOOLING_ROOT}/scripts/reports/scan-vulnerabilities.sh"
+
+echo "Step 3: Parsing vulnerabilities..."
+REPORT_FILE=""
+if [[ -f vulnerabilities-repository-report.json ]]; then
+  REPORT_FILE="vulnerabilities-repository-report.json"
+elif [[ -f vulnerabilities-repository-report.tmp.json ]]; then
+  REPORT_FILE="vulnerabilities-repository-report.tmp.json"
+fi
+
+if [[ -n "$REPORT_FILE" ]]; then
+  "${TOOLING_ROOT}/scripts/reports/parse-vulnerabilities.sh" "$REPORT_FILE" "true"
+
+  # Check if Critical or High vulnerabilities exist and fail
+  CRITICAL_COUNT=$(jq '[.matches[] | select(.vulnerability.severity == "Critical") | {id: .vulnerability.id, package: .artifact.name, version: .artifact.version}] | unique_by([.id, .package, .version]) | length' "$REPORT_FILE")
+  HIGH_COUNT=$(jq '[.matches[] | select(.vulnerability.severity == "High") | {id: .vulnerability.id, package: .artifact.name, version: .artifact.version}] | unique_by([.id, .package, .version]) | length' "$REPORT_FILE")
+
+  if [[ "$CRITICAL_COUNT" -gt 0 || "$HIGH_COUNT" -gt 0 ]]; then
+    echo ""
+    echo "❌ Found $CRITICAL_COUNT Critical and $HIGH_COUNT High severity vulnerabilities"
+    exit 1
+  fi
+else
+  echo ""
+  echo "❌ Error: No vulnerability report found"
+  echo "  Expected: vulnerabilities-repository-report.json or vulnerabilities-repository-report.tmp.json"
+  exit 1
+fi

scripts/init.mk

@@ -40,6 +40,12 @@ githooks-run: # Run git hooks configured in this repository @Operations
 		--config scripts/config/pre-commit.yaml \
 		--all-files
 
+githooks-dependencies: # Run git hook for manually scanning depdencies
+	pre-commit run \
+		--config scripts/config/pre-commit.yaml \
+		--hook-stage manual scan-dependencies \
+		--all-files
+
 _install-dependency: # Install asdf dependency - mandatory: name=[listed in the '.tool-versions' file]; optional: version=[if not listed]
 	echo ${name}
 	asdf plugin add ${name} ||: