Setting up the CodeQL CLI

To get started with the CodeQL CLI, you need to download and set up the CLI so that it can access the tools and libraries required to create and analyze databases.

Wer kann dieses Feature verwenden?

CodeQL ist für die folgenden Repositorytypen verfügbar:

In diesem Artikel

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 plan to use the CodeQL CLI for security research or to test or contribute queries, you may want a more advanced setup of CodeQL CLI. For more information, see Advanced setup of the CodeQL CLI.

If you are setting up the CodeQL CLI in your CI system, you need to make the full contents of the CodeQL CLI bundle available to every CI server that you want to run CodeQL code scanning analysis on. For example, you might configure each server to copy the bundle from a central, internal location and extract it. Alternatively, you could use the REST API to get the bundle directly from GitHub, ensuring that you benefit from the latest improvements to queries. For more information, see REST-API-Endpunkte für Releases und Releaseressourcen in the REST API documentation.

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.

Hinweis

The CodeQL CLI is currently not compatible with non-glibc Linux distributions such as (muslc-based) Alpine Linux.

1. Download the CodeQL CLI tar archive

Das CodeQL CLI-Downloadpaket ist ein tar-Archiv, das Tools, Skripts und verschiedene für CodeQL spezifische Dateien enthält. Wenn du keine GitHub Enterprise-Lizenz besitzt, stimmst du mit dem Herunterladen dieses Archivs den GitHub CodeQL-Geschäftsbedingungen zu.

Du solltest das CodeQL-Paket aus https://github.com/github/codeql-action/releases herunterladen. Das Paket enthält Folgendes:

  • CodeQL CLI product
  • Eine kompatible Version der Abfragen und Bibliotheken von https://github.com/github/codeql
  • Vorkompilierte Versionen aller im Paket enthaltenen Abfragen

Sie sollten immer das CodeQL-Bundle verwenden. Dies stellt Kompatibilität und weitaus bessere Leistung sicher, als ein separater Download von CodeQL CLI und Check-Out der CodeQL-Abfragen. Wenn du die CLI nur auf einer bestimmten Plattform ausführst, lade die entsprechende codeql-bundle-PLATFORM.tar.zst-Datei herunter. Alternativ kannst du codeql-bundle.tar.zst herunterladen. Diese Datei enthält die CLI für alle unterstützten Plattformen.

Es gibt auch tar.gz-Varianten des Bundles, die mit den tar.zst-Varianten identisch sind, außer dass, sie mit dem weniger effizienten Gzip-Algorithmus komprimiert sind. Der einzige Grund zum Herunterladen der tar.gz-Varianten ist, wenn Sie ältere Dekomprimierungstools verwenden, die den Zstandard-Komprimierungsalgorithmus nicht unterstützen.

2. Extract the CodeQL CLI tar archive

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

3. Launch codeql

Nach der Extraktion kannst du CodeQL-Prozesse ausführen, indem du die ausführbare codeql-Datei auf verschiedene Arten ausführst:

  • Indem du <extraction-root>/codeql/codeql ausführst, wobei <extraction-root> der Ordner ist, in dem du das CodeQL CLI-Paket extrahiert hast
  • Indem du <extraction-root>/codeql zu deinem PATH hinzufügst, damit du die ausführbare Datei einfach als codeql ausführen kannst

An diesem Punkt kannst du die CodeQL-Befehle ausführen. Eine vollständige Liste der CodeQL CLI-Befehle findest du unter CodeQL CLI commands manual.

Hinweis

If you add codeql to your PATH, it can be accessed by CodeQL for Visual Studio Code to compile and run queries. For more information about configuring VS Code to access the CodeQL CLI, see Configuring access to the CodeQL CLI.

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 Customizing analysis with CodeQL packs.

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.

Hinweis

The codeql resolve packs command is available in the CodeQL CLI versions 2.19.0 and later. For earlier versions of the CLI, you should run the codeql resolve qlpacks command, which produces similar, but less detailed output.

Next steps

To learn how to prepare your code to be analyzed by the CodeQL CLI, see Preparing your code for CodeQL analysis.