codeql

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

plugins/modern-python/hooks/shims/pip3

plugins/modern-python/hooks/shims/python3

Audit 0.4.1 · source sha dea80e4aaaef · 31 Oct 2026Report an issue or request a re-scan

• Publishertrailofbits GitHub organizationOwner of the repository this skill is read from
• Source foldertrailofbits/skills/plugins/static-analysis/skills/codeqlThe exact folder we audited
• LicenceCC-BY-SA-4.0As the repository states it
• Commit pinned for this verdictdea80e4aaaefA new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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",…

---
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.

```bash
# 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:

```bash
# 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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

uv run {baseDir}/scripts/check_db_quality.py "$DB_NAME"
uv run {baseDir}/scripts/verify_query_suite.py "$SUITE_FILE"

git clone https://github.com/trailofbits/skills
git -C skills checkout dea80e4aaaef

Works in

1. 2026-10-31
   !CAUTION B 89 / 100

   first audit · source dea80e4aaaef

Questions about codeql

• github.com/trailofbits/skills/tree/main/plugins/static-analysis/ — the audited source at commit dea80e4aaaef and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology