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

```bash
# 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

```bash
# 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:

```bash
# Download ToB