Einrichten der CodeQL-CLI

Um mit CodeQL CLI zu beginnen, musst du die CLI herunterladen und so einrichten, dass sie auf die Tools und Bibliotheken zugreifen kann, die zum Erstellen und Analysieren von Datenbanken erforderlich sind.

Wer kann dieses Feature verwenden?

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

In diesem Artikel

Einrichten der CodeQL CLI

Um CodeQL Befehle auszuführen, müssen Sie die CodeQL CLI einrichten, damit sie auf die Tools, Abfragen und Bibliotheken zugreifen kann, die zum Erstellen und Analysieren von Datenbanken erforderlich sind.

CodeQL CLI unterstützt eine Reihe von Anwendungsfällen und Verzeichnisstrukturen. In diesem Artikel wird ein einfaches Setup erläutert, das für die meisten Benutzer und Umgebungen funktioniert.

Wenn Sie beabsichtigen, die CodeQL CLI für Sicherheitsforschungen zu verwenden, Abfragen zu testen oder Beiträge zu leisten, benötigen Sie möglicherweise eine erweiterte Konfiguration. Weitere Informationen finden Sie unter Erweiterte Einrichtung der CodeQL CLI.

Bevor Sie anfangen

Wenn du macOS auf Apple Silicon (z. B. Apple M1) verwendest, stelle sicher, dass die Entwicklertools für die Xcode-Befehlszeile und Rosetta 2 installiert sind.

Hinweis

Die CodeQL CLI ist aktuell nicht mit Nicht-Glibc-Linux-Distributionen wie z. B. dem (muslc-basierten) Alpine Linux kompatibel.

1. Laden Sie das CodeQL CLI tar-Archiv herunter

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 http://github.com/github/codeql-action/releases herunterladen. Das Paket enthält Folgendes:

  • CodeQL CLI product
  • Eine kompatible Version der Abfragen und Bibliotheken von http://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. Extrahieren Sie das CodeQL CLI tar-Archiv

Extrahieren Sie dasCodeQL CLI tar-Archiv in ein Verzeichnis Ihrer Wahl.

Optional: Stellen Sie CodeQL CLI in Ihrem CI-System zur Verfügung.

Wenn Sie vorhaben, eine CodeQL code scanning Analyse in einem CI-System durchzuführen, stellen Sie sicher, dass der vollständige Inhalt des CodeQL CLI Pakets für jeden CI-Server verfügbar ist, der die Analyse durchführen wird.

Beispielsweise können Sie folgende Aktionen ausführen:

  • Kopieren Sie das Bündel von einem zentralen internen Speicherort, und extrahieren Sie es auf jedem Server oder
  • Verwenden Sie die REST-API, um das Bundle direkt von GitHub herunterzuladen, um sicherzustellen, dass Sie die neuesten Verbesserungen für Abfragen erhalten. Weitere Informationen finden Sie unter REST-API-Endpunkte für Releases und Releaseressourcen.

3. Starten von 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 Leitfaden zu CodeQL-CLI-Befehlen.

Hinweis

Wenn du codeql zu deinem PATH hinzufügst, kannst du mit CodeQL für Visual Studio Code darauf zugreifen, um Abfragen zu kompilieren und auszuführen. Weitere Informationen zur Konfiguration von VS Code für den Zugriff auf CodeQL CLI findest du unter Konfigurieren des Zugriffs auf die CodeQL CLI.

Testen der CodeQL CLI-Konfiguration

Nachdem du das CodeQL CLI-Paket extrahiert hast, kannst du den folgenden Befehl ausführen, um zu überprüfen, ob die CLI ordnungsgemäß zum Erstellen und Analysieren von Datenbanken konfiguriert ist:

  •         `codeql resolve packs` wenn `/<extraction root>/codeql` auf der `PATH` steht.

  •         `/<extraction root>/codeql/codeql resolve packs` sonst.

Wenn du erfolgreich bist, solltest du eine Ausgabe ähnlich dem unten stehenden Auszug sehen:

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

Die Ergebnisse wurden aus Gründen der Übersichtlichkeit verkürzt dargestellt. Die tatsächlichen Ergebnisse werden länger und detaillierter sein.

Du solltest überprüfen, ob die Ausgabe die erwarteten Sprachen enthält und ob der Verzeichnisspeicherort der qlpack-Dateien korrekt ist. Der Speicherort sollte sich innerhalb des extrahierten CodeQL CLI-Pakets befinden, das in früheren Beispielen als <extraction root> angezeigt wurde. Wenn die CodeQL CLI die qlpacks für die erwarteten Sprachen nicht finden kann, solltest du überprüfen, ob du das CodeQL-Paket und nicht die eigenständige Kopie der CodeQL CLI heruntergeladen hast.

Du kannst auch codeql resolve languages ausführen, um die für die Datenbankerstellung verfügbaren Sprachen anzuzeigen. Dadurch werden die Sprachen aufgelistet, die standardmäßig in deinem CodeQL CLI-Paket unterstützt werden.

Optional kannst du einige CodeQL-Pakete mit vorkompilierten Abfragen herunterladen, die du ausführen möchtest. Weitere Informationen finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.

Der codeql resolve packs-Befehl ist nützlich, um Probleme zu diagnostizieren, wenn CodeQL CLI nicht in der Lage ist, Abfrage-Packs zu finden, von denen du erwartest, dass sie für die Analyse verfügbar sind.

Hinweis

Der codeql resolve packs-Befehl ist in den CodeQL CLI Versionen 2.19.0 und später verfügbar. Für frühere Versionen des CLI solltest du den codeql resolve qlpacks-Befehl ausführen, der eine ähnliche, aber weniger detaillierte Ausgabe liefert.

Nächste Schritte

Wie du deinen Code für die Analyse durch CodeQL CLI vorbereitest, erfährst du unter Vorbereiten des Codes für die CodeQL-Analyse.