Anpassen der Analyse mit CodeQL-Paketen

Sie können Ihre CodeQL Analyse anpassen, indem Sie Pakete herunterladen, die von anderen personen erstellt wurden, und sie auf Ihrer Codebasis ausführen. Weitere Informationen findest du unter CodeQL-Abfragepakete.

Herunterladen und Verwenden von CodeQL Abfragepaketen

Bevor Sie ein CodeQL Abfragepaket verwenden können, um eine Datenbank zu analysieren, müssen Sie alle Pakete, die Sie benötigen, von GitHubContainer registry herunterladen. Dies kann durch Verwendung des Flags --download als Teil des Befehls codeql database analyze erfolgen, oder durch Ausführen von codeql pack download. Wenn ein Paket nicht öffentlich verfügbar ist, müssen Sie zur Authentifizierung GitHub App oder personal access token verwenden. Weitere Informationen und ein Beispiel findest du unter Hochladen von CodeQL-Analyseergebnissen in GitHub.

Auswahl	Erforderlich	Usage
`<scope/name@version:path>`		Geben Sie den Bereich und den Namen eines oder CodeQL mehrerer Abfragepakete an, die mithilfe einer durch Trennzeichen getrennten Liste heruntergeladen werden sollen. Schließe optional die Version ein, die heruntergeladen und entpackt werden soll. Standardmäßig wird die neueste Version des Pakets heruntergeladen. Optional kannst du einen Pfad zu einer Abfrage, einem Verzeichnis oder einer Abfragesammlung angeben, die ausgeführt werden soll. Wenn kein Pfad angegeben ist, führe die Standardabfragen dieses Pakets aus.
`--github-auth-stdin`		Geben Sie der CLI über die Standardeingabe das GitHub App oder personal access token zur Authentifizierung mit der REST-API von GitHub aus Ihrem geheimen Speicher. Dies ist nicht erforderlich, wenn der Befehl über Zugriff auf `GITHUB_TOKEN`-Umgebungsvariablen verfügt, die mit diesem Token festgelegt wurden.

Hinweis

Wenn Sie eine bestimmte Version eines zu verwendenden Abfragepakets angeben, beachten Sie, dass die angegebene Version möglicherweise zu alt wird, damit die neueste Version CodeQL effizient genutzt werden kann. Um eine optimale Leistung sicherzustellen, sollten Sie, wenn Sie genaue Versionen von Abfragepaketen angeben müssen, jedes Mal neu bewerten, auf welche Versionen Sie diese festlegen, wenn Sie die verwendete CodeQL CLI aktualisieren.

Weitere Informationen zur Kompatibilität von Paketen findest du unter Referenz zu CodeQL-Abfragepaketen.

Einfaches Beispiel für das Herunterladen und Verwenden von Abfragepaketen

In diesem Beispiel wird der Befehl codeql database analyze mit der Option --download für folgende Zwecke ausgeführt:

Herunterladen der neuesten Version des Pakets octo-org/security-queries
Herunterladen einer Version des Pakets octo-org/optional-security-queries, die mit Version 1.0.1 kompatibel ist (in diesem Fall Version 1.0.2) Weitere Informationen zur SemVer-Kompatibilität findest du in der npm-Dokumentation zur semantischen Versionierung unter „Ranges“.
Ausführen aller Standardabfragen in octo-org/security-queries
Ausschließliches Ausführen der Abfrage queries/csrf.ql in octo-org/optional-security-queries

$ echo $OCTO-ORG_ACCESS_TOKEN | codeql database analyze --download /codeql-dbs/example-repo \
    octo-org/security-queries \
    octo-org/optional-security-queries@~1.0.1:queries/csrf.ql \
    --format=sarif-latest --output=/temp/example-repo-js.sarif

> Download location: /Users/mona/.codeql/packages
> Installed fresh octo-org/[email protected]
> Installed fresh octo-org/[email protected]
> Running queries.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> [1/2] Found in cache: /Users/mona/.codeql/packages/octo-org/security-queries/1.0.0/potential-sql-injection.ql.
> Starting evaluation of octo-org/security-queries/query1.ql.
> Compiling query plan for /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> [2/2] Found in cache: /Users/mona/.codeql/packages/octo-org/optional-security-queries/1.0.2/queries/csrf.ql.
> Starting evaluation of octo-org/optional-security-queries/queries/csrf.ql.
> [2/2 eval 694ms] Evaluation done; writing results to octo-org/security-queries/query1.bqrs.
> Shutting down query evaluator.
> Interpreting results.

Direkter Download von CodeQL Paketen

Wenn Sie ein CodeQL Paket herunterladen möchten, ohne es sofort auszuführen, können Sie den codeql pack download Befehl verwenden. Dies ist nützlich, wenn Sie beim Ausführen von CodeQL Abfragen den Zugriff auf das Internet vermeiden möchten. Wenn Sie die CodeQL Analyse ausführen, können Sie Pakete, Versionen und Pfade auf die gleiche Weise angeben wie im vorherigen Beispiel:

echo $OCTO-ORG_ACCESS_TOKEN | codeql pack download <scope/name@version:path> <scope/name@version:path> ...

Herunterladen von Paketen CodeQL aus mehreren GitHub Containerregistrierungen

Wenn sich Ihre CodeQL Pakete in mehreren Containerregistrierungen befinden, müssen Sie die Stelle anweisen, an der CodeQL CLI die einzelnen Pakete zu finden sind. Weitere Informationen findest du unter Workflowkonfigurationsoptionen für die Codeüberprüfung.

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, 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. Globmuster werden nicht unterstützt.

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

Beispielabfragespezifizierer

codeql/python-queries - Alle Abfragen in der standardmäßigen Suite der neuesten Version des codeql/python-queries Packs.
codeql/[email protected] - Alle Abfragen in der Standard-Abfrage-Suite der Version 1.2.3 des codeql/python-queries Packs.
codeql/python-queries@~1.2.3 - Alle Abfragen in der Standard-Abfrage-Suite der neuesten Version des codeql/python-queries Packs, die >= 1.2.3 und < 1.3.0 ist.
codeql/python-queries:Functions - Alle Abfragen im Verzeichnis Functions in der letzten Version des codeql/python-queries Packs.
codeql/[email protected]:Functions - Alle Abfragen im Verzeichnis Functions in der Version 1.2.3 des codeql/python-queries Packs.
codeql/[email protected]:codeql-suites/python-code-scanning.qls - Alle Abfragen im Verzeichnis codeql-suites/python-code-scanning.qls in der Version 1.2.3 des codeql/python-queries Packs.
suites/my-suite.qls - Alle Abfragen in der Datei suites/my-suite.qls relativ zum aktuellen Arbeitsverzeichnis.

Tipp

Die Standard-Abfrage-Suite der Standard-CodeQLAbfragepakete ist codeql-suites/<lang>-code-scanning.qls. Weitere nützliche Abfragesammlungen findest du auch im codeql-suites-Verzeichnis jedes Pakets. Das codeql/cpp-queries-Paket enthält beispielsweise die folgenden Abfragesammlungen:

cpp-code-scanning.qls - Standard Code Scanning Abfragen für C++. Dies ist die Standardabfragesammlung für dieses Paket.

* cpp-security-extended.qls - Abfragen aus der Standard cpp-code-scanning.qls Suite für C++, plus Abfragen mit geringerem Schweregrad und geringerer Genauigkeit. * cpp-security-and-quality.qls - Abfragen aus cpp-security-extended.qls, plus Wartbarkeits- und Zuverlässigkeitsabfragen.

Sie können die Quellen für diese Abfragesammlungen im CodeQL Repository anzeigen. Abfragesammlungen für andere Sprachen sind ähnlich.

Verwenden von Modellpaketen zum Analysieren von Aufrufen von benutzerdefinierten Abhängigkeiten

Sie können veröffentlichte Modellpakete in eine code scanning Analyse mit der --model-packs Option einschließen. Beispiel:

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

In diesem Beispiel verwenden die relevanten Abfragen im Standardabfragepaket codeql/java-queries die Abhängigkeitsinformationen aus dem Modellpaket, my-repo/my-java-model-pack, um nach Sicherheitsrisiken im Code zu suchen, der diese Abhängigkeiten aufruft.

Sie können mehrere veröffentlichte Modellpakete in einer Analyse angeben.

Weitere Informationen zum Schreiben eigener Modellpakete findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Informationen zu veröffentlichten Paketen

Wenn ein Paket für das Verwenden in Analysen veröffentlicht wird, überprüfen die Befehle codeql pack create oder codeql pack publish, ob der Inhalt vollständig ist, und fügt diesem auch einige zusätzliche Inhalte hinzu:

Bei Abfragepaketen: eine Kopie aller Bibliothekspakete, von denen das Abfragepaket abhängig ist, in den genauen Versionen, mit denen es entwickelt wurde. Benutzer*innen des Abfragepakets müssen diese Bibliothekspakete nicht separat herunterladen.
Bei Abfragepaketen: vorkompilierte Darstellungen der einzelnen Abfragen. Diese können schneller ausgeführt werden, als wenn die QL-Quelle für die Abfrage bei jeder Analyse kompiliert werden müsste.

Die meisten dieser Daten befinden sich in einem Verzeichnis namens .codeql im veröffentlichten Paket, doch vorkompilierte Abfragen befinden sich für jede Abfrage in Dateien mit dem Suffix .qlx neben der .ql-Quelle. Beim Analysieren einer Datenbank mit einer Abfrage aus einem veröffentlichten Paket CodeQL werden diese Dateien anstelle der .ql Quelle geladen. Wenn du den Inhalt eines veröffentlichten Pakets ändern musst, entferne alle .qlx-Dateien, da diese möglicherweise verhindern, dass Änderungen an den .ql-Dateien wirksam werden.

Wer kann dieses Feature verwenden?

In diesem Artikel