Skip to content

Commit 2c53008

Browse files
authored
feat(sast): resolve CodeQL build mode per language.
* docs(sast): document accepted CodeQL languages and fix runner docs. * feat(sast): resolve CodeQL build mode per language. * docs(sast): correct consumer onboarding guidance; reject unknown entry keys. sast-scan-codeql.yml matrixed over languages but passed a single build-mode and a single runs-on to every leg, so language sets with differing requirements could not be expressed. Go rejects build-mode none and Rust supports nothing else, making '["go","rust"]' impossible whichever value was set. Add a resolve job that normalizes languages into a matrix, deriving a build mode per language the way GitHub Default setup does, so callers do not need to know the support table. build-mode becomes a preference applied where the language supports it, with each substitution reported as a job-log notice and the resolved matrix written to the job summary. Entries may also be objects carrying an explicit build-mode or runs-on; an explicit mode CodeQL does not support is an error rather than a silent substitution.
1 parent 725e63e commit 2c53008

6 files changed

Lines changed: 341 additions & 49 deletions

File tree

‎.github/workflows/README.md‎

Lines changed: 34 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -132,41 +132,56 @@ jobs:
132132
| Model | Use for | How |
133133
|---|---|---|
134134
| **Default setup** (Security Configuration) | The vast majority of repos | Org/enterprise owner enables it centrally; no file in the repo |
135-
| **This reusable workflow** | Repos needing custom query packs, path filters, a shared build step, or a centrally-pinned action | Add a caller (below) |
135+
| **This reusable workflow** | Repos needing path filters, a non-default query suite, or a centrally-pinned action | Add a caller (below) |
136136
| **Standalone advanced** | Rare repos with a bespoke, non-generalizable build | Repo-local `codeql.yml` |
137137

138138
Use `sast-scan-codeql.yml` only when you actually need the customization. If you don't, use Default setup.
139139

140140
Scan-specific prerequisites:
141141

142142
- **Licensing.** Public repos get code scanning free. Private/internal repos require GitHub Advanced Security (Code Security).
143-
- **Default setup must be off.** Default setup and an advanced/reusable CodeQL workflow are mutually exclusive; if Default setup is on, this workflow's upload fails.
143+
- **Default setup must not cover the same languages.** Default setup and this workflow both publish the `/language:<lang>` SARIF category, so any language covered by both makes the two uploads collide. Default setup covering *other* languages is fine and common — this repository runs exactly that way, with an org Security Configuration analyzing `python` while the self-test analyzes `actions`.
144144
- **Runner toolchain.** `build-mode: none` needs no toolchain. `build-mode: autobuild` needs the language's build tools.
145-
- **Rollout alerts-first.** Enable without a merge gate, triage the backlog, then enforce via branch protection — turning enforcement on fleet-wide on day one lights every repo red.
145+
- **This workflow never fails a pull request.** It publishes findings to code scanning and always exits 0 — there is no `failure_policy` equivalent, unlike [`secret-scan-pulse.yml`](secret-scan-pulse.yml). Enabling it buys visibility, not a merge gate. Gating is a separate, repository-side decision: configure it through code-scanning alert rules and branch protection once the backlog is triaged. Plan the rollout that way deliberately — turning enforcement on fleet-wide on day one lights every repo red.
146+
- **`queries` defaults to `security-extended`, which is broader than Default setup's `default` suite.** Expect a larger initial backlog than an equivalent Default-setup repo, and name a triage owner before enabling. Pass `queries: default` to match Default setup's volume.
147+
- **GHCR-hosted query `packs` are not usable.** The workflow does not declare `packages: read` and a called workflow's token cannot exceed what it declares, so granting the scope in the caller has no effect.
146148

147-
Key inputs: `languages` (required, JSON array — one matrix leg per entry), `runs-on` (default `ubuntu-latest`), `build-mode` (default `none`), `queries` (default `security-extended`), `packs`, `config-file`.
149+
Key inputs: `languages` (required, JSON array — one matrix leg per entry), `runs-on` (default `ubuntu-latest`), `build-mode` (default `none`), `resolve-runs-on` (default `ubuntu-latest`), `queries` (default `security-extended`), `packs`, `config-file`.
148150

149151
#### Accepted `languages` values
150152

151-
`languages` takes CodeQL's supported languages. Anything else fails at CodeQL init.
153+
`languages` takes CodeQL's supported languages. Anything else fails validation before any scan starts.
152154

153-
| Value | Covers |
154-
|---|---|
155-
| `actions` | GitHub Actions workflows |
156-
| `c-cpp` | C, C++ |
157-
| `csharp` | C# |
158-
| `go` | Go |
159-
| `java-kotlin` | Java, Kotlin |
160-
| `javascript-typescript` | JavaScript, TypeScript |
161-
| `python` | Python |
162-
| `ruby` | Ruby |
163-
| `rust` | Rust |
164-
| `swift` | Swift |
155+
| Value | Covers | Buildless (`none`) | Resolved mode by default |
156+
|---|---|---|---|
157+
| `actions` | GitHub Actions workflows | yes | `none` |
158+
| `c-cpp` | C, C++ | yes | `none` |
159+
| `csharp` | C# | yes | `none` |
160+
| `go` | Go | **no** | `autobuild` |
161+
| `java-kotlin` | Java, Kotlin | Java only — **Kotlin needs a build** | `none` |
162+
| `javascript-typescript` | JavaScript, TypeScript | yes | `none` |
163+
| `python` | Python | yes | `none` |
164+
| `ruby` | Ruby | yes | `none` |
165+
| `rust` | Rust | yes — **only** `none` | `none` |
166+
| `swift` | Swift | **no** (and macOS runners only) | `autobuild` |
165167

166-
Two gaps to plan around:
168+
**You do not have to work this table out yourself.** The workflow resolves a build mode per language, mirroring what GitHub Default setup picks,
169+
so languages with incompatible requirements can be combined in one call: `'["go","rust"]'` is valid even though Go rejects `none` and Rust accepts
170+
nothing else. Each substitution is reported as a notice in the job log, and the resolved matrix is written to the job summary.
171+
172+
`build-mode` sets your *preference*, applied wherever the language supports it. For exact control, use the object form of an entry:
173+
174+
```yaml
175+
sast-languages: '[{"language":"c-cpp","build-mode":"autobuild"},{"language":"swift","runs-on":"macos-14"},"rust"]'
176+
```
177+
178+
An explicit per-language `build-mode` that CodeQL does not support is an error, not a silent substitution — the run fails in the resolver with the offending
179+
pair named, before any analysis starts. `manual` is rejected everywhere: a reusable workflow cannot carry repo-specific build steps.
180+
181+
Two coverage gaps to plan around:
167182

168183
- **No shell analyzer.** CodeQL cannot analyze Bash or other shell. Cover shell with a linter such as [`shellcheck`](https://www.shellcheck.net/), typically at pre-commit.
169-
- **No CUDA analyzer.** The `c-cpp` extractor does not understand CUDA, so `.cu` / `.cuh` device code is not analyzed. A CUDA-heavy repository gets coverage only of its host-side translation units, and a useful C/C++ database usually needs `build-mode: autobuild` plus the full toolchain — price that build before enabling `c-cpp`.
184+
- **No CUDA analyzer.** The `c-cpp` extractor does not understand CUDA, so `.cu` / `.cuh` device code is not analyzed. A CUDA-heavy repository pays full C/C++ extraction cost for coverage of its host-side translation units only — measure that trade before enabling `c-cpp`.
170185

171186
Every entry is its own matrix leg, so scan cost scales with the list. Start with the languages carrying the most risk, then widen once you have a runtime and alert-volume baseline.
172187

‎.github/workflows/ci.yml‎

Lines changed: 123 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -290,9 +290,130 @@ jobs:
290290
security-events: write
291291
uses: ./.github/workflows/security-suite.yml
292292

293+
# SAST resolver — contract tests for the language matrix.
294+
#
295+
# Runs the resolver extracted from sast-scan-codeql.yml itself, so the tests exercise the shipped script rather than a copy that can drift.
296+
# Covers what a live scan cannot: build modes this repo has no sources for (go, rust, swift), and the rejection paths, whose expected outcome is a non-zero exit
297+
# Asserting them here keeps the run green, matching how the Pulse negatives above are shaped.
298+
# ============================================================================
299+
sast-resolver-contract:
300+
name: SAST resolver — contract tests
301+
runs-on: ubuntu-latest
302+
permissions:
303+
contents: read
304+
steps:
305+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
306+
with:
307+
persist-credentials: false
308+
309+
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
310+
with:
311+
python-version: '3.x'
312+
313+
- name: Extract the resolver from sast-scan-codeql.yml
314+
run: |
315+
set -euo pipefail
316+
pip install --quiet pyyaml
317+
python - <<'PY'
318+
import os, pathlib, yaml
319+
workflow = yaml.safe_load(pathlib.Path(".github/workflows/sast-scan-codeql.yml").read_text())
320+
script = workflow["jobs"]["resolve"]["steps"][0]["run"]
321+
pathlib.Path(os.environ["RUNNER_TEMP"], "resolve.sh").write_text(script)
322+
PY
323+
test -s "$RUNNER_TEMP/resolve.sh"
324+
325+
- name: Assert resolved matrices and rejections
326+
env:
327+
RESOLVER: ${{ runner.temp }}/resolve.sh
328+
run: |
329+
set -uo pipefail
330+
failures=0
331+
332+
# run <languages> <default-build-mode> -> sets $code and $matrix.
333+
# `|| code=$?` is required: Actions runs this step under `bash -e`, and the rejection
334+
# cases below expect the resolver to exit non-zero, which would otherwise abort the step.
335+
run_case() {
336+
: > "$RUNNER_TEMP/out.txt"
337+
code=0
338+
LANGUAGES="$1" DEFAULT_BUILD_MODE="$2" DEFAULT_RUNS_ON=ubuntu-latest \
339+
GITHUB_OUTPUT="$RUNNER_TEMP/out.txt" GITHUB_STEP_SUMMARY=/dev/null \
340+
bash "$RESOLVER" > "$RUNNER_TEMP/log.txt" 2>&1 || code=$?
341+
matrix=$(sed -n 's/^matrix=//p' "$RUNNER_TEMP/out.txt")
342+
}
343+
344+
expect_ok() {
345+
local name="$1" langs="$2" mode="$3" want="$4"
346+
run_case "$langs" "$mode"
347+
if [ "$code" -ne 0 ]; then
348+
echo "::error::${name}: expected success, exited ${code}"; cat "$RUNNER_TEMP/log.txt"; failures=$((failures+1)); return
349+
fi
350+
if ! diff -q <(printf '%s' "$matrix" | jq -S .) <(printf '%s' "$want" | jq -S .) >/dev/null; then
351+
echo "::error::${name}: matrix mismatch"
352+
echo " want: $(printf '%s' "$want" | jq -Sc .)"
353+
echo " got: $(printf '%s' "$matrix" | jq -Sc .)"
354+
failures=$((failures+1)); return
355+
fi
356+
echo "✓ ${name}"
357+
}
358+
359+
expect_rejected() {
360+
local name="$1" langs="$2" mode="$3"
361+
run_case "$langs" "$mode"
362+
if [ "$code" -eq 0 ]; then
363+
echo "::error::${name}: expected the resolver to reject this, but it succeeded"; failures=$((failures+1)); return
364+
fi
365+
if ! grep -q '::error::' "$RUNNER_TEMP/log.txt"; then
366+
echo "::error::${name}: failed without an actionable ::error:: message"; failures=$((failures+1)); return
367+
fi
368+
echo "✓ ${name} — $(grep -m1 '::error::' "$RUNNER_TEMP/log.txt" | sed 's/^::error:://')"
369+
}
370+
371+
leg() { printf '{"language":"%s","buildMode":"%s","runsOn":"%s"}' "$1" "$2" "${3:-ubuntu-latest}"; }
372+
373+
expect_ok "string array stays back-compatible" \
374+
'["actions","python"]' none \
375+
"{\"include\":[$(leg actions none),$(leg python none)]}"
376+
377+
expect_ok "go is promoted to autobuild, rust stays none" \
378+
'["go","rust"]' none \
379+
"{\"include\":[$(leg go autobuild),$(leg rust none)]}"
380+
381+
expect_ok "rust is demoted from a global autobuild preference" \
382+
'["c-cpp","rust"]' autobuild \
383+
"{\"include\":[$(leg c-cpp autobuild),$(leg rust none)]}"
384+
385+
expect_ok "explicit per-language build-mode is honoured" \
386+
'[{"language":"c-cpp","build-mode":"autobuild"},"python"]' none \
387+
"{\"include\":[$(leg c-cpp autobuild),$(leg python none)]}"
388+
389+
expect_ok "per-language runs-on reaches the leg" \
390+
'[{"language":"swift","runs-on":"macos-14"}]' none \
391+
"{\"include\":[$(leg swift autobuild macos-14)]}"
392+
393+
expect_ok "java-kotlin defaults to none like GitHub default setup" \
394+
'["java-kotlin"]' none \
395+
"{\"include\":[$(leg java-kotlin none)]}"
396+
397+
expect_rejected "unknown language" '["bash"]' none
398+
expect_rejected "rust with an explicit autobuild" '[{"language":"rust","build-mode":"autobuild"}]' none
399+
expect_rejected "manual build-mode" '[{"language":"go","build-mode":"manual"}]' none
400+
expect_rejected "duplicate language" '["python","python"]' none
401+
expect_rejected "empty language list" '[]' none
402+
expect_rejected "malformed JSON" '["python"' none
403+
expect_rejected "misspelled build-mode key" '[{"language":"go","buildMode":"none"}]' none
404+
expect_rejected "misspelled runs-on key" '[{"language":"swift","runsOn":"macos-14"}]' none
405+
406+
if [ "$failures" -ne 0 ]; then
407+
echo "::error::${failures} resolver contract case(s) failed"
408+
exit 1
409+
fi
410+
echo "All resolver contract cases passed."
411+
293412
# SAST (CodeQL) — self test the reusable workflow on this repo's own sources.
294413
# This repo is workflows + shell, so the relevant CodeQL language is "actions".
295-
# Alerts-first: analyze uploads to code scanning; it does not fail on findings.
414+
# Uses the object entry form so the parsing path a plain string array never reaches is covered end to end.
415+
# Only "actions" is analyzed: an org Security Configuration already runs CodeQL default setup for python on this repo, and analyzing it here too would
416+
# publish a second /language:python analysis for the same commit.
296417
# ============================================================================
297418
sast-codeql-dogfood:
298419
name: SAST (CodeQL) — self test
@@ -302,5 +423,5 @@ jobs:
302423
security-events: write
303424
uses: ./.github/workflows/sast-scan-codeql.yml
304425
with:
305-
languages: '["actions"]'
426+
languages: '[{"language":"actions","build-mode":"none"}]'
306427
runs-on: ubuntu-latest

0 commit comments

Comments
 (0)