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