Codeql

CodeQL Static Analysis

When to Use CodeQL

Ideal scenarios:

• Source code access with ability to build (for compiled languages)
• Open-source projects or GitHub Advanced Security license
• Need for interprocedural data flow and taint tracking
• Finding complex vulnerabilities requiring AST/CFG analysis
• Comprehensive security audits where analysis time is not critical

Consider Semgrep instead when:

• No build capability for compiled languages
• Licensing constraints
• Need fast, lightweight pattern matching
• Simple, single-file analysis is sufficient

Why Interprocedural Analysis Matters

Simple grep/pattern tools only see one function at a time. Real vulnerabilities often span multiple functions:

HTTP Handler → Input Parser → Business Logic → Database Query
     ↓              ↓              ↓              ↓
   source      transforms       passes       sink (SQL)

CodeQL tracks data flow across all these steps. A tainted input in the handler can be traced through 5+ function calls to find where it reaches a dangerous sink.

Pattern-based tools miss this because they can't connect request.param in file A to db.execute(query) in file B.

When NOT to Use

Do NOT use this skill for:

• Projects that cannot be built (CodeQL requires successful compilation for compiled languages)
• Quick pattern searches (use Semgrep or grep for speed)
• Non-security code quality checks (use linters instead)
• Projects without source code access

Environment Check

# Check if CodeQL is installed
command -v codeql >/dev/null 2>&1 && echo "CodeQL: installed" || echo "CodeQL: NOT installed (run install steps below)"

Installation

CodeQL CLI

# macOS/Linux (Homebrew)
brew install --cask codeql

# Update
brew upgrade codeql

Manual: Download bundle from https://github.com/github/codeql-action/releases

Trail of Bits Queries (Optional)

Install public ToB security queries for additional coverage:

# Download ToB query packs
codeql pack download trailofbits/cpp-queries trailofbits/go-queries

# Verify installation
codeql resolve qlpacks | grep trailofbits

Core Workflow

1. Create Database

codeql database create codeql.db --language= [--command=''] --source-root=.

| Language | --language= | Build Required | |----------|---------------|----------------| | Python | python | No | | JavaScript/TypeScript | javascript | No | | Go | go | No | | Ruby | ruby | No | | Rust | rust | Yes (--command='cargo build') | | Java/Kotlin | java | Yes (--command='./gradlew build') | | C/C++ | cpp | Yes (--command='make -j8') | | C# | csharp | Yes (--command='dotnet build') | | Swift | swift | Yes (macOS only) |

2. Run Analysis

# List available query packs
codeql resolve qlpacks

Run security queries:

# SARIF output (recommended)
codeql database analyze codeql.db \
  --format=sarif-latest \
  --output=results.sarif \
  -- codeql/python-queries:codeql-suites/python-security-extended.qls

# CSV output
codeql database analyze codeql.db \
  --format=csv \
  --output=results.csv \
  -- codeql/javascript-queries

With Trail of Bits queries (if installed):

codeql database analyze codeql.db \
  --format=sarif-latest \
  --output=results.sarif \
  -- trailofbits/go-queries

Writing Custom Queries

Query Structure

CodeQL uses SQL-like syntax: from Type x where P(x) select f(x)

Basic Template

/**
 * @name Find SQL injection vulnerabilities
 * @description Identifies potential SQL injection from user input
 * @kind path-problem
 * @problem.severity error
 * @security-severity 9.0
 * @precision high
 * @id py/sql-injection
 * @tags security
 *       external/cwe/cwe-089
 */

import python
import semmle.python.dataflow.new.DataFlow
import semmle.python.dataflow.new.TaintTracking

module SqlInjectionConfig implements DataFlow::ConfigSig {
  predicate isSource(DataFlow::Node source) {
    // Define taint sources (user input)
    exists(source)
  }

  predicate isSink(DataFlow::Node sink) {
    // Define dangerous sinks (SQL execution)
    exists(sink)
  }
}

module SqlInjectionFlow = TaintTracking::Global;

from SqlInjectionFlow::PathNode source, SqlInjectionFlow::PathNode sink
where SqlInjectionFlow::flowPath(source, sink)
select sink.getNode(), source, sink, "SQL injection from $@.", source.getNode(), "user input"

Query Metadata

| Field | Description | Values | |-------|-------------|--------| | @kind | Query type | problem, path-problem | | @problem.severity | Issue severity | error, warning, recommendation | | @security-severity | CVSS score | 0.0 - 10.0 | | @precision | Confidence | very-high, high, medium, low |

Key Language Features

// Predicates
predicate isUserInput(DataFlow::Node node) {
  exists(Call c | c.getFunc().(Attribute).getName() = "get" and node.asExpr() = c)
}

// Transitive closure: + (one or more), * (zero or more)
node.getASuccessor+()

// Quantification
exists(Variable v | v.getName() = "password")
forall(Call c | c.getTarget().hasName("dangerous") | hasCheck(c))

Creating Query Packs

codeql pack init myorg/security-queries

Structure:

myorg-security-queries/
├── qlpack.yml
├── src/
│   └── SqlInjection.ql
└── test/
    └── SqlInjectionTest.expected

qlpack.yml:

name: myorg/security-queries
version: 1.0.0
dependencies:
  codeql/python-all: "*"

CI/CD Integration (GitHub Actions)

name: CodeQL Analysis

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * 1'  # Weekly

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      matrix:
        language: ['python', 'javascript']

    steps:
      - uses: actions/checkout@v4

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: security-extended,security-and-quality
          # Add custom queries/packs:
          # queries: security-extended,./codeql/custom-queries
          # packs: trailofbits/python-queries

      - uses: github/codeql-action/autobuild@v3

      - uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

Testing Queries

codeql test run test/

Test file format:

def vulnerable():
    user_input = request.args.get("q")  # Source
    cursor.execute("SELECT * FROM users WHERE id = " + user_input)  # Alert: sql-injection

def safe():
    user_input = request.args.get("q")
    cursor.execute("SELECT * FROM users WHERE id = ?", (user_input,))  # OK

Troubleshooting

| Issue | Solution | |-------|----------| | Database creation fails | Clean build environment, verify build command works independently | | Slow analysis | Use --threads, narrow query scope, check query complexity | | Missing results | Check file exclusions, verify source files were parsed | | Out of memory | Set CODEQL_RAM=48000 environment variable (48GB) | | CMake source path issues | Adjust --source-root to point to actual source location |

Rationalizations to Reject

| Shortcut | Why It's Wrong | |----------|----------------| | "No findings means the code is secure" | CodeQL only finds patterns it has queries for; novel vulnerabilities won't be detected | | "This code path looks safe" | Complex data flow can hide vulnerabilities across 5+ function calls; trace the full path | | "Small change, low risk" | Small changes can introduce critical bugs; run full analysis on every change | | "Tests pass so it's safe" | Tests prove behavior, not absence of vulnerabilities; they test expected paths, not attacker paths | | "The query didn't flag it" | Default query suites don't cover everything; check if custom queries are needed for your domain |

Resources

• Docs: https://codeql.github.com/docs/
• Query Help: https://codeql.github.com/codeql-query-help/
• Security Lab: https://securitylab.github.com/
• Trail of Bits Queries: https://github.com/trailofbits/codeql-queries
• VSCode Extension: "CodeQL" for query development

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: allanninal
• Source: allanninal/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.