Analysieren des Codes mit CodeQL-Abfragen

Sie können Abfragen für eine CodeQL Datenbank ausführen, die aus einer Codebasis extrahiert wurde.

Wer kann dieses Feature verwenden?

CodeQL ist für die folgenden Repositorytypen verfügbar:

In diesem Artikel

Informationen zum Analysieren von Datenbanken mit dem CodeQL CLI

Um eine Codebasis zu analysieren, führen Sie Abfragen für eine CodeQL Datenbank aus, die aus dem Code extrahiert wurde. CodeQL-Analysen erzeugen Ergebnisse, die in GitHub hochgeladen werden können, um Code-Scan-Benachrichtigungen zu generieren.

Voraussetzungen

Bevor du eine Analyse startest, musst du Folgendes tun:

  •         [Einrichten des CodeQL CLI](/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli) zum lokalen Ausführen von Befehlen.

  •         [Erstellen Sie eine CodeQL Datenbank](/code-security/codeql-cli/getting-started-with-the-codeql-cli/preparing-your-code-for-codeql-analysis) für den Quellcode, den Sie analysieren möchten.

Die einfachste Methode, codeql database analyze auszuführen, ist die Verwendung der Standardabfragen, die im CodeQL CLI-Bundle enthalten sind.

Wird ausgeführt codeql database analyze

Beim Ausführen von database analyze geschieht Folgendes:

  1. Lädt optional alle referenzierten CodeQL Pakete herunter, die nicht lokal verfügbar sind.
  2. Führt eine oder mehrere Abfragedateien aus, indem sie über eine CodeQL Datenbank ausgeführt werden.
  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 Sie mehrere CodeQL Datenbanken für einen einzelnen Commit analysieren, müssen Sie eine SARIF-Kategorie für jede Gruppe von Ergebnissen angeben, die von diesem Befehl generiert werden. Wenn Sie die Ergebnisse zu GitHub hochladen, verwendet code scanning diese Kategorie, um die Ergebnisse für jede Sprache separat zu speichern. Wenn Sie dies vergessen, überschreibt jeder Upload die alten Ergebnisse.

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

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

OptionErforderlichUsage
<database>Geben Sie den Pfad für das Verzeichnis an, das die CodeQL zu analysierende Datenbank enthält.
<packs,queries>Geben Sie CodeQL Pakete oder Abfragen an, die ausgeführt werden sollen. Wenn Sie die standardabfragen ausführen möchten, die für code scanningden Parameter verwendet werden, lassen Sie diesen Parameter aus. Führen Sie codeql resolve queries aus, um die anderen in das CodeQL CLI-Paket aufgenommenen Abfragesammlungen anzuzeigen. Die dort aufgeführten Sammlungen können mit oder ohne die .qls-Erweiterung bereitgestellt werden. Informationen zum Erstellen Ihrer eigenen Abfragesuite finden Sie in der Dokumentation zu Erstellen von CodeQL-Abfragesammlungen.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 auf GitHub sollte es sein:sarif-latest. Weitere Informationen finden Sie 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-baseline-file-info
          **Empfohlen.** Wird verwendet, um Dateiabdeckungsdaten an die Seite mit dem Toolstatus zu übermitteln. Weitere Informationen finden Sie unter [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/about-the-tool-status-page#how-codeql-defines-scanned-files). |

| --sarif-include-query-help | | Geben Sie an, ob Abfragehilfe in die SARIF-Ausgabe eingeschlossen werden soll. Eine der folgenden Möglichkeiten: always: Abfragehilfe für alle Abfragen einschließen. custom_queries_only (Standard): Abfragehilfe nur für benutzerdefinierte Abfragen einschließen, d. h. Abfragen in Abfragepaketen, die nicht die Form codeql/<lang>-queries haben. never: Schließt keine Abfragehilfe für Abfragen ein. Alle Abfragehilfen für benutzerdefinierte Abfragen, die in der SARIF-Ausgabe enthalten sind, werden in den Codeüberprüfungswarnungen für die Abfrage angezeigt. Weitere Informationen finden Sie unter Schreiben von benutzerdefinierten Abfragen für die CodeQL CLI. | | <packs> | | Verwenden Sie CodeQL, wenn Sie Abfragepakete in Ihre Analyse einbeziehen möchten. Weitere Informationen finden Sie unter Herunterladen und Verwenden von CodeQL Paketen. | | --download | | Verwenden Sie, wenn einige Ihrer CodeQL Abfragepakete noch nicht auf dem Datenträger vorhanden sind und vor dem Ausführen von Abfragen heruntergeladen werden müssen. | | --threads | | Verwenden Sie diese Option, wenn Sie mehrere Threads zum Ausführen von Abfragen verwenden möchten. Der Standardwert ist 1. Sie können weitere Threads angeben, um die Abfrageausführung zu beschleunigen. Gib 0 an, um die Anzahl der Threads auf die Anzahl der logischen Prozessoren festzulegen. | | --verbose | | Verwende diese Option, um weitere Informationen zum Analyseprozess und Diagnosedaten zum Prozess der Datenbankerstellung zu erhalten. | | --threat-model | | (Öffentliche Vorschau) Dient zum Hinzufügen von Bedrohungsmodellen zum Konfigurieren zusätzlicher Quellen in Ihrer CodeQL Analyse. Während der öffentliche VorschauBedrohungsmodelle werden nur von der Java-Analyse unterstützt. Weitere Informationen finden Sie unter Datenbankanalyse. |

Hinweis

          **Aktualisieren von Datenbanken**

Für Datenbanken, die von CodeQL CLI v2.3.3 oder einer früheren Version erstellt wurden, müssen Sie die Datenbank explizit aktualisieren, bevor Sie eine Analyse mit einer neueren Version der CodeQL CLIDatei ausführen können. 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.

Bei Datenbanken, die von CodeQL CLI v2.3.4 oder höher erstellt wurden, führt die CLI implizit alle erforderlichen Upgrades aus. Das explizite Ausführen des Upgradebefehls ist nicht erforderlich.

Ausführliche Informationen zu allen Optionen, die beim Analysieren von Datenbanken verwendet werden können, finden Sie unter Datenbankanalyse.

Grundlegendes Beispiel für die Analyse einer CodeQL Datenbank

In diesem Beispiel wird eine CodeQL Datenbank analysiert, die bei /codeql-dbs/example-repo gespeichert ist, und die Ergebnisse werden als SARIF-Datei gespeichert: /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 Sie mehrere CodeQL Datenbanken für einen einzelnen Commit in einem Repository analysieren müssen.

$ codeql database analyze /codeql-dbs/example-repo \
    javascript-code-scanning.qls --sarif-category=javascript-typescript \
    --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.

Hinzufügen von Dateiabdeckungsinformationen zu deinen Ergebnissen zur Überwachung

Sie können optional Dateiabdeckung GitHub zur Anzeige auf Seite mit dem Toolstatus für code scanning einreichen. Weitere Informationen zu Dateiabdeckungsinformationen finden Sie unter Verwenden der Toolstatusseite zum Scannen von Code.

Um Dateiabdeckungsinformationen in Ihre code scanning Ergebnisse einzuschließen, fügen Sie das --sarif-add-baseline-file-info und codeql database analyze Kennzeichen zum Aufruf in Ihrem CI-System hinzu, zum Beispiel:

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

Beispiele für die Ausführung von Datenbankanalysen

Die folgenden Beispiele zeigen, wie database analyze mit CodeQL-Paketen ausgeführt wird und wie Sie ein lokales Checkout des CodeQL-Repositorys nutzen können. In diesen Beispielen wird davon ausgegangen, dass Ihre CodeQL Datenbanken in einem Verzeichnis erstellt wurden, das ein gleichgeordnetes Element Ihrer lokalen Kopien des CodeQL Repositorys ist.

Ausführen eines CodeQL Abfragepakets

Zum Ausführen eines vorhandenen CodeQL Abfragepakets aus dem GitHubContainer registrykönnen Sie einen oder mehrere Packnamen angeben:

codeql database analyze <database> microsoft/[email protected] github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Mit diesem Befehl wird die Standardabfragesuite von zwei Abfragepaketen <c0> ausgeführt: <c1> Version 1.0.0 und die neueste Version von <c2> auf der angegebenen Datenbank. Weitere Informationen zu Standardsammlungen finden Sie unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Das --download-Flag ist optional. Wenn du es verwendest, wird sichergestellt, dass das Abfragepaket heruntergeladen wird, wenn es noch nicht lokal verfügbar ist.

Ausführen einer einzelnen Abfrage

Um eine einzelne Abfrage über eine CodeQL Datenbank für eine JavaScript-Codebasis auszuführen, können Sie den folgenden Befehl aus dem Verzeichnis verwenden, das Ihre Datenbank enthält:

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

Dieser Befehl führt eine einfache Abfrage aus, die potenzielle Fehler im Zusammenhang mit nicht verwendeten Variablen, Importen, Funktionen oder Klassen findet – es handelt sich um eine der JavaScript-Abfragen, die CodeQL im 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 Sie das CodeQL Repository ausgecheckt haben, können Sie auch die gleichen Abfragen ausführen, indem Sie den Pfad zur Abfrage direkt angeben:

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 dazu, wie Sie Ihre Abfragen zur Verwendung mit dem CodeQL CLI vorbereiten, finden Sie unter Schreiben von benutzerdefinierten Abfragen für die 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

Sie sollten vermeiden, den Stamm eines Kernabfragepakets CodeQL anzugeben, wenn Sie database analyze ausführen, da es möglicherweise einige spezielle Abfragen enthalten kann, die nicht für die Verwendung mit dem Befehl vorgesehen 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 Verzeichnis Functions im abfragepaket codeql/python-queries enthalten sind, würden Sie Folgendes ausführen:

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

Wenn Sie das CodeQL Repository ausgecheckt haben, können Sie auch die gleichen Abfragen ausführen, indem Sie den Pfad zum Verzeichnis direkt angeben:

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 von CodeQL unterstützten SARIF-Spezifikation formatiert werden.

Ausführen einer Teilmenge von Abfragen in einem CodeQL Paket

Wenn Sie v2.8.1 oder höher verwenden CodeQL CLI , können Sie einen Pfad am Ende einer Packspezifikation einfügen, um eine Teilmenge von Abfragen innerhalb des Pakets auszuführen. Dies gilt für jeden Befehl, der Abfragen innerhalb eines Pakets sucht oder ausführt.

Du kannst mehrere Abfragen in der Form scope/name@range:path angeben, wobei Folgendes gilt:

  •         `scope/name` ist der qualifizierte Name eines CodeQL Pakets.

  •         `range` ist ein [Semver-Bereich](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges).

  •         `path` ist ein Dateisystempfad zu einer einzelnen Abfrage, einem Verzeichnis, das Abfragen enthält, oder einer Abfrage-Suite-Datei.

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.

Wenn du einen scope/name und einen path angibst, kann der path nicht absolut sein. Es wird relativ zum Stamm der CodeQL Paket

So analysieren Sie eine Datenbank mithilfe aller Abfragen im Ordner des experimental/Security``codeql/cpp-queriesCodeQL Pakets:

codeql database analyze --format=sarif-latest --output=results <db> \
    codeql/cpp-queries:experimental/Security

So führen Sie die RedundantNullCheckParam.ql Abfrage im codeql/cpp-queriesCodeQL Pack aus:

codeql database analyze --format=sarif-latest --output=results <db> \
    'codeql/cpp-queries:experimental/Likely Bugs/RedundantNullCheckParam.ql'

Um Ihre Datenbank mithilfe der cpp-security-and-quality.qls Abfragesuite aus einer Version des Pakets codeql/cpp-queriesCodeQL zu analysieren, die >= 0.0.3 und < 0.1.0 (die höchste kompatible Version wird ausgewählt) können Sie Folgendes verwenden:

codeql database analyze --format=sarif-latest --output=results <db> \
   'codeql/cpp-queries@~0.0.3:codeql-suites/cpp-security-and-quality.qls'

Wenn du auf eine Abfragedatei, ein Verzeichnis oder eine Sammlung verweisen musst, deren Pfad ein @ oder : enthält, kannst du der Abfragespezifikation path: voranstellen:

codeql database analyze --format=sarif-latest --output=results <db> \
    path:C:/Users/ci/workspace@2/security/query.ql

Weitere Informationen zu CodeQL Paketen finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.

Ausführen von Abfragesammlungen

Um eine Abfragesuite für eine CodeQL Datenbank für eine C/C++-Codebasis auszuführen, können Sie den folgenden Befehl aus dem Verzeichnis verwenden, das Ihre 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-queriesCodeQL Abfragepaket herunter, führt die Analyse aus und generiert eine Datei im SARIF Version 2.1.0-Format, das von allen Versionen unterstützt GitHubwird. Diese Datei kann in GitHub hochgeladen werden, indem codeql github upload-results ausgeführt wird oder die Codescan-API verwendet wird. Weitere Informationen findest du unter Hochladen von CodeQL-Analyseergebnissen in GitHub oder REST-API-Endpunkte für die Codeüberprüfung.

          CodeQL Abfragesammlungen sind `.qls` Dateien, die Direktiven verwenden, um Abfragen auszuwählen, die basierend auf bestimmten Metadateneigenschaften ausgeführt werden sollen. Die Standardpakete CodeQL verfügen über Metadaten, die den Speicherort der Abfragesammlungen angeben, die von der Codeüberprüfung verwendet werden. Daher weiß dies CodeQL CLI , wo diese Suitedateien automatisch gefunden werden sollen, und Sie müssen nicht den vollständigen Pfad in der Befehlszeile angeben.

Weitere Informationen finden Sie unter Erstellen von CodeQL-Abfragesammlungen.

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

Einschließen von Modellpaketen zum Hinzufügen potenzieller Quellen von enthaltenen Daten

Hinweis

Gefahrenmodelle befinden sich derzeit in der öffentliche Vorschau. Änderungen sind vorbehalten. Während der öffentliche Vorschau werden Gefahrenmodelle nur durch die Analyse für Java/Kotlin und C# unterstützt.

Sie können Bedrohungsmodelle in einer code scanning Analyse konfigurieren. Weitere Informationen finden Sie in der Dokumentation unter Bedrohungsmodelle für Java- und Kotlin- und CodeQL.

$ codeql database analyze /codeql-dbs/my-company --format=sarif-latest \
  --threat-model=local \
  --output=/temp/my-company.sarif codeql/java-queries

In diesem Beispiel verwenden die relevanten Abfragen im codeql/java-queries-Standardabfragepaket das local-Gefahrenmodell sowie das Standard-Gefahrenmodell für remote-Datenflussquellen. Sie sollten das local-Gefahrenmodell verwenden, wenn Sie Daten aus lokalen Quellen (z. B. Dateisysteme, Befehlszeilenargumente, Datenbanken und Umgebungsvariablen) als potenzielle Datenquellen für die Codebasis betrachten.

Ergebnisse

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

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

Weitere Informationen dazu, wie die Ergebnisse im CSV-Format aussehen, finden Sie 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 Sie eine Datenbank mithilfe einer CodeQLcode scanning Abfragesuite analysieren, berichtet die CLI zusätzlich zum Erzeugen detaillierter Informationen zu Warnungen die Diagnosedaten aus dem Schritt der Datenbankgenerierung und die zusammenfassenden Metriken. Wenn du SARIF-Ausgaben generierst, sind die zusätzlichen Daten auch in der SARIF-Datei enthalten. Bei Repositorys mit wenigen Warnungen finden Sie diese Informationen möglicherweise 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 finden Sie unter Codescanprotokolle.

Sie können Diagnoseinformationen GitHub exportieren und hochladen, selbst wenn eine CodeQL-Analyse fehlschlägt. Weitere Informationen finden Sie unter Hochladen von CodeQL-Analyseergebnissen in GitHub.

Nächste Schritte