Analysieren von Datenbanken mit der CodeQL-CLI

Informationen zum Analysieren von Datenbanken mit der CodeQL CLI

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.

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:

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>...

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 du github 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.

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 pathangeben, 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 des codeql/python-queries-Pakets

• codeql/python-queries@1.2.3: Alle Abfragen in der Standardabfragesammlung von Version 1.2.3 des codeql/python-queries-Pakets

• codeql/python-queries@~1.2.3: Alle Abfragen in der Standardabfragesammlung der neuesten Version des codeql/python-queries-Pakets (neuer als 1.2.3 und älter als 1.3.0)

• codeql/python-queries:Functions: Alle Abfragen im Functions-Verzeichnis der neuesten Version des codeql/python-queries-Pakets

• codeql/python-queries@1.2.3:Functions: Alle Abfragen im Functions-Verzeichnis der Version 1.2.3 des codeql/python-queries-Pakets

• codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls: Alle Abfragen im codeql-suites/python-code-scanning.qls-Verzeichnis der Version 1.2.3 des codeql/python-queries-Pakets

• suites/my-suite.qls: Alle Abfragen in der suites/my-suite.qls-Datei relativ zum aktuellen Arbeitsverzeichnis

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.

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.

Weiterführende Themen

• Analysieren deiner Projekte in CodeQL für VS Code