codeql.yml

# Code security analysis.
#
# Three complementary layers, because they catch different things:
#
#   1. CodeQL — deep taint-tracking over four languages. The C++ parser is the
#      real attack surface (it opens hostile ZIP archives), the Python layer
#      handles paths and templates, the shipped JavaScript renders untrusted
#      document text into a page, and the workflows themselves are code.
#   2. zizmor — static analysis of these workflows, for template injection,
#      credential persistence and over-broad permissions. CodeQL's `actions`
#      pack and zizmor overlap only partly; both are cheap.
#   3. dependency-review — blocks a pull request that introduces a dependency
#      with a known advisory, before it is ever merged.
#
# Query selection, path filters and the reasoning behind them live in
# .github/codeql/codeql-config.yml.

name: "Code security"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    # Weekly, so a newly published query or advisory finds existing code rather
    # than waiting for the next commit.
    - cron: '33 17 * * 5'
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: code-security-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ── CodeQL ──────────────────────────────────────────────────────────────────
  analyze:
    name: CodeQL (${{ matrix.language }})
    runs-on: ubuntu-latest
    timeout-minutes: 90

    permissions:
      # Required to upload results to the Security tab.
      security-events: write
      # Required to fetch internal or private CodeQL packs.
      packages: read
      # Only required for workflows in private repositories.
      actions: read
      contents: read

    strategy:
      fail-fast: false
      matrix:
        include:
          # Compiled with a real build rather than autobuild: autobuild would
          # configure CMake without pybind11 and without zlib headers, which
          # silently drops python_bindings.cpp — the Python/C++ trust boundary,
          # and the one file where a type confusion becomes a memory-safety bug
          # reachable from a script.
          - language: c-cpp
            build-mode: manual
          - language: python
            build-mode: none
          # report.js and diff.js are inlined verbatim into generated HTML
          # reports next to attacker-supplied comment text. A DOM-XSS finding
          # there is a live vulnerability in a file users email to each other.
          - language: javascript-typescript
            build-mode: none
          # The workflows in this directory are code with write permissions and
          # a publishing token in reach.
          - language: actions
            build-mode: none

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      # ── Setup for the manual C++ build ─────────────────────────────────────
      - name: Install C++ build dependencies
        if: matrix.language == 'c-cpp'
        run: sudo apt-get update -qq && sudo apt-get install -y zlib1g-dev

      - name: Set up Python for the pybind11 bindings
        if: matrix.language == 'c-cpp'
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install pybind11
        if: matrix.language == 'c-cpp'
        run: python -m pip install --upgrade pybind11

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
          config-file: ./.github/codeql/codeql-config.yml

      - name: Build C++ for analysis
        if: matrix.build-mode == 'manual'
        shell: bash
        run: |
          set -euo pipefail
          # Everything on: the shared library, the pybind11 extension and the
          # test suite, so CodeQL sees all four core sources plus the bindings.
          #
          # LTO is turned off for this build only. It changes nothing about the
          # analysis — CodeQL extracts from the compiler front-end, not from the
          # optimised object — and it removes a link-time step that has no value
          # here and a history of being slow.
          #
          # Note this is the *regular* CMake mode, not the wheel build: it emits
          # a shared library plus an extension that links against it, and writes
          # that extension into src/docx_comment_parser/ (see CMakeLists.txt).
          # Harmless on a throwaway runner; do not run this build in a working
          # tree whose in-place extension you rely on, because the result is not
          # self-contained and will fail to import.
          cmake -B build -S . \
            -DCMAKE_BUILD_TYPE=Release \
            -DBUILD_TESTS=ON \
            -DBUILD_PYTHON_BINDINGS=ON \
            -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF \
            -DPython3_EXECUTABLE="$(which python)"
          cmake --build build -j"$(nproc)"

          # pybind11 missing would only produce a CMake *warning* and a build
          # that skips python_bindings.cpp — a green, quietly incomplete
          # analysis, which is the exact failure mode this job exists to avoid.
          if ! find src/docx_comment_parser -name '_core*.so' | grep -q .; then
            echo "::error::pybind11 extension was not built; python_bindings.cpp is unanalysed"
            exit 1
          fi

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.language }}"

  # ── Workflow security audit ─────────────────────────────────────────────────
  # Finds the class of bug that turns a public repository into someone else's
  # PyPI account: `${{ }}` expansion inside a `run:` block, credentials left in
  # .git/config for a later step to exfiltrate, `pull_request_target` misuse,
  # and permissions wider than a job needs.
  actions-audit:
    name: Audit workflows (zizmor)
    runs-on: ubuntu-latest
    timeout-minutes: 15

    permissions:
      security-events: write
      contents: read
      actions: read

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: actions/setup-python@v5
        with:
          python-version: "3.x"

      - name: Install zizmor
        run: python -m pip install --upgrade zizmor

      - name: Audit workflows
        env:
          # Lets zizmor resolve action references online — needed for the
          # impostor-commit and unpinned-uses audits.
          GH_TOKEN: ${{ github.token }}
        # In SARIF mode zizmor always exits 0; findings are reported through the
        # Security tab rather than by failing the build, so a new advisory in a
        # third-party action does not block an unrelated pull request.
        run: zizmor --format sarif . > zizmor.sarif

      - name: Upload results
        uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: zizmor.sarif
          category: zizmor

  # ── Supply chain ────────────────────────────────────────────────────────────
  # The runtime install has zero dependencies, so this guards the extras and the
  # build/test toolchain — where a compromised or vulnerable package would still
  # be executing on a runner that can publish to PyPI.
  #
  # Requires the repository's dependency graph to be enabled (on by default for
  # public repositories: Settings → Code security → Dependency graph).
  dependency-review:
    name: Dependency review
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    timeout-minutes: 15

    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false

      - uses: actions/dependency-review-action@v4
        with:
          fail-on-severity: moderate
          comment-summary-in-pr: on-failure