CodeQL is a code analysis engine developed by Github to automate security checks.

It is used for Code Scanning in the TianoCore edk2 repository.

1. Overview
2. CodeQL Usage in edk2
   • Query Target List
   • Query Filtering in edk2
   • Process for Suggesting New Queries for edk2
   • Query Enabling Process
   • CodeQL in Pull Requests
   • Dismissing CodeQL Alerts
3. CodeQL CLI Local Commands
4. The CodeQL Project

CodeQL is open source and free for open source projects. It is maintained by GitHub and naturally has excellentintegration with GitHub projects. CodeQL uses a semantic code analysis engine to discover vulnerabilities in anumber of programming languages (both compiled and interpreted).

General CodeQL Information

TianoCore uses CodeQL C/C++ queries to find common programming errors and security vulnerabilities in firmware code.Many open-source queries are officially supported and comprise the vulnerability analysis performed against thedatabase.

CodeQL Query Repository

In addition, anyone can leverage the code analysis engine by writing a custom query. Information around writing acustom query is available in the official documentation.

CodeQL Query Documentation.

Theedk2 repository uses GitHub's Code Scanning feature (free for publicrepositories on GitHub.com) to show alerts directly in the repository and run CodeQL on pull requests and pushesto the repository.

About GitHub Code Scanning

Current CodeQL scanning results in the edk2 project are available in the "Actions" page of the GitHub repository.

edk2 CodeQL Workflow

A CodeQL command-line interface (CLI) is also available which can be run locally. A CodeQL CLI reference and manualare available in the documentation to learn how to use the CLI.

CodeQL CLI Documenation

At a high-level, there's two main phases of CodeQL execution to be aware of.

1. CodeQL database generation
   • CodeQL Database Documentation
2. CodeQL database analysis
   • CodeQL Analysis Documentation

The CodeQL CLI hooks into the normal firmware build process to generate a CodeQL database. Once the database isgenerated, any number of CodeQL queries can be run against the database for analysis.

CodeQL analysis results can be stored in theSARIF (Static Analysis Results Interchange Format) file format.

CodeQL SARIF documentation

SARIF files are JSON following the SARIF specification/schema. The files can be opened with SARIF viewers to moreconveniently view the results in the file.

For example, theSARIF Viewer extension for VS Codecan open a .sarif file generated by the CodeQL CLI and allow you to click links directly to the problematic line insource files.

In summary, the edk2 repository runs CodeQL on pull requests and CI builds. Any alerts will be flagged in the pullrequest status checks area. The queries used by the edk2 repository are stored in the edk2 CodeQL query set file.

edk2 CodeQL Query Set

CodeQL provides the capability to debug the actual queries and for our (TianoCore) community to write our own queriesand even contribute back to the upstream repo when appropriate. In other cases, we might choose to keep our ownqueries in a separate TianoCore repo or within a directory in the edk2 code tree.

This is all part of CodeQL Scanning. Information on the particular topic of running additional custom queries inCode Scanning is documentedherein that page.

In addition, CodeQL offers the flexibility to:

• Build databases locally
• Retrieve databases from server builds
• Relatively quickly test queries locally against a database for a fast feedback loop
• Suppress false positives
• Customize the files and queries used in the edk2 project and quickly keep this list in sync between the server and local execution

While CodeQL can scan various languages including Python and C/C++, the TianoCore project is only focused on C/C++checks at this time. TianoCore has an initial set of queries to evaluate shown below (checked boxes are done).

• cpp/conditionally-uninitialized-variable
• cpp/infinite-loop-with-unsatisfiable-exit-condition
• cpp/overflow-buffer
• cpp/pointer-overflow-check
• cpp/potential-buffer-overflow
• cpp/toctou-race-condition
• cpp/unclear-array-index-validation
• cpp/unsafe-strncat
• cpp/use-after-free
• cpp/user-controlled-null-termination-tainted
• cpp/wrong-number-format-arguments
• cpp/wrong-type-format-argument

Additional queries completed:

• cpp/overrunning-write
• cpp/overrunning-write-with-float
• cpp/very-likely-overrunning-write

CodeQL query files (.ql files) contain metadata about the query. For example,cpp/conditionally-uninitialized-variablestates the following about the query:

/** * @name Conditionally uninitialized variable * @description An initialization function is used to initialize a local variable, but the *              returned status code is not checked. The variable may be left in an uninitialized *              state, and reading the variable may result in undefined behavior. * @kind problem * @problem.severity warning * @security-severity 7.8 * @id cpp/conditionally-uninitialized-variable * @tags security *       external/cwe/cwe-457 */

edk2 automatically include queries against certain criteria using "query filters". For example, this could include anyproblem query above a certainsecurity-severity level. Or all queries withsecurity intags.

Because edk2 favors consistency in CI results, the project maintains a relatively fixed query set that is updated withindividual queries over time.

• edk2 Active Queries
• edk2 Active CodeQL Configuration

Note: Additional queries can be found here as well -https://lgtm.com/search?q=cpp&t=rules

New query adoption in edk2 can be proposed by sending an RFC to the TianoCore development mailing list(devel@edk2.groups.io) with the query link and justification for adopting the query in edk2.

Everyone is welcome to suggest new queries.

Enabling a new query may trigger zero to thousands of alerts. Therefore, two paths are used to enable a new query inthe project.

1. A single patch series - The first set of patches fixes the issues needed for the query to pass. The later set ofpatches enables the query.
2. A query enabling branch - A branch is created where multiple contributors can work together on fixing issues relatedto enabling a new query. Once the branch is ready, the history is cleaned up into a patch series that is submittedto the edk2 project.

(1) is recommended if the query is relatively simple to enable and one or two people are doing the work. (2) isrecommended if a lot of effort is needed to fix issues for the query especially issues spanning across packages.

If a query is deemed fruitless during enabling testing, it can simply be rejected. The goal for CodeQL in edk2 is toenable an effective set of queries that improve the codebase. As the list of enabled queries grows, total CodeQLcoverage will increase against active pull requests. We want to have relevant and effective coverage.

TianoCore is enabling CodeQL in a step-by-step fashion. The goal with this approach is to make steady progressenabling CodeQL to become more comprehensive and useful while not impacting day-to-day code contributions.

Throughout the process described in this section, CodeQL Code Scanning is be a mandatory status check for edk2pull requests.

The following documentation describes how to dismiss alerts:Dismissing Alerts

Note: If query has a false positive a GitHub Issue can be submitted in theCodeQL repo issues page with thefalse-positive tag to help improvethe query.

TheCodeQL CLI can be used as follows to wrap around the edk2 buildprocess (MdeModulePkg in this case) to generate a database in the directorycpp-database. The example shown usesstuart build commands.

codeql database create cpp-database --language=cpp --command="stuart_ci_build -c .pytool/CISettings.py -p MdeModulePkg-a IA32,X64 TOOL_CHAIN_TAG=VS2019 Target=DEBUG --clean" --overwrite

The following command can be used to generate aSARIF file(calledquery-results.sarif) from that database with the results of thecpp/conditionally-uninitialized-variable query:

codeql database analyze cpp-database codeql\cpp\ql\src\Security\CWE\CWE-457\ConditionallyUninitializedVariable.ql --format=sarifv2.1.0 --output=query-results.sarif

SARIF logs can be read by log viewers such as theSarif Viewer extension forVS Code.

CodeQL is an actively maintained project. Here is a comparison of edk2 commit activity versus CodeQL for reference:

• CodeQL Commit Activity
• edk2 Commit Activity

Because CodeQL does maintain a strong open-source presence, the TianoCore community should be able to fileissues andpull requestsinto the project.

The original RFC for adoption of CodeQL in edk2 is available here for reference:Adoption of CodeQL in edk2