Installieren der CodeQL-CLI in deinem CI-System

Informationen zur Verwendung der CodeQL CLI für das code scanning

Du kannst die CodeQL CLI zum Ausführen von code scanning von Code verwenden, den du in einem CI-System (Continuous Integration) eines Drittanbieters verarbeitest. Code scanning ist ein Feature, das du zum Analysieren des Codes in einem GitHub-Repository verwendest, um Sicherheitsrisiken und Codefehler zu finden. Alle von der Analyse identifizierten Probleme werden in GitHub Enterprise Server angezeigt. Weitere Informationen findest du unter Informationen zu Codescans mit CodeQL. Die empfohlenen Spezifikationen (RAM, CPU-Kerne und Festplatte) zum Ausführen von CodeQL-Analysen findest du unter Empfohlene Hardwareressourcen zum Ausführen von CodeQL.

Die CodeQL CLI sind ein eigenständiges Produkt, mit dem du Code analysieren kannst. Ihr Hauptzweck besteht darin, eine Datenbankdarstellung einer Codebasis zu generieren: eine CodeQL-Datenbank. Wenn die Datenbank bereit ist, kannst du sie interaktiv abfragen oder eine Reihe von Abfragen ausführen, um Ergebnissets im SARIF-Format zu generieren und auf deine GitHub Enterprise Server-Instanz hochzuladen.

Alternativ kannst du GitHub Actions zum Ausführen von code scanning mit GitHub Enterprise Server verwenden. Informationen zur code scanning mit Aktionen findest du unter Konfigurieren der Codeüberprüfung für ein Repository. Eine Übersicht der Optionen für CI-Systeme findest du unter Informationen zur CodeQL-Codeüberprüfung in deinem CI-System.

Herunterladen der CodeQL CLI

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.

Einrichten der CodeQL CLI in deinem CI-System

Du musst den gesamten Inhalt des CodeQL CLI-Pakets für jeden CI-Server zur Verfügung stellen, auf dem CodeQL code scanning-Analysen 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. Updates für die CodeQL CLI werden alle zwei bis drei Wochen veröffentlicht. Beispiel:

$ wget https://HOSTNAME/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
$ tar -xvzf ./codeql-bundle-linux64.tar.gz

Nachdem du das CodeQL CLI-Paket extrahiert hast, kannst du die ausführbare codeql-Datei auf dem Server ausführen:

• 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

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 oben als <extraction root> angezeigt wird, 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.

Generieren eines Tokens zur Authentifizierung mit GitHub Enterprise Server

Jeder CI-Server benötigt eine GitHub App oder ein personal access token für die CodeQL CLI, damit die Ergebnisse auf GitHub Enterprise Server hochgeladen werden können. Du musst ein Zugriffstoken oder eine GitHub App mit der Schreibberechtigung security_events verwenden. Wenn CI-Server bereits ein Token mit diesem Bereich zum Auschecken von Repositorys aus GitHub Enterprise Server nutzen, kannst du möglicherweise zulassen, dass die CodeQL CLI dasselbe Token verwendet. Andernfalls solltest du ein neues Token mit der Schreibberechtigung security_events erstellen und es dem Geheimnisspeicher des CI-Systems hinzufügen. Weitere Informationen findest du unter Erstellen von GitHub-Apps und unter Verwalten deiner persönlichen Zugriffstoken.

Nächste Schritte

Du kannst nun das CI-System zum Ausführen von CodeQL-Analysen, dem Generieren von Ergebnissen und dem Hochladen in GitHub Enterprise Server konfigurieren, wo die Ergebnisse einem Branch oder Pull Request zugeordnet und als code scanning-Warnungen angezeigt werden. Ausführliche Informationen findest du unter Konfigurieren der CodeQL-CLI in deinem CI-System.