Veröffentlichen und Verwenden von CodeQL-Paketen

Arbeiten mit CodeQL Paketen an GitHub Enterprise-Cloud mit Datenresidenz

Standardmäßig erwartet CodeQL CLI, dass Pakete von CodeQL heruntergeladen und auf Container registry bei GitHub.com veröffentlicht werden. Sie können jedoch auch mit CodeQL Paketen in einem Container registry auf GitHub Enterprise-Cloud mit Datenresidenz arbeiten, indem Sie eine qlconfig.yml Datei erstellen, um dem CLI mitzuteilen, welche Container registry für jedes Paket verwendet werden soll.

Erstellen Sie eine ~/.codeql/qlconfig.yml-Datei unter Linux/MacOS oder %HOMEPATH%\.codeql\qlconfig.yml auf Windows mit Ihrem bevorzugten Text-Editor, und fügen Sie Einträge hinzu, um anzugeben, welche Registrierung für ein oder mehrere Paketnamenmuster verwendet werden soll. Die folgende qlconfig.yml-Datei ordnet zum Beispiel alle Pakete dem Container registry an SUBDOMAIN.ghe.com zu, mit Ausnahme von Paketen, die codeql/\* entsprechen oder der other-org/*-Organisation angehören, welche dem Container registry an GitHub.com zugeordnet sind:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `SUBDOMAIN.ghe.com`
  url: https://containers.SUBDOMAIN.ghe.com

Das CodeQL CLI wird bestimmen, welche Registrierung für einen bestimmten Paketnamen verwendet werden soll, indem das erste Element in der registries-liste gesucht wird, das eine packages-Eigenschaft hat, die diesem Paketnamen entspricht. Dies bedeutet, dass du im Allgemeinen zuerst die spezifischsten Paketnamenmuster definieren musst. Die packages-Eigenschaft kann ein einzelner Paketname, ein Globmuster oder eine YAML-Liste mit Paketnamen und Globmustern sein.

Die registries Liste kann auch innerhalb einer codeql-workspace.yml Datei platziert werden. Auf diese Weise können Sie die Registrierungen definieren, die in einem bestimmten Arbeitsbereich verwendet werden sollen, damit sie unter anderen CodeQL Benutzern des Arbeitsbereichs geteilt werden können. Die registriesListe in codeql-workspace.yml wird mit der Liste in der globalen qlconfig.yml zusammengeführt und hat Vorrang vor ihr. Weitere Informationen zu codeql-workspace.yml findest du unter Informationen zu CodeQL-Arbeitsbereichen.

Sie können jetzt codeql pack publish, codeql pack download und codeql database analyze verwenden, um Pakete auf GitHub Enterprise-Cloud mit Datenresidenz zu verwalten.

Authentifizierung für GitHubContainer registries

Sie können Pakete veröffentlichen und private Pakete herunterladen, indem Sie sich bei der entsprechenden GitHubContainer registry anmelden.

Authentifizierung bei Container registries auf GitHub.com

Sie können sich auf zwei Arten bei Container registry authentifizieren:

Übergeben Sie die --github-auth-stdin Option an den CodeQL CLI, und geben Sie dann ein GitHub Apps Token oder personal access token über die Standardeingabe an.
Legen Sie die Umgebungsvariable GITHUB_TOKEN auf ein GitHub Apps Token oder personal access tokenein .

Authentifizierung bei Container registries auf GitHub Enterprise-Cloud mit Datenresidenz

Ebenso können Sie sich bei einem Container registry auf GitHub Enterprise-Cloud mit Datenresidenz authentifizieren oder sich bei mehreren Registrys gleichzeitig authentifizieren — z. B. zum Herunterladen oder Ausführen privater Pakete aus mehreren Registrys — auf zwei verschiedene Arten:

Übergeben Sie die --registries-auth-stdin Option an den CodeQL CLI, und geben Sie dann eine Registrierungsauthentifizierungszeichenfolge über die Standardeingabe an.
Legen Sie die Umgebungsvariable CODEQL_REGISTRIES_AUTH auf eine Registrierungsauthentifizierungs-Zeichenfolge fest.

Eine Registrierungsauthentifizierungszeichenfolge ist eine durch Kommas getrennte Liste von <registry-url>=<token>-Paaren, wobei registry-url eine Container registry-URL ist, z.B. https://containers.SUBDOMAIN.ghe.com, und token ein GitHub Apps-Token oder personal access token für diese Container registry ist. Dadurch wird sichergestellt, dass jedes Token nur an die Container registry angegebene Person übergeben wird.

Die folgende Registrierungsauthentifizierungszeichenfolge gibt beispielsweise an, dass die CodeQL CLI Authentifizierung wie folgt erfolgt:

Verwenden Sie das Token <token1>, um sich bei Container registry auf GitHub.com zu authentifizieren.
Verwenden Sie das Token <token2>, um sich beim Container registry für das Unternehmen an https://containers.SUBDOMAIN.ghe.com zu authentifizieren.

https://ghcr.io/v2/=<token1>,https://containers.SUBDOMAIN.ghe.com=<token2>

Veröffentlichen Ihres CodeQL Pakets

Wenn Sie Ihr CodeQL Paket für andere Personen freigeben möchten, können Sie es in der Container registryDatei veröffentlichen.

Konfigurieren der `qlpack.yml`-Datei vor der Veröffentlichung

Sie können die Konfigurationsdetails Ihres CodeQL Pakets vor der Veröffentlichung überprüfen und ändern. Öffnen Sie die qlpack.yml-Datei in Ihrem bevorzugten Text-Editor.

library: # set to true if the pack is a library. Set to false or omit for a query pack
name: <scope>/<pack>
version: <x.x.x>
description: <Description to publish with the package>
defaultSuite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
defaultSuiteFile: default-queries.qls # optional, a pointer to a query-suite in this pack
license: # optional, the license under which the pack is published
dependencies: # map from CodeQL pack name to version range

        `name:` muss dem `<scope>/<pack>` Format folgen, wobei `<scope>` die Organisation ist, zu der Sie veröffentlichen, und `<pack>` der Name für das Paket ist.

Es ist maximal eine defaultSuite- bzw. defaultSuiteFile-Komponente zulässig. Dies sind zwei verschiedene Möglichkeiten, eine auszuführende Standardabfragesammlung zu definieren: die erste durch direktes Angeben von Abfragen in der Datei „qlpack.yml“ und die zweite durch Angeben einer Abfragesammlung im Paket.

Wird ausgeführt `codeql pack publish`

Wenn Sie bereit sind, ein Paket auf GitHubContainer registry zu veröffentlichen, können Sie den folgenden Befehl im Stammverzeichnis des Pakets ausführen:

codeql pack publish

Das veröffentlichte Paket wird im Abschnitt "Pakete" der GitHub Organisation angezeigt, der durch den Bereich in der qlpack.yml Datei angegeben ist.

Hinweis

Wenn Sie Modellpakete veröffentlichen, um die GitHubContainer registry-Abdeckung auf alle Repositorys in einer Organisation als Teil einer Standardkonfiguration zu erweitern, müssen Sie sicherstellen, dass Repositorys, die Codescanning ausführen, auf diese Modellpakete zugreifen können. Weitere Informationen findest du unter Bearbeiten der Konfiguration des Standardsetups und Konfigurieren der Zugriffssteuerung und Sichtbarkeit von Paketen.

Herunterladen eines vorhandenen CodeQL Pakets

Um ein Paket auszuführen, das eine andere Person erstellt hat, müssen Sie es zuerst herunterladen, indem Sie den folgenden Befehl ausführen:

codeql pack download <scope>/<pack>@x.x.x

        `<scope>`: der Name der Organisation, von der Sie herunterladen.

        `<pack>`: der Name des Pakets, das du herunterladen möchtest.

        `@x.x.x`: eine optionale Versionsnummer. Wenn sie nicht angegeben wird, wird die neueste Version heruntergeladen.

Dieser Befehl akzeptiert Argumente für mehrere Pakete.

Wenn Sie Skripts schreiben, die eine bestimmte Versionsnummer eines herunterzuladenden Abfragepakets angeben, denken Sie daran, dass Sie möglicherweise auch zu einer neueren Version des Abfragepakets wechseln müssen, wenn Sie Ihre Version CodeQL auf eine neuere Version des Abfragepakets aktualisieren. Neuere Versionen von CodeQL_können_ eine beeinträchtigte Leistung bieten, wenn sie mit Abfragepaketen verwendet wird, die an eine sehr alte Version angeheftet wurden. Weitere Informationen findest du unter Referenz zu CodeQL-Abfragepaketen.

Verwenden eines CodeQL Pakets zum Analysieren einer CodeQL Datenbank

Führen Sie den folgenden Befehl aus, um eine CodeQL Datenbank mit einem CodeQL Paket zu analysieren:

codeql database analyze <database> <scope>/<pack>@x.x.x:<path>

        `<database>`: die CodeQL zu analysierende Datenbank.

        `<scope>`: der Name der GitHub Organisation, in der das Paket veröffentlicht wird.

        `<pack>`: der Name des Packs, das du verwendest.

        `@x.x.x`: eine optionale Versionsnummer. Wenn sie nicht angegeben wird, wird die neueste Version verwendet.

        `:<path>`: ein optionaler Pfad zu einer Abfrage, einem Verzeichnis oder einer Suite von Abfragen. Wenn dieser nicht angegeben wird, wird die Standardabfragesammlung des Pakets verwendet.

Der analyze Befehl führt die Standardsuite aller angegebenen CodeQL Pakete aus. Sie können mehrere CodeQL Pakete angeben, die für die Analyse einer CodeQL Datenbank verwendet werden sollen. Beispiel:

codeql <database> analyze <scope>/<pack> <scope>/<other-pack>