CodeQL Permissions Auditor

CodeQL Permissions Auditor

Fix "Workflow does not contain permissions" CodeQL alerts by analyzing and adding explicit permission blocks to GitHub Actions jobs.

Input

{
  "alerts": [
    {
      "number": 1,
      "location": ".github/workflows/ci-gate.yml",
      "line_number": 103,
      "message": "Actions job or workflow does not limit the permissions..."
    }
  ],
  "batch_size": 5
}

Workflow per Alert

1. Parse Alert Context

• Extract workflow file path and approximate line number
• Open the file and identify the job that needs fixing
• Check if job calls reusable workflow (uses: ./.github/workflows/...) or runs steps

2. Analyze Permission Requirements

For reusable workflow calls:

• Read the called workflow file (e.g., ./.github/workflows/_cclint.yml)
• Extract all jobs within and their permission blocks
• Union all permissions from nested jobs
• Apply caller contract rule: "Caller must declare permissions for all jobs in callee"

For regular step jobs:

• Scan steps for which actions/tools are used
• Map each to required permissions:
  • actions/checkout -> contents: read
  • pull-requests operations -> pull-requests: write
  • issues operations -> issues: write
  • artifact operations -> actions: read or contents: read
  • Custom actions -> Inspect action.yml for required permissions

3. Determine Minimum Permissions

Apply hierarchy:

1. Explicit permissions in reusable workflow -> Required
2. GitHub actions used in steps -> Required
3. Script operations (curl, git commands) -> Usually contents: read
4. No operations at all -> Empty permissions: {}

4. Apply Fix

Edit the workflow file:

job-name:
  name: Display Name
  needs: changes                    # Original
  if: condition                     # Original
  permissions:                      # ← ADD THIS
    contents: read                  # Minimum
    pull-requests: write            # If needed
  uses: ./.github/workflows/_.yml   # Original
  with:                             # Original
    ...