Anpassen der Analyse mit CodeQL-Paketen

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

Informationen zu CodeQL-Paketen

CodeQL-Pakete werden verwendet, um CodeQL-Abfragen und -Bibliotheken zu erstellen, zu teilen, auszuführen und sie als Abhängigkeiten zu nutzen. Du kannst deine eigenen CodeQL-Pakete veröffentlichen und von anderen Personen erstellte Pakete herunterladen. CodeQL-Pakete enthalten Abfragen, Bibliotheksdateien, Abfragesammlungen und Metadaten.

Es gibt zwei Arten von CodeQL-Paketen: Abfragepakete und Bibliothekspakete.

Abfragepakete sind zum Ausführen konzipiert. Wenn ein Abfragepaket veröffentlicht wird, enthält es alle transitiven Abhängigkeiten und vorkompilierten Darstellungen jeder Abfrage, zusätzlich zu den Abfragequellen. Dadurch wird konsistentes und effizientes Ausführen der Abfragen im Paket sichergestellt.
Bibliothekspakete sind zum Verwenden durch Abfragepakete oder andere Bibliothekspakete konzipiert und enthalten selbst keine Abfragen. Die Bibliotheken werden nicht separat kompiliert.

Du kannst die Paketverwaltungsbefehle in der CodeQL CLI verwenden, um CodeQL-Pakete zu erstellen, Abhängigkeiten zu Paketen hinzuzufügen und Abhängigkeiten zu installieren oder zu aktualisieren. Weitere Informationen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen. Du kannst CodeQL-Pakete auch mit der CodeQL CLI veröffentlichen und herunterladen. Weitere Informationen findest du unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Die CodeQL-Standardpakete für alle unterstützten Sprachen werden im Container registry veröffentlicht. Das CodeQL-Repository enthält Quelldateien für die CodeQL-Standardpakete für alle unterstützten Sprachen.

CodeQL-Paketstruktur

Ein CodeQL-Paket muss in seinem Stammverzeichnis eine Datei namens qlpack.yml enthalten. In der Datei qlpack.yml muss das Feld name: einen Wert mit dem Format von <scope>/<pack> aufweisen, wobei <scope> der GitHub-Organisation oder dem -Benutzerkonto entspricht, in der oder dem das Paket veröffentlicht wird. Bei <pack> handelt es sich um den Namen des Pakets. Darüber hinaus enthalten Abfragepakete und Bibliothekspakete mit CodeQL-Tests eine codeql-pack.lock.yml-Datei mit den aufgelösten Abhängigkeiten des Pakets. Diese Datei wird während eines Aufrufs des Befehls codeql pack install generiert, soll nicht manuell bearbeitet werden und sollte deinem Versionskontrollsystem hinzugefügt werden.

Die anderen Dateien und Verzeichnisse innerhalb des Pakets sollten logisch organisiert sein. Hier findest du ein häufiges Beispiel:

Abfragen werden in Verzeichnissen für bestimmte Kategorien organisiert.
Abfragen für bestimmte Produkte, Bibliotheken und Frameworks werden in ihren eigenen Verzeichnissen der obersten Ebene organisiert.

Herunterladen und Verwenden von CodeQL-Abfragepaketen

Hinweis: Die CodeQL-Paketverwaltungsfunktionen, einschließlich CodeQL-Paketen, befinden sich derzeit in der Betaphase und können noch geändert werden.

Das CodeQL CLI-Paket enthält Abfragen, die von GitHub-Experten, Sicherheitsforschern und Community-Mitwirkenden verwaltet werden. Wenn du Abfragen ausführen möchtest, die von anderen Organisationen entwickelt wurden, bieten CodeQL-Abfragepakete eine effiziente und zuverlässige Möglichkeit zum Herunterladen und Ausführen von Abfragen. Weitere Informationen findest du unter Informationen zu Codescans mit CodeQL.

Bevor du ein CodeQL-Paket verwenden kannst, um eine Datenbank zu analysieren, müssen alle Pakete heruntergeladen werden, die du aus der GitHub Container registry benötigst. Dies kann durch Verwendung des Flags --download als Teil des Befehls codeql database analyze erfolgen. Wenn ein Paket nicht öffentlich verfügbar ist, musst du eine GitHub App oder ein personal access token zum Authentifizieren verwenden. Weitere Informationen und ein Beispiel findest du unter Hochladen von Ergebnissen in GitHub Enterprise Cloud.

Option	Erforderlich	Verwendung
`<scope/name@version:path>`		Gib unter Verwendung einer durch Trennzeichen getrennten Liste den Bereich und den Namen von mindestens einem CodeQL-Abfragepaket an, das heruntergeladen werden soll. 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`		Übergebe die CLI an die GitHub App oder das personal access token, das zur Authentifizierung mit der REST-API von GitHub aus deinem Geheimnisspeicher über die Standardeingabe erstellt wurde. Dies ist nicht erforderlich, wenn der Befehl über Zugriff auf `GITHUB_TOKEN`-Umgebungsvariablen verfügt, die mit diesem Token festgelegt wurden.

Hinweis: Wenn du eine bestimmte Version eines zu verwendenden Abfragepakets angibst, solltest du beachten, dass die von dir angegebene Version irgendwann veraltet sein kann, sodass die neueste Version von CodeQL sie nicht mehr effektiv nutzen kann. Um eine optimale Leistung zu gewährleisten, solltest du bei jedem Upgrade der verwendeten CodeQL CLI neu abwägen, welche Versionen du anpinnst, wenn du genaue Abfragepaketversionen angeben musst.

Weitere Informationen zur Paketkompatibilität findest du unter Veröffentlichen und Verwenden von CodeQL-Paketen.

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/security-queries@1.0.0
> Installed fresh octo-org/optional-security-queries@1.0.2
> 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.

Direktes Herunterladen von CodeQL-Paketen

Wenn du ein CodeQL-Paket herunterladen möchtest, ohne es sofort auszuführen, kannst du den Befehl codeql pack download verwenden. Dies ist nützlich, wenn du bei der Ausführung von CodeQL-Abfragen den Zugriff auf das Internet vermeiden möchtest. Wenn du die CodeQL-Analyse ausführst, kannst du Pakete, Versionen und Pfade auf die gleiche Weise wie im vorherigen Beispiel angeben:

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

Herunterladen von CodeQL-Paketen aus mehreren GitHub-Containerregistrierungen

Wenn sich deine CodeQL-Pakete in mehreren Containerregistrierungen befinden, musst du der CodeQL CLI mitteilen, wo jedes Paket zu finden ist. Weitere Informationen findest du unter Anpassen des erweiterten Setups für 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 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. Globmuster werden nicht unterstützt.

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

Beispielabfragespezifizierer

codeql/python-queries: Alle Abfragen in der Standardabfragesammlung der neuesten Version des codeql/python-queries-Pakets
codeql/python-queries@1.2.3: Alle Abfragen in der Standardabfragesammlung von Version 1.2.3 des codeql/python-queries-Pakets
codeql/python-queries@~1.2.3: Alle Abfragen in der Standardabfragesammlung der neuesten Version des codeql/python-queries-Pakets (neuer als 1.2.3 und älter als 1.3.0)
codeql/python-queries:Functions: Alle Abfragen im Functions-Verzeichnis der neuesten Version des codeql/python-queries-Pakets
codeql/python-queries@1.2.3:Functions: Alle Abfragen im Functions-Verzeichnis der Version 1.2.3 des codeql/python-queries-Pakets
codeql/python-queries@1.2.3:codeql-suites/python-code-scanning.qls: Alle Abfragen im codeql-suites/python-code-scanning.qls-Verzeichnis der Version 1.2.3 des codeql/python-queries-Pakets
suites/my-suite.qls: Alle Abfragen in der suites/my-suite.qls-Datei relativ zum aktuellen Arbeitsverzeichnis

Tipp

Die Standardabfragesammlung der CodeQL-Standardabfragepakete 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: Die Standardabfragen zur Codeüberprüfung für C++. Dies ist die Standardabfragesammlung für dieses Paket.
cpp-security-extended.qls: Abfragen aus der cpp-code-scanning.qls-Standardsammlung für C++ sowie Abfragen mit geringerem Schweregrad und geringerer Genauigkeit
cpp-security-and-quality.qls: Abfragen aus cpp-security-extended.qls, sowie zusätzliche Abfragen zur Verwaltbarkeit und Zuverlässigkeit

Die Quellen für diese Abfragesammlungen sind im Repository CodeQL zu finden. Abfragesammlungen für andere Sprachen sind ähnlich.

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 lädt CodeQL diese Dateien anstelle der .ql-Quelle. 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.

Anpassen der Analyse mit CodeQL-Paketen

In diesem Artikel