Skip to main content

Installieren der CodeQL-CLI in deinem CI-System

Du kannst die CodeQL CLI installieren und zum Ausführen des CodeQL-code scanning in einem Continuous Integration-Drittanbietersystem verwenden.

Code scanning ist für organisationseigene Repositorys in GitHub Enterprise Server verfügbar. Dieses Feature erfordert eine Lizenz für GitHub Advanced Security. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Hinweis: Dein Websiteadministrator muss code scanning für your GitHub Enterprise Server instance aktivieren, damit du dieses Feature verwenden kannst. Weitere Informationen findest du unter Konfigurieren von code scanning für deine Appliance.

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 Codierungsfehler zu finden. Alle von der Analyse identifizierten Probleme werden in GitHub Enterprise Server angezeigt. Weitere Informationen findest du unter Informationen zu code scanning mit CodeQL. Empfohlene Spezifikationen (RAM, CPU-Kerne und Datenträger) zum Ausführen der CodeQL-Analyse 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 your GitHub Enterprise Server instance hochzuladen.

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

Hinweise:

  • Die CodeQL CLI ist für Kunden mit einer Lizenz für Advanced Security verfügbar.

  • 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
Für GitHub Enterprise Server 3.5 wird die CodeQL CLI-Version 2.8.5 empfohlen.

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 Kompilieren von GitHub Apps und Erstellen eines personal access token.

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. Weitere Informationen findest du unter Konfigurieren der CodeQL CLI in deinem CI-System.