codeql

intent

run interprocedural security vulnerability scanning across Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, and Swift codebases using CodeQL's data flow analysis. use this skill when you need to find SQL injection, command injection, path traversal, XSS, or other taint-based vulnerabilities that span multiple functions or modules. the skill enforces database quality checks, custom data extensions for project-specific APIs, and explicit query suite references to avoid silent filtering and false negatives.

inputs

codeql cli

• install via homebrew, apt, or download from github.com/github/codeql-cli-binaries
• add to PATH; verify with codeql --version
• minimum version: 2.12.0 (check release notes for security fixes)

source code repository

• local git clone or extracted archive
• note: monorepos require per-module database builds or careful extractor config

language-specific build tools

• python: pip, poetry, or setuptools; optional venv setup
• javascript/typescript: node, npm/yarn/pnpm
• go: go compiler (1.18+)
• java/kotlin: jdk 11+, maven or gradle
• c/c++: gcc/clang, make or cmake; arm64 macos requires rosetta or homebrew arm64 tools
• c#: dotnet sdk 6.0+
• ruby: ruby interpreter + bundler
• swift: xcode command line tools (macos only)

codeql database location

• filesystem path where codeql database create will write (typically ./codeql-db-<lang>)
• requires ~5-20 GB free space per database (varies by codebase size)

query suite files

• custom .qls files (not pack names) referencing security queries
• stored in {baseDir}/queries/ or {baseDir}/references/
• example: security-and-quality.qls instead of codeql/python-queries

external connections

• (optional) github.com api token for private repo checkout (env var: GITHUB_TOKEN)
• (optional) sarif upload endpoint or analysis platform webhook (env var: SARIF_ENDPOINT)

reference materials

• workflow templates at {baseDir}/workflows/ (e.g., build-analyze-python.sh)
• query templates and data extension examples at {baseDir}/references/

procedure

1. select language and confirm build method

   • input: target source code directory, language identifier
   • examine build files (setup.py, package.json, pom.xml, go.mod, etc.) to confirm build method (package manager, make, cmake, etc.)
   • output: confirmed language, build command, and extractor strategy
   • note: if build is unclear, check codeql resolve languages and language-specific docs

2. create codeql database

   • input: source root, language, build command
   • run: codeql database create --language=<lang> --source-root=<path> --build-mode=auto <dbpath>
   • for c/c++ on arm64 macos with exit 137: retry with --build-mode=none or use rosetta
   • output: populated codeql database at <dbpath>
   • edge case: if build fails, try --build-mode=none (source-based extraction only; some languages less precise)

3. assess database quality

   • input: codeql database path
   • run: codeql database info <dbpath> and codeql database analyze <dbpath> --format=json --output=quality.json codeql/python-queries (substitute language)
   • check: file counts match source tree, extractor log has no fatal errors, baseline lines-of-code match expected project size
   • output: quality report (stdout and quality.json)
   • decision: if file counts <50% of source tree or extractor errors present, investigate build issues or missing dependencies before proceeding

4. create data extensions for custom code paths

   • input: codeql database, project source code
   • review: identify custom wrappers, orms, request parsers, or shell execution patterns not covered by standard frameworks
   • generate or adapt data extension .ql files from {baseDir}/references/data-extensions/
   • example: if project wraps django querysets, create extension modeling the wrapper's taint propagation
   • run: codeql database index-files <dbpath> --additional-packs=<ext-pack-dir>
   • output: indexed database with data extensions applied
   • edge case: zero data extensions is acceptable if project uses only standard libraries; always document this decision

5. generate explicit query suite file

   • input: security query pack, quality assessment results
   • create .qls suite file (not a pack name) at {baseDir}/queries/security-and-quality.qls
   • include: relevant security queries for language (e.g., codeql-python/ql/src/Security/CWE-089/SqlInjection.ql)
   • do not pass pack name (e.g., codeql/python-queries) directly to analyze; packs apply hidden defaultSuiteFile filters
   • output: explicit .qls file with full query paths and metadata
   • example format:

     - query: Security/CWE-089/SqlInjection.ql
     - query: Security/CWE-078/CommandInjection.ql
     

6. run analysis with explicit suite reference

   • input: codeql database, .qls suite file
   • run: codeql database analyze <dbpath> --format=sarif-latest --output=results.sarif <suite-file.qls>
   • capture: all alerts with CWE, sink location, data flow path
   • output: sarif file with detailed results
   • note: always include diagnostic queries to confirm suite was applied

7. investigate zero findings

   • input: results.sarif with zero alerts
   • check: database quality from step 3, confirm data extensions applied, verify suite file syntax and query paths, re-run with --verbose flag
   • do not report clean results without confirming database and query configuration are correct
   • output: investigation summary or revised results
   • edge case: zero findings may indicate poor extractor precision on source-only builds; consider re-building with compiled artifacts

8. process and deliver sarif results

   • input: results.sarif file
   • post-process: filter by severity (optional), map to tracking system (jira, github issues)
   • (optional) upload to sarif endpoint: curl -X POST <SARIF_ENDPOINT> -d @results.sarif
   • output: formatted alert list, tracking issue links, or sarif blob in external system
   • edge case: if sarif endpoint unreachable, log error and save local copy for manual review

decision points

if build method is unclear:

• try codeql resolve languages and consult language-specific extractor docs
• fallback: use --build-mode=none (source-only extraction; less precise but will complete)

if database build fails with exit 137 on arm64 macos:

• likely arm64e/arm64 mismatch; try rosetta: arch -x86_64 codeql database create ...
• or install homebrew arm64 tools and retry
• if both fail, use --build-mode=none

if database quality check fails (low file count or many extractor errors):

• do not proceed to analysis
• investigate: missing dependencies, wrong build command, or incomplete source checkout
• fix root cause before re-running database create

if zero findings after analysis:

• do not report clean results; investigate first
• re-run with --verbose to confirm suite applied correctly
• check data extensions are loaded and suite file syntax is valid
• if issue persists, database quality or query configuration is likely wrong

if custom data extensions needed:

• create them; they catch project-specific code paths that standard frameworks miss
• if no custom code paths identified, document this and skip extensions
• always run quality assessment with extensions applied to confirm indexing succeeded

if sarif upload fails (network timeout, auth error, endpoint down):

• log error with timestamp
• save results.sarif locally for manual review or retry later
• do not treat upload failure as analysis failure

output contract

codeql database

• location: <dbpath> specified in step 2
• format: binary codeql database (directory structure with trap, log, and source files)
• invariant: must pass quality assessment (step 3) before analysis

quality report

• location: quality.json from step 3
• format: json with file counts, lines-of-code, extractor errors, warnings
• invariant: all language-specific files must be indexed; extractor fatal errors must be zero

data extensions (if applicable)

• location: {baseDir}/references/data-extensions/ or custom pack directory
• format: .ql files defining custom sources, sinks, taint steps
• invariant: must be indexed into database (step 4) before analysis

query suite file

• location: {baseDir}/queries/security-and-quality.qls
• format: yaml-style .qls with explicit query paths (no pack names)
• invariant: must reference full query paths, not pack defaults

sarif results

• location: results.sarif from step 6
• format: sarif 2.1.0 (application/sarif+json)
• content: all detected vulnerabilities with cwes, sink locations, taint flow graphs, remediation guidance
• invariant: zero findings must include investigation summary (step 7) confirming database and query config

investigation summary (if zero findings)

• location: stdout or investigation.txt
• format: plain text describing quality check results, data extension status, suite syntax verification, verbose log snippet
• invariant: must document why results are clean before reporting

outcome signal

• success: sarif file contains one or more confirmed vulnerabilities with full data flow paths, cwes, and sink locations; or investigation summary confirms database/query config is correct and zero findings is legitimate
• partial success: sarif generated but investigation reveals quality issues; re-run database or tune queries
• failure: database build fails, quality check fails, or analysis returns results but investigation shows suite was silently filtered (check defaultSuiteFile logic)
• user verification: open results.sarif in codeql vscode extension or github security tab to inspect taint flows and confirm false positives are acceptable before triaging