codeql-scan

Console Output

=== CodeQL Security Scan ===

[OK] CodeQL CLI found at .codeql/cli/codeql
[OK] Languages detected: python, actions
[OK] 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

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

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

SARIF Files

Results are saved in SARIF format for IDE integration.

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

{
  "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": "scripts/example.py"
          },
          "region": {
            "startLine": 42
          }
        }
      }]
    }]
  }]
}

JSON Output (CI Mode)

{
  "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"
  ]
}

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_codeql_quick_scan.py
• Quick config: .github/codeql/codeql-config-quick.yml
• Targeted queries: CWE-078 (command injection), CWE-089 (SQL injection), CWE-079 (XSS), CWE-022 (path traversal), CWE-798 (hardcoded credentials)

Performance:

Graceful Degradation:

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

Running Diagnostics

# Console output (default)
python3 .codeql/scripts/get_codeql_diagnostics.py

# JSON output (programmatic parsing)
python3 .codeql/scripts/get_codeql_diagnostics.py --output-format json

# Markdown report
python3 .codeql/scripts/get_codeql_diagnostics.py --output-format markdown > diagnostics.md

Checks Performed

get_codeql_diagnostics.py Exit Codes

CodeQL CLI Not Found

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

Solution:

python3 .codeql/scripts/install_codeql.py --add-to-path
codeql version

Configuration Validation Failed

Error: Invalid query pack: codeql/unknown-queries

Solution:

python3 .codeql/scripts/test_codeql_config.py
codeql resolve qlpacks

Scan Timeout

Error: Query execution timed out after 300s

Solution: Reduce scope by scanning a specific language.

python3 .claude/skills/codeql-scan/scripts/invoke_codeql_scan.py --operation full --languages python

Cache Invalidation Issues

Warning: Using cached database, but source files changed

Solution: Force database rebuild with a full scan.

python3 .claude/skills/codeql-scan/scripts/invoke_codeql_scan.py --operation full

Hook Not Triggering

PostToolUse hook not running after file writes. 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

Verify:

python3 .codeql/scripts/get_codeql_diagnostics.py
test -f .claude/hooks/PostToolUse/invoke_codeql_quick_scan.py && echo "Hook exists"