Skip to content

Commit 725e63e

Browse files
authored
docs(sast): document accepted CodeQL languages and fix runner docs. (#20)
1 parent 711025b commit 725e63e

4 files changed

Lines changed: 44 additions & 4 deletions

File tree

‎.github/workflows/README.md‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ Branch or tag references (`@main`, `@latest`) are not acceptable.
2121
**2. Grant every permission the workflow declares.** A caller must grant *at least* what the reusable workflow declares, or the run fails at load time with `requesting '<scope>', but is only allowed '<scope>: none'`.
2222
Copy the `permissions:` block from the scan's section — do not trim it to what looks necessary.
2323

24-
**3. Use a nv-gha-runner label as assigned.** `runs-on` takes a label (e.g. `linux-amd64-cpu4`). See the [runner label catalog](https://nv/gha-runner-labels) (NVIDIA-internal).
24+
**3. Set `runs-on` to a real label.** Scans that reach NVIDIA-internal services (OIDC → Vault, `nvcr.io`) run **only** on self-hosted runners and need an `nv-gha-runners` label (e.g. `linux-amd64-cpu4`) — see the [runner label catalog](https://nv/gha-runner-labels) (NVIDIA-internal).
25+
Scans with no internal dependency (CodeQL SAST) default to a GitHub-hosted runner and need no label. Each scan's section below states which applies.
2526

2627
**4. Onboard the repository first.** Runner access and repository-level expectations (Actions enabled, branch protection, `copy-pr-bot` for fork PRs) are in [Onboarding a repository](../../README.md#onboarding-a-repository).
2728

@@ -56,7 +57,7 @@ turning a default on is treated as a breaking change (see [Versioning](../../REA
5657
| Input | Enables | Notes |
5758
|---|---|---|
5859
| `enable-secret-scan` | [`secret-scan-pulse.yml`](secret-scan-pulse.yml) | Self-hosted `nv-gha-runners` and the Vault / Pulse variables required. |
59-
| `enable-sast-scan` | [`sast-scan-codeql.yml`](sast-scan-codeql.yml) | Requires `sast-languages`, and requires CodeQL Default setup to be **off**. Most repositories should stay on Default setup and leave this off. |
60+
| `enable-sast-scan` | [`sast-scan-codeql.yml`](sast-scan-codeql.yml) | Requires `sast-languages` — accepted values are listed under [Accepted `languages` values](#accepted-languages-values) — and requires CodeQL Default setup to be **off**. Most repositories should stay on Default setup and leave this off. |
6061

6162
**Grant the union of every scan's permissions, not just the ones you enable.** GitHub
6263
validates a caller against what the called workflow *declares*, before any `if:` is
@@ -143,7 +144,31 @@ Scan-specific prerequisites:
143144
- **Runner toolchain.** `build-mode: none` needs no toolchain. `build-mode: autobuild` needs the language's build tools.
144145
- **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.
145146

146-
Key inputs: `languages` (required, JSON array — one matrix leg per entry), `runs-on` (default `linux-amd64-cpu4`), `build-mode` (default `none`), `queries` (default `security-extended`), `packs`, `config-file`.
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`.
148+
149+
#### Accepted `languages` values
150+
151+
`languages` takes CodeQL's supported languages. Anything else fails at CodeQL init.
152+
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 |
165+
166+
Two gaps to plan around:
167+
168+
- **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`.
170+
171+
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.
147172

148173
```yaml
149174
permissions:

‎.github/workflows/sast-scan-codeql.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,13 @@ on:
2121
description: >-
2222
JSON array of CodeQL languages to analyze; each entry becomes a matrix leg. Examples: '["actions"]' or '["python","javascript-typescript"]'.
2323
Valid values: actions, c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby, rust, swift.
24+
CodeQL has no shell analyzer (cover Bash with a linter such as shellcheck) and no CUDA analyzer (c-cpp skips .cu/.cuh device code).
2425
type: string
2526
required: true
2627
runs-on:
27-
description: Runner label to run on (an nv-gha-runners label).
28+
description: >-
29+
Runner label to run on. CodeQL reaches no NVIDIA-internal service, so the GitHub-hosted default is fine;
30+
pass an nv-gha-runners label (e.g. linux-amd64-cpu4) only if the repository cannot use GitHub-hosted runners.
2831
type: string
2932
required: false
3033
default: ubuntu-latest

‎.github/workflows/security-suite.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ on:
5959
sast-languages:
6060
description: >-
6161
JSON array of CodeQL languages, for example '["actions"]'.
62+
Accepted values: actions, c-cpp, csharp, go, java-kotlin, javascript-typescript, python, ruby, rust, swift
63+
— see sast-scan-codeql.yml for per-language caveats.
6264
Required when enable-sast-scan is true; ignored otherwise.
6365
type: string
6466
required: false

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@ All notable changes to the workflows in this repository will be documented in th
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). See [`README.md`](README.md#versioning) for the SHA-pinning contract that consumers are expected to follow.
66

7+
## [Unreleased]
8+
9+
### Added
10+
11+
- Documentation — the accepted `languages` / `sast-languages` values are now listed in the [workflow catalogue](.github/workflows/README.md#accepted-languages-values), with the two coverage gaps consumers hit first: CodeQL has no shell analyzer (cover Bash with `shellcheck`) and no CUDA analyzer (`c-cpp` skips `.cu` / `.cuh` device code). The list previously existed only in the `sast-scan-codeql.yml` input description, so callers could not find it from the repository's documentation.
12+
13+
### Fixed
14+
15+
- Documentation — the workflow catalogue gave the CodeQL `runs-on` default as `linux-amd64-cpu4`; the workflow defaults to `ubuntu-latest`. The catalogue's shared runner rule also stated that every workflow needs an `nv-gha-runners` label, which is untrue for CodeQL — it reaches no NVIDIA-internal service. The `runs-on` input description in [`sast-scan-codeql.yml`](.github/workflows/sast-scan-codeql.yml) carried the same contradiction.
16+
717
## [0.3.0] - 2026-08-11
818

919
### Added

0 commit comments

Comments
 (0)