codeql.yml

---
# CodeQL Security Analysis
# Purpose: Performs deep static analysis to detect security vulnerabilities and coding errors.
# Trigger: Push to main, weekly schedule, and manual dispatch.
# Permissions:
#   - security-events: write (Required to upload SARIF results to the GitHub Security tab).
#   - actions: read (Required to determine workflow run status).
#   - contents: read (Required for code analysis).
# Concurrency:
#   - group: ${{ github.workflow }}-${{ github.ref }} (Ensures only the latest scan results are processed).
#   - cancel-in-progress: true (In-progress scans are superseded by newer commits to save resources).
# Design:
#   - Utilizes advanced matrix strategy for multi-language support (Go, Python).
#   - Leverages internal CodeQL autobuild for zero-config compilation where possible.

name: "🔬 CodeQL Analysis"

"on":
  push:
    branches:
      - "main"
      - "dev"
  pull_request:
    branches:
      - "main"
      - "dev"
      - "feat/**"
      - "branch/**"
      - "feature/**"
      - "fix/**"
      - "pr/**"

permissions: {}

env:
  UNIRTM_LOCKED: 1

jobs:
  analyze:
    name: "🛡️ Deep Semantic Analysis (${{ matrix.language }})"
    runs-on: ubuntu-latest
    concurrency:
      group: codeql-${{ github.workflow }}-${{ matrix.language }}-${{ github.event.pull_request.number || github.ref }}
      cancel-in-progress: true
    permissions:
      security-events: write # Required to upload SARIF results to the GitHub Security tab
      actions: read # Required to determine workflow run status
      contents: read # Required for code analysis
    timeout-minutes: 360 # Deep scans on large repos can take significant time

    strategy:
      fail-fast: false
      matrix:
        language:
          - actions
          # Uncomment the following lines when source files exist in the repo:
          - go # Go (*.go) — golangci-lint, gofmt
          # - python                # Python (*.py) — ruff, ansible-lint
          # - javascript-typescript # JS/TS (*.js, *.ts, *.jsx, *.tsx) — eslint
          # - c-cpp                 # C/C++/Obj-C (*.c, *.cpp, *.h) — clang-format
          # - csharp                # C# (*.cs) — dotnet format
          # - java-kotlin           # Java/Kotlin (*.java, *.kt) — ktlint
          # - ruby                  # Ruby (*.rb) — rubocop
          # - swift                 # Swift (*.swift) — swiftformat, swiftlint

    steps:
      - name: "🔒 Harden Runner"
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          disable-sudo: true
          egress-policy: block
          allowed-endpoints: >
            *.aquasecurity.github.io:443
            *.azurecr.io:443
            *.centos.org:443
            *.debian.org:443
            *.debian.org:80
            *.dkr.ecr.*.amazonaws.com:443
            *.gcr.io:443
            *.githubusercontent.com:443
            *.pkg.dev:443
            *.quay.io:443
            *.redhat.com:443
            *.rockylinux.org:443
            *.sigstore.dev:443
            *.ubuntu.com:443
            *.ubuntu.com:80
            api.github.com:443
            api.osv.dev:443
            api.securityscorecards.dev:443
            auth.docker.io:443
            cdn.deno.land:443
            deno.land:443
            dl-cdn.alpinelinux.org:443
            downloads.gradle-dn.com:443
            downloads.gradle.org:443
            files.pythonhosted.org:443
            formulae.brew.sh:443
            get.trivy.dev:443
            ghcr.io:443
            github.com:443
            index.crates.io:443
            index.docker.io:443
            nodejs.org:443
            oss-fuzz-build-logs.storage.googleapis.com:443
            osv-vulnerabilities.storage.googleapis.com:443
            packages.microsoft.com:443
            packagist.org:443
            pkg-containers.githubusercontent.com:443
            production.cloudflare.docker.com:443
            proxy.golang.org:443
            public.ecr.aws:443
            pypi.org:443
            registry-1.docker.io:443
            registry.npmjs.org:443
            registry.terraform.io:443
            registry.yarnpkg.com:443
            repo.maven.apache.org:443
            repo.yarnpkg.com:443
            rubygems.org:443
            services.gradle.org:443
            static.rust-lang.org:443
            sum.golang.org:443
            www.bestpractices.dev:443
            storage.googleapis.com:443
            go.dev:443
            golang.org:443
            *.actions.githubusercontent.com:443
            *.blob.core.windows.net:443
      - name: "📂 Checkout Repository Code"
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
        with:
          persist-credentials: false

      - name: "🛡️ Initialize CodeQL Engine"
        uses: github/codeql-action/init@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
        with:
          # Sets up the CodeQL database for the specified technical stack (e.g., Python, Go).
          languages: ${{ matrix.language }}
          config-file: .github/codeql/codeql-config.yml

      - name: "🚀 Bootstrap Target Build"
        uses: github/codeql-action/autobuild@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
        # Attempts to automatically compile the project to enable full-trace analysis.

      - name: "🔍 Perform Deep Security Analysis"
        uses: github/codeql-action/analyze@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
        with:
          # Executes the semantic queries and generates the final vulnerability report.
          category: "/language:${{ matrix.language }}"