codeql.yml

name: CodeQL

# Static analysis of the C sources with CodeQL. c-cpp is the one extractor CodeQL has for
# both languages (the CLI still spells it `cpp`); what it records is whatever the traced
# compiler did, so a tree of .c files is extracted as C.
#
# Uses the "advanced" setup
# (not GitHub default setup) because the database must be built by tracing a real
# compile - here the host CMake build of every native env, which covers the security-critical cores
# (HTTP parser, WebSocket, multipart, base64/JSON, SSH crypto, SNMP, the codecs).
#
# The analyze step publishes a code-scanning check named "CodeQL" - require that
# context in the branch-protection rule / ruleset for main. (If GitHub "default"
# code scanning is enabled for C/C++, disable it under
# Settings -> Code security -> Code scanning so this advanced workflow can run.)

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "27 6 * * 1" # weekly, Mondays 06:27 UTC

permissions:
  contents: read

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

jobs:
  analyze:
    name: Analyze (c-cpp)
    runs-on: ubuntu-latest
    permissions:
      security-events: write # upload SARIF / publish the CodeQL check
      actions: read
      contents: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          submodules: true # include/MMgr: src/ builds against it

      - name: Set up Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.14"

      # PlatformIO only fetches the host build's libraries (Unity, littlefs) into .pio/libdeps/host.
      # The envs themselves are CMake targets.
      - name: Install PlatformIO and the host libraries
        run: |
          pip install --upgrade platformio
          python3 test/harness.py libs

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4.38.2
        with:
          languages: c-cpp
          queries: security-and-quality
          config-file: ./.github/codeql/codeql-config.yml

      # Host build of every native env: test/CMakeLists.txt, generated from test/test_matrix.json, so
      # adding an env to the matrix extends the scan with it. CodeQL traces the compiler, so a
      # translation unit is only analyzed if something here compiled it. MMgr's own suites are left
      # out: MMgr is a separate repository, and its sources are excluded in codeql-config.yml.
      #
      # Nothing is run here; test-report.yml runs and gates the tests. -k keeps the build going past a
      # failed target: extraction happens per compiler invocation, so the units that did compile are
      # still in the database, and stopping would discard the whole scan over one bad env - which is
      # how this workflow produced nothing at all. Failures go to the run summary instead.
      - name: Build (native, traced by CodeQL)
        run: |
          python3 tools/harness.py build cmake
          cmake -S test -B build/codeql -DMMGR_BUILD_TESTS=OFF
          rc=0
          cmake --build build/codeql -j "$(nproc)" -- -k >build.log 2>&1 || rc=$?
          FAILED="$(grep -c '^make\[[0-9]*\]: \*\*\*' build.log || true)"
          {
            echo "### CodeQL extraction"
            echo "cmake --build exited $rc; $FAILED failed make step(s)."
          } >>"$GITHUB_STEP_SUMMARY"
          if [ "$rc" -ne 0 ]; then
            grep -E 'error:|\*\*\*' build.log | head -50
            echo "::warning title=CodeQL build::the host build had failures; their units may be missing from the database"
          fi
          exit 0

      - name: Perform CodeQL analysis
        uses: github/codeql-action/analyze@v4.38.2
        with:
          category: "/language:c-cpp"