themarmack codeql-onboarding-helper
A Category 3 ops tool. CodeQL setup has more decision points than people realize: setup type, query suite, custom packs, triage routing, exception process. Getting them wrong on a regulated-data repo means false negatives (real findings missed) or false-positive saturation (real findings buried). This skill makes the decision tree explicit.
When to use
- Onboarding a new repo to GHAS code scanning.
- Refactoring an existing CodeQL setup that's been ignored or under-tuned.
- Org-wide consistency audit: are repos using the right query suite for their language + risk?
- Planning a custom pack rollout (org-specific patterns).
When NOT to use
- Specific alert triage / dismissal → out of scope.
- Building a custom CodeQL query →
codeql-pattern-finder. - Workflow-level Actions security →
actions-workflow-hardener. - Org-wide GHAS posture →
ghas-config-reviewer.
Decision matrix
Default setup vs advanced setup
| Use default setup if | Use advanced setup if |
|---|---|
| Standard build (no custom JDK pin, no proprietary build system) | Custom build command, monorepo with non-standard layout |
| GitHub-hosted runners are acceptable | Build requires private-network access (internal Maven, internal pip) |
| No custom packs needed | Custom CodeQL packs (community or org-internal) needed |
| Standard query suite is sufficient | Need to combine multiple suites or modify per-language |
| Repo's languages are all CodeQL-default-supported | Build matrix is complex |
For a regulated organization, advanced setup is the more common right answer because of internal-Maven/npm registry access requirements for the build step.
Query suite selection
| Suite | When to use | Trade-off |
|---|---|---|
code-scanning (default) |
Low-stakes repos, exploratory phases | Misses some real findings |
security-extended |
Default for regulated-data repos | More findings, higher false-positive rate; requires triage discipline |
security-and-quality |
Repos where code quality alerts are wanted alongside security | Largest alert volume; reserve for repos with dedicated review capacity |
Custom pack recommendation
- Community packs:
github/codeqlcontains the standard packs; per-language community packs atcodeql-packs/*cover ecosystem-specific patterns (e.g. spring/log4j hardening). - Bank-internal packs (TBD; not built yet): cover org-specific patterns — internal data-access wrappers, deprecated crypto APIs, internal auth token misuse. Worth building once the SDLC modernization program has a critical mass of repeated patterns to encode.
Alert triage workflow
For each repo:
- Severity routing: critical/high → CODEOWNERS-assigned reviewer within 7 days; medium → 30 days; low → 90 days or auto-dismiss per [[2026-06-20-dependabot-best-practices-regulated-org]] auto-triage pattern.
- Dismissal rules: dismissals require a comment with category (false-positive | won't-fix | mitigated | duplicate). The comment becomes audit evidence.
- Exception process: a finding dismissed as
won't-fixrequires adecisions/note viacopilot-exception-handler-equivalent pattern (a futureghas-exception-handlerwould generalize this).
Output
An onboarding plan note at vault/research/codeql/YYYY-MM-DD-codeql-onboarding-{repo-slug}.md. Present the plan in chat for the user (it goes to the repo owner), then — as the explicit final step — write the full plan via vault-writer.write_research to that path (frontmatter per research.yml, topic: codeql) so the next session can query it. Structure:
- Repo context — language(s), stack, risk profile, current state.
- Setup-type decision — default vs advanced, with rationale.
- Query suite recommendation — which suite + why.
- Custom packs — list + rationale.
- Sample workflow (if advanced setup) — ready-to-commit
.github/workflows/codeql.yml. - Triage workflow — concrete rules for this repo.
- Exception process — how this repo's team handles
won't-fixfindings. - Acceptance checklist — what "onboarded" means for this repo.
Composes with
ghas-config-reviewer— code-scanning baseline check item.actions-workflow-hardener— when the CodeQL workflow itself needs review.codeql-pattern-finder— for custom-pack rollout.vault-writer.write_research— persists the onboarding plan (final step of Output).
Acceptance test (for step 19 done-criteria)
Produce one onboarding plan for a hypothetical target (e.g., Payments primary service repo). Confirm all 8 sections present, setup-type decision justified, and at minimum one compliance-relevant custom pack recommendation.