Erste Schritte mit der CodeQL CLI

Erste Schritte mit 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.

Einrichten der CodeQL CLI

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.

Informationen zum Installieren von CodeQL CLI in einem CI-System, um Ergebnisse zu erstellen, die in GitHub als Codescanwarnungen angezeigt werden, findest du unter Installieren von 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.

Wenn du Linux, Windows oder macOS 10.14 (Mojave) oder eine frühere Version verwendest, lade einfach das ZIP-Archiv für die gewünschte Version herunter.

Wenn du die CLI für eine bestimmte Plattform benötigst, lade die entsprechende codeql-PLATFORM.zip-Datei herunter. Alternativ kannst du codeql.zip 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)

Wenn du macOS 10.15 (Catalina), macOS 11 (Big Sur) oder der kommenden Version 12 (Monterey) verwendest, musst du sicherstellen, dass dein Webbrowser nicht automatisch ZIP-Dateien 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ü Einstellungen... aus.
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“ oder „Monterey“ 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.

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

• (Optional) Du kannst einige CodeQL-Pakete 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.

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 4 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 Informationen zu CodeQL-Paketen.

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.