Veröffentlichen und Verwenden von CodeQL-Paketen

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

Du kannst die Konfigurationsdetails deines CodeQL-Pakets vor der Veröffentlichung überprüfen und ändern. Öffne die qlpack.yml-Datei in deinem 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>
default-suite: # optional, one or more queries in the pack to run by default
    - query: <relative-path>/query-file>.ql
default-suite-file: 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 das <scope>/<pack>-Format verwenden, wobei <scope> die GitHub-Organisation, in die du veröffentlichen möchtest, und der Name des Pakets ist.

• Es ist maximal eine default-suite- bzw. default-suite-file-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 du bereit bist, ein Paket in der GitHub-Container registry zu veröffentlichen, kannst du 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.

Wird ausgeführt codeql pack download <scope>/<pack>

Um ein Paket auszuführen, das eine andere Person erstellt hat, musst du es zuerst herunterladen, indem du den folgenden Befehl ausführst:

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

• <scope>: Name der GitHub-Organisation, von der du das Paket herunterladen möchtest
• <pack>: Name des Pakets, das du herunterladen möchtest
• @x.x.x: Optionale Versionsnummer. Wenn sie nicht angegeben wird, wird die neueste Version heruntergeladen.

Dieser Befehl akzeptiert Argumente für mehrere Pakete.

Verwenden eines CodeQL-Pakets zum Analysieren einer CodeQL-Datenbank

Führe 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>: CodeQL-Datenbank, die analysiert werden soll
• <scope>: Name der GitHub-Organisation, in die das Paket veröffentlicht wird
• <pack>: Name des Pakets, das du verwendest
• @x.x.x: Optionale Versionsnummer. Wenn sie nicht angegeben wird, wird die neueste Version verwendet.
• :<path>: Optionaler Pfad zu einer Abfrage, einem Verzeichnis oder einer Abfragesammlung. Wenn dieser nicht angegeben wird, wird die Standardabfragesammlung des Pakets verwendet.

Der analyze-Befehl führt die Standardsammlung aller angegebenen CodeQL-Pakete aus. Du kannst mehrere CodeQL-Pakete angeben, die für die Analyse einer CodeQL-Datenbank verwendet werden sollen. Zum Beispiel:

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

Arbeiten mit CodeQL-Paketen in GitHub Enterprise Server

Standardmäßig erwartet die CodeQL CLI, dass CodeQL-Pakete aus der Container registry auf GitHub.com heruntergeladen und dort veröffentlicht werden. Du kannst jedoch auch mit CodeQL-Paketen in einer Container registry auf GitHub Enterprise Server arbeiten, indem du eine qlconfig.yml-Datei erstellst, um der CLI mitzuteilen, welche Container registry für jedes Paket verwendet werden soll.

Erstelle eine ~/.codeql/qlconfig.yml-Datei mit deinem bevorzugten Text-Editor, und füge Einträge hinzu, um anzugeben, welche Registrierung für ein oder mehrere Paketnamenmuster verwendet werden soll. In der folgenden qlconfig.yml-Datei werden beispielsweise alle Pakete der Container registry für GitHub Enterprise Server unter GHE_HOSTNAME zugeordnet, mit Ausnahme von den mit codeql/\* übereinstimmenden Paketen, die der Container registry auf GitHub.com zugeordnet sind:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  url: https://ghcr.io/v2/
- packages: '*'
  url: https://containers.GHE_HOSTNAME/v2/

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 in einer codeql-workspace.yml-Datei platziert werden. Auf diese Weise kannst du die Registrierungen definieren, die in einem bestimmten Arbeitsbereich verwendet werden sollen, sodass sie für andere CodeQL-Benutzer*innen des Arbeitsbereichs freigegeben werden können. Die registries-Liste in codeql-workspace.yml wird mit der Liste in der globalen qlconfig.yml-Datei zusammengeführt und hat Vorrang vor dieser. 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 zum Verwalten von Paketen in GitHub Enterprise Server verwenden.

Authentifizieren bei GitHub-Container registries

Du kannst Pakete veröffentlichen und private Pakete herunterladen, indem du dich bei der entsprechenden GitHub-Container registry authentifizieren.

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

1. Übergebe die Option --github-auth-stdin an die CodeQL CLI, und übermittle dann ein GitHub Apps-Token oder personal access token über die Standardeingabe.
2. Lege die Umgebungsvariable GITHUB_TOKEN auf ein GitHub Apps-Token oder personal access token fest.

Ebenso kannst du dich auf zwei Arten bei einer GitHub Enterprise Server-Container registry oder bei mehreren Registrierungen gleichzeitig authentifizieren (z. B. zum Herunterladen oder Ausführen privater Pakete aus mehreren Registrierungen):

1. Übergebe die --registries-auth-stdin-Option an die CodeQL CLI, und übermittle dann eine Registrierungsauthentifizierungs-Zeichenfolge über die Standardeingabe.
2. Lege die Umgebungsvariable CODEQL_REGISTRIES_AUTH auf eine Registrierungsauthentifizierungs-Zeichenfolge fest.

Eine Registrierungsauthentifizierungs-Zeichenfolge ist eine durch Kommas getrennte Liste von <registry-url>=<token>-Paaren, wobei registry-url eine Container registry-URL (z. B. https://containers.GHE_HOSTNAME/v2/) und token ein GitHub Apps-Token oder personal access token für diese GitHub-Container registry ist. Dadurch wird sichergestellt, dass jedes Token nur an die von dir angegebene Container registry übergeben wird. Die folgende Registrierungsauthentifizierungs-Zeichenfolge gibt beispielsweise an, dass sich die CodeQL CLI bei der Container registry auf GitHub.com mithilfe des Tokens <token1> und bei der Container registry für die GHES-Instanz unter GHE_HOSTNAME mithilfe des Tokens <token2> authentifizieren soll:

https://ghcr.io/v2/=<token1>,https://containers.GHE_HOSTNAME/v2/=<token2>