codeql-scan

name	codeql-scan
description	Execute CodeQL security scans with language detection, database caching, and SARIF output. Use when performing static security analysis on Python or GitHub Actions code.
version	1.0.0
license	MIT
model	claude-sonnet-4-5
metadata	{"domains":["security","static-analysis","codeql"],"type":"security-tool"}

CodeQL Scan Skill

Execute CodeQL security scans with automated language detection, database caching, and SARIF output generation.

Quick Start

Manual Invocation

# Via Claude Code skill system
/codeql-scan

# Direct script invocation
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full

# Quick scan with cached databases
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation quick

# Validate configuration only
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation validate

Triggers

• "Run CodeQL scan"
• "Check for vulnerabilities"
• "Validate CodeQL configuration"
• "Quick security scan"

Decision Tree

Need CodeQL analysis?
├─ First time setup → Install-CodeQL.ps1
├─ Validate config → Test-CodeQLConfig.ps1
├─ Full repository scan → Invoke-CodeQLScan.ps1
├─ Quick scan (cached) → Invoke-CodeQLScan.ps1 -UseCache
├─ Specific language → Invoke-CodeQLScan.ps1 -Languages "python"
└─ CI mode → Invoke-CodeQLScan.ps1 -CI -Format json

When to Use Each Operation

Operation	Use When	Performance	Output
full	First scan, major changes, pre-PR validation	30-60s	SARIF + Console
quick	Iterative development, minor changes	10-20s	SARIF + Console
validate	Config changes, troubleshooting	<5s	Console only

Process Overview

flowchart TD
    A[Start CodeQL Scan] --> B{Operation Type}
    B -->|full| C[Check CLI Installed]
    B -->|quick| C
    B -->|validate| D[Run Test-CodeQLConfig.ps1]

    C --> E{CLI Available?}
    E -->|No| F[Error: Install CLI]
    E -->|Yes| G[Detect Languages]

    G --> H[Run Invoke-CodeQLScan.ps1]
    H --> I{Scan Successful?}

    I -->|Yes| J[Generate SARIF]
    I -->|No| K[Error: Scan Failed]

    J --> L[Display Summary]
    D --> M[Display Config Status]

    L --> N[Exit 0]
    M --> N
    F --> O[Exit 3]
    K --> P[Exit 3]

Workflow

1. Full Repository Scan

Use Case: Comprehensive security analysis of entire codebase

Steps:

1. Check Prerequisites:

   # Verify CodeQL CLI is installed
   if (-not (Test-Path .codeql/cli/codeql)) {
       Write-Error "CodeQL CLI not found. Run: pwsh .codeql/scripts/Install-CodeQL.ps1"
       exit 3
   }
   

2. Run Scan:

   pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full
   

3. Review Results:

   • SARIF files: .codeql/results/*.sarif
   • Console output: Summary of findings by severity
   • Exit code: 0 (success), 1 (findings in CI mode), 3 (scan failed)

Expected Output:

=== CodeQL Security Scan ===

[✓] CodeQL CLI found at .codeql/cli/codeql
[✓] Languages detected: python, actions
[✓] Running full scan (no cache)...

Scanning python...
  Database created: .codeql/db/python
  Queries executed: 89
  Findings: 1 (0 high, 0 medium, 1 low)

Scanning actions...
  Database created: .codeql/db/actions
  Queries executed: 45
  Findings: 0

[✓] SARIF results saved to .codeql/results/
[✓] Scan completed successfully

Total findings: 1 (0 high, 0 medium, 1 low)

2. Quick Scan (Cached)

Use Case: Rapid iteration during development

Steps:

1. Run Quick Scan:

   pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation quick
   

2. Review Changes:

   • Only re-scans if source files changed
   • Uses cached databases from previous full scan
   • 3-5x faster than full scan

Performance:

• Full scan: 30-60 seconds (creates databases + runs all queries)
• Quick scan (CLI): 10-20 seconds (cached database + all queries)
• Quick scan (PostToolUse hook): 5-15 seconds (cached database + targeted queries only)
• Cache invalidation: Automatic on source file, config, or script changes

2a. Quick Scan (PostToolUse Hook)

Use Case: Automatic security feedback during file editing

How It Works:

The PostToolUse hook automatically triggers targeted CodeQL scans after you write Python files (.py) or GitHub Actions workflows (.yml in .github/workflows/). Uses a focused query set (5-10 critical CWEs) to complete within 30 seconds.

Automatic Triggers:

• Write a Python file → Quick scan for CWE-078, CWE-089, CWE-079, etc.
• Write a workflow file → Quick scan for command injection, credential leaks

Configuration:

• Hook location: .claude/hooks/PostToolUse/Invoke-CodeQLQuickScan.ps1
• Quick config: .github/codeql/codeql-config-quick.yml
• Targeted queries only: CWE-078 (command injection), CWE-089 (SQL injection), CWE-079 (XSS), CWE-022 (path traversal), CWE-798 (hardcoded credentials)

Performance:

• Quick scan (cached DB): 5-15 seconds
• Quick scan (first run): 20-30 seconds
• Timeout budget: 30 seconds (graceful timeout if exceeded)

Output:

**CodeQL Quick Scan**: Analyzed `script.py` - No findings

# Or if findings detected:
**CodeQL Quick Scan**: Analyzed `script.py` - **2 finding(s) detected**

Graceful Degradation:

• If CodeQL CLI not installed → Hook exits silently (non-blocking)
• If scan times out → Warning message displayed, full scan recommended

3. Configuration Validation

Use Case: Verify CodeQL configuration YAML syntax and query packs

Steps:

1. Validate Config:

   pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation validate
   

2. Review Output:

   • YAML syntax validation
   • Query pack resolution
   • Language configuration checks

Expected Output:

=== CodeQL Configuration Validation ===

[✓] Configuration file found: .github/codeql/codeql-config.yml
[✓] YAML syntax valid
[✓] Query packs resolved:
    - codeql/python-queries
    - codeql/actions-queries
[✓] Language configurations valid

Configuration is valid

4. Language-Specific Scan

Use Case: Scan only specific languages (faster iteration)

Steps:

1. Specify Languages:

   pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 `
       -Operation full `
       -Languages "python"
   

2. Use Cases:

   • Testing Python scripts only
   • Validating GitHub Actions workflows only
   • Focused analysis during refactoring

5. CI Mode (Non-Interactive)

Use Case: Integration with continuous integration pipelines

Steps:

1. Run in CI Mode:

   pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 `
       -Operation full `
       -CI
   

2. Exit Behavior:

   • Exit 0: No findings
   • Exit 1: Findings detected (fails CI)
   • Exit 3: Scan execution failed

Script Reference

Invoke-CodeQLScanSkill.ps1

Wrapper script providing skill-specific functionality.

Parameters:

Parameter	Type	Default	Description
-Operation	ValidateSet	"full"	Operation type: full, quick, validate
-Languages	String[]	(auto-detect)	Languages to scan: python, actions
-CI	Switch	$false	Enable CI mode (exit 1 on findings)

Exit Codes (ADR-035):

Code	Meaning	CI Behavior
0	Success (no findings or findings ignored)	Pass
1	Findings detected (CI mode only)	Fail
2	Configuration invalid	Fail
3	Scan execution failed	Fail

Examples:

# Full scan with auto-detected languages
.\Invoke-CodeQLScanSkill.ps1 -Operation full

# Quick scan (cached databases)
.\Invoke-CodeQLScanSkill.ps1 -Operation quick

# Validate configuration only
.\Invoke-CodeQLScanSkill.ps1 -Operation validate

# CI mode (exit 1 on findings)
.\Invoke-CodeQLScanSkill.ps1 -Operation full -CI

# Scan specific language
.\Invoke-CodeQLScanSkill.ps1 -Operation full -Languages "python"

# Scan multiple languages
.\Invoke-CodeQLScanSkill.ps1 -Operation full -Languages "python", "actions"

Underlying Scripts

This skill wraps these core CodeQL scripts:

Script	Purpose	Location
Install-CodeQL.ps1	Download and install CodeQL CLI	.codeql/scripts/
Invoke-CodeQLScan.ps1	Execute security scans	.codeql/scripts/
Test-CodeQLConfig.ps1	Validate configuration	.codeql/scripts/
Get-CodeQLDiagnostics.ps1	Comprehensive health check	.codeql/scripts/

Diagnostics

Use Case: Troubleshoot CodeQL setup and configuration

Run Diagnostics:

# Console output (default)
pwsh .codeql/scripts/Get-CodeQLDiagnostics.ps1

# JSON output (programmatic parsing)
pwsh .codeql/scripts/Get-CodeQLDiagnostics.ps1 -OutputFormat json

# Markdown report
pwsh .codeql/scripts/Get-CodeQLDiagnostics.ps1 -OutputFormat markdown > diagnostics.md

Checks Performed:

Check	What It Validates
CLI	Installation, version, executable permissions
Config	YAML syntax, query pack availability, language support
Database	Existence, cache validity, size, creation timestamp
Results	SARIF files, findings count, last scan timestamp

Example Output:

========================================
CodeQL Diagnostics Report
========================================

[CodeQL CLI]
  ✓ Status: INSTALLED
  ✓ Path: /path/to/.codeql/cli/codeql
  ✓ Version: 2.15.3

[Configuration]
  ✓ Status: VALID
  ✓ Query Packs: 2

[Database]
  ✓ Status: EXISTS
  ✓ Languages: python, actions
  ✓ Size: 45.3 MB
  ✓ Created: 2026-01-15 20:00:00
  ✓ Cache: VALID

[Last Scan Results]
  ✓ Status: AVAILABLE
  ✓ Last Scan: 2026-01-15 20:05:00
  ✓ Total Findings: 0

========================================
Overall Status: PASS
========================================

Exit Codes:

Code	Meaning
0	All checks passed
1	Some checks failed (warnings)
3	Unable to run diagnostics

Recommendations:

Diagnostics provides actionable recommendations when issues detected:

• CLI not found → Run: pwsh .codeql/scripts/Install-CodeQL.ps1 -AddToPath
• Config invalid YAML → Check YAML formatting
• Cache metadata missing → Database will be rebuilt on next scan
• No SARIF files found → Run scan to generate results

Output Format

SARIF Files

Results are saved in SARIF format for IDE integration:

Location: .codeql/results/<language>.sarif

Structure:

{
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "CodeQL",
        "version": "2.15.0"
      }
    },
    "results": [{
      "ruleId": "py/sql-injection",
      "level": "error",
      "message": {
        "text": "Potential SQL injection vulnerability"
      },
      "locations": [{
        "physicalLocation": {
          "artifactLocation": {
            "uri": 
          
           
             
          
        
      
    
  

Console Output

Human-readable summary with severity counts:

=== CodeQL Scan Results ===

python:
  ❌ High:   0
  ⚠️  Medium: 0
  ℹ️  Low:    1

actions:
  ✓ No findings

Total: 1 finding (0 high, 0 medium, 1 low)

SARIF files: .codeql/results/

JSON Output (CI Mode)

Machine-readable format for CI integration:

{
  "status": "findings_detected",
  "languages": ["python", "actions"],
  "findings": {
    "total": 1,
    "high": 0,
    "medium": 0,
    "low": 1
  },
  "sarif_files": [
    ".codeql/results/python.sarif",
    ".codeql/results/actions.sarif"
  ]
}

Anti-Patterns

❌ Don't: Skip Configuration Validation

Wrong:

# Running scan without verifying config
pwsh .codeql/scripts/Invoke-CodeQLScan.ps1

Correct:

# Always validate config first
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation validate

# Then run scan
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full

❌ Don't: Ignore Exit Codes

Wrong:

# Ignoring exit code
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full
# Continue even if scan failed

Correct:

# Check exit code
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full
if ($LASTEXITCODE -ne 0) {
    throw "CodeQL scan failed with exit code $LASTEXITCODE"
}

❌ Don't: Suppress Errors Before Checking Exit Code

Wrong:

# Redirecting stderr BEFORE exit code check hides errors
$output = & codeql database create ... 2>&1 | Write-Verbose
if ($LASTEXITCODE -ne 0) {
    Write-Error "Command failed"  # Error message already lost!
}

Correct:

# Check exit code FIRST, then redirect stderr conditionally
$output = & codeql database create ... 2>&1
if ($LASTEXITCODE -ne 0) {
    # IMPORTANT: Sanitize $output for secrets before logging in production.
    Write-Error "Command failed: $($output | Out-String)"
} else {
    $output | Write-Verbose
}

❌ Don't: Run Full Scans Unnecessarily

Wrong:

# Full scan on every minor change
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full

Correct:

# Use quick scan for iterative development
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation quick

# Reserve full scans for:
# - First run
# - Major refactoring
# - Pre-PR validation

❌ Don't: Mix Skill Wrapper with Direct Script Calls

Wrong:

# Mixing interfaces
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full
pwsh .codeql/scripts/Invoke-CodeQLScan.ps1 -Languages "python"

Correct:

# Consistent interface via skill wrapper
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full -Languages "python"

Verification Checklist

Before completing a security scan task:

• CodeQL CLI installed and accessible
• Configuration validated (-Operation validate)
• Scan completed successfully (exit code 0)
• SARIF files generated in .codeql/results/
• Findings reviewed (if any)
• High/medium severity findings addressed
• Low severity findings documented or suppressed
• Cache refreshed if source files changed significantly
• PostToolUse hook enabled and functioning (automatic scans on file writes)
• Diagnostics run and all checks passing

Related Skills

Skill	Purpose	When to Use
security-detection	Detect security-critical file changes	Before CodeQL scan to identify high-risk changes
github	GitHub operations (PR comments, issues)	Report CodeQL findings to PR reviews
session-init	Initialize session with protocol	Before starting security analysis workflow

Troubleshooting

CodeQL CLI Not Found

Error:

Error: CodeQL CLI not found at .codeql/cli/codeql

Solution:

# Install CodeQL CLI
pwsh .codeql/scripts/Install-CodeQL.ps1 -AddToPath

# Verify installation
codeql version

Configuration Validation Failed

Error:

Error: Invalid query pack: codeql/unknown-queries

Solution:

# Check configuration syntax
pwsh .codeql/scripts/Test-CodeQLConfig.ps1

# Verify query packs exist
codeql resolve qlpacks

Scan Timeout

Error:

Error: Query execution timed out after 300s

Solution:

# Increase timeout in VSCode settings
# .vscode/settings.json:
# "codeQL.runningQueries.timeout": 600

# Or scan specific language to reduce scope
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 `
    -Operation full `
    -Languages "python"

Cache Invalidation Issues

Error:

Warning: Using cached database, but source files changed

Solution:

# Force database rebuild
pwsh .codeql/scripts/Invoke-CodeQLScan.ps1 -UseCache:$false

# Or use full operation (always rebuilds)
pwsh .claude/skills/codeql-scan/scripts/Invoke-CodeQLScanSkill.ps1 -Operation full

Hook Not Triggering

Symptom:

PostToolUse hook not running after file writes

Troubleshooting:

# 1. Verify file type matches filter (*.py, *.yml in .github/workflows/)
#    Hook only triggers for Python files and workflow files

# 2. Check if CodeQL CLI is installed
pwsh .codeql/scripts/Get-CodeQLDiagnostics.ps1

# 3. Verify hook file exists and is executable
Test-Path .claude/hooks/PostToolUse/Invoke-CodeQLQuickScan.ps1

# 4. Check Claude Code hooks configuration
#    Hooks should be enabled in Claude Code settings

Common Causes:

• File type not supported (hook only scans .py and .yml in workflows)
• CodeQL CLI not installed (graceful degradation, no error shown)
• Hook disabled in Claude Code settings

References

• CodeQL Documentation: https://codeql.github.com/docs/
• SARIF Specification: https://sarifweb.azurewebsites.net/
• ADR-035: Exit code standardization
• ADR-005: PowerShell-only scripting standard
• Session Protocol: .agents/SESSION-PROTOCOL.md