CodeQL Analysis skill for Codex

CodeQL treats code as data you query. Its strength is dataflow and taint tracking across functions and files — finding that user input reaches a sink three calls away, which pattern scanners miss. That power costs build time and query-writing effort, so use it where depth pays off and keep the alert set triaged.

When CodeQL vs a pattern scanner

• CodeQL — deep taint/dataflow (injection through layers, SSRF across helpers), whole- program reasoning, compiled languages. Slower; needs a build for compiled langs.
• Semgrep (hand off to semgrep-sast) — fast, pattern/lightweight-taint, great for style/footgun rules and quick CI. Use it for breadth and speed.

Many teams run both: Semgrep on every push, CodeQL on a schedule/PR.

Supported languages

C/C++, C#, Go, Java/Kotlin, JavaScript/TypeScript, Python, Ruby, Swift. Interpreted languages (JS/TS, Python, Ruby) need no build; compiled ones need CodeQL to observe the build.

GitHub code scanning (the easy path)

For a GitHub repo, the default setup wires everything:

# .github/workflows/codeql.yml
name: "CodeQL"
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }
  schedule: [{ cron: "0 3 * * 1" }]
jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions: { security-events: write, actions: read, contents: read }
    strategy:
      matrix: { language: [javascript-typescript, python] }
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with: { languages: ${{ matrix.language }}, queries: security-extended }
      # Compiled langs: replace autobuild with your real build if autobuild fails
      - uses: github/codeql-action/autobuild@v3
      - uses: github/codeql-action/analyze@v3

Query suites: security-extended (more coverage, some noise) or security-and-quality (adds maintainability). Start with security-extended.

Local CLI (when you need control or offline-ish work)

The CodeQL CLI builds a database you query directly. It is a large download and compiled- language DB builds run your toolchain — Codex’s sandbox may need approval for the install and build; call that out.

# Interpreted language: no build command needed
codeql database create db --language=python --source-root=.
# Compiled language: wrap the real build
codeql database create db --language=java --command="mvn -B clean install -DskipTests"
# Run the standard security queries, output SARIF
codeql database analyze db codeql/python-queries:codeql-suites/python-security-extended.qls \
  --format=sarifv2.1.0 --output=results.sarif

Upload results.sarif to GitHub code scanning with codeql github upload-results if you want alerts in the UI.

Triage alerts

CodeQL alerts carry a dataflow path (source → steps → sink) — read it; it tells you whether the taint is real.

• True positive → fix the sink or add a sanitizer on the path; CodeQL re-tracks on the next run.
• False positive → if a sanitizer exists that CodeQL does not recognize, model it in a custom query/sanitizer rather than blanket-dismissing. In the UI, dismiss with a reason (“false positive” / “won’t fix” / “used in tests”); the reason is auditable.
• Fix the source of a class, not one alert at a time, when many share a root cause.

Custom queries (QL basics)

Write a query when you need a project-specific source or sink the standard packs miss. CodeQL queries are written in QL and typically extend the dataflow library:

/**
 * @name User input reaches our raw query helper
 * @kind path-problem
 * @problem.severity error
 * @id js/custom/raw-query-taint
 */
import javascript
import DataFlow::PathGraph

class Config extends TaintTracking::Configuration {
  Config() { this = "RawQueryTaint" }
  override predicate isSource(DataFlow::Node n) { n instanceof RemoteFlowSource }
  override predicate isSink(DataFlow::Node n) {
    exists(DataFlow::CallNode c | c.getCalleeName() = "rawQuery" and n = c.getArgument(0))
  }
}
from Config cfg, DataFlow::PathNode src, DataFlow::PathNode sink
where cfg.hasFlowPath(src, sink)
select sink.getNode(), src, sink, "Untrusted input reaches rawQuery()."

Iterate queries against your database with codeql query run or the VS Code CodeQL extension (which gives autocomplete over the QL libraries). Start by copying a standard query close to your target and adjusting the source/sink.

Verification

• Re-run after a fix: the alert closes and the dataflow path no longer resolves.
• For a custom query, confirm it finds a known-bad path you planted and not the sanitized version.
• PR gate: code scanning shows no new error-severity alerts introduced by the change.

Output contract

## CodeQL analysis — <repo> (<date>)
Languages: <list>. Suite: security-extended. Mode: <GitHub Actions | CLI>.

### Alerts (triaged)
| Query | Severity | Source → Sink | Verdict | Action |
|-------|----------|---------------|---------|--------|
| js/sql-injection | error | req.body → rawQuery() | true positive | parameterize |

### Custom queries added: <ids>
### Gate: fail PR on new error-severity alerts.

Hard rules

• For compiled languages, make sure CodeQL sees the real build; a DB from a failed build misses most of the code and gives false confidence.
• Read the dataflow path before judging an alert; dismiss false positives with a reason, never silently.
• Model missing sanitizers in a query instead of mass-dismissing a true pattern.
• Use CodeQL where depth matters; for fast broad pattern rules, hand off to semgrep-sast.