codeql-queries - qa-security-scanning

Overview

Per docs.github.com/code-security/codeql-cli (opens in new window):

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 (opens in new window). Per cql-docs (opens in new window) 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 (opens in new window) 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 (opens in new window) - 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

Reference detail for codeql-queries. The SKILL.md spine keeps the core create/analyze/triage path; this file holds the full pack list, the custom .ql example, and the GitHub Actions integration. Per docs.github.com/code-security/codeql-cli (opens in new window).

Query packs

Pack	Coverage
`codeql/javascript-queries`	JS/TS standard checks
`codeql/python-queries`	Python checks
`codeql/java-queries`	Java + Kotlin checks
`codeql/go-queries`	Go checks
`codeql/cpp-queries`	C/C++ checks
`codeql/csharp-queries`	C# checks
`codeql/ruby-queries`	Ruby checks
`codeql/swift-queries`	Swift checks

Each pack ships query suites: code-scanning (default for GitHub Code Scanning), security-and-quality (broader), security-extended (more rules, more false positives).

codeql database analyze my-db \
  codeql/javascript-queries:codeql-suites/javascript-security-extended.qls \
  --format=sarif-latest \
  --output=results.sarif

Custom query authoring

/**
 * @name Hardcoded JWT secret in jwt.sign call
 * @description Detects jwt.sign() calls with literal-string secret
 * @kind problem
 * @problem.severity error
 * @id js/hardcoded-jwt-secret
 * @tags security
 *       external/cwe/cwe-798
 */

import javascript

from CallExpr call, StringLiteral secret
where
  call.getCalleeName() = "sign" and
  call.getReceiver().(VarRef).getName() = "jwt" and
  call.getArgument(1) = secret
select call, "Hardcoded JWT secret detected: " + secret.getValue()

Custom queries register in a query suite (.qls) for selective execution. Validate them with codeql test against expected-results files.

CI integration (GitHub Actions)

Most teams use the GitHub-hosted action for any GitHub-hosted repo:

jobs:
  codeql:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # for SARIF upload to Security tab
    steps:
      - uses: actions/checkout@v5
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript, python
          queries: security-extended
      - run: ./gradlew build   # or whatever build step is needed
      - uses: github/codeql-action/analyze@v3
        with:
          category: "/language:javascript"

For non-GitHub CI (GitLab / Jenkins), use the CodeQL CLI directly (create + analyze) and upload SARIF to GitHub Code Scanning via the API or a SARIF-compatible viewer.