Analysieren des Codes mit CodeQL-Abfragen

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 hochgeladen werden können, um Codeüberprüfungswarnungen zu generieren.

Voraussetzungen

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.

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:

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

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

Option	Erforderlich	Verwendung
`<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.
`--format`		Gib 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.
`--output`		Gib den Speicherort an, an dem du die SARIF-Ergebnisdatei speichern möchtest, einschließlich des gewünschten Dateinamens mit der `.sarif`-Erweiterung.
`--sarif-category`		Diese 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. Verwende dies, um die Dateiabdeckungsinformationen an Seite mit dem Toolstatus zu übermitteln. Weitere Informationen findest du unter Informationen zur Toolstatusseite für die Codeüberprüfung.
`--sarif-add-query-help`		Verwende 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.
`<packs>`		Verwende die Option, wenn du CodeQL-Abfragepakete in deine Analyse einschließen möchtest. Weitere Informationen findest du unter Herunterladen und Verwenden von CodeQL-Paketen.
`--download`		Verwende die Option, wenn einige deiner CodeQL-Abfragepakete noch nicht auf dem Datenträger enthalten sind und heruntergeladen werden müssen, bevor Abfragen ausgeführt werden können.
`--threads`		Verwende 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.
`--verbose`		Verwende diese Option, um weitere Informationen zum Analyseprozess und Diagnosedaten zum Prozess der Datenbankerstellung zu erhalten.
`--threat-model`		(Beta) Verwenden Sie diese Option, um Gefahrenmodelle hinzuzufügen und zusätzliche Quellen in Ihrer CodeQL-Analyse zu konfigurieren. Während der Betaphase werden Gefahrenmodelle nur von der Java-Analyse unterstützt. Weitere Informationen findest du unter database analyze.

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

Du kannst optional Dateiabdeckungsinformationen an GitHub übermitteln, um sie auf der Seite mit dem Toolstatus für code scanning anzuzeigen. Weitere Informationen zu Dateiabdeckungsinformationen findest du unter Informationen zur Toolstatusseite für die Codeüberprüfung.

Um Dateiabdeckungsinformationen in deine code scanning-Ergebnisse einzuschließen, füge das --sarif-add-baseline-file-info-Flag dem codeql database analyze-Aufruf in deinem CI-System hinzu, z. B.:

$ 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 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 eines CodeQL-Abfragepakets

Hinweis

Die CodeQL-Paketverwaltungsfunktionen (einschließlich der CodeQL-Pakete) sind derzeit als Betaversion verfügbar und können Änderungen unterliegen. Während der Betaversion sind CodeQL-Pakete nur mit GitHub Packages verfügbar – der GitHub Container registry. Um diese Betafunktion zu verwenden, installiere die neueste Version des CodeQL CLI-Bundles aus https://github.com/github/codeql-action/releases.

Du kannst einen oder mehrere Paketnamen angeben, um ein vorhandenes CodeQL-Abfragepaket aus der GitHub Container registry auszuführen:

codeql database analyze <database> microsoft/coding-standards@1.0.0 github/security-queries --format=sarifv2.1.0 --output=query-results.sarif --download

Mit diesem Befehl wird die Standardabfragesammlung aus zwei CodeQL-Abfragepaketen ausgeführt: Version 1.0.0 von microsoft/coding-standards und der neuesten Version von github/security-queries für die angegebene Datenbank. Weitere Informationen zu Standardsammlungen findest du 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, 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 einer Teilmenge von Abfragen in einem CodeQL-Paket

Wenn du die CodeQL CLI (Version 2.8.1 oder später) verwendest, kannst du einen Pfad am Ende einer Paketspezifikation einschließen, um eine Teilmenge von Abfragen im Paket 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.
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.

Wenn du einen scope/name und einen path angibst, kann der path nicht absolut sein. Er wird als relativ zum Stamm des CodeQL-Pakets betrachtet.

Du kannst Folgendes verwenden, um eine Datenbank mit allen Abfragen im experimental/Security-Ordner im codeql/cpp-queries-CodeQL-Paket zu analysieren:

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

Verwende Folgendes, um die RedundantNullCheckParam.ql-Abfrage im codeql/cpp-queries-CodeQL-Paket auszuführen:

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

Um deine Datenbank mithilfe der cpp-security-and-quality.qls-Abfragesammlung aus einer Version des codeql/cpp-queries-CodeQL-Pakets zu analysieren (neuer als 0.0.3 und älter als 0.1.0, die neuste kompatible Version wird ausgewählt), kannst du Folgendes auswählen:

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 findest du unter Anpassen der Analyse mit CodeQL-Paketen.

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 REST-API-Endpunkte für die 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.

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

Hinweis: Die Gefahrenmodelle befinden sich derzeit in der Betaphase und können noch geändert werden. Bei der Betaversion werden Gefahrenmodelle nur von der Analyse für Java/Kotlin und C# unterstützt.

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

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

Informationen zum Hochladen deiner CodeQL-Analyseergebnisse in GitHub findest du unter Hochladen von CodeQL-Analyseergebnissen auf GitHub.