codeql.yml

# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2025-2026 SKY, LLC.
#
# ─────────────────────────────────────────────────────────────────────────────
# CodeQL — static-analysis (SAST) for Rust
#
# What this catches that the other gates don't:
#
#   * cargo-deny   → known CVEs + license policy + source allow-list
#   * cargo-vet    → trust chain for every resolved crate-version
#   * cargo-geiger → structural unsafe / build.rs / proc-macro footprint
#   * clippy       → lint-level correctness + idiom issues
#   * CodeQL       → *semantic* bug patterns (path injection, SQL/regex
#                    injection, cryptographic misuse, unsafe cryptographic
#                    default picks, unvalidated URL redirections, …) that
#                    fire on whole-program dataflow rather than local AST
#                    shape.
#
# Rust support status:
#
#   CodeQL 2.22.1 (July 2025) brought Rust to **public preview**; CodeQL
#   2.23.3 / 2.23.7 / 2.23.8 added additional queries; CodeQL 2.25.x
#   (bundled with codeql-action v4.35.x) is the current baseline.  Rust
#   support currently ONLY accepts `build-mode: none` — the CodeQL
#   bundle includes its own Rust parser / analyzer and resolves crate
#   metadata without invoking cargo.  Treat failures as informational
#   on first rollout; the query pack is still maturing, and the check
#   is NOT wired into branch protection for that reason.
#
# Triggers:
#
#   * `schedule` — weekly baseline, independent of PR traffic.  Tuesday
#     06:30 UTC is a deliberate offset from the Monday 06:00 Tier 2 cron
#     and the Monday 08:00 cargo-vet-refresh cron so the three weekly
#     jobs don't share a runner queue.
#   * `push: main` — capture the baseline on every merge.
#   * `pull_request: main` — catches regressions before merge.  If the
#     query pack gets noisy on a PR and blocks a human, the workflow
#     can be re-run or temporarily disabled via `workflow_dispatch`; it
#     is deliberately NOT added to required checks.
#
# Cost:
#
#   ~5-10 min per run on ubuntu-22.04.  `build-mode: none` means no
#   cargo build, no rust-cache, no debuginfo fetch — the Rust extractor
#   parses source directly and emits a small DB (hundreds of MB rather
#   than the multi-GB DB a compiled-extraction language like C++ would
#   produce).

name: "🔍 CodeQL (Rust SAST)"

on:
  push:
    branches: [main]
    paths:
      - '**/*.rs'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - '**/Cargo.toml'
      - '**/Cargo.lock'
      - 'rust-toolchain.toml'
      - '.github/workflows/codeql.yml'
  pull_request:
    branches: [main]
    paths:
      - '**/*.rs'
      - 'Cargo.toml'
      - 'Cargo.lock'
      - '**/Cargo.toml'
      - '**/Cargo.lock'
      - 'rust-toolchain.toml'
      - '.github/workflows/codeql.yml'
  schedule:
    # Weekly baseline — Tuesday 06:30 UTC (offset from Monday Tier 2 +
    # Monday cargo-vet refresh so they don't share a runner queue).
    - cron: '30 6 * * 2'
  workflow_dispatch:

permissions:
  # Read source + write SARIF to the repo's code-scanning panel.
  # `security-events: write` is the permission that lets
  # `codeql-action/analyze` post findings to the Security tab.
  contents: read
  security-events: write
  # Required by codeql-action for CI artifact publishing on old runners.
  actions: read

# Cancel superseded PR runs; let scheduled / main-push runs complete.
concurrency:
  group: codeql-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-22.04
    timeout-minutes: 20
    # CodeQL is informational-only on UFFS (Rust support is in public
    # preview; we do not wire it into branch protection — see the
    # header comment above for the rationale).  `continue-on-error:
    # true` codifies that intent at the workflow-engine level:
    #
    #   * When the job fails — e.g. because `codeload.github.com`
    #     returned 429s for the `github/codeql-action` tarball during
    #     "Set up job", which is structurally un-retryable from inside
    #     our steps — the workflow-level conclusion remains `success`.
    #     The job itself still shows ❌ in the PR's check-runs panel
    #     so genuine analysis failures stay visible (and the Security
    #     tab continues to receive findings on green runs), but the
    #     red badge no longer leaks into the workflow conclusion that
    #     auto-merge / branch protection observe.
    #
    #   * Paired with `auto-rerun-transient.yml` (Layer B): that
    #     watcher fires on every completed run regardless of conclusion
    #     and reruns the failed jobs once if their logs match transient
    #     signatures (429 / ECONNRESET / etc.).  So 429-class failures
    #     are silently retried; only persistent failures stay red.
    #
    # Reference: 2026-05-12 PR F (this PR) — auto-rerun-transient
    # workflow + this continue-on-error flag, landed together.
    continue-on-error: true
    strategy:
      fail-fast: false
      matrix:
        language: [rust]

    steps:
      - name: Checkout repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          # §2.8: pin checkout to the PR head SHA (not the synthetic
          # merge commit that `actions/checkout` defaults to for PR
          # events).  For `push` / `schedule` / `workflow_dispatch`,
          # `pull_request.head.sha` is undefined and we fall back to
          # `github.sha` — which is already the correct commit for
          # those triggers.  Net effect: CodeQL always analyses the
          # exact bytes pushed / proposed, never a synthetic merge.
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Initialize CodeQL
        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
        with:
          languages: ${{ matrix.language }}
          # Rust support (public preview) currently only accepts
          # `build-mode: none`.  In this mode the extractor parses the
          # source tree directly and resolves crate metadata via
          # CodeQL's own bundled tooling — no cargo / rustc invocation,
          # no build cache required.
          build-mode: none
          # security-extended adds higher-recall queries at the cost of
          # more findings to triage; start with the default `security`
          # pack and upgrade once we've seen a few weeks of baseline.
          # queries: security-and-quality

      - name: Perform CodeQL analysis
        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
        with:
          category: "/language:${{ matrix.language }}"