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. Laden Sie das CodeQL CLI tar-Archiv herunter
Das CodeQL CLI-Downloadpaket ist ein tar-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
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.
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 Sie das CodeQL CLI tar-Archiv
Extrahieren Sie das tar-Archiv in das Verzeichnis, das Sie in Schritt 2 erstellt haben.
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
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 deinemPATH
hinzufügst, damit du die ausführbare Datei einfach alscodeql
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.