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 Cloud 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 ist ein eigenständiges Befehlszeilentool, 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 GitHub.com hochzuladen.

Alternativ kannst du GitHub Actions zum Ausführen von code scanning mit GitHub Enterprise Cloud verwenden. Weitere Informationen zum code scanning mithilfe von Aktionen findest du unter Konfigurieren des Standardsetups für das Codescanning und Konfigurieren des erweiterten Setups für das Codescanning. Eine Übersicht der Optionen für CI-Systeme findest du unter Informationen zur CodeQL-Codeüberprüfung in deinem CI-System.

Hinweise:

Die CodeQL CLI kann in öffentlichen Repositorys, die auf GitHub.com verwaltet werden, kostenlos verwendet werden und steht in privaten Repositorys, die Kunden mit einer Lizenz für Advanced Security gehören, zur Verfügung. Weitere Informationen findest du unter GitHub Enterprise Cloud CodeQL-Geschäftsbedingungen und CodeQL-CLI.
Die CodeQL CLI ist derzeit nicht mit Nicht-Glibc-Linux-Distributionen wie (musl-basiertem) Alpine Linux kompatibel.

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.

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

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 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. Updates für die CodeQL CLI werden alle zwei bis drei Wochen veröffentlicht.

Zuerst musst du das CodeQL CLI-Bundle extrahieren. Anschließend kannst du die ausführbare Datei codeql auf dem Server auf zwei Arten 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

Wenn du die CodeQL CLI zum Analysieren von in Python geschriebenem Code verwendest, musst du sicherstellen, dass auf deinem CI-System Python 3 installiert ist.

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.

Hier siehst du einen Auszug 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 Cloud

Jeder CI-Server benötigt eine GitHub App oder ein personal access token für die CodeQL CLI, damit die Ergebnisse auf GitHub Enterprise Cloud 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 Cloud 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 Cloud 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.