Skip to content

MaarkssDN/Birthub-360 / .agents/skills/codeql-queries

codeql-queries

Verified

Use when a GitHub-hosted repo needs deep semantic static analysis (SAST) beyond pattern matching, such as cross-file taint and data flow: codeql database create and analyze per language, query packs, SARIF upload to code scanning, and suppressions.

codeql-queries

Overview

Per docs.github.com/code-security/codeql-cli:

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. Per cql-docs 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 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:

MechanismExampleWhen to use
Inline // codeql[<rule-id>]// codeql[js/sql-injection] - Reason: input pre-sanitized via library XSingle-line exception with documented rationale
SARIF post-processing filtercat 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 dismissalUI: "Dismiss alert" → False positive / Won't fix / Used in testsPersistent, 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-patternWhy it failsFix
Skip --command for compiled languagesDatabase empty; analysis returns no findings silentlyAlways wrap the build (Step 2)
Use security-extended without baselineFlood of pre-existing findings overwhelms the teamStart with code-scanning; ratchet up
Inline comment without GitHub dismissalNo audit trailUse Security-tab dismissal for persistent FPs (Step 4)
Run CodeQL on every PR for large codebaseDatabase creation is slow (10 - 30 min); PR cycle slowSchedule full scan nightly; PR-only delta scanning via Code Scanning
Custom queries without test suiteBugs in custom queries miss real findingsUse 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 - 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
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall
Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 117kUpdated Claude CodeCodexVerifiedInstall