Hinweis: Dieser Artikel wurde im Januar 2023 von der CodeQL-Dokumentationswebsite migriert.
Informationen zum Analysieren von Datenbanken mit der CodeQL CLI
Hinweis: In diesem Artikel werden die Features beschrieben, die im CodeQL CLI 2.8.5-Bundle im ursprünglichen Release von GitHub Enterprise Server 3.5 enthalten sind.
Wenn dein Websiteadministrator deine CodeQL CLI auf eine neuere Version aktualisiert hat, findest du in der GitHub Enterprise Cloud-Version dieses Artikels Informationen über die neuesten Features.
Führe Abfragen für eine aus dem Code extrahierte CodeQL-Datenbank aus, um eine Codebasis zu analysieren.
CodeQL-Analysen erzeugen interpretierte Ergebnisse, die als Warnungen oder Pfade im Quellcode angezeigt werden können.
Informationen zum Schreiben von Abfragen, die mit database analyze
ausgeführt werden sollen, findest du unter Verwenden von benutzerdefinierten Abfragen mit der CodeQL CLI.
Andere Befehle, bei denen Abfragen ausgeführt werden
Abfragen, die mit database analyze
ausgeführt werden, weisen strenge Metadatenanforderungen auf. Du kannst Abfragen auch mit den folgenden Unterbefehlen auf plumbing-Ebene ausführen:
-
database run-queries: Gibt nicht interpretierte Ergebnisse in einem binären Zwischenformat namens BQRS aus
-
query run: Gibt die BQRS-Dateien oder Ergebnistabellen direkt in der Befehlszeile aus. Das Anzeigen von Ergebnissen direkt in der Befehlszeile kann für die iterative Abfrageentwicklung mithilfe der CLI nützlich sein.
Abfragen, die mit diesen Befehlen ausgeführt werden, haben nicht die gleichen Metadatenanforderungen.
Um jedoch für Menschen lesbare Daten zu speichern, musst du jede BQRS-Ergebnisdatei mithilfe des plumbing-Unterbefehls bqrs decode verarbeiten. Daher ist es in den meisten Anwendungsfällen am einfachsten, database analyze
zu verwenden, um interpretierte Ergebnisse direkt zu generieren.
Bevor du eine Analyse startest, musst du Folgendes tun:
- Richte die CodeQL CLI ein, um Befehle lokal auszuführen.
- Erstelle eine CodeQL-Datenbank für den zu analysierenden Quellcode.
codeql database analyze
lässt sich am einfachsten mithilfe von CodeQL-Paketen ausführen. Du kannst den Befehl auch mithilfe von Abfragen aus einem lokalen Check-Out des CodeQL-Repositorys ausführen, was du tun solltest, wenn du die Basisabfragen von CodeQL anpassen möchtest.
Wird ausgeführt codeql database analyze
Beim Ausführen von database analyze
geschieht Folgendes:
- Alle nicht lokal verfügbaren CodeQL-Pakete, auf die verwiesen wird, werden optional heruntergeladen.
- Es wird mindestens eine Abfragedatei ausgeführt, indem sie über eine CodeQL-Datenbank ausgeführt wird.
- Die Ergebnisse werden auf Grundlage bestimmter Abfragemetadaten interpretiert, sodass Warnungen an der richtigen Stelle im Quellcode angezeigt werden können.
- 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>...
Dabei musst du Folgendes festlegen:
<database>
: Der Pfad zur CodeQL-Datenbank, die du analysieren möchtest--format
: Das Format der während der Analyse generierten Ergebnisdatei. Es werden verschiedene Formate unterstützt, darunter CSV-, SARIF- und Graphformate. Weitere Informationen zu CSV und SARIF findest du unter Ergebnisse. Informationen dazu, welche anderen Ergebnisformate unterstützt werden, findest du in der database analyze.--output
: Der Ausgabepfad der während der Analyse generierten Ergebnisdatei
Du kannst auch Folgendes angeben:
-
<query-specifiers>...
: Eine durch Leerzeichen getrennte Liste von Abfragen, die für deine Datenbank ausgeführt werden sollen. Dies ist eine Liste von Argumenten, wobei jedes Argument Folgendes sein kann:- Ein Pfad zu einer Abfragedatei
- Ein Pfad zu einem Verzeichnis, das Abfragedateien enthält
- Ein Pfad zu einer Abfragesammlungsdatei
- Der Name eines CodeQL-Abfragepakets
- Mit einem optionalen Versionsbereich
- Mit einem optionalen Pfad zu einer Abfrage, einem Verzeichnis oder einer Abfragesammlung innerhalb des Pakets
Wenn keine Angabe erfolgt, wird die Standardabfragesammlung für die Sprache der analysierten Datenbank verwendet. Die vollständige Syntax von Abfragespezifizierern findest du unter Angeben, welche Abfragen in einem CodeQL-Paket ausgeführt werden sollen.
-
--sarif-category
: Eine identifizierende Kategorie für die Ergebnisse. Sie wird verwendet, wenn du mehrere Ergebnisse für einen Commit hochladen möchtest. Das ist beispielsweise der Fall, wenn dugithub upload-results
verwendest, um Ergebnisse für mehrere Sprachen an die Codeüberprüfungs-API für GitHub zu senden. Weitere Informationen zu diesem Anwendungsfall findest du unter Konfigurieren der CodeQL CLI in deinem CI-System. -
--sarif-add-query-help
: (unterstützt ab Version 2.7.1) Der Befehl fügt jede in Markdown geschriebene benutzerdefinierte Abfragehilfe zu den von der Analyse erzeugten SARIF-Dateien (Version 2.1.0 oder höher) hinzu. In.qhelp
-Dateien gespeicherte Abfragehilfen müssen vor dem Ausführen der Analyse in.md
-Dateien konvertiert werden. Weitere Informationen findest du unter Einschließen von Abfragehilfen für benutzerdefinierte CodeQL-Abfragen in SARIF-Dateien. -
--download
: Ein boolesches Flag, mit dem die CLI nicht lokal verfügbare CodeQL-Pakete herunterladen kann, auf die verwiesen wird. Wenn dieses Flag fehlt und ein CodeQL-Paket nicht lokal verfügbar ist, schlägt der Befehl fehl.
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.
Angeben, welche Abfragen in einem CodeQL-Paket ausgeführt werden sollen
Abfragespezifizierer werden von codeql database analyze
und anderen Befehlen verwendet, die für mehrere Abfragen ausgeführt werden.
Die vollständige Form eines Abfragespezifizierers lautet scope/name@range:path
, wobei Folgendes gilt:
-
scope/name
ist der qualifizierte Name eines CodeQL-Pakets. -
range
ist ein SemVer-Bereich. -
path
ist ein Dateisystempfad zu einer einzelnen Abfrage, einem Verzeichnis mit Abfragen oder einer Abfragesammlungsdatei.
Wenn du einen scope/name
angibst, sind range
und path
optional. Wenn du range
nicht angibst, wird die neueste Version des angegebenen Pakets verwendet. Wenn du path
nicht angibst, wird die Standardabfragesammlung des angegebenen Pakets verwendet.
Der path
kann Folgendes sein: eine .ql
-Abfragedatei, ein Verzeichnis mit einer oder mehreren Abfragen oder eine .qls
-Abfragesammlungsdatei. Wenn du den Namen eines Pakets nicht angibst, musst du einen path
angeben, der relativ zum Arbeitsverzeichnis des aktuellen Prozesses interpretiert wird. Globmuster werden nicht unterstützt.
Wenn du sowohl einen scope/name
als auch einen path
angibst, kann der path
nicht absolut sein. Er wird als relativ zum Stamm des CodeQL-Pakets betrachtet.
Beispielabfragespezifizierer
-
codeql/python-queries
: Alle Abfragen in der Standardabfragesammlung der neuesten Version descodeql/python-queries
-Pakets -
codeql/python-queries@1.2.3
: Alle Abfragen in der Standardabfragesammlung von Version1.2.3
descodeql/python-queries
-Pakets -
codeql/python-queries@~1.2.3
: Alle Abfragen in der Standardabfragesammlung der neuesten Version descodeql/python-queries
-Pakets (neuer als1.2.3
und älter als1.3.0
) -
codeql/python-queries:Functions
: Alle Abfragen imFunctions
-Verzeichnis der neuesten Version descodeql/python-queries
-Pakets -
codeql/python-queries@1.2.3:Functions
: Alle Abfragen imFunctions
-Verzeichnis der Version 1.2.3 descodeql/python-queries
-Pakets -
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls
: Alle Abfragen imcodeql-suites/python-code-scanning.qls
-Verzeichnis der Version 1.2.3 descodeql/python-queries
-Pakets -
suites/my-suite.qls
: Alle Abfragen in dersuites/my-suite.qls
-Datei relativ zum aktuellen Arbeitsverzeichnis
Tipp
Die Standardabfragesammlung der CodeQL-Standardabfragepakete ist codeql-suites/<lang>-code-scanning.qls
. Weitere nützliche Abfragesammlungen findest du auch im codeql-suites
-Verzeichnis jedes Pakets. Das codeql/cpp-queries
-Paket enthält beispielsweise die folgenden Abfragesammlungen:
-
cpp-code-scanning.qls
: Die Standardabfragen zur Codeüberprüfung für C++. Dies ist die Standardabfragesammlung für dieses Paket. -
cpp-security-extended.qls
: Abfragen aus dercpp-code-scanning.qls
-Standardsammlung für C++ sowie Abfragen mit geringerem Schweregrad und geringerer Genauigkeit -
cpp-security-and-quality.qls
: Abfragen auscpp-security-extended.qls
, sowie zusätzliche Abfragen zur Verwaltbarkeit und Zuverlässigkeit
Die Quellen für diese Abfragesammlungen sind im Repository CodeQL zu finden. Abfragesammlungen für andere Sprachen sind ähnlich.
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 von benutzerdefinierten 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 Konfigurieren der CodeQL-CLI in deinem CI-System 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.
Diagnose- und Zusammenfassungsinformationen
Wenn du eine CodeQL-Datenbank erstellst, speichert der Extraktor Diagnosedaten in der Datenbank. Die Abfragesammlungen für die Codeüberprüfung enthalten zusätzliche Abfragen zum Melden dieser Diagnosedaten und zum Berechnen von Zusammenfassungsmetriken. Nach Abschluss des database analyze
-Befehls generiert die CLI die Ergebnisdatei und meldet alle Diagnose- und Zusammenfassungsdaten an die Standardausgabe. Wenn du SARIF-Ausgaben generierst, sind die zusätzlichen Daten auch in der SARIF-Datei enthalten.
Wenn die Analyse weniger Ergebnisse für Standardabfragen als erwartet gefunden hat, überprüfe die Ergebnisse der Diagnose- und Zusammenfassungsabfragen, um zu ermitteln, ob die CodeQL-Datenbank wahrscheinlich eine gute Darstellung der zu analysierenden Codebasis darstellt.
Integrieren eines CodeQL-Pakets in einen Codeüberprüfungsworkflow in GitHub
Du kannst CodeQL-Abfragepakete in deinem Codeüberprüfungs-Setup verwenden. Dadurch kannst du Abfragepakete auswählen, die von verschiedenen Quellen veröffentlicht wurden, und sie zum Analysieren deines Codes verwenden. Weitere Informationen findest du unter Verwenden von CodeQL-Abfragepaketen beim CodeQL-Vorgang oder Herunterladen und Verwenden von CodeQL-Abfragepaketen in deinem CI-System.
Einschließen von Abfragehilfen für benutzerdefinierte CodeQL-Abfragen in SARIF-Dateien
Wenn du die CodeQL CLI zum Ausführen von Codeüberprüfungsanalysen auf CI/CD-Systemen von Drittanbietern verwendest, kannst du die Abfragehilfe für deine benutzerdefinierten Abfragen in SARIF-Dateien einschließen, die während einer Analyse generiert wurden. Nach dem Hochladen der SARIF-Datei in GitHub wird die Abfragehilfe auf der Codeüberprüfungs-Benutzeroberfläche für alle Warnungen angezeigt, die von den benutzerdefinierten Abfragen generiert wurden.
Ab CodeQL CLI (Version 2.7.1) kannst du markdowngerenderte Abfragehilfen in SARIF-Dateien einschließen, indem du die --sarif-add-query-help
-Option beim Ausführen von codeql database analyze
bereitstellst.
Weitere Informationen findest du unter Konfigurieren der CodeQL CLI in deinem CI-System.
Du kannst Abfragehilfen für benutzerdefinierte Abfragen direkt in eine Markdowndatei schreiben und sie zusammen mit der entsprechenden Abfrage speichern. Um die Einheitlichkeit mit den CodeQL-Standardabfragen zu gewährleisten, kannst du die Abfragehilfe auch im .qhelp
-Format schreiben. In .qhelp
-Dateien geschriebene Abfragehilfen können nicht in SARIF-Dateien eingefügt werden, und sie können nicht durch die Codeüberprüfung verarbeitet werden, weshalb sie vor der Ausführung der Analyse in Markdown-Dateien konvertiert werden müssen. Weitere Informationen findest du unter Abfragehilfedateien und Testen von Abfragehilfedateien.
Ergebnisse
Sie können 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.
Wenn du Ergebnisse im CSV-Format generieren möchtest, entspricht jede Zeile in der Ausgabedatei einer Warnung. Jede Zeile ist eine durch Trennzeichen getrennte Liste mit den folgenden Informationen.
Eigenschaft | Beschreibung | Beispiel |
---|---|---|
Name | Der Name der Abfrage, die das Ergebnis ermittelt hat | Inefficient regular expression |
BESCHREIBUNG | Die Beschreibung der Abfrage. | A regular expression that requires exponential time to match certain inputs can be a performance bottleneck, and may be vulnerable to denial-of-service attacks. |
severity | Wichtigkeit der Abfrage | error |
Message | Warnmeldung | This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'. |
Pfad | Pfad der Datei, die die Warnung enthält | /vendor/codemirror/markdown.js |
Erste Zeile | Die Zeile der Datei, in der der Code beginnt, der die Warnung ausgelöst hat. | 617 |
Erste Spalte | Die Spalte der ersten Zeile, in der der Warnungscode beginnt. Nicht enthalten, wenn gleich 1. | 32 |
Letzte Zeile | Die Zeile der Datei, in der der Code endet, der die Warnung ausgelöst hat. Nicht enthalten, wenn der gleiche Wert wie bei der ersten Zeile vorhanden ist. | 64 |
Letzte Spalte | Falls vorhanden, die Spalte der letzten Zeile, in der der Warnungscode endet. Andernfalls wird die letzte Zeile wiederholt. | 617 |
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.