Skip to main content

GitHub AE ist derzeit begrenzt freigegeben.

Analysieren des Codes mit CodeQL-Abfragen

Du kannst Abfragen für eine CodeQL-Datenbank ausführen, die aus einer Codebasis extrahiert wurde.

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Informationen zum Analysieren von Datenbanken mit der CodeQL CLI

Zum Analysieren einer Codebasis führst du Abfragen in einer CodeQL-Datenbank aus, die aus dem Code extrahiert wurde. CodeQL-Analysen erzeugen Ergebnisse, die in GitHub AE hochgeladen werden können, um Codeüberprüfungswarnungen zu generieren.

Voraussetzungen

Bevor du eine Analyse startest, musst du Folgendes tun:

Die einfachste Methode zum Ausführen von codeql database analyze ist die Verwendung der Standardabfragen, die im CodeQL CLI-Paket enthalten sind.

Wird ausgeführt codeql database analyze

Beim Ausführen von database analyze geschieht Folgendes:

  1. Alle nicht lokal verfügbaren CodeQL-Pakete, auf die verwiesen wird, werden optional heruntergeladen.
  2. Es wird mindestens eine Abfragedatei ausgeführt, indem sie über eine CodeQL-Datenbank ausgeführt wird.
  3. Die Ergebnisse werden auf Grundlage bestimmter Abfragemetadaten interpretiert, sodass Warnungen an der richtigen Stelle im Quellcode angezeigt werden können.
  4. Die Ergebnisse aller Diagnose- und Zusammenfassungsabfragen werden an die Standardausgabe gesendet.

Du kannst eine Datenbank analysieren, indem du den folgenden Befehl ausführst:

codeql database analyze <database> --format=<format> --output=<output> <query-specifiers>...

Hinweis: Wenn du mehrere CodeQL-Datenbanken für einen einzelnen Commit analysierst, musst du für alle von diesem Befehl generierten Ergebnisse eine SARIF-Kategorie angeben. Wenn du die Ergebnisse auf GitHub AE hochlädst, wird diese Kategorie bei der code scanning verwendet, um die Ergebnisse separat für jede Sprache zu speichern. Wenn du dies vergisst, überschreibt jeder Upload die alten Ergebnisse.

codeql database analyze <database> --format=<format> \
    --sarif-category=<language-specifier> --output=<output> \
    <queries>

Dabei musst du <database>, --format und --output angeben. Je nachdem, welche Analyse du durchführen möchtest, kannst du zusätzliche Optionen angeben.

OptionErforderlichVerwendung
<database>Gib den Pfad des Verzeichnisses an, das die zu analysierende CodeQL-Datenbank enthält.
<packs,queries>Gib CodeQL-Pakete oder -Abfragen an, die ausgeführt werden sollen. Lass diesen Parameter aus, um die Standardabfragen zur code scanning auszuführen. Die anderen Abfragesammlungen, die im CodeQL CLI-Paket enthalten sind, findest du unter /<extraction-root>/qlpacks/codeql/<language>-queries/codeql-suites. Weitere Informationen zum Erstellen einer eigenen Abfragesammlung findest du unter Erstellen von CodeQL-Abfragesammlungen in der Dokumentation für die CodeQL CLI.
--formatGib das während der Analyse generierte Format für die Ergebnisdatei an. Es werden verschiedene Formate unterstützt, darunter CSV-, SARIF- und Graphformate. Für den Upload in GitHub sollte dies sein: sarif-latest. Weitere Informationen findest du unter SARIF-Unterstützung für die Codeüberprüfung.
--outputGib den Speicherort an, an dem du die SARIF-Ergebnisdatei speichern möchtest, einschließlich des gewünschten Dateinamens mit der .sarif-Erweiterung.
--sarif-categoryDiese Option kann optional bei der Analyse einer einzelnen Datenbank verwendet werden. Diese Option ist erforderlich, um die Sprache zu definieren, wenn du mehrere Datenbanken für einen einzelnen Commit in einem Repository analysierst.

Gib eine Kategorie an, die in die SARIF-Ergebnisdatei für diese Analyse aufgenommen werden soll. Eine Kategorie wird verwendet, um mehrere Analysen für dasselbe Tool und denselben Commit zu unterscheiden, die jedoch für verschiedene Sprachen oder Teile des Codes ausgeführt werden.
--sarif-add-query-helpVerwende diese Option, wenn du alle verfügbaren, mit Markdown gerenderten Abfragen, die in deiner Analyse verwendet werden, einschließen möchtest. Alle Abfragehilfen für benutzerdefinierte Abfragen, die in der SARIF enthalten sind, werden auf der Benutzeroberfläche für die Codeüberprüfung angezeigt, wenn die entsprechende Abfrage eine Warnung generiert. Weitere Informationen findest du unter Verwenden benutzerdefinierter Abfragen mit der CodeQL-CLI.
--threadsVerwende diese Option, wenn du mehrere Threads zum Ausführen von Abfragen verwenden möchtest. Standardwert: 1. Du kannst weitere Threads angeben, um die Abfrageausführung zu beschleunigen. Gib 0 an, um die Anzahl der Threads auf die Anzahl der logischen Prozessoren festzulegen.
--verboseVerwende diese Option, um weitere Informationen zum Analyseprozess und Diagnosedaten zum Prozess der Datenbankerstellung zu erhalten.

Aktualisieren von Datenbanken

Für Datenbanken, die von der CodeQL CLI (Version 2.3.3 oder früher) erstellt wurden, muss explizit ein Upgrade durchgeführt werden, bevor du eine Analyse mit einer neueren Version der CodeQL CLI ausführen kannst. Wenn dieser Schritt erforderlich ist, wird beim Ausführen von database analyze die Meldung angezeigt, dass für deine Datenbank ein Upgrade durchgeführt werden muss.

Für Datenbanken, die von der CodeQL CLI (Version 2.3.4 oder später) erstellt wurden, führt die CLI implizit alle erforderlichen Upgrades durch. Das explizite Ausführen des Upgradebefehls ist nicht erforderlich.

Ausführliche Informationen zu allen Optionen, die du beim Analysieren von Datenbanken verwenden kannst, findest du in der database analyze.

Einfaches Beispiel für die Analyse einer CodeQL-Datenbank

In diesem Beispiel wird eine CodeQL-Datenbank analysiert, die unter /codeql-dbs/example-repo gespeichert ist und die Ergebnisse als SARIF-Datei speichert: /temp/example-repo-js.sarif. Dabei wird --sarif-category verwendet, um zusätzliche Informationen in die SARIF-Datei einzuschließen, die die Ergebnisse als JavaScript kennzeichnen. Dies ist wichtig, wenn du über mehrere CodeQL-Datenbanken verfügst und einen einzelnen Commit in einem Repository analysieren möchtest.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Running queries.
> Compiling query plan for /codeql-home/codeql/qlpacks/codeql-javascript/AngularJS/DisablingSce.ql.
...
> Shutting down query evaluator.
> Interpreting results.

Beispiele für die Ausführung von Datenbankanalysen

Die folgenden Beispiele zeigen, wie du database analyze mit CodeQL-Paketen ausführen und einen lokalen Check-Out des CodeQL-Repositorys verwenden kannst. In diesen Beispielen wird davon ausgegangen, dass deine CodeQL-Datenbanken in einem Verzeichnis erstellt wurden, das gleichgeordnet zu deinen lokalen Kopien des CodeQL-Repositorys ist.

Ausführen einer einzelnen Abfrage

Um eine einzelne Abfrage über eine CodeQL-Datenbank für eine JavaScript-Codebasis auszuführen, kannst du den folgenden Befehl aus dem Verzeichnis verwenden, das deine Datenbank enthält:

codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Mit diesem Befehl wird eine einfache Abfrage ausgeführt, die potenzielle Fehler im Zusammenhang mit nicht verwendeten Variablen, Importen, Funktionen oder Klassen sucht. Dabei handelt es sich um eine der JavaScript-Abfragen, die im CodeQL-Repository enthalten sind. Du kannst mehrere Abfragen ausführen, indem du eine durch Leerzeichen getrennte Liste mit ähnlichen Pfaden angibst.

Die Analyse generiert eine CSV-Datei (js-results.csv) in einem neuen Verzeichnis (js-analysis).

Wenn du das CodeQL-Repository ausgecheckt hast, kannst du alternativ dieselben Abfragen ausführen, indem du den Pfad zur Abfrage direkt angibst:

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

Du kannst auch eigene benutzerdefinierten Abfragen mit dem database analyze-Befehl ausführen. Weitere Informationen zum Vorbereiten deiner Abfragen für die Verwendung mit der CodeQL CLI findest du unter Verwenden benutzerdefinierter Abfragen mit der CodeQL-CLI.

Ausführen aller Abfragen in einem Verzeichnis

Du kannst alle Abfragen in einem Verzeichnis ausführen, indem du den Verzeichnispfad angibst, anstatt alle Abfragedateien einzeln aufzulisten. Pfade werden rekursiv durchsucht, sodass alle Abfragen, die in Unterordnern enthalten sind, auch ausgeführt werden.

Wichtig

Du solltest beim Ausführen von database analyze vermeiden, den Stamm eines CodeQL-Basisabfragepakets anzugeben, da es möglicherweise spezielle Abfragen enthält, die nicht für die Verwendung mit dem Befehl konzipiert sind. Führe stattdessen das Abfragepaket aus, um die Standardabfragen des Pakets in die Analyse einzubeziehen, oder führe eine der Abfragesammlungen für die Codeüberprüfung aus.

Um beispielsweise alle Python-Abfragen auszuführen, die im Functions-Verzeichnis im codeql/python-queries-Abfragepaket enthalten sind, führe Folgendes aus:

codeql database analyze <python-database> codeql/python-queries:Functions --format=sarif-latest --output=python-analysis/python-results.sarif --download

Wenn du das CodeQL-Repository ausgecheckt hast, kannst du alternativ dieselben Abfragen ausführen, indem du den Pfad zum Verzeichnis direkt angibst:

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

Nach Abschluss der Analyse wird eine SARIF-Ergebnisdatei generiert. Durch die Angabe von --format=sarif-latest wird sichergestellt, dass die Ergebnisse gemäß der neuesten SARIF-Spezifikation formatiert werden, die von der CodeQL unterstützt wird.

Ausführen von Abfragesammlungen

Um eine Abfragesammlung in einer CodeQL-Datenbank für eine C- bzw. C++-Codebasis auszuführen, kannst du den folgenden Befehl aus dem Verzeichnis verwenden, das deine Datenbank enthält:

codeql database analyze <cpp-database> codeql/cpp-queries:codeql-suites/cpp-code-scanning.qls --format=sarifv2.1.0 --output=cpp-results.sarif --download

Dieser Befehl lädt das codeql/cpp-queries-CodeQL-Abfragepaket herunter, führt die Analyse aus und generiert eine Datei im SARIF-Format (Version 2.1.0), die von allen Versionen von GitHub unterstützt wird. Diese Datei kann durch Ausführen von codeql github upload-results oder der Codeüberprüfungs-API in GitHub hochgeladen werden. Weitere Informationen findest du unter Hochladen von CodeQL-Analyseergebnissen auf GitHub oder Codeüberprüfung.

CodeQL-Abfragesammlungen sind .qls-Dateien, die Anweisungen verwenden, um Abfragen auf der Grundlage bestimmter Metadateneigenschaften auszuwählen. Die CodeQL-Standardpakete verfügen über Metadaten, die den Speicherort der Abfragesammlungen angeben, die von der Codeüberprüfung verwendet werden. Daher weiß die CodeQL CLI automatisch, wo diese Sammlungsdateien zu finden sind, und du musst nicht den vollständigen Pfad in der Befehlszeile angeben. Weitere Informationen findest du unter Erstellen von CodeQL-Abfragesammlungen.

Informationen zum Erstellen von benutzerdefinierten Abfragesammlungen findest du unter Erstellen von CodeQL-Abfragesammlungen.

Ergebnisse

Du kannst Analyseergebnisse in verschiedenen Formaten speichern, darunter SARIF und CSV.

Das SARIF-Format soll die Ausgabe zahlreicher statischer Analysetools wiedergeben. Weitere Informationen findest du unter SARIF-Ausgabe der CodeQL CLI.

Weitere Informationen dazu, wie die Ergebnisse im CSV-Format aussehen, findest du unter CodeQL CLI CSV-Ausgabe.

Ergebnisdateien können mit deiner eigenen Codeüberprüfungs- oder Debuginfrastruktur integriert werden. Beispielsweise kann die SARIF-Dateiausgabe verwendet werden, um Warnungen an der richtigen Stelle in deinem Quellcode hervorzuheben, indem ein SARIF-Viewer-Plug-In für deine IDE verwendet wird.

Anzeigen von Protokoll- und Diagnoseinformationen

Wenn du eine CodeQL-Datenbank mithilfe einer code scanning-Abfragesuite analysierst, generiert die CLI detaillierte Informationen zu Warnungen und meldet zusätzlich Diagnosedaten aus dem Schritt für die Datenbankgenerierung und Zusammenfassungsmetriken. Wenn du SARIF-Ausgaben generierst, sind die zusätzlichen Daten auch in der SARIF-Datei enthalten. Für Repositorys mit wenigen Warnungen sind diese Informationen möglicherweise für dich hilfreich, um festzustellen, ob es wirklich wenige Probleme im Code gibt, oder wenn Fehler beim Generieren der CodeQL-Datenbank aufgetreten sind. Wenn du eine ausführlichere codeql database analyze-Ausgabe wünschst, verwende die Option --verbose.

Weitere Informationen zum Typ der verfügbaren Diagnoseinformationen findest du unter Anzeigen von Codescanprotokollen.

Du kannst dich entscheiden, Diagnoseinformationen in GitHub AE zu exportieren und hochzuladen, auch wenn eine CodeQL-Analyse fehlschlägt. Weitere Informationen findest du unter Hochladen von CodeQL-Analyseergebnissen auf GitHub.

Nächste Schritte