feat: improve Macaron's GitHub Actions reports

.github/workflows/_build.yaml

@@ -52,7 +52,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 

.github/workflows/_build_docker.yaml

@@ -27,7 +27,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 

.github/workflows/_deploy-github-pages.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2023 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # This workflow deploys the documentations to GitHub Pages.
@@ -30,7 +30,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 

.github/workflows/_generate-rebase.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2023 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Automatically rebase main branch on top of release after a new package version is published.
@@ -36,7 +36,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
         token: ${{ secrets.REPO_ACCESS_TOKEN }}

.github/workflows/build_base_image.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2023 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2023 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # This workflow builds the base Docker image. The base image will be pushed to ghcr.io.
@@ -19,7 +19,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 

.github/workflows/build_semgrep_wheel.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2025 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2025 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # This is a manually-triggered workflow to build the minimal macaron dependencies image that stores the built-from-source
@@ -26,7 +26,7 @@ jobs:
     #   change the version tag in the 'name' description
     #   change the 'ref' field to use the commit hash of that tag
     - name: Check out Semgrep v1.113.0 repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         repository: semgrep/semgrep.git
         ref: 4729a05d24bf9cee8face447e8a6d418037d61d8 # v1.113.0

.github/workflows/codeql-analysis.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2025, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Run CodeQL over the package. For more configuration options see codeql/codeql-config.yaml
@@ -35,7 +35,7 @@ jobs:
     steps:
 
     - name: Checkout repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
     - name: Set up Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0

.github/workflows/macaron-analysis.yaml

@@ -26,7 +26,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
         persist-credentials: false

.github/workflows/pr-conventional-commits.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2024, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # This workflow lints the PR's title and commits. It uses the commitizen
@@ -25,7 +25,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 

.github/workflows/release.yaml

@@ -39,7 +39,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
         token: ${{ secrets.REPO_ACCESS_TOKEN }}
@@ -115,7 +115,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         fetch-depth: 0
 
@@ -305,7 +305,7 @@ jobs:
   #   steps:
 
   #   - name: Check out repository
-  #     uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+  #     uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
   #     with:
   #       fetch-depth: 0
 

.github/workflows/scorecards-analysis.yaml

@@ -1,4 +1,4 @@
-# Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2022 - 2026, Oracle and/or its affiliates. All rights reserved.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
 
 # Run Scorecard for this repository to further check and harden software and process.
@@ -29,7 +29,7 @@ jobs:
     steps:
 
     - name: Check out repository
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         persist-credentials: false
 

.github/workflows/test_macaron_action.yaml

@@ -28,7 +28,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -78,7 +78,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -143,7 +143,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -197,7 +197,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -270,7 +270,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -304,7 +304,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -337,7 +337,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -378,7 +378,7 @@ jobs:
       MACARON_IMAGE_TAG: ${{ inputs.macaron_image_tag }}
       DOCKER_PULL: never
     steps:
-    - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
     - name: Download test Docker image artifact
       if: ${{ inputs.docker_image_artifact_name != '' }}
       uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1

action.yaml

@@ -192,15 +192,24 @@ runs:
   - name: Enforce VSA generation
     if: ${{ always() && inputs.policy_file != '' }}
     run: |
+      RUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+      SUMMARY_URL="${RUN_URL}#macaron-analysis-summary"
+      REMEDIATIONS_URL="${RUN_URL}#macaron-full-findings-remediation-details"
       if [ "${VSA_GENERATED}" != "true" ]; then
-        echo "Policy verification failed. VSA was not generated at ${OUTPUT_DIR}/vsa.intoto.jsonl. Check uploaded reports."
+        echo "Policy verification failed. VSA was not generated at ${OUTPUT_DIR}/vsa.intoto.jsonl."
+        echo "Check Workflow summary and uploaded reports: ${SUMMARY_URL}"
+        echo "Full Findings and Remediation details: ${REMEDIATIONS_URL}"
+        echo "If the action failed but no findings are reported, check your configuration and make sure policy_purl is valid."
         exit 1
       fi
     shell: bash
     env:
       OUTPUT_DIR: ${{ inputs.output_dir }}
       VSA_GENERATED: ${{ steps.collect-reports.outputs.vsa_generated }}
       POLICY_FILE: ${{ inputs.policy_file }}
+      GITHUB_SERVER_URL: ${{ github.server_url }}
+      GITHUB_REPOSITORY: ${{ github.repository }}
+      GITHUB_RUN_ID: ${{ github.run_id }}
 
   - name: Upload Attestation
     if: ${{ inputs.upload_attestation == 'true' && steps.collect-reports.outputs.vsa_generated == 'true' }}

docs/source/pages/macaron_action.rst

@@ -1,10 +1,15 @@
 Macaron GitHub Action
 =====================
 
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
 Overview
 --------
 
 This document describes the composite GitHub Action defined in ``action.yaml`` at the repository root. The action uses the Macaron CLI to run supply-chain security analysis and policy verification from a GitHub Actions workflow.
+For the list of currently checked GitHub Actions security patterns, see the `GitHub Actions security analysis README <https://github.com/oracle/macaron/blob/main/src/macaron/code_analyzer/gha_security_analysis/README.md>`_.
 
 Quick usage
 -----------
@@ -17,11 +22,11 @@ When you use this action, you can reference it directly in your workflow. For a
     analyze:
       runs-on: ubuntu-latest
       steps:
-        - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         - name: Run Macaron Security Analysis Action
           uses: oracle/macaron@b31acfe389133a5587d9639063ec70cb84e7bc47 # v0.23.0
           with:
-            repo_path: 'https://github.com/example/project'
+            repo_path: ./
             policy_file: check-github-actions
             policy_purl: 'pkg:github.com/example/project@.*'
             reports_retention_days: 90

scripts/actions/write_job_summary.py

@@ -90,7 +90,7 @@ def _write_header(
         vsa_path = _env("VSA_PATH", f"{output_dir}/vsa.intoto.jsonl")
         policy_succeeded = bool(vsa_path) and Path(vsa_path).is_file()
 
-    _append_line(summary_path, "## Macaron Analysis Results")
+    _append_line(summary_path, "<h2 id=\"macaron-analysis-summary\">Macaron Analysis Results</h2>")
     _append_line(summary_path)
     if upload_reports:
         _append_line(summary_path, "Download reports from this artifact link:")
@@ -370,9 +370,14 @@ def write_compact_gha_vuln_diagnostics(summary_path: Path, columns: list[str], r
                     f"| {priority} | {finding_type} | {action_name} | {action_version} | {workflow} |",
                 )
 
+    _append_line(summary_path)
+    _append_line(
+        summary_path,
+        "<h2 id=\"macaron-full-findings-remediation-details\">Full Findings and Remediation Details</h2>",
+    )
     _append_line(summary_path)
     _append_line(summary_path, "<details>")
-    _append_line(summary_path, "<summary>Detailed findings</summary>")
+    _append_line(summary_path, "<summary>Show full findings</summary>")
     _append_line(summary_path)
     detail_groups = groups_in_rows if groups_in_rows else ["all_findings"]
     row_counter = 1

src/macaron/code_analyzer/gha_security_analysis/README.md

@@ -0,0 +1,48 @@
+# GitHub Actions Security Detection Rules
+
+This document describes the findings produced by:
+- `src/macaron/code_analyzer/gha_security_analysis/detect_injection.py`
+- `src/macaron/slsa_analyzer/checks/github_actions_vulnerability_check.py`
+
+These findings are shown in GitHub job summaries by `scripts/actions/write_job_summary.py` under:
+- `workflow_security_issue`
+- `third_party_action_risk`
+
+## Finding Groups and Priorities
+
+### `workflow_security_issue`
+
+| finding_type | Default priority | What triggers it |
+|---|---:|---|
+| `potential-injection` | 100 (critical) | A `run:` command uses attacker-controlled GitHub context values (for example PR head ref, issue/comment body) in shell execution. |
+| `untrusted-fork-code` | 100 (critical) | `actions/checkout` uses PR-controlled refs on `pull_request`. |
+| `pr-target-untrusted-checkout` | 100 (critical) | `pull_request_target` is used and checkout targets PR-controlled refs. |
+| `overbroad-permissions` | 80 (high) | Workflow/job uses broad write permissions (for example `permissions: write-all` or PR-target workflow with write scopes). |
+| `remote-script-exec` | 80 (high) | Pipe patterns like `curl ... \| bash/sh/tar` or `wget ... \| ...` are detected. |
+| `privileged-trigger` | 80 (high) | `pull_request_target` is combined with other risky patterns in the same workflow. |
+| `missing-permissions` | 60 (medium) | Workflow and at least one job omit explicit `permissions`. |
+| `self-hosted-runner` | 60 (medium) | Job runs on `self-hosted` runners. |
+
+### `third_party_action_risk`
+
+| finding_type | Default priority | What triggers it |
+|---|---:|---|
+| `known-vulnerability` | 100 (critical) | OSV reports the referenced GitHub Action version as affected by a known vulnerability. |
+| `unpinned-third-party-action` | 20 (low) | A third-party action uses a mutable ref (tag/branch/short SHA) instead of a full 40-char commit SHA. |
+
+## Rule Notes
+
+- Internal actions (`uses: ./...`) are excluded from unpinned-action findings.
+- `finding_type` is the subtype; `finding_group` is the report section key.
+- For workflow issue findings, line anchors are extracted from workflow metadata or inferred from source text.
+- `potential-injection` and `remote-script-exec` findings include structured payload data in the raw issue string (job, step, command, line metadata).
+
+## Remediation Intent by Rule
+
+- `potential-injection`: treat GitHub context as untrusted input; avoid direct shell interpolation.
+- `remote-script-exec`: avoid downloader-to-executor pipes; pin and verify scripts.
+- `missing-permissions` / `overbroad-permissions`: define explicit least-privilege permissions.
+- `untrusted-fork-code` / `pr-target-untrusted-checkout` / `privileged-trigger`: avoid executing PR-controlled code in privileged contexts.
+- `self-hosted-runner`: isolate runners and avoid untrusted workloads.
+- `known-vulnerability`: upgrade to a non-vulnerable action release.
+- `unpinned-third-party-action`: pin actions to immutable full commit SHAs.