Veröffentlichen und Verwenden von CodeQL-Paketen

Arbeiten mit CodeQL Packs auf GitHub Enterprise-Cloud mit Datenresidenz

Standardmäßig erwartet die CodeQL CLI, dass CodeQL-Pakete aus der Container registry auf GitHub.com heruntergeladen und dort veröffentlicht werden. Du kannst aber auch mit CodeQL Packs in einer Container registry auf GitHub Enterprise-Cloud mit Datenresidenz arbeiten, indem du eine qlconfig.yml Datei erstellst, die dem CLI mitteilt, welche Container registry für jedes Pack 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. In der folgenden qlconfig.yml-Datei werden zum Beispiel alle Pakete mit der Container registry unter SUBDOMAIN.ghe.com verknüpft, mit Ausnahme der Pakete, die codeql/\* oder der other-org/* Organisation entsprechen, die mit der Container registry auf GitHub.com verknüpft 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

Die CodeQL CLI bestimmt, welche Registrierung für einen angegebenen Paketnamen verwendet werden soll, indem das erste Element in der registries-Liste mit einer packages-Eigenschaft ermittelt wird, das 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, sodass sie für andere CodeQL-Benutzer des Arbeitsbereichs freigegeben 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.

Du kannst jetzt codeql pack publish, codeql pack download und codeql database analyze verwenden, um Pakete auf GitHub Enterprise-Cloud mit Datenresidenz zu verwalten.

Authentifizierung bei GitHub Container registries

Du kannst Packs veröffentlichen und private Packs herunterladen, indem du dich bei den entsprechenden GitHub authentifizierst. Container registry.

Authentifizierung bei Container registries auf GitHub.com

Du kannst dich bei der Container registry auf zwei Arten authentifizieren:

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

Authentifizierung bei Container registries auf GitHub Enterprise-Cloud mit Datenresidenz

Ebenso kannst du dich an einer Container registry auf GitHub Enterprise-Cloud mit Datenresidenz authentifizieren oder dich an mehreren Registrierungen gleichzeitig authentifizieren (z.B. um private Packs von mehreren Registrierungen herunterzuladen oder auszuführen), und zwar auf zwei Arten:

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

Eine Zeichenfolge zur Authentifizierung bei der Registrierung ist eine kommagetrennte Liste von <registry-url>=<token> Paaren, wobei registry-url eine Container registry URL ist, wie 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 von Ihnen angegebene Container registry übergeben wird.

Die folgende Zeichenfolge zur Authentifizierung in der Registrierung legt zum Beispiel fest, dass sich CodeQL CLI wie folgt authentifizieren soll:

Verwende das Token <token1> zur Authentifizierung bei Container registry auf GitHub.com.
Benutze das Token <token2>, um dich bei der Container registry für das Unternehmen unter https://containers.SUBDOMAIN.ghe.com zu authentifizieren.

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

Veröffentlichung Ihres CodeQL Pakets

Um Ihr CodeQL-Paket mit anderen zu teilen, können Sie es in der Container registry 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 GitHub Organisation ist, in der du veröffentlichen wirst und `<pack>` der Name für das Pack 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 in der GitHub-Container registry zu veröffentlichen, können Sie den folgenden Befehl im Stammverzeichnis des Paketverzeichnisses ausführen:

codeql pack publish

Das veröffentlichte Paket wird im Paketabschnitt der GitHub-Organisation angezeigt, die durch den Bereich in der qlpack.yml-Datei angegeben wird.

Hinweis

Wenn du Model Packs an den GitHub veröffentlichst Container registry veröffentlichst, um die Abdeckung als Element einer Standard-Einrichtung auf alle Repositories in einer Organisation auszuweiten, musst du sicherstellen, dass Repositories, die Code-Scans ausführen, auf diese Model Packs 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 GitHub Organisation, von der du das Paket herunterladen wirst.

        `<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 du Skripte schreibst, die eine bestimmte Versionsnummer eines herunterzuladenden Abfragepakets angeben, denke daran, dass du, wenn du deine Version von CodeQL auf eine neuere Version aktualisierst, möglicherweise auch auf eine neuere Version des Abfragepakets umsteigen musst. Neuere Versionen von CodeQL bieten möglicherweise eine schlechtere Leistung, wenn sie mit Abfragepaketen verwendet werden, 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 auszuführen:

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

        `<database>`: die CodeQL Datenbank, die analysiert werden soll.

        `<scope>`: der Name der GitHub Organisation, bei der das Pack 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 Standardsammlung 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>