/codeql

name: codeql
description: >-
  Scans a codebase for security vulnerabilities using CodeQL's interprocedural data flow and
  taint tracking analysis. Triggers on "run codeql", "codeql scan", "build codeql database",
  "SAST scan", "taint analysis", "dataflow analysis", or "find vulnerabilities in this repo".
  Covers Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, and Swift. Supports
  "run all" (security-and-quality + security-experimental) and "important only"
  (high-precision) scan modes, and creates data extension models for project-specific sources
  and sinks. For fast single-file pattern matching, or when no build is available for a
  compiled language, use the semgrep skill; to parse SARIF that already exists rather than
  produce it, use the sarif-parsing skill.
allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion TaskCreate TaskList TaskUpdate TaskGet

CodeQL Analysis

Supported languages: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.

**Skill resources:** Reference files and templates are located at `{baseDir}/references/` and `{baseDir}/workflows/`.

Essential Principles

1. **Database quality is non-negotiable.** A database that builds is not automatically good — a cached build extracts nothing while reporting success.

2. **Data extensions catch what CodeQL misses.** Django, Spring, and Express projects still wrap database calls, request parsing, and shell execution in project-specific APIs that no shipped model covers.

3. **Explicit suite references prevent silent query dropping.** Never pass pack names to `codeql database analyze` — each pack's `defaultSuiteFile` applies hidden filters that can produce zero results. Always generate a `.qls`.

4. **Zero findings needs investigation, not celebration.** It can mean poor extraction, missing models, the wrong packs, or suite filtering. Run `{baseDir}/scripts/check_db_quality.py` after the build, confirm `{baseDir}/scripts/verify_query_suite.py` exited zero for the suite in use — the generation scripts run it, so invoke it by hand only for a reused or hand-edited suite — and say in the report that both passed.

5. **macOS Apple Silicon requires workarounds for compiled languages.** Exit code 137 is an `arm64e`/`arm64` mismatch, not a build failure. Try Homebrew arm64 tools or Rosetta before falling back to `build-mode=none`.

6. **Follow workflows step by step.** Each phase gates the next; skipping quality assessment or data extensions leaves the gap invisible in the results.

Each Bash call is a fresh shell

Nothing carries across a Bash call: not variables, not arrays, not functions sourced from `build_log.sh`. Every block below that uses a value must re-establish it in the same block. The workflows point back here rather than repeating it; what they do state is the specific damage at that site, because each one fails differently and silently:

• a lost **function** makes `run_logged` exit 127, which the build ladder reads as a failed

method and walks down to `--build-mode=none`, never having invoked CodeQL

• a lost **array** expands to nothing, so every `--threat-model` and `--model-packs` the user

chose is dropped while the final report still lists them as used

• a lost **scalar** under `set -u` aborts the block with `unbound variable`

Output Directory

All generated files (database, build logs, diagnostics, extensions, results) are stored in a single output directory.

• **If the user specifies an output directory** in their prompt, use it as `OUTPUT_DIR`.
• **If not specified**, default to `./static_analysis_codeql_1`. If that already exists, increment to `_2`, `_3`, etc.

In both cases, **always create the directory** with `mkdir -p` before writing any files.

Set `USER_SPECIFIED_DIR` to the literal path from the user's prompt before running this, or leave it unset to auto-increment. Nothing else assigns it.

# Resolve output directory
USER_SPECIFIED_DIR="${USER_SPECIFIED_DIR:-}"   # substitute the user's path here, if any
if [ -n "$USER_SPECIFIED_DIR" ]; then
  OUTPUT_DIR="$USER_SPECIFIED_DIR"
else
  BASE="static_analysis_codeql"
  N=1
  while [ -e "${BASE}_${N}" ]; do
    N=$((N + 1))
  done
  OUTPUT_DIR="${BASE}_${N}"
fi
mkdir -p "$OUTPUT_DIR"

The output directory is resolved **once** at the start before any workflow executes. All workflows receive `$OUTPUT_DIR` and store their artifacts there:

$OUTPUT_DIR/
├── rulesets.txt                 # Selected query packs (logged after Step 3)
├── codeql.db/                   # CodeQL database (dir containing codeql-database.yml)
├── build.log                    # Build log
├── codeql-config.yml            # Exclusion config (interpreted languages)
├── diagnostics/                 # Diagnostic queries and CSVs
├── extensions/                  # Data extension YAMLs
├── raw/                         # Unfiltered analysis output
│   ├── results.sarif
│   └── run-all.qls | important-only.qls
└── results/                     # Final results (filtered for important-only, copied for run-all)
    └── results.sarif

Database Discovery

A CodeQL database is identified by the presence of a `codeql-database.yml` marker file inside its directory. When searching for existing databases, **always collect all matches** — there may be multiple databases from previous runs or for different languages.

**Discovery command.** `find_databases.sh` prints one database path per line, filtering out the marker files a failed build leaves behind. Build the array **in the same block that selects from it** — each Bash call is a fresh shell, so an array built here is empty by the next call, and the run concludes there is no database:

# Command substitution, not `done < <(...)`: a process substitution discards the script's
# exit status, so "codeql is not on this shell's PATH" (exit 2) would arrive as an empty
# list and route to "build a new database" with three good ones sitting on disk.
if ! DB_L