Einrichten der CodeQL-CLI

Einrichten der CodeQL CLI

Zum Ausführen von CodeQL-Befehlen musst du die CLI so einrichten, dass sie auf die Tools, Abfragen und Bibliotheken zugreifen kann, die zum Erstellen und Analysieren von Datenbanken erforderlich sind.

CodeQL CLI kann so eingerichtet werden, dass viele verschiedene Anwendungsfälle und Verzeichnisstrukturen unterstützt werden. Um schnell beginnen zu können, wird empfohlen, ein relativ einfaches Setup zu verwenden, wie in den folgenden Schritten beschrieben.

Wenn du beabsichtigst, die CodeQL CLI für Sicherheitsforschung zu verwenden oder Abfragen zu testen oder mitzuwirken, möchtest du möglicherweise eine erweiterte Einrichtung von CodeQL CLI. Weitere Informationen findest du unter Erweiterte Einrichtung der CodeQL CLI.

Wenn du CodeQL CLI in deinem CI-System einrichtest, musst du den gesamten Inhalt des CodeQL CLI-Pakets für jeden CI-Server zur Verfügung stellen, auf dem code scanning-Analysen von CodeQL ausgeführt werden sollen. Du kannst beispielsweise jeden Server so konfigurieren, dass das Paket von einem zentralen, internen Speicherort kopiert und extrahiert wird. Alternativ kannst du die REST-API verwenden, um das Paket direkt aus GitHub abzurufen. Dadurch wird sichergestellt, dass du von den neuesten Verbesserungen für Abfragen profitierst. Weitere Informationen finden Sie in der REST-API-Dokumentation unter REST-API-Endpunkte für Releases und Releaseressourcen.

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.

1. Herunterladen des CodeQL CLI-ZIP-Pakets

Das CodeQL CLI-Downloadpaket ist ein ZIP-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

Du solltest immer das CodeQL-Paket verwenden, da dadurch die Kompatibilität gewährleistet und auch eine wesentlich bessere Leistung erzielt wird als bei einem separaten Download der CodeQL CLI und dem Auschecken der CodeQL-Abfragen. Wenn du die CLI nur auf einer bestimmten Plattform ausführst, lade die entsprechende codeql-bundle-PLATFORM.tar.gz-Datei herunter. Alternativ kannst du codeql-bundle.tar.gz herunterladen. Diese Datei enthält die CLI für alle unterstützten Plattformen.

Herunterladen von Informationen zu Benutzer*innen von macOS Catalina (oder höher)

Ab der macOS-Version 10.15 („Catalina“) musst du sicherstellen, dass dein Webbrowser ZIP-Dateien nicht automatisch extrahiert. Wenn du Safari verwendest, führe die folgenden Schritte aus, bevor du das CodeQL CLI-ZIP-Archiv herunterlädst:

1. Öffne Safari.
2. Wähle im Safari-Menü Präferenzen... oder Einstellungen... (ab Version 13 „Ventura“).
3. Klicke auf die Registerkarte Allgemein.
4. Stelle sicher, dass das Kontrollkästchen Sichere Dateien nach dem Herunterladen öffnen deaktiviert ist.

2. Extrahieren des ZIP-Archivs

Extrahiere für Linux-, Windows- und macOS-Benutzer*innen (Version 10.14 „Mojave“ und früher) einfach das ZIP-Archiv.

Extrahieren von Informationen zu Benutzer*innen von macOS Catalina (oder höher)

Benutzer*innen von macOS „Catalina“, „Big Sur“, „Monterey“ oder „Ventura“ sollten die folgenden Befehle im Terminal ausführen, wobei ${extraction-root} der Pfad zu dem Verzeichnis ist, in den du das CodeQL CLI-ZIP-Archiv extrahierst:

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

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.

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 qlpacks, wenn /<extraction-root>/codeql sich auf dem PATH befindet.
• Andernfalls /<extraction-root>/codeql/codeql resolve qlpacks.

Die Ausgabe sollte etwa folgendem Beispiel entsprechen.

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

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) du kannst einige CodeQL-Pakete herunterladen, die vorkompilierte Abfragen enthalten, die du ausführen möchtest. Weitere Informationen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Nächste Schritte

Informationen zum Vorbereiten des Codes für die Analyse durch CodeQL CLI findest du unter Vorbereiten des Codes für die CodeQL-Analyse.