Ausführung von CodeQL-Abfragen

Informationen zum Ausführen von CodeQL Abfragen

Das github/codeql-Repository enthält eine große Anzahl von Beispielabfragen. Sie können über die Ansicht „Abfragen“ auf alle vorhandenen Abfragen in Ihrem Arbeitsbereich zugreifen.

Voraussetzungen

Um eine Codebasis zu analysieren, führen Sie Abfragen für eine CodeQL Datenbank aus, die aus dem Code extrahiert wurde. Daher müssen Sie eine Datenbank auswählen, mit der sie in der Erweiterung arbeiten soll. Sie können eine Datenbank lokal (aus einem ZIP-Archiv oder einem nicht archivierten Ordner), aus einer öffentlichen URL oder aus der URL eines Projekts unter GitHub.comauswählen. Weitere Informationen findest du unter Verwalten von CodeQL-Datenbanken.

Ausführen einer einzelnen Abfrage

1. Öffnen Sie in der Randleiste die Ansicht „Abfragen“.

2. Um eine Abfrage für die ausgewählte Datenbank auszuführen, zeigen Sie mit der Maus auf die gewünschte Abfrage, und klicken Sie dann auf das Symbol Lokale Abfrage ausführen.

Die CodeQL Erweiterung führt die Abfrage in der aktuellen Datenbank aus und meldet den Fortschritt in der unteren rechten Ecke der Anwendung. Wenn die Ergebnisse bereit sind, werden sie in der CodeQL Ansicht "Abfrageergebnisse" angezeigt.

Wenn Probleme beim Ausführen einer Abfrage auftreten, wird in der unteren rechten Ecke der Anwendung eine Benachrichtigung angezeigt. Zusätzlich zur Fehlermeldung enthält die Benachrichtigung Details zur Behebung des Problems.

Ausführen aller Abfragen in einem Verzeichnis

Sie können jede Abfrage in einem Verzeichnis ausführen.

1. Öffnen Sie in der Randleiste die Ansicht „Abfragen“.

2. Zeigen Sie mit der Maus auf das gewünschte Verzeichnis der Abfragen, und klicken Sie dann auf das Symbol Lokale Abfragen ausführen.

Ausführen einer Auswahl von Abfragen

Sie können mehrere Abfragen mit einem einzigen Befehl ausführen.

1. Wechseln Sie zu Datei-Explorer.

2. Wählen Sie mehrere Dateien oder Ordner aus, die Abfragen enthalten.

3. Klicken Sie mit der rechten Maustaste, und wählen Sie folgendes aus CodeQL: Abfragen in ausgewählten Dateien ausführen.

Ausführen einer Abfrage ohne Setup

Wenn Sie an einer neuen Abfrage arbeiten, können Sie eine „Schnellabfrage“-Registerkarte öffnen, um den Code auf einfache Weise auszuführen und die Ergebnisse anzuzeigen, ohne eine .ql-Datei in Ihrem Arbeitsbereich speichern zu müssen. Wählen Sie CodeQL: Quick Query aus dem VS Code Command Palette, dann verwenden Sie zum Ausführen der Abfrage CodeQL: Abfrage in der ausgewählten Datenbank ausführen.

Alle Schnellabfragen, die Sie in der aktuellen Sitzung ausgeführt haben, werden in der Ansicht „Abfrageverlauf“ angezeigt. Klicken Sie auf einen Eintrag, um den genauen Text der Schnellabfrage anzuzeigen, die die Ergebnisse erzeugt hat. Weitere Informationen finden Sie unter Anzeigen Ihres Abfrageverlaufs.

Sobald Sie mit Ihrer schnellen Abfrage zufrieden sind, sollten Sie sie in einem CodeQL Paket speichern, damit Sie später darauf zugreifen können. Weitere Informationen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Ausführen eines bestimmten Teils einer Abfrage oder Bibliothek

Dies kann hilfreich sein, wenn Sie eine Abfrage oder Bibliothek debuggen und den falschen Teil finden möchten.

: Anstatt "Abfrage für ausgewählte Datenbank" auszuführen, um die gesamte Abfrage auszuführen (die Auswahlklausel und alle Abfrage-Prädikate), können Sie Folgendes verwenden: : Schnelle Auswertung, um einen bestimmten Teil einer - oder -Datei auszuführen.

          **
          CodeQL: Die Schnellauswertung** wertet einen codeausschnitt aus, den Sie ausgewählt haben, statt der gesamten Abfrage, und zeigt ergebnisse dieser Auswahl in der Ansicht "Ergebnisse" an.

Mögliche Ziele für Schnellauswertungen sind:

• Auswählen des Namens einer CodeQL Entität (z. B. einer Klasse oder eines Prädikats), um diese Entität auszuwerten.

• Auswählen einer Formel oder eines Ausdrucks mit freien Variablen, um diese Formel oder diesen Ausdruck auszuwerten.

Im folgenden Codeausschnitt können Sie z. B. den Prädikatnamen foo oder die Formel s = "bar" für die Schnellauswertung auswählen:

predicate foo(string s) { s = "bar" }

Ausführen einer Abfrage für mehrere Datenbanken

Dies kann hilfreich sein, wenn Sie Ihre Abfrage auf mehreren Codebasen testen oder eine Sicherheitsanfälligkeit in mehreren Projekten finden möchten.

1. (.ql)-Abfragedatei öffnen

2. Klicken Sie mit der rechten Maustaste, und wählen Sie folgendes aus CodeQL: Abfrage für mehrere Datenbanken ausführen.

3. Im Dropdownmenü können Sie die Datenbanken auswählen, für die Sie die Abfrage ausführen möchten.

Anzeigen des Abfrageverlaufs

Um die Abfragen anzuzeigen, die Sie in der aktuellen Sitzung ausgeführt haben, öffnen Sie die Ansicht „Abfrageverlauf“.

Die Ansicht „Abfrageverlauf“ enthält Informationen, einschließlich Datum und Uhrzeit der Ausführung der Abfrage, des Namens der Abfrage, der Datenbank, auf der sie ausgeführt wurde, und wie lange es dauerte, die Abfrage auszuführen:

• Um die angezeigten Informationen anzupassen, klicken Sie mit der rechten Maustaste auf einen Eintrag, und wählen Sie Umbenennen aus.

• Filtern Sie die Ansicht optional mithilfe der Sprachauswahl nach Sprache. Weitere Informationen finden Sie unter Filtern von Datenbanken und Abfragen nach Sprache.

• Klicken Sie auf einen Eintrag, um die entsprechenden Ergebnisse anzuzeigen, und doppelklicken Sie, um die Abfrage selbst im Editor anzuzeigen (oder klicken Sie mit der rechten Maustaste, und wählen Sie Abfrage anzeigen aus).

• Um den exakten Text anzuzeigen, der die Ergebnisse für einen bestimmten Eintrag erzeugt hat, klicken Sie mit der rechten Maustaste darauf, und wählen Sie Abfragetext anzeigen aus. Dies kann sich von Abfrage anzeigen unterscheiden, da die Abfragedatei möglicherweise seit der letzten Ausführung geändert wurde.

• Um Abfragen aus der Ansicht zu entfernen, wählen Sie alle Abfragen aus, die Sie entfernen möchten, und klicken Sie dann mit der rechten Maustaste, und wählen Sie Löschen aus.

Verstehen der Abfrageergebnisse

1. Klicken Sie in der Ansicht „Abfrageverlauf“ auf eine Abfrage, um die Ergebnisse in der Ansicht „Ergebnisse“ anzuzeigen.

   Hinweis

   Je nach Abfrage können Sie auch unterschiedliche Ansichten wie CSV, SARIF-Ausgabe der CodeQL CLI oder DIL-Format auswählen. Wenn Sie z. B. das DIL-Format anzeigen möchten, klicken Sie mit der rechten Maustaste auf ein Ergebnis, und wählen Sie DIL anzeigen aus. Die verfügbaren Ausgabeansichten werden durch das Format und die Metadaten der Abfrage bestimmt. Weitere Informationen finden Sie unter CodeQL Abfragen.

2. Verwenden Sie das Dropdownmenü in der Ansicht „Ergebnisse“, um auszuwählen, welche Ergebnisse angezeigt werden sollen, und in welchem Formular sie angezeigt werden sollen, z. B. eine formatierte Warnmeldung oder eine Tabelle mit unformatierten Ergebnissen.

3. Wenn Sie die Ergebnisse nach den Einträgen in einer bestimmten Spalte sortieren möchten, klicken Sie auf die Spaltenüberschrift.

Wenn ein Ergebnis mit einem Quellcodeelement verknüpft ist, können Sie darauf klicken, um es in der Quelle anzuzeigen.

Um Standardfunktionen für die Codenavigation im Quellcode zu verwenden, können Sie mit der rechten Maustaste auf ein Element klicken und die Befehle Gehe zu Definition oder Gehe zu Verweise verwenden. Dadurch wird eine CodeQL Abfrage über die aktive Datei ausgeführt, die einige Sekunden dauern kann. Diese Abfrage muss für jede Datei einmal ausgeführt werden, so dass alle weiteren Verweise auf dieselbe Datei schnell sind.

Vergleichen von Abfrageergebnissen

Wenn Sie eine Abfrage schreiben oder debuggen, ist es hilfreich, zu sehen, wie sich Ihre Änderungen auf die Ergebnisse auswirken. Sie können zwei Ergebnisgruppen vergleichen, um genau zu sehen, was sich geändert hat. Zum Vergleichen der Ergebnisse müssen die beiden Abfragen in derselben Datenbank ausgeführt werden.

1. Klicken Sie in der Ansicht „Abfrageverlauf“ mit der rechten Maustaste auf eine Abfrage, und wählen Sie Ergebnisse vergleichen aus.

2. Ein Schnellauswahlmenü zeigt alle gültigen Abfragen an, mit denen verglichen werden soll. Wählen Sie eine Abfrage aus.

3. In der Ansicht „Vergleichen“ werden die Unterschiede in den Ergebnissen der beiden Abfragen angezeigt.

Problembehandlung

Wenn Sie die Protokolle aus der Ausführung einer bestimmten Abfrage anzeigen möchten, klicken Sie in der Ansicht „Abfrageverlauf“ mit der rechten Maustaste auf die Abfrage, und wählen Sie Abfrageprotokoll anzeigen aus. Wenn die Protokolldatei zu groß ist, um von der Erweiterung geöffnet zu werdenVS Code, wird die Datei im Windows-Explorer angezeigt, damit Sie sie mit einem externen Programm öffnen können.

Ausführliche Informationen zum Kompilieren und Ausführen von Abfragen sowie Informationen zu Datenbankupgrades finden Sie im CodeQL Abfrageserverprotokoll. Weitere Informationen findest du unter Zugreifen auf Protokolle für CodeQL in Visual Studio Code.

Standardmäßig löscht die Erweiterung Protokolle nach jeder Arbeitsbereichssitzung. Um dieses Verhalten außer Kraft zu setzen, können Sie ein benutzerdefiniertes Verzeichnis für Abfrageserverprotokolle angeben. Weitere Informationen findest du unter Anpassen von Einstellungen.

Sie können den CodeQLBefehl "Abfrageserver neu starten " verwenden, um den Abfrageserver neu zu starten. Dadurch wird der Server neu gestartet, ohne dass sich dies auf den CodeQL Sitzungsverlauf auswirkt. Sie müssen den Abfrageserver wahrscheinlich neu starten, wenn Sie externe Änderungen an Dateien vornehmen, die die Erweiterung verwenden. In VS Code beispielsweise wird eine CodeQL Datenbank regeneriert, die geöffnet ist. Zusätzlich zu Problemen im Protokoll können Sie auch sehen: Fehler beim Hervorheben von Code, falsche Ergebnissummen oder duplizierte Benachrichtigungen, die eine Abfrage ausführt.

Nächste Schritte

Optional können Sie die Erweiterung verwenden, um eigene benutzerdefinierte Abfragen zu erstellen. Weitere Informationen findest du unter Erstellen einer benutzerdefinierten Abfrage.

Informationen zur Ausführung von Analysen in großem Umfang in vielen CodeQL Datenbanken finden Sie unter Ausführung von CodeQL-Abfragen in großem Maßstab mit der Analyse von Varianten über mehrere Repositories.