codeql-queries

Overview

Per docs.github.com/code-security/codeql-cli:

CodeQL is GitHub's semantic-analysis SAST: build a database of the codebase (control flow, data flow, type info), run .ql queries against it, emit SARIF for GitHub Code Scanning. This database-then-query model catches cross-file taint flows (user input reaching a SQL sink unsanitized) that pattern matchers cannot express.

When to use

The team uses GitHub-hosted repos (Code Scanning is GitHub-native).
The codebase has cross-file taint flows that pattern-matchers miss (e.g., user input → service A → service B → SQL).
A security audit requires CodeQL coverage (some compliance regimes prefer it).
The team writes custom queries for org-specific patterns.

For multi-platform CI without GitHub, use semgrep-rules or sonarqube-rules.

Step 1 - Install

CodeQL CLI download from github.com/github/codeql-cli-binaries/releases. Per cql-docs the CLI is bundled separately from the queries - install both:

# Download CodeQL CLI (per platform)
curl -L https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-linux64.zip -o codeql.zip
unzip codeql.zip
export PATH="$PATH:$PWD/codeql"

# Verify
codeql --version

Query packs (the .ql files) are pulled per-scan via --download flag or pre-installed via codeql pack download.

Step 2 - Create a database

# For interpreted languages (JS, Python, Ruby): no build needed
codeql database create my-db --language=javascript --source-root=.

# For compiled languages (Java, C#, Go): wrap the build
codeql database create my-db --language=java --command="./gradlew build" --source-root=.

codeql database create my-db --language=cpp --command="make all"

The --language flag accepts: cpp / csharp / go / java / javascript / python / ruby / swift / kotlin (verify support against cql-docs for the current CodeQL release).

For JS/TS + Python, the --build-mode none extraction works without a build step. For Java/C#/C++, you MUST wrap the project's build via --command so CodeQL can observe compilation.

Step 3 - Analyze with query packs

codeql database analyze my-db \
  --format=sarif-latest \
  --output=results.sarif \
  codeql/javascript-queries

The full per-language pack list, the query suites (code-scanning, security-and-quality, security-extended), a custom .ql query example, and the GitHub Actions CI integration are in references/codeql-reference.md.

Step 4 - False-positive triage (MANDATORY)

Three layers:

Mechanism	Example	When to use
Inline `// codeql[<rule-id>]`	`// codeql[js/sql-injection] - Reason: input pre-sanitized via library X`	Single-line exception with documented rationale
SARIF post-processing filter	`cat results.sarif \| jq 'del(.runs[].results[] \| select(.ruleId == "js/path-injection" and .locations[].physicalLocation.artifactLocation.uri \| startswith("vendor/")))'`	Bulk exclusion of vendored / generated code
GitHub Security tab dismissal	UI: "Dismiss alert" → False positive / Won't fix / Used in tests	Persistent, auditable, requires reviewer comment

Justification template (mandatory in code):

// codeql[js/sql-injection]
// Reason: parameter pre-validated via Joi schema (line 42); literal interpolation safe
// Reviewer: alice@example.com (2026-05-15)
// Expires: 2026-12-15
const result = await db.query(`SELECT * FROM users WHERE id = ${userId}`);

GitHub Security tab dismissals are persistent + auditable + show in the audit log; prefer them over inline comments for production suppressions.

Cadence: every quarter, review GitHub Security → "Dismissed alerts" filter; expired ones reopened for re-review.

Step 5 - Database performance

CodeQL databases can be GBs for large codebases. Performance flags:

codeql database create my-db --language=java \
  --command="./gradlew build" \
  --threads=8 \
  --ram=8192   # MB

For incremental scanning (changed-files-only), GitHub's hosted runner uses caching across runs. Self-hosted CI must implement caching manually (the codeql-action/init action handles it on GitHub).

Anti-patterns

Anti-pattern	Why it fails	Fix
Skip `--command` for compiled languages	Database empty; analysis returns no findings silently	Always wrap the build (Step 2)
Use `security-extended` without baseline	Flood of pre-existing findings overwhelms the team	Start with `code-scanning`; ratchet up
Inline comment without GitHub dismissal	No audit trail	Use Security-tab dismissal for persistent FPs (Step 4)
Run CodeQL on every PR for large codebase	Database creation is slow (10 - 30 min); PR cycle slow	Schedule full scan nightly; PR-only delta scanning via Code Scanning
Custom queries without test suite	Bugs in custom queries miss real findings	Use `codeql test` to validate against expected-results files

Limitations

Database creation is slow for large codebases (10 - 30 min on monorepos); incremental scanning helps but requires caching.
Custom-query authoring has a steep learning curve; the CodeQL University courses help.
Some languages have less depth than others (Go, Ruby, Swift are newer than JS/Java/C++).
Self-hosted (non-GitHub) integration requires manual SARIF routing.
License: CodeQL CLI is free for open-source repos; commercial use requires GitHub Advanced Security license.

References

cql-docs - CodeQL CLI getting started
codeql.github.com/docs - official documentation root
codeql.github.com/codeql-standard-libraries/ - per-language stdlibs
github.com/github/codeql - query packs source
learningqltest.github.io/learningql/ - CodeQL University training
semgrep-rules, sonarqube-rules, language-native-sast - sister scanners

testland/codeql-queries