Настройка интерфейса командной строки CodeQL

Setting up the CodeQL CLI

To run CodeQL commands, you need to set up the CLI so that it can access the tools, queries, and libraries required to create and analyze databases.

The CodeQL CLI can be set up to support many different use cases and directory structures. To get started quickly, we recommend adopting a relatively simple setup, as outlined in the steps below.

If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply follow the steps below. For macOS version 10.15 ("Catalina") or newer, there are additional notes for some of the steps. If you are using macOS on Apple Silicon (for example, Apple M1), ensure that the Xcode command-line developer tools and Rosetta 2 are installed.

For information about installing the CodeQL CLI in a CI system to create results to display in GitHub as code scanning alerts, see "Installing CodeQL CLI in your CI system."

1. Download the CodeQL CLI zip package

The CodeQL CLI download package is a zip archive containing tools, scripts, and various CodeQL-specific files. If you don’t have a GitHub Enterprise license then, by downloading this archive, you are agreeing to the GitHub CodeQL Terms and Conditions.

You should download the CodeQL bundle from https://github.com/github/codeql-action/releases. The bundle contains:

• CodeQL CLI product
• A compatible version of the queries and libraries from https://github.com/github/codeql
• Precompiled versions of all the queries included in the bundle

You should always use the CodeQL bundle as this ensures compatibility and also gives much better performance than a separate download of the CodeQL CLI and checkout of the CodeQL queries. If you will only be running the CLI on one specific platform, download the appropriate codeql-bundle-PLATFORM.tar.gz file. Alternatively, you can download codeql-bundle.tar.gz, which contains the CLI for all supported platforms.

Download information for macOS "Catalina" (or newer) users

From macOS version 10.15 ("Catalina") onwards you need to ensure that your web browser does not automatically extract zip files. If you use Safari, complete the following steps before downloading the CodeQL CLI zip archive:

1. Open Safari.
2. From the Safari menu, select Preferences... or Settings... (version 13 "Ventura" onwards).
3. Click the General Tab.
4. Ensure the check-box labeled Open "safe" files after downloading is unchecked.

2. Extract the zip archive

For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier) simply extract the zip archive.

Extraction information for macOS "Catalina" (or newer) users

macOS "Catalina", "Big Sur", "Monterey", or "Ventura" users should run the following commands in the Terminal, where ${extraction-root} is the path to the directory where you will extract the CodeQL CLI zip archive:

1. mv ~/Downloads/codeql\*.zip ${extraction-root}
2. cd ${extraction-root}
3. /usr/bin/xattr -c codeql\*.zip
4. unzip codeql\*.zip

3. Launch codeql

Once extracted, you can run CodeQL processes by running the codeql executable in a couple of ways:

• By executing <extraction-root>/codeql/codeql, where <extraction-root> is the folder where you extracted the CodeQL CLI package.
• By adding <extraction-root>/codeql to your PATH, so that you can run the executable as just codeql.

At this point, you can execute CodeQL commands. For a full list of the CodeQL CLI commands, see "CodeQL CLI commands manual."

Testing the CodeQL CLI configuration

After you extract the CodeQL CLI bundle, you can run the following command to verify that the CLI is correctly configured to create and analyze databases:

• codeql resolve qlpacks if /<extraction-root>/codeql is on the PATH.
• /<extraction-root>/codeql/codeql resolve qlpacks otherwise.

Extract from successful output:

codeql/cpp-all (/<extraction-root>/qlpacks/codeql/cpp-all/<version>)
codeql/cpp-examples (/<extraction-root>/qlpacks/codeql/cpp-examples/<version>)
codeql/cpp-queries (/<extraction-root>/qlpacks/codeql/cpp-queries/<version>)
codeql/csharp-all (/<extraction-root>/qlpacks/codeql/charp-all/<version>)
codeql/csharp-examples (/<extraction-root>/qlpacks/codeql/charp-examples/<version>)
codeql/csharp-queries (/<extraction-root>/qlpacks/codeql/charp-queries/<version>)
codeql/java-all (/<extraction-root>/qlpacks/codeql/java-all/<version>)
codeql/java-examples (/<extraction-root>/qlpacks/codeql/java-examples/<version>)
codeql/java-queries (/<extraction-root>/qlpacks/codeql/java-queries/<version>)
codeql/javascript-all (/<extraction-root>/qlpacks/codeql/javascript-all/<version>)
codeql/javascript-examples (/<extraction-root>/qlpacks/codeql/javascript-examples/<version>)
codeql/javascript-queries (/<extraction-root>/qlpacks/codeql/javascript-queries/<version>)
codeql/python-all (/<extraction-root>/qlpacks/codeql/python-all/<version>)
codeql/python-examples (/<extraction-root>/qlpacks/codeql/python-examples/<version>)
codeql/python-queries (/<extraction-root>/qlpacks/codeql/python-queries/<version>)
codeql/ruby-all (/<extraction-root>/qlpacks/codeql/ruby-all/<version>)
codeql/ruby-examples (/<extraction-root>/qlpacks/codeql/ruby-examples/<version>)
codeql/ruby-queries (/<extraction-root>/qlpacks/codeql/ruby-queries/<version>)
...

You should check that the output contains the expected languages and also that the directory location for the qlpack files is correct. The location should be within the extracted CodeQL CLI bundle, shown in the earlier example as <extraction root>, unless you are using a checkout of github/codeql. If the CodeQL CLI is unable to locate the qlpacks for the expected languages, check that you downloaded the CodeQL bundle and not a standalone copy of the CodeQL CLI.

You can also run codeql resolve languages to show which languages are available for database creation. This will list the languages supported by default in your CodeQL CLI package.

(Optional) You can download some "Customizing analysis with CodeQL packs" containing pre-compiled queries you would like to run. To do this, run codeql pack download <pack-name> [...pack-name], where pack-name is the name of the pack you want to download. The core query packs are a good place to start. They are:

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

Alternatively, you can download query packs during the analysis by using the --download flag of the codeql database analyze command.

Generating a token for authentication with GitHub Enterprise Server

If you eventually want to upload your results to GitHub Enterprise Server to display as code scanning alerts, you will need to generate a personal access token with the security_events write permission. For more information, see "Managing your personal access tokens."

If you have installed the CodeQL CLI in a third-party CI system to create results to display in GitHub as code scanning alerts, you can use a GitHub App or personal access token to upload results to GitHub Enterprise Server. For more information, see "Installing CodeQL CLI in your CI system."

Checking out the CodeQL source code directly

Some users prefer working with CodeQL query sources directly in order to work on or contribute to the Open Source shared queries. In order to do this, the following steps are recommended. Note that the following instructions are a slightly more complicated alternative to working with CodeQL packages as explained above.

1. Download the CodeQL CLI zip

Follow step 1 from the previous section.

2. Create a new CodeQL directory

Create a new directory where you can place the CLI and any queries and libraries you want to use. For example, $HOME/codeql-home.

The CLI’s built-in search operations automatically look in all of its sibling directories for the files used in database creation and analysis. Keeping these components in their own directory prevents the CLI searching unrelated sibling directories while ensuring all files are available without specifying any further options on the command line.

3. Obtain a local copy of the CodeQL queries

The CodeQL repository contains the queries and libraries required for CodeQL analysis of all supported languages. Clone a copy of this repository into codeql-home.

By default, the root of the cloned repository will be called codeql. Rename this folder codeql-repo to avoid conflicting with the CodeQL CLI that you will extract in step 1. If you use git on the command line, you can clone and rename the repository in a single step by running git clone git@github.com:github/codeql.git codeql-repo in the codeql-home folder.

Within this repository, the queries and libraries are organized into CodeQL packs. Along with the queries themselves, CodeQL packs contain important metadata that tells the CodeQL CLI how to process the query files. For more information, see "Customizing analysis with CodeQL packs."

4. Extract the zip archive

For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier) simply extract the zip archive into the directory you created in step 2.

For example, if the path to your copy of the CodeQL repository is $HOME/codeql-home/codeql-repo, then extract the CLI into $HOME/codeql-home/.

5. Launch codeql

See step 3 from the previous section.

6. Verify your CodeQL CLI setup

CodeQL CLI has subcommands you can execute to verify that you are correctly set up to create and analyze databases:

• Run codeql resolve languages to show which languages are available for database creation. This will list the languages supported by default in your CodeQL CLI package.
• Run codeql resolve qlpacks to show which CodeQL packs the CLI can find. This will display the names of all the CodeQL packs directly available to the CodeQL CLI. This should include:
• Query packs for each supported language, for example, codeql/{language}-queries. These packs contain the standard queries that will be run for each analysis.
• Library packs for each supported language, for example, codeql/{language}-all. These packs contain query libraries, such as control flow and data flow libraries, that may be useful to query writers.
• Example packs for each supported language, for example, codeql/{language}-examples. These packs contain useful snippets of CodeQL that query writers may find useful.
• Legacy packs that ensure custom queries and libraries created using older products are compatible with your version of CodeQL.

Using two versions of the CodeQL CLI

If you want to use the latest CodeQL features to execute queries or CodeQL tests, but also want to prepare databases that are compatible with a specific version of CodeQL code scanning on GitHub Enterprise Server, you may need to install two versions of the CLI. The recommended directory setup depends on which versions you want to install:

• If both versions are 2.0.2 (or newer), you can unpack both CLI archives in the same parent directory.
• If at least one of the versions is 2.0.1 (or older), the unpacked CLI archives cannot be in the same parent directory, but they can share the same grandparent directory. For example, if you unpack version 2.0.2 into $HOME/codeql-home/codeql-cli, the older version should be unpacked into $HOME/codeql-older-version/old-codeql-cli. Here, the common grandparent is the $HOME directory.