codeql

Subscribe to all “codeql” posts via RSS or follow GitHub Changelog on Twitter to stay updated on everything we ship.

→ ~ cd github-changelog
→ ~/github-changelog|main git log main
showing all changes successfully

Code scanning adds beta support for Ruby

Ruby is the 10th most popular language within the open source community. To help more open source maintainers and organizations find potential vulnerabilities in their code, we’ve added Ruby support (beta) to the CodeQL engine that powers GitHub code scanning.

Our CodeQL analysis identifies security issues in your code, along with the flow of data to the vulnerable location. To help secure services and tools created with Ruby, the CodeQL beta release spots many of the most common security issues:

We’ve been putting this beta through its paces by analyzing some of the world's largest Ruby codebases at GitHub and select customers. The feedback has been overwhelmingly positive, and in many cases CodeQL identified real vulnerabilities, all while keeping the number of false-positives at a minimum.

CodeQL for Ruby is available by default in GitHub.com code scanning, the CodeQL CLI, and the CodeQL extension for VS Code starting today. It will also be included in GitHub Enterprise Server 3.4. Ruby joins the list of supported CodeQL languages, which also includes C/C++, C#, Java, JavaScript/TypeScript, Python, and Go.

We currently support all common Ruby versions, up to and including 3.02. Check out the documentation for more details on compatibility.

To start using the new Ruby analysis, simply update your existing workflow file by adding Ruby to the language matrix:

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        # add here
        language: ['ruby']

If you’re new to code scanning, set up a CodeQL analysis workflow from the Security tab in your repository.

Want to contribute or write your own CodeQL queries for Ruby? This guide will help you get started.

To give us feedback, join the Ruby beta discussion in the public CodeQL repository, which is also a good place to ask questions about anything CodeQL.

See more

CodeQL code scanning now supports Java 16 language features

We've added support for Java 16 standard language features (such as records and pattern matching) to CodeQL. Code using those features can now benefit from CodeQL's security analysis as part of code scanning.

We also continue to support older Java versions. CodeQL is able to analyze code written in Java version 7 through 16.

Learn more about CodeQL and code scanning.

See more

CodeQL runner deprecation

GitHub code scanning with CodeQL works seamlessly with GitHub Actions. For users of other CI/CD systems, we provided a way to run the code analysis using the CodeQL runner. The CodeQL runner acts as the glue between your CI/CD system and the CodeQL analysis engine (CLI).

In response to customer feedback, we have now transferred all CodeQL runner functionality natively into the CodeQL CLI. This means that there are fewer components to install, use, and update if you're running CodeQL code scanning on a 3rd party CI/CD system.

As of CodeQL CLI 2.6.2 (released today), there is now full feature parity between the CodeQL CLI and the runner. We are therefore announcing the deprecation of the CodeQL runner. This affects users of 3rd party CI/CD systems; users of CodeQL code scanning on GitHub Actions are not affected.

Deprecation timeline: GitHub Enterprise Server (GHES)

The CodeQL runner will continue to be part of the GitHub Enterprise Server releases up to and including the 3.3.x series. It will no longer be part of GitHub Enterprise Server starting the 3.4.0 (scheduled for 2022). The CodeQL CLI is a feature-complete replacement for the CodeQL runner, and is fully compatible with GitHub Enterprise Server.

Deprecation timeline: GitHub.com (including GitHub Enterprise Cloud)

The CodeQL bundle will continue to contain the CodeQL runner until March 2022. In the run-up to the final release we will start displaying clear deprecation warnings. After March 2022, code scanning API change on GitHub.com will likely not be compatible with older CodeQL runner releases. The CodeQL CLI is a feature-complete replacement for the CodeQL runner, and is fully compatible with GitHub.com.

How does this affect me?

If you’re using CodeQL code scanning on GitHub Actions, you are not affected by this change.

If you’ve configured code scanning to run the CodeQL runner inside another CI/CD system, we recommend migrating to the CodeQL CLI as soon as possible. Version 2.6.2 of the CodeQL CLI has full feature parity with the CodeQL runner and allows you to analyze codebases on 3rd party CI/CD systems in the same way as the CodeQL runner.

New users of CodeQL code scanning should use CodeQL CLI version >= 2.6.2.

What actions should I take?

You should configure your CI/CD system to use the CodeQL CLI before March 2022 and/or before upgrading to GHES 3.4.0. When setting up the CodeQL CLI, we recommend that you test the CodeQL CLI set up to verify that the CLI is correctly configured to create and analyze databases.

Learn more about how to migrate from the CodeQL runner to CodeQL CLI 2.6.2 here.

See more

Introducing the CodeQL package manager (public beta)

The CodeQL package manager is now available in public beta on GitHub.com. CodeQL packages can contain CodeQL queries and CodeQL libraries — and of course you can express dependencies between packs. You can upload your packs to the package registry on GitHub.com, and CodeQL will automatically fetch any required dependencies when running queries from a pack. This makes it simple to create and share CodeQL queries and libraries!

CodeQL packs of course also integrate with GitHub code scanning (example below). Alternatively, you can use packs using the CodeQL CLI (version 2.6.0-beta.1 and up) on your local machine. More documentation about CodeQL packs can be found here.

Integrating CodeQL packs into GitHub code scanning workflows

You can integrate CodeQL packs into GitHub code scanning workflows by specifying that you want to run the CodeQL 2.6.0 beta version, and then specify the pack(s) you'd like to run. For example:

 - uses: github/codeql-action/init@v1
   with:
     tools: https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.6.0-beta.1
     packs: codeql/csharp-queries1@~1.2.3, octo-org/csharp-security

Alternatively, you can select CodeQL packs by specifying a list of package references in the packs section of your CodeQL configuration file. For example:

     - queries/DeadCodeCondition.ql
     - queries/GlobalUseBeforeInit.qls
   packs:
     - codeql/csharp-queries@~1.2.3  # latest version compatible with 1.2.3
     - octo-org/csharp-security      # latest version

For more information, see Configuring code scanning.

Standard CodeQL packs

All of our own CodeQL queries and libraries are now also released as CodeQL packs at github.com/codeql.

For each language there is a query pack containing all CodeQL queries for that language (from our open source repository). These packs are named codeql/<language>-queries. For example, the CodeQL pack containing the standard C/C++ queries is called codeql/cpp-queries.

We've also released packs with all CodeQL standard libraries for each language. These packs are named codeql/<language>-all (e.g. codeql/cpp-all). If you're writing your own query pack, you'll likely want to express a dependency on the CodeQL standard libraries for that language.

CodeQL pack visibility

You can choose the permission levels required for users to view and access your CodeQL packs. Currently, all CodeQL packs default to Internal and should manually be set to Public. If you want to make your CodeQL pack visible to everyone, go to the settings section of the package and Change package visibility to Public.

Downloading CodeQL packs

All CodeQL packs can be downloaded and installed using the CodeQL CLI. You do not need to use the docker pull command shown on the package page. For more information, see Publishing and using CodeQL packs.

For more information, see About CodeQL packs.

See more

CodeQL code scanning: new severity levels for security alerts

New severity levels for security alerts

We now show security-severity levels for CodeQL security alerts in code scanning. security-severity levels help you understand in more detail the risks posed by security alerts, allowing you to assess the potential impact of the alerts, and make the right decision on which alerts to fix first. The severity level of security alerts can be critical, high, medium, or low.

The new security-severity levels are displayed on all security alerts. For example, if a PR triggers security alerts, the security-severity is visible on the alert annotations under the Files changed tab. You can also see the security-severity for each alert present in a repository by clicking Security > Code scanning alerts.

security-severity

About security severity levels

Security severity levels are displayed on code scanning alerts that are generated by security queries.
CodeQL automatically calculates security-severity levels and assigns an exact numerical score to each security query. To calculate the security-severity of an alert, we first group all CVEs reported by the CWEs assigned to the security query. We then calculate the 75th percentile of the CVSS score for those CVEs. Finally, we translate numerical scores to critical, high, medium, or low using the following definitions:

Severity Score Range
None 0.0
Low 0.1 – 3.9
Medium 4.0 – 6.9
High 7.0 – 8.9
Critical 9.0 – 10.0

Defining which security-severity levels cause pull request check failure

By default, any code scanning alerts with a security-severity of critical or high will cause pull request check failure. You can specify which security-severity level for code scanning results should cause check failure by going to the Security & Analysis tab in the repository settings.

security-settings

Severity levels for non-security alerts

Severity levels for non-security alerts remain as error, warning, or note. By default, any code scanning results with the severity of error will cause check failure. You can change this setting using the dropdown on the Security & Analysis tab in the repository settings. It allows two selections that apply to the security and non-security alerts.

Security severity levels in the code scanning API

You can also access security_severity_level data for security queries using the /alerts endpoint of the code scanning API.

How to add security-severity to a CodeQL query

You can add the expected security-severity level to the your custom security queries by adding the numerical score to the @security-severity query metadata property in the .ql file.

The new security-severity levels for security queries have been deployed to GitHub.com. These improvements will also be available in GitHub Enterprise Server 3.2.

Learn more about CodeQL and code scanning by reading the documentation.

See more

CodeQL code scanning now recognizes more sources and uses of untrusted user data

We’ve improved the depth of CodeQL's analysis by adding support for more libraries and frameworks and increasing the coverage of our existing library and framework models for several languages (C++, JavaScript, Python, and Java). As a result, CodeQL can now detect even more potential sources of untrusted user data, steps through which that data flows, and potentially dangerous sinks in which this data could end up. This results in an overall improvement of the quality of the code scanning alerts.

We carefully choose and prioritize the libraries and frameworks supported by CodeQL based on their popularity and through user feedback. The libraries and frameworks added and improved are listed below.

C/C++

JavaScript and TypeScript

Python

Java

Learn more about CodeQL and code scanning.

See more

Code scanning: Diagnostic information is available!

Code scanning with CodeQL now generates diagnostic information for all supported languages.

Before analyzing your code, CodeQL first creates a CodeQL database containing all of the important information about your codebase. This database is then analyzed by executing CodeQL queries against it.

The new diagnostic information includes important information to help learn more about the CodeQL analysis.

Diagnostic information includes:

  • Lines of code in your codebase (as a baseline)
  • Lines of code in the CodeQL database extracted from your code
  • Lines of code in the CodeQL database excluding auto-generated files and external libraries
  • Number of files successfully analyzed
  • Number of files that generate extractor errors and warnings during database creation

You can see the detailed diagnostic information in GitHub CodeQL Actions Logs.

CodeQL Action Log

You also can view Lines of code in your codebase and Lines of code in the CodeQL database by going to the Security tab and selecting Code scanning alerts.

Code scanning CodeQL security tab

Diagnostic information queries are available in CodeQL CLI 2.5.6 and later. The CodeQL bundle includes both the CodeQL CLI and a compatible set of queries.

See more

CodeQL Code Scanning: It’s now easier to analyze multiple languages on 3rd party CI/CD systems with the CodeQL CLI

The latest release of the CodeQL CLI supports creating CodeQL databases for multiple languages in a single command. This makes it easier for customers using CI/CD systems other than GitHub Actions to run code scanning analysis. Previously, these users had to use the separate CodeQL Runner. The Runner will continue to be available, but the recommended way to handle multiple languages in your codebase is to use the CodeQL CLI directly.

To use this new option:

  • Download the updated CodeQL bundle, which includes the updated CodeQL CLI.
  • Check out your codebase at the Git reference you want to analyze.
  • Create CodeQL databases for the supported languages in your codebase using codeql database create. You need to specify a parent directory for the databases using the --db-cluster option, and the -l option for each language you want to create a database for.

After creating the databases, you must run codeql database analyze separately for each language. Use the --sarif-category option, setting different values for each language. Specifying this option lets code scanning know that each SARIF file it receives from these analyses should be retained. Similarly, you must also run codeql github upload-results separately for the SARIF file generated by each analysis.

For more information about setting up the CodeQL CLI with your CI system, see "Running CodeQL CLI in your CI system."

The new codeql database create option for creating databases for multiple languages in a single command is available in CodeQL 2.5.6 and later. The CodeQL bundle includes both the CodeQL CLI and a compatible set of queries.

See more

CodeQL Code Scanning: improvements for users analyzing codebases on 3rd party CI/CD systems

The latest release of the CodeQL CLI supports uploading analysis results to GitHub. This makes it easier to run code analysis for customers who wish to use CI/CD systems other than GitHub Actions. Previously, such users had to use the separate CodeQL Runner, which will continue to be available.

To get started, first download the updated CodeQL bundle, which includes the updated CodeQL CLI, and check out your codebase at the Git reference you want to analyze. After analyzing your codebase with codeql database create ... and codeql database analyze ..., you can use the new codeql github upload-results command to upload the SARIF file with scanning results back to GitHub Code Scanning.

codeql github upload-results currently works for one language at a time and can replace the current workflow of codeql-runner init / build / codeql-runner analyze when a single language is being analyzed.

If you want to analyze more than one language at a time or integrate CodeQL as a separate step into your existing CI workflow, you may use CodeQL runner.

The new codeql github upload-results command is available starting version 2.4.5 of the CodeQL CLI. The CodeQL bundle includes both the CodeQL CLI and a compatible set of queries.

See more