Codeql

# CodeQL Alert Management Reference

Guide for understanding, triaging, dismissing, and resolving code scanning alerts generated by CodeQL.

## Alert Severity Levels

### Standard Severity

All code scanning alerts have one of these severity levels:

| Level | Description |
|---|---|
| `Error` | High-confidence, high-impact issues that should be fixed |
| `Warning` | Moderate-confidence or moderate-impact issues |
| `Note` | Low-confidence or informational findings |

### Security Severity

Security alerts additionally have a security severity derived from CVSS scores:

| Level | CVSS Score Range | Description |
|---|---|---|
| `Critical` | > 9.0 | Severe vulnerabilities requiring immediate attention |
| `High` | 7.0 – 8.9 | Significant vulnerabilities that should be prioritized |
| `Medium` | 4.0 – 6.9 | Moderate vulnerabilities to address in normal workflow |
| `Low` | 0.1 – 3.9 | Minor issues with limited security impact |

When a security severity is present, it takes precedence over the standard severity for display and sorting.

### How Security Severity Is Calculated

For each CodeQL security query added to the Default or Extended suite:
1. All CVEs matching the query's CWE tags are identified
2. The 75th percentile of CVSS scores for those CVEs is calculated
3. That score becomes the query's security severity
4. The numerical score maps to Critical/High/Medium/Low per CVSS definitions

## Alert Labels

Alerts in non-application code receive category labels:

| Label | Description |
|---|---|
| **Generated** | Code generated by the build process |
| **Test** | Test code (detected by file path) |
| **Library** | Library or third-party code |
| **Documentation** | Documentation files |

These labels are assigned automatically based on file paths. They cannot be manually overridden.

## Alert Triage in Pull Requests

### How PR Alerts Work

- Alerts appear as annotations in the **Conversation** tab and **Files changed** tab
- The **Code scanning results** check summarizes all findings
- Alerts only appear in a PR if ALL identified lines exist in the PR diff
- New alerts on changed lines are shown; pre-existing alerts are not

### PR Check Failure Behavior

By default, the check fails if alerts have severity of `error`, `critical`, or `high`. Override this threshold via repository Settings → Rules → Rulesets → Code scanning.

### Merge Protection

Configure rulesets to block PR merging when:
- A required tool finds alerts matching the severity threshold
- A required tool's analysis is still in progress
- A required tool is not configured for the repository

## Copilot Autofix

GitHub Copilot Autofix automatically generates fix suggestions for CodeQL alerts in pull requests.

### Availability
- Free for all public repositories
- Available for private repos with GitHub Code Security license
- No Copilot subscription required
- Supports a subset of CodeQL queries (not all)

### How It Works
1. Code scanning detects an alert in a PR
2. Alert information is sent to the LLM for analysis
3. Fix suggestions are posted as PR comments with inline code changes
4. Developers review, edit, and commit the suggested fix

### Using Autofix Suggestions
- Click **Edit** to apply the fix directly on GitHub or via GitHub CLI
- Use **View autofix patch** to apply locally
- Always review and test the fix before committing
- The fix may include changes to files not in the original PR diff (e.g., adding a dependency to `package.json`)

### Dismissing Autofix
Click **Dismiss suggestion** on the comment to reject a suggestion.

## Dismissing Alerts

### When to Dismiss

Dismiss alerts when:
- The finding is a false positive (code uses a pattern CodeQL doesn't recognize as safe)
- The code is used only for testing and risk is acceptable
- The effort to fix is greater than the benefit

### Dismissal Reasons

Choose the appropriate reason — it affects whether the query continues running:

| Reason | When to Use |
|---|---|
| **False positive** | The al