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 Enterprise Server 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:

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

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.

Ausführliche Informationen zu allen Optionen, die du beim Analysieren von Datenbanken verwenden kannst, findest du unter 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=sarifv2.1.0 --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 Enterprise Server ü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=sarifv2.1.0 \
    --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

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.

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

Sie können Gefahrenmodelle in einer code scanning-Analyse konfigurieren. Weitere Informationen findest du unter Bedrohungsmodelle für Java und Kotlin und Bedrohungsmodelle 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 Enterprise Server zu exportieren und hochzuladen, auch wenn eine CodeQL-Analyse fehlschlägt. Weitere Informationen finden Sie unter Hochladen von CodeQL-Analyseergebnissen auf GitHub.

Nächste Schritte

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