Setting up the CodeQL CLI

Setting up the CodeQL CLI

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

The CodeQL CLI supports a range of use cases and directory structures. This article walks through a simple setup that works for most users and environments.

If you plan to use the CodeQL CLI for security research or to test or contribute queries, you may need a more advanced setup. For more information, see Сведения о интерфейсе командной строки CodeQL.

Before you begin

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.

1. Download the CodeQL CLI tar archive

Пакет скачивания CodeQL CLI — это архив tar, содержащий средства, скрипты и различные файлы данных CodeQL. Если у вас нет лицензии GitHub Enterprise , скачав этот архив, вы согласны с GitHub CodeQL условий.

Загрузите пакет CodeQL из https://github.com/github/codeql-action/releases. Содержимое пакета:

• Продукт CodeQL CLI
• совместимая версия запросов и библиотек из https://github.com/github/codeql;
• предварительно скомпилированные версии всех запросов, включенных в пакет.

Всегда следует использовать пакет CodeQL . Это обеспечивает совместимость и обеспечивает гораздо более высокую производительность, чем отдельная загрузка запросов CodeQL CLI и извлечении запросов CodeQL. Если вы будете запускать CLI только на одной конкретной платформе, скачайте соответствующий файл codeql-bundle-PLATFORM.tar.zst. Кроме того, можно скачать файл codeql-bundle.tar.zst, содержащий CLI для всех поддерживаемых платформ.

Существуют также tar.gz варианты пакета, которые идентичны tar.zst вариантам, кроме сжатых с помощью менее эффективного алгоритма gzip. Единственной причиной скачивания tar.gz вариантов является использование старых средств декомпрессии, которые не поддерживают алгоритм сжатия Zstandard.

2. Extract the CodeQL CLI tar archive

Extract the CodeQL CLI tar archive to a directory of your choosing.

Optional: Make the CodeQL CLI available in your CI system

If you plan to run CodeQL code scanning analysis in a CI system, ensure that the full contents of the CodeQL CLI bundle are available to every CI server that will run analysis.

For example, you can:

• Copy the bundle from a central internal location and extract it on each server, or
• Use the REST API to download the bundle directly from GitHub, ensuring that you receive the latest improvements to queries. For more information, see Конечные точки REST API для выпусков и ресурсов выпуска.

3. Launch codeql

После извлечения можно выполнить процессы CodeQL путем выполнения codeql исполняемого файла несколькими способами:

• Выполнив выполнение <extraction-root>/codeql/codeql, где <extraction-root> находится папка, в которой извлечен пакет CodeQL CLI.
• Добавив <extraction-root>/codeql в PATH, чтобы можно было запустить исполняемый файл просто как codeql.

На этом этапе можно выполнить команды CodeQL. Полный список команд CodeQL CLI см. в разделе Команды CLI CodeQL вручную.

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 packs if /<extraction root>/codeql is on the PATH.
• /<extraction root>/codeql/codeql resolve packs otherwise.

If successful, you should see output similar to the extract below:

Searching directories specified by `--additional-packs`. All directories have equal priority.
  Searching in:
    No packs were found at this location.
Searching directories specified by `--search-path`. Directories are searched in order.
Searching the root of the CodeQL distribution.
  Searching in:
      <extraction root>
    The following packs were found:
      codeql/java-all@<version>: (library) <extraction root>/qlpacks/codeql/javat-all/<version>/qlpack.yml
      codeql/java-queries@<version>: (query) <extraction root>/qlpacks/codeql/java-queries/<version>/qlpack.yml
      codeql/javascript-all@<version>: (library) <extraction root>/qlpacks/codeql/javascript-all/<version>/qlpack.yml
      codeql/javascript-queries@<version>: (query) <extraction root>/qlpacks/codeql/javascript-queries/<version>/qlpack.yml
      codeql/swift-all@<version>: (library) <extraction root>/qlpacks/codeql/swift-all/<version>/qlpack.yml
      codeql/swift-queries@<version>: (query) <extraction root>/qlpacks/codeql/swift-queries/<version>/qlpack.yml
...

The results have been truncated for brevity. The actual results will be longer and more detailed.

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>. 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.

Optionally, you can download some CodeQL packs containing pre-compiled queries you would like to run. For more information, see Настройка анализа с помощью пакетов CodeQL.

The codeql resolve packs command is useful for diagnosing problems when the CodeQL CLI is unable to locate query packs that you expect to be available for analysis.

Next steps

To learn how to prepare your code to be analyzed by the CodeQL CLI, see Подготовка кода для анализа CodeQL.