CodeQL¶
Overview¶
CodeQL is open source and free for open-source projects. It is maintained by GitHub and naturally has excellent integration with GitHub projects. CodeQL uses a semantic code analysis engine to discover vulnerabilities in a number of programming languages (both compiled and interpreted).
Project Mu (and TianoCore) use CodeQL C/C++ queries to find common programming errors and security vulnerabilities in
firmware code. This platform leverages the CodeQL build plugin from Mu Basecore that makes it very easy to run CodeQL
against this platform. You simply use provide the --codeql argument in your normal stuart_update and stuart_build
commands.
CodeQL Command-Line Interface (CLI)¶
Because of CodeQL's integration with GitHub, it is often run in projects hosted on GitHub via an officially supported GitHub Action (codeql-action).
However, a CodeQL CLI application is also available that provides a command-line interface to CodeQL. This facilitates a local developer workflow by using the CLI application to perform two main tasks:
- Generate a CodeQL database
- Analyze the CodeQL database
There's ample documentation written on creating CodeQL databases and analyzing CodeQL databases.
Our unique firmware build environment poses several challenges and further integrating the CLI with the stuart tool set can be daunting for those unfamiliar with stuart's internals.
Therefore, Project Mu and, by extension, this platform, use a set of CodeQL plugins from Mu Basecore to simplify CodeQL usage.
CodeQL Plugins¶
The CodeQL plugins are described in the plugin readme. This readme does not repeat information and instead focuses on explaining the context of the plugins within this platform.
Put simply, the plugins allow a single command-line argument (--codeql) to be provided to the normal stuart
commands already used in this platform to run CodeQL.
For example:
stuart_update --codeql- Downloads the appropriate CodeQL CLI for your operating system.stuart_build --codeql- Generates a CodeQL database using that CodeQL during the build. In post-build, the database is automatically analyzed and a SARIF file is generated.
Be aware that these commands will take a long time. The CodeQL CLI is several hundred megabytes in size and hooking CodeQL into the build (1) forces a clean build (2) adds additional CodeQL database logic, both of which increase the overall time of the build.
Note: The CodeQL queries run during analysis by default are those in MuCodeQlQueries.qls.
The CodeQL plugin readme describes how to change the queries run and change how the plugin interprets the results. It also describes how to view SARIF results conveniently in an IDE such as Visual Studio Code.
Also by default, this platform shows CodeQL result from those queries but does not fail the build if there are any errors.
CodeQL Database and Result Locations¶
Although the database and result directory locations are documented in the plugin readme, they are repeated here for convenience.
The CodeQL database is written to a directory unique to the package and target being built:
Build/codeql-db-<package>-<target>-<instance>
For example: Build/codeql-db-qemuq35pkg-debug-0
The plugin does not delete or overwrite existing databases, the instance value is simply increased. This is because databases are large, take a long time to generate, and are important for reproducing analysis results. The user is responsible for deleting database directories when they are no longer needed.
Similarly, analysis results are written to a directory unique to the package and target. For analysis, results are stored in individual files so those files are stored in a single directory.
For example, all analysis results for the above package and target will be stored in:
codeql-analysis-qemuq35pkg-debug
CodeQL results are stored in SARIF (Static Analysis Results Interchange Format) (CodeQL SARIF documentation) files. Each SARIF file corresponding to a database will be stored in a file with an instance matching the database instance.
For example, the analysis result file for the above database would be stored in this file:
codeql-analysis-qemuq35pkg-debug/codeql-db-qemuq35pkg-debug-0.sarif
The SARIF Viewer extension for VS Code can open the .sarif file generated by this plugin and allow you to click links directly to the problem area in source files.