Installation and first steps

Installation and first steps #

Initial setup #

For detailed installation instructions, please refer to the official documentation.

Installing CodeQL #

CodeQL can either be installed manually, or if you are on macOS or Linux, you can alternatively use the package manager Homebrew.

To install the CodeQL CLI manually, navigate to the CodeQL release page and download the latest bundle for your architecture.

On macOS or Linux, you can install CodeQL using Homebrew using the following command:

brew install --cask codeql

In either case, the installed bundle contains the codeql binary, query libraries for supported languages, and pre-compiled versions for all of the included queries.

Keeping CodeQL up to date #

CodeQL is under active development, and it is important to stay updated with the latest releases to take advantage of these improvements and ensure your security testing is as effective as possible.

If you installed CodeQL manually, you need to navigate to the CodeQL release page to download new updates. If you used Homebrew to install CodeQL, you can ensure that your local installation is up to date by running:

brew upgrade codeql

Building a database #

To build a new CodeQL database you typically need to be able to build the corresponding codebase. Make sure that the codebase is in a clean state (e.g. by running make clean, go clean, or similar), and then build the codebase with the CodeQL CLI as follows:

To build a database for a C or C++ project, pass cpp as language to the CodeQL CLI. The build command is specified using the command argument.

codeql database create codeql.db --language=cpp --command='make -j8'

If you are using a meta-build system like CMake, you would first execute cmake to generate the build-configuration files and then pass the actual build command to CodeQL.

If your source files are not in the same tree as where you are building (e.g. if you are using cmake for out-of-source builds), add the --source-root argument when generating the database to correctly set the root of the source file tree.

To build a database for a Golang project, pass go as language to the CodeQL CLI.

codeql database create codeql.db --language=go

If you are using a build script, or more complex build system, you can pass the build command to the CodeQL using the --command argument.

To build a database for a Java or Kotlin project, pass java as language to the CodeQL CLI.

codeql database create codeql.db --language=java

If you are using a build script, or more complex build system, you can pass the build command to the CodeQL using the --command argument.

To build a database for a JavaScript or TypeScript project, pass javascript as language to the CodeQL CLI.

codeql database create codeql.db --language=javascript

To build a database for a Python project, pass python as language to the CodeQL CLI.

codeql database create codeql.db --language=python

To build a database for a Swift project, pass swift as language to the CodeQL CLI.

codeql database create codeql.db --language=swift

If you are using a build script, or more complex build system, you can pass the build command to the CodeQL using the --command argument.

To build a database for a Ruby project, pass ruby as language to the CodeQL CLI.

codeql database create codeql.db --language=ruby

If you are using a build script, or more complex build system, you can pass the build command to the CodeQL using the --command argument.

To build a database for a C# project, pass csharp as language to the CodeQL CLI.

codeql database create codeql.db --language=csharp

If you are using a build script, or more complex build system, you can pass the build command to the CodeQL using the --command argument.

Excluding individual files #

CodeQL will instrument the build process and successively add information about each compilation unit to the database. In practice, this means that if the compiler skips one or more source files (e.g. because the corresponding object files already exist and are up to date), then the corresponding functions and types will not be added to the database either. This can be used to reduce the size of the resulting database. For example, to avoid including third-party libraries in the database simply build the project once, delete any object files directly related to the project, and then build the project database using the CodeQL CLI as above.

However, it is important to remember that ignoring files means that CodeQL will have only partial knowledge about the corresponding code, and will not be able to reason about data flow through functions or methods defined in those files. For this reason, it is often better to include third-party libraries and filter issues based on the location in the codebase where they occur instead. This also means that you generally get more comprehensive analysis results if you vendor third-party libraries than if you rely on dynamic linking at runtime.

Analyzing a database #

The CodeQL bundle comes with a set of pre-compiled query packs included. It is also possible to install third-party query packs using the CodeQL CLI. To see the list of installed query packs, you can use the following command.

codeql resolve qlpacks

The command codeql database analyze runs a set of queries on an existing database. The output is written to a file and the output format is given as an argument on the command line. The following command runs the pre-compiled query pack codeql/cpp-queries on a given CodeQL database. The output is written to the SARIF-file results.sarif.

codeql database analyze codeql.db --format=sarif-latest --output=results.sarif -- codeql/cpp-queries

SARIF is a common output format used by many static-analysis tools. If you are using VSCode, the SARIF output can be displayed inline by the VSCode SARIF Viewer extension. Apart from SARIF, CodeQL also supports CSV output.

Installing new query packs #

Apart from the pre-compiled query packs that ship with the CLI bundle, it is also possible to install third-party query packs using the CodeQL CLI. Published query packs are identified by their scope, name, and an optional version. For query packs published to the GitHub container registry, the scope identifies the organization or account who owns the corresponding repository. The following command downloads (the latest version of) the cpp-queries and go-queries query packs published by Trail of Bits.

codeql pack download trailofbits/cpp-queries trailofbits/go-queries

For more information about our public CodeQL queries and published query packs we refer to our trailofbits/codeql-queries repository.

This content is licensed under a Creative Commons Attribution 4.0 International license.