Run Analysis Workflow

Run Analysis Workflow

Execute CodeQL security queries on an existing database with ruleset selection and result formatting.

Task System

Create these tasks on workflow start:

TaskCreate: "Select database and detect language" (Step 1)
TaskCreate: "Check additional query packs and detect model packs" (Step 2) - blockedBy: Step 1
TaskCreate: "Select query packs, model packs, and threat models" (Step 3) - blockedBy: Step 2
TaskCreate: "Execute analysis" (Step 4) - blockedBy: Step 3
TaskCreate: "Process and report results" (Step 5) - blockedBy: Step 4

Mandatory Gates

Steps

Step 1: Select Database and Detect Language

Find available databases:

# List all CodeQL databases
ls -dt codeql_*.db 2>/dev/null | head -10

# Get the most recent database
get_latest_db() {
  ls -dt codeql_*.db 2>/dev/null | head -1
}

DB_NAME=$(get_latest_db)
if [[ -z "$DB_NAME" ]]; then
  echo "ERROR: No CodeQL database found. Run build-database workflow first."
  exit 1
fi
echo "Using database: $DB_NAME"

If multiple databases exist, use AskUserQuestion to let user select:

header: "Database"
question: "Multiple databases found. Which one to analyze?"
options:
  - label: "codeql_3.db (latest)"
    description: "Created: <timestamp>"
  - label: "codeql_2.db"
    description: "Created: <timestamp>"
  - label: "codeql_1.db"
    description: "Created: <timestamp>"

Verify and detect language:

# Check database exists and get language(s)
codeql resolve database -- "$DB_NAME"

# Get primary language from database
LANG=$(codeql resolve database --format=json -- "$DB_NAME" \
  | jq -r '.languages[0]')
LANG_COUNT=$(codeql resolve database --format=json -- "$DB_NAME" \
  | jq '.languages | length')
echo "Primary language: $LANG"
if [ "$LANG_COUNT" -gt 1 ]; then
  echo "WARNING: Multi-language database ($LANG_COUNT languages)"
  codeql resolve database --format=json -- "$DB_NAME" \
    | jq -r '.languages[]'
fi

Multi-language databases: If more than one language is detected, ask the user which language to analyze or run separate analyses for each.

Step 2: Check Additional Query Packs and Detect Model Packs

Check if recommended third-party query packs are installed and detect available model packs. For each missing pack, prompt user to install or ignore.

2a: Query Packs

Available packs by language (see ruleset-catalog.md):

For each pack available for the detected language:

# Check if pack is installed
codeql resolve qlpacks | grep -i "<PACK_NAME>"

If NOT installed, use AskUserQuestion:

header: "<PACK_TYPE>"
question: "<PACK_NAME> for <LANG> is not installed. Install it?"
options:
  - label: "Install (Recommended)"
    description: "Run: codeql pack download <PACK_NAME>"
  - label: "Ignore"
    description: "Skip this pack for this analysis"

On "Install":

codeql pack download <PACK_NAME>

On "Ignore": Mark pack as skipped, continue to next pack.

2b: Detect Model Packs

Model packs contain data extensions (custom sources, sinks, flow summaries) that improve CodeQL's data flow analysis for project-specific or framework-specific APIs. To create new extensions, run the create-data-extensions workflow first.

Search three locations:

1. In-repo model packs — qlpack.yml or codeql-pack.yml with dataExtensions:

# Find CodeQL pack definitions in the codebase
fd '(qlpack|codeql-pack)\.yml$' . --exclude codeql_*.db | while read -r f; do
  if grep -q 'dataExtensions' "$f"; then
    echo "MODEL PACK: $(dirname "$f") - $(grep '^name:' "$f")"
  fi
done

2. In-repo standalone data extensions — .yml files with extensions: key (auto-discovered by CodeQL):

# Find data extension YAML files in the codebase
rg -l '^extensions:' --glob '*.yml' --glob '!codeql_*.db/**' | head -20

3. Installed model packs — library packs resolved by CodeQL that contain models:

# List all resolved packs and filter for model/library packs
# Model packs typically have "model" in the name or are library packs
codeql resolve qlpacks 2>/dev/null | grep -iE 'model|extension'

Record all detected model packs for presentation in Step 3. If no model packs are found, note this and proceed — model packs are optional.

Step 3: CRITICAL GATE - Select Query Packs and Model Packs

⛔ MANDATORY CHECKPOINT - DO NOT SKIP

Present all available packs as checklists. Query packs first, then model packs.

3a: Select Query Packs

Use AskUserQuestion tool with multiSelect: true:

header: "Query Packs"
question: "Select query packs to run:"
multiSelect: false
options:
  - label: "Use all (Recommended)"
    description: "Run all installed query packs for maximum coverage"
  - label: "security-extended"
    description: "codeql/<lang>-queries - Core security queries, low false positives"
  - label: "security-and-quality"
    description: "Includes code quality checks - more findings, more noise"
  - label: "Select individually"
    description: "Choose specific packs from the full list"

If "Use all": Include all installed query packs: security-extended + Trail of Bits + Community Packs (whichever are installed).

If "Select individually": Follow up with a multiSelect: true question listing all installed packs:

header: "Query Packs"
question: "Select query packs to run:"
multiSelect: true
options:
  - label: "security-extended"
    description: "codeql/<lang>-queries - Core security queries, low false positives"
  - label: "security-and-quality"
    description: "Includes code quality checks - more findings, more noise"
  - label: "security-experimental"
    description: "Bleeding-edge queries - may have higher false positives"
  - label: "Trail of Bits"
    description: "trailofbits/<lang>-queries - Memory safety, domain expertise"
  - label: "Community Packs"
    description: "GitHubSecurityLab/CodeQL-Community-Packs-<Lang> - Additional security queries"

Only show built-in and third-party packs that are installed (from Step 2a)

⛔ STOP: Await user selection

3b: Select Model Packs (if any detected)

Skip this sub-step if no model packs were detected in Step 2b.

Present detected model packs from Step 2b. Categorize by source:

Use AskUserQuestion tool:

header: "Model Packs"
question: "Model packs add custom data flow models (sources, sinks, summaries). Select which to include:"
multiSelect: false
options:
  - label: "Use all (Recommended)"
    description: "Include all detected model packs and data extensions"
  - label: "Select individually"
    description: "Choose specific model packs from the list"
  - label: "Skip"
    description: "Run without model packs"

If "Use all": Include all model packs and data extensions detected in Step 2b.

If "Select individually": Follow up with a multiSelect: true question:

header: "Model Packs"
question: "Select model packs to include:"
multiSelect: true
options:
  # For each in-repo model pack found in 2b:
  - label: "<pack-name>"
    description: "In-repo model pack at <path> - custom data flow models"
  # For each standalone data extension found in 2b:
  - label: "In-repo extensions"
    description: "<N> data extension files found in codebase (auto-discovered)"
  # For each installed model pack found in 2b:
  - label: "<pack-name>"
    description: "Installed model pack - <description if available>"

Notes:

• In-repo standalone data extensions (.yml files with extensions: key) are auto-discovered by CodeQL during analysis — selecting them here ensures the source directory is passed via --additional-packs
• In-repo model packs (with qlpack.yml) need their parent directory passed via --additional-packs
• Installed model packs are passed via --model-packs

⛔ STOP: Await user selection

Step 3c: Select Threat Models

Threat models control which input sources CodeQL treats as tainted. The default (remote) covers HTTP/network input only. Expanding the threat model finds more vulnerabilities but may increase false positives. See threat-models.md for details on each model.

Use AskUserQuestion:

header: "Threat Models"
question: "Which input sources should CodeQL treat as tainted?"
multiSelect: false
options:
  - label: "Remote only (Recommended)"
    description: "Default — HTTP requests, network input. Best for web services and APIs."
  - label: "Remote + Local"
    description: "Add CLI args, local files. Use for CLI tools or desktop apps."
  - label: "All sources"
    description: "Remote, local, environment, database, file. Maximum coverage, more noise."
  - label: "Custom"
    description: "Select specific threat models individually"

If "Custom": Follow up with multiSelect: true:

header: "Threat Models"
question: "Select threat models to enable:"
multiSelect: true
options:
  - label: "remote"
    description: "HTTP requests, network input (always included)"
  - label: "local"
    description: "CLI args, local files — for CLI tools, batch processors"
  - label: "environment"
    description: "Environment variables — for 12-factor/container apps"
  - label: "database"
    description: "Database results — for second-order injection audits"

Build the threat model flag:

# Only add --threat-models when non-default models are selected
# Default (remote only) needs no flag
THREAT_MODEL_FLAG=""  # or "--threat-models=remote,local" etc.

Step 4: Execute Analysis

Run analysis with only the packs selected by user in Step 3.

# Results directory matches database name
RESULTS_DIR="${DB_NAME%.db}-results"
mkdir -p "$RESULTS_DIR"

# Build pack list from user selections in Step 3a
PACKS="<USER_SELECTED_QUERY_PACKS>"

# Build model pack flags from user selections in Step 3b
# --model-packs for installed model packs
# --additional-packs for in-repo model packs and data extensions
MODEL_PACK_FLAGS=""
ADDITIONAL_PACK_FLAGS=""

# Threat model flag from Step 3c (empty string if default/remote-only)
# THREAT_MODEL_FLAG=""

codeql database analyze $DB_NAME \
  --format=sarif-latest \
  --output="$RESULTS_DIR/results.sarif" \
  --threads=0 \
  $THREAT_MODEL_FLAG \
  $MODEL_PACK_FLAGS \
  $ADDITIONAL_PACK_FLAGS \
  -- $PACKS

Flag reference for model packs:

Example (C++ with query packs and model packs):

codeql database analyze codeql_1.db \
  --format=sarif-latest \
  --output=codeql_1-results/results.sarif \
  --threads=0 \
  --additional-packs=./codeql-models \
  -- codeql/cpp-queries:codeql-suites/cpp-security-extended.qls \
     trailofbits/cpp-queries \
     GitHubSecurityLab/CodeQL-Community-Packs-CPP

Example (Python with installed model pack):

codeql database analyze codeql_1.db \
  --format=sarif-latest \
  --output=codeql_1-results/results.sarif \
  --threads=0 \
  --model-packs=myorg/python-models \
  -- codeql/python-queries:codeql-suites/python-security-extended.qls

Performance Flags

If codebase is large then read ../references/performance-tuning.md and apply relevant optimizations.

Step 5: Process and Report Results

Count findings:

jq '.runs[].results | length' "$RESULTS_DIR/results.sarif"

Summary by SARIF level:

jq -r '.runs[].results[] | .level' "$RESULTS_DIR/results.sarif" \
  | sort | uniq -c | sort -rn

Summary by security severity (more useful for triage):

jq -r '
  .runs[].results[] |
  (.properties["security-severity"] // "none") + " " +
  (.message.text // "no message" | .[0:80])
' "$RESULTS_DIR/results.sarif" | sort -rn | head -20

Summary by rule:

jq -r '.runs[].results[] | .ruleId' "$RESULTS_DIR/results.sarif" \
  | sort | uniq -c | sort -rn

Final Output

Report to user:

## CodeQL Analysis Complete

**Database:** $DB_NAME
**Language:** <LANG>
**Query packs:** <list of query packs used>
**Model packs:** <list of model packs used, or "None">
**Threat models:** <list of threat models, or "default (remote)">

### Results Summary:
- Total findings: <N>
- Error: <N>
- Warning: <N>
- Note: <N>

### Output Files:
- SARIF: $RESULTS_DIR/results.sarif