Skip to main content

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.

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

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 Linux, Windows oder macOS 10.14 (Mojave) oder eine frühere Version verwendest, führe einfach die folgenden Schritte aus. Für macOS 10.15 (Catalina) oder höher gibt es zusätzliche Hinweise für einige der Schritte. 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 derzeit nicht mit Nicht-Glibc-Linux-Distributionen wie (muslc-basiertem) Alpine Linux kompatibel.

Weitere Informationen zur Installation der CodeQL CLI in einem CI-System (Continuous Integration) zur Erzeugung von Ergebnissen, die in GitHub als Codescanwarnungen angezeigt werden sollen, findest du unter Installieren der CodeQL-CLI in deinem CI-System.

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.

Hinweis: Die CodeQL-Paketverwaltungsfunktionen, einschließlich CodeQL-Paketen, befinden sich derzeit in der Betaphase und können noch geändert werden.

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.

Hinweis: Wenn du codeql zu PATH hinzufügst, kann CodeQL darauf zugreifen, damit Visual Studio Code Abfragen kompilieren und ausführen kann. Weitere Informationen zum Konfigurieren von VS Code für den Zugriff auf CodeQL CLI findest du unter Einrichten von CodeQL in Visual Studio Code.

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.

Ausschnitt aus einer erfolgreichen Ausgabe:

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, es sei denn, du verwendest ein Check-Out von github/codeql. 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 Anpassen der Analyse mit CodeQL-Paketen herunterladen, die vorkompilierte Abfragen enthalten, die du ausführen möchtest. Führe dazu codeql pack download <pack-name> [...pack-name] aus, wobei pack-name der Name des Pakets ist, das du herunterladen möchtest. Die Kernabfragepakete sind ein guter Ausgangspunkt. Sie lauten wie folgt:

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

Alternativ kannst du Abfragepakete während der Analyse herunterladen, indem du das --download-Flag des codeql database analyze-Befehls verwendest.

Generieren eines Tokens zur Authentifizierung mit GitHub Enterprise Cloud

Wenn du deine Ergebnisse schließlich auf GitHub Enterprise Cloud hochladen möchtest, um diese als Codescanwarnungen anzuzeigen, musst du ein personal access token mit der security_events-Schreibberechtigung generieren. Weitere Informationen findest du unter Verwalten deiner persönlichen Zugriffstoken.

Wenn du die CodeQL CLI in einem CI-System (Continuous Integration) eines Drittanbieters installiert hast, um Ergebnisse zu erstellen, die in GitHub als Codescanwarnungen angezeigt werden, kannst du GitHub App oder ein personal access token verwenden, um die Ergebnisse aufGitHub Enterprise Cloud hochzuladen. Weitere Informationen findest du unter Installieren der CodeQL-CLI in deinem CI-System.

Direktes Auschecken des CodeQL-Quellcodes

Einige Benutzer*innen bevorzugen die direkte Arbeit mit CodeQL-Abfragequellen, um an den freigegebenen Open-Source-Abfragen zu arbeiten oder daran mitzuwirken. Dazu werden die folgenden Schritte empfohlen. Beachte, dass die folgenden Anweisungen eine etwas kompliziertere Alternative zum Arbeiten mit CodeQL-Paketen sind, wie oben erläutert.

1. Herunterladen der CodeQL CLI-ZIP-Datei

Führe Schritt 1 aus dem vorherigen Abschnitt aus.

2. Erstellen eines neuen CodeQL-Verzeichnisses

Erstelle ein neues Verzeichnis, in dem du die CLI und alle Abfragen und Bibliotheken platzieren kannst, die du verwenden möchtest. Beispiel: $HOME/codeql-home.

Die integrierten Suchvorgänge der CLI suchen automatisch in allen gleichgeordneten Verzeichnissen nach den Dateien, die bei der Datenbankerstellung und -analyse verwendet werden. Wenn diese Komponenten in einem eigenen Verzeichnis gespeichert werden, wird verhindert, dass die CLI nicht verwandte gleichgeordnete Verzeichnisse durchsucht. Gleichzeitig wird sichergestellt, dass alle Dateien verfügbar sind, ohne weitere Optionen in der Befehlszeile anzugeben.

3. Abrufen einer lokalen Kopie der CodeQL-Abfragen

Das CodeQL-Repository enthält die Abfragen und Bibliotheken, die für die CodeQL-Analyse aller unterstützten Sprachen erforderlich sind. Klone eine Kopie dieses Repositorys in codeql-home.

Der Stamm des geklonten Repositorys trägt standardmäßig den Namen codeql. Benenne diesen Ordner in codeql-repo um, um Konflikte mit der CodeQL CLI zu vermeiden, die du in Schritt 1 extrahieren wirst. Wenn du Git in der Befehlszeile verwendest, kannst du das Repository in einem einzigen Schritt klonen und umbenennen, indem du git clone git@github.com:github/codeql.git codeql-repo im codeql-home-Ordner ausführst.

Innerhalb dieses Repositorys sind die Abfragen und Bibliotheken in CodeQL-Paketen organisiert. Zusammen mit den Abfragen selbst enthalten CodeQL-Pakete wichtige Metadaten, die CodeQL CLI darüber informieren, wie die Abfragedateien verarbeitet werden sollen. Weitere Informationen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Hinweis: Es gibt verschiedene Versionen der CodeQL-Abfragen für verschiedene Benutzer*innen. Überprüfe die richtige Version für deinen Anwendungsfall:

  • Für die Abfragen, die mit dem neuesten CodeQL CLI-Release verwendet werden sollen, sieh dir den Branch mit dem Tag codeql-cli/latest an. Du solltest diesen Branch für Datenbanken verwenden, die du mit CodeQL CLI erstellt hast, aus der Codeüberprüfung für GitHub abgerufen oder kürzlich von GitHub.com heruntergeladen hast.
  • Die aktuellsten CodeQL-Abfragen findest du im main-Branch. Dieser Branch stellt die neueste Version der Analyse von CodeQL dar.

4. Extrahieren des ZIP-Archivs

Extrahiere für Linux-, Windows- und macOS-Benutzer*innen (macOS 10.14 „Mojave“ und früher) einfach das ZIP-Archiv in das Verzeichnis, das du in Schritt 2 erstellt hast.

Wenn der Pfad zu deiner Kopie des CodeQL-Repositorys beispielsweise $HOME/codeql-home/codeql-repo lautet, extrahiere die CLI in $HOME/codeql-home/.

5. Starten von codeql

Weitere Informationen findest du in Schritt 3 aus dem vorherigen Abschnitt.

6. Überprüfen deines CodeQL CLI-Setups

CodeQL CLI verfügt über Unterbefehle, die du ausführen kannst, um zu überprüfen, ob alles richtig eingerichtet ist, um Datenbanken zu erstellen und zu analysieren:

  • Führe codeql resolve languages aus, um anzuzeigen, welche Sprachen für die Datenbankerstellung verfügbar sind. Dadurch werden die Sprachen aufgelistet, die standardmäßig in deinem CodeQL CLI-Paket unterstützt werden.
  • Führe codeql resolve qlpacks aus, um anzuzeigen, welche CodeQL-Pakete die CLI finden kann. Dadurch werden die Namen aller CodeQL-Pakete angezeigt, die direkt für die CodeQL CLI verfügbar sind. Dies sollte Folgendes umfassen:
  • Abfragepakete für jede unterstützte Sprache, z. B codeql/{language}-queries. Diese Pakete enthalten die Standardabfragen, die für jede Analyse ausgeführt werden.
  • Bibliothekspakete für jede unterstützte Sprache, z. B codeql/{language}-all. Diese Pakete enthalten Abfragebibliotheken, z. B. Ablaufsteuerungs- und Datenflussbibliotheken, die für Abfrageautoren nützlich sein können.
  • Beispielpakete für jede unterstützte Sprache, z. B codeql/{language}-examples. Diese Pakete enthalten nützliche Codeschnipsel von CodeQL, die Abfrageautoren möglicherweise nützlich finden.
  • Legacypakete, die sicherstellen, dass benutzerdefinierte Abfragen und Bibliotheken, die mit älteren Produkten erstellt wurden, mit deiner Version von CodeQL kompatibel sind

Verwenden von zwei Versionen von CodeQL CLI

Wenn du die neuesten CodeQL-Features verwenden möchtest, um Abfragen oder CodeQL-Tests auszuführen, aber auch Datenbanken vorbereiten möchtest, die mit einer bestimmten Version von CodeQL-Codeüberprüfungen auf GitHub Enterprise Server kompatibel sind, musst du möglicherweise zwei Versionen der CLI installieren. Die empfohlene Verzeichniseinrichtung hängt davon ab, welche Versionen du installieren möchtest:

  • Wenn beide Versionen 2.0.2 (oder höher) sind, kannst du beide CLI-Archive im selben übergeordneten Verzeichnis entpacken.
  • Wenn mindestens eine der Versionen 2.0.1 (oder älter) ist, können sich die entpackten CLI-Archive nicht im selben übergeordneten Verzeichnis befinden, aber sie können dasselbe übergeordnete Verzeichnis der zweiten Ebene verwenden. Wenn du beispielsweise Version 2.0.2 in $HOME/codeql-home/codeql-cli entpackst, sollte die ältere Version in $HOME/codeql-older-version/old-codeql-cli entpackt werden. Hier ist das allgemeine übergeordnete Verzeichnis der zweiten Ebene das $HOME-Verzeichnis.