Executive Summary: CodeQL in GitHub Advanced Security

CodeQL is GitHub’s static code analysis engine, used to identify security vulnerabilities and code quality issues by querying source code as if it were data. It is a core component of GitHub Advanced Security (GHAS) and supports both open-source and enterprise repositories.

Purpose

CodeQL enables developers and security teams to:

  • Detect known vulnerabilities.
  • Enforce secure coding practices.

How It Works

  • CodeQL builds a database from the source code.
  • It runs queries against this database to find patterns that indicate potential security issues.
  • Results are surfaced in the GitHub UI under Code scanning alerts.

Enablement in GitHub

CodeQL can be enabled in two ways:

  1. Default Setup: GitHub automatically configures scanning for supported languages.(Phase 1)
  2. Advanced Setup: Users define custom workflows using GitHub Actions, allowing for:
    • Custom build steps
    • Query customization
    • Language-specific tuning

Supported Languages

Includes JavaScript/TypeScript, Python, Java, C/C++, C#, Go, Ruby and Rust.
More details:
https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/


Integration

  • Runs via GitHub Actions.
  • Can be triggered on push, pull request, or schedule.
  • Integrates with branch protection rules and security policies.

Benefits

  • Early detection of vulnerabilities.
  • Customizable and extensible query framework.
  • Scales across large codebases and organizations.

Governance

Organizations can enforce CodeQL scanning through security configurations, ensuring consistent application of security policies across repositories.


Before Enabling Code Security:

After Enabling Code Security At Repo Level:

At Org Level:

About alerts from code scanning

The default CodeQL analysis is used to configure code scanning to check the code in a repository . When the analysis is complete, the resulting alerts are displayed alongside each other in the security view of the repository.

By default, code scanning analyzes your code periodically on the default branch and during pull requests. For information about managing alerts on a pull request, see Triaging code scanning alerts in pull requests.

Viewing the alerts for a repository

You need write permission to view a summary of all the alerts for a repository on the Security tab.

By default, the code scanning alerts page is filtered to show alerts for the default branch of the repository only.

  1. On GitHub, navigate to the main page of the repository.
  2. Under the repository name, click Security. If you cannot see the "Security" tab, select the  dropdown menu, and then click Security.
  3. In the left sidebar, click Code scanning.
  4. Optionally, use the free text search box or the dropdown menus to filter alerts. For example, you can filter by the tool that was used to identify alerts.
  5. Under "Code scanning," click the alert you'd like to explore to display the detailed alert page. The status and details on the alert page only reflect the state of the alert on the default branch of the repository, even if the alert exists in other branches. You can see the status of the alert on non-default branches in the Affected branchessection on the right-hand side of the alert page. If an alert doesn't exist in the default branch, the status of the alert will display as "in pull request" or "in branch" and will be colored grey. The Development section shows linked branches and pull requests that will fix the alert.

Resolving code scanning alerts

From the security view, you can view, fix, or dismiss alerts for potential vulnerabilities or errors in your project's code.

Who can use this feature?

Users with write access

Generating suggested fixes for code scanning alerts

GitHub Copilot Autofix can generate fixes for alerts identified by code scanning analysis. Most CodeQL alert types are supported and also some alerts from third-party tools. For more information, see Responsible use of Copilot Autofix for code scanning.

Note

You do not need a subscription to GitHub Copilot to use GitHub Copilot Autofix. Copilot Autofix is available to all public repositories on GitHub.com. On GitHub, navigate to the main page of the repository.

  1. Under the repository name, click  Security. If you cannot see the "Security" tab, select the  dropdown menu, and then click Security.
  1. In the left sidebar, click  Code scanning.
  2. Click the name of an alert.
  3. If Copilot Autofix can suggest a fix, at the top of the page, click  Generate fix.
  4. Once the suggested fix has been generated, at the bottom of the page, you can click Create PR with fix to automatically generate a pull request with the suggested fix. A new branch is created from the default branch, the generated fix is committed and a draft pull request is created. You can test and edit the suggested fix as you would with any other fix.

For information about the limitations of automatically generated fixes, see Limitations of suggestions.

Fixing an alert manually

Anyone with write permission for a repository can fix an alert by committing a correction to the code. If the repository has code scanning scheduled to run on pull requests, it's best to raise a pull request with your correction. This will trigger code scanning analysis of the changes and test that your fix doesn't introduce any new problems. For more information, see Triaging code scanning alerts in pull requests.

Dismissing alerts

There are two ways of closing an alert. You can fix the problem in the code, or you can dismiss the alert.

Dismissing an alert is a way of closing an alert that you don't think needs to be fixed. For example, an error in code that's used only for testing, or when the effort of fixing the error is greater than the potential benefit of improving the code. You can dismiss alerts from code scanning annotations in code, or from the summary list within the Security tab.

When you dismiss an alert:

  • It's dismissed in all branches.
  • The alert is removed from the number of current alerts for your project.
  • The alert is moved to the "Closed" list in the summary of alerts, from where you can reopen it, if required.
  • The reason why you closed the alert is recorded.
  • Optionally, you can comment on a dismissal to record the context of an alert dismissal.
  • Next time code scanning runs, the same code won't generate an alert.

To dismiss alerts:

  1. On GitHub, navigate to the main page of the repository.
  2. Under the repository name, click  Security. If you cannot see the "Security" tab, select the  dropdown menu, and then click Security.
  3. In the left sidebar, click  Code scanning.
  4. If you want to dismiss an alert, it's important to explore the alert first, so that you can choose the correct dismissal reason. Click the alert you'd like to explore.
  5. Review the alert, then click Dismiss alert and choose, or type, a reason for closing the alert.

It's important to choose the appropriate reason from the drop-down menu as this may affect whether a query continues to be included in future analysis. Optionally, you can comment on a dismissal to record the context of an alert dismissal. The dismissal comment is added to the alert timeline and can be used as justification during auditing and reporting.

Dismissing multiple alerts at once

If a project has multiple alerts that you want to dismiss for the same reason, you can bulk dismiss them from the summary of alerts. Typically, you'll want to filter the list and then dismiss all of the matching alerts. For example, you might want to dismiss all of the current alerts in the project that have been tagged for a particular Common Weakness Enumeration (CWE) vulnerability.

Re-opening dismissed alerts

If you dismiss an alert but later realize that you need to fix the alert, you can re-open it and fix the problem with the code. Display the list of closed alerts, find the alert, display it, and reopen it. You can then fix the alert in the same way as any other alert.

About code scanning results on pull requests

In repositories where code scanning is configured as a pull request check, code scanning checks the code in the pull request. By default, this is limited to pull requests that target the default branch, but you can change this configuration within GitHub Actions or in a third-party CI/CD system.

If the lines of code changed in the pull request generate code scanning alerts, the alerts are reported in the following places on the pull request.

  • Check results in the pull request
  • The Conversation tab of the pull request, as part of a pull request review
  • The Files changed tab of the pull request

Note

Code scanning displays alerts in pull requests only when all the lines of code identified by the alert exist in the pull request diff. For more information, see SARIF support for code scanning.

GitHub Copilot Autofix will suggest fixes for alerts from code scanning analysis (including CodeQL analysis) in repositories. For more information on working with suggestions from Copilot Autofix in pull requests, see Working with Copilot Autofix suggestions for alerts on a pull request.

Default setup for CodeQL

Default setup for code scanning is the quickest, easiest, most low-maintenance way to enable code scanning for your repository. Based on the code in your repository, default setup will automatically create a custom code scanning configuration. After enabling default setup, the code written in CodeQL-supported languages in your repository will be scanned:

  • On each push to the repository's default branch, or any protected branch. For more information on protected branches, see About protected branches.
  • When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks.
  • On a weekly schedule.

Advanced setup for CodeQL

Advanced setup for code scanning is helpful when you need to customize your code scanning. By creating and editing a workflow file, you can define how to build compiled languages, choose which queries to run, select the languages to scan, use a matrix build, and more. You also have access to all the options for controlling workflows, for example: changing the scan schedule, defining workflow triggers, specifying specialist runners to use. For more information about GitHub Actions workflows, see Workflows.

Recommendations

When you are setting up code scanning for the first time, or across multiple repositories, it's best to use default setup. Default setup uses the simplest method available to generate a CodeQL database and analyze your code, so that you can start fixing alerts as soon as possible. Once you have resolved the initial alerts, you may want to switch to advanced setup with a manual build process for high risk repositories.

  • No labels