Erweiterte Einrichtung der CodeQL CLI

Du kannst deine CodeQL CLI-Einrichtung ändern, um ein lokales Auschecken des CodeQL-Repository für die Analyse zu verwenden, mehrere Versionen der CodeQL CLI einzurichten und Datenbanken zu analysieren, die du aus GitHub.com heruntergeladen hast.

Wer kann dieses Feature verwenden?

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.

In diesem Artikel

Informationen zur erweiterten Einrichtung CodeQL CLI

Wenn du beabsichtigst, CodeQL für mehr als nur die Codeüberprüfung zu verwenden, bevorzuge möglicherweise eine erweiterte Einrichtung von CodeQL CLI.

  • Wenn du zur Open Source-Freigabe von CodeQL-Abfragen beitragen möchtest, möchtest du möglicherweise direkt mit dem Quellcode CodeQL arbeiten.
  • Wenn du die neuesten CodeQL-Features verwenden möchtest, um Codeüberprüfungswarnungen für eine Codebasis zu generieren, aber auch eine andere Codebasis analysieren möchtest, die nur mit einer bestimmten Version der CodeQL CLI kompatibel ist, kannst du mehrere Versionen der herunterladen.

Weitere Informationen zur einfachsten Einrichtung der CodeQL CLI findest du unter Einrichten der CodeQL-CLI.

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.

1. Herunterladen der CodeQL CLI-ZIP-Datei

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

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. 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 Erstellen und Arbeiten 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 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/.

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

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

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. Du kannst die gewünschten Versionen von CodeQL CLI herunterladen und beide CLI-Archive im selben übergeordneten Verzeichnis entpacken.

Herunterladen von Datenbanken von GitHub.com

GitHub speichert CodeQL-Datenbanken für über 200.000 Repositorys auf GitHub.com, die Sie mithilfe der REST-API herunterladen können. Die Liste der Repositorys wird ständig erweitert und aktualisiert, damit die interessantesten Codebasen für die Sicherheitsforschung enthalten sind.

Du kannst Datenbanken auch aus GitHub.com analysieren, indem du CodeQL für die Erweiterung VS Code verwendest. Weitere Informationen findest du unter Ausführung von CodeQL-Abfragen.

Du kannst überprüfen, ob ein Repository über CodeQL-Datenbanken verfügt, die über den /repos/<owner>/<repo>/code-scanning/codeql/databases-Endpunkt heruntergeladen werden können. Wenn du beispielsweise mithilfe der GitHub CLI nach CodeQL-Datenbanken suchen möchtest, musst die Folgendes ausführen:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases

Dieser Befehl gibt Informationen zu allen CodeQL-Datenbanken zurück, die für ein Repository verfügbar sind, einschließlich der Sprache, in der die Datenbank vorliegt, und dem Zeitpunkt, an dem die Datenbank zuletzt aktualisiert wurde. Wenn keine CodeQL-Datenbanken verfügbar sind, ist die Antwort leer.

Wenn du überprüft hast, ob eine CodeQL-Datenbank für die gewünschte Sprache vorhanden ist, kannst du sie mit dem folgenden Befehl herunterladen:

gh api /repos/<owner>/<repo>/code-scanning/codeql/databases/<language> -H 'Accept: application/zip' > path/to/local/database.zip

Weitere Informationen findest du in der Dokumentation zum CodeQL-Datenbankendpunkt.

Bevor du eine Analyse mit der CodeQL CLI durchführst, musst du die Datenbanken entzippen.