awesome-copilot/skills/codeql/references/alert-management.md

# 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 alert is incorrect; the code is actually safe |
| **Won't fix** | The risk is accepted or the code is being deprecated |
| **Used in tests** | The vulnerable pattern is only in test code |

### Dismissal Comments
- Add a comment explaining the dismissal rationale
- Comments are stored in the alert timeline for audit/compliance
- Accessible via REST API at `alerts/{alert_number}` → `dismissed_comment`

### Contributing Improvements
For false positives from unsupported sanitization libraries, consider contributing to the CodeQL repository to improve analysis accuracy.

## Resolving Alerts

### Fix and Re-scan
1. Fix the vulnerability in the source code
2. Commit and push the changes
3. The next code scanning run will verify the fix
4. Alert is automatically closed when the fix is confirmed

### Removing Stale Configurations
If alerts persist from old/disabled configurations:
1. Navigate to the alert's **Affected branches** section
2. Identify stale configurations
3. Delete the stale configuration to remove outdated alerts

## Alert Data Flow

For `path-problem` queries, alerts include data flow information:

- **Source** — where untrusted data enters (e.g., user input)
- **Sink** — where the data is used unsafely (e.g., SQL query, HTML output)
- **Path** — the intermediate steps data takes from source to sink

Click **Show paths** on alert annotations to visualize the full data flow.

## Multi-Configuration Alerts

When multiple code scanning configurations analyze the same file:
- The same problem detected by the same query appears as a single alert
- The **Affected branches** section shows which configurations found the alert
- Different configurations may show different statuses
- Re-run out-of-date configurations to synchronize alert statuses

## Viewing Alerts

### Repository Security Tab
- Navigate to **Security** → **Code scanning alerts**
- Filter by: tool, severity, rule, branch, state
- Click an alert to see full details, affected branches, and data flow

### Pull Request Checks
- View **Code scanning results** check in the PR
- Click **View all branch alerts** for the full alert list
- Annotations appear inline in **Files changed**

### REST API
- `GET /repos/{owner}/{repo}/code-scanning/alerts` — list alerts
- `GET /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}` — get alert details
- `PATCH /repos/{owner}/{repo}/code-scanning/alerts/{alert_number}` — update alert status