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 /-Format verwenden, wobei 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.

Wenn du Skripts schreibst, die eine bestimmte Versionsnummer eines Abfragepakets angeben, das heruntergeladen werden soll, solltest du daran denken, dass du möglicherweise zu einer neueren Version des Abfragepakets wechseln musst, wenn du deine Version von CodeQL auf eine höhere Version aktualisierst. 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 Informationen zur CodeQL-Paketkompatibilität.

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. Beispiel:

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

Informationen zur CodeQL-Paketkompatibilität

Wenn ein Abfragepaket veröffentlicht wird, enthält es vorkompilierte Darstellungen aller Abfragen darin. Die Ausführung dieser vorkompilierten Abfragen ist in der Regel viel schneller als die Kompilierung der QL-Quelle während der Analyse von Grund auf. Die vorkompilierten Abfragen hängen jedoch auch von bestimmten internen Komponenten des QL-Evaluators ab. Wenn sich also die CodeQL-Version, die die Analyse durchführt, zu sehr von der Version unterscheidet, die codeql pack publish ausgeführt hat, kann es erforderlich sein, die Abfragen stattdessen während der Analyse aus der Quelle zu kompilieren. Die Neukompilierung erfolgt automatisch und wirkt sich nicht auf die Ergebnisse der Analyse aus, kann die Analyse jedoch erheblich verlangsamen.

Es kann im Allgemeinen davon ausgegangen werden, dass die vorkompilierten Abfragen direkt von späteren Releases von CodeQL verwendet werden können, wenn ein Paket mit einem Release von CodeQL veröffentlicht wird, solange zwischen den Releaseterminen nicht mehr als sechs Monate liegen. Wir geben unser Bestes, um neue Releases länger kompatibel zu halten, können dies jedoch nicht versprechen.

Es kann auch davon ausgegangen werden, dass ein Paket, das vom neuesten öffentlichen Release von CodeQL veröffentlicht wird, von der CodeQL-Version verwendet werden kann, die vom code scanning und GitHub Actions verwendet wird, obwohl dies häufig ein etwas älteres Release ist.

Als Ausnahme sind Pakete, die mit CodeQL-Versionen vor Version 2.12.0 veröffentlicht wurden, nicht mit früheren oder höheren Versionen kompatibel. Diese alten Versionen haben keine vorkompilierten Abfragen in einem Format geschrieben, das die Kompatibilität zwischen Releases unterstützte. Von diesen Versionen veröffentlichte Pakete können weiterhin von neueren Versionen verwendet werden, aber die Analyse ist langsamer, da die Abfragen zuerst neu kompiliert werden müssen.

Als Benutzer*in eines veröffentlichten Abfragepakets kannst du überprüfen, ob CodeQL die darin vorkompilierten Abfragen verwendet, indem du die Terminalausgabe einer Analyseausführung überprüfst, die das Abfragepaket verwendet. Wenn sie Zeilen wie die folgenden enthält, wurden die vorkompilierten Abfragen erfolgreich verwendet:

[42/108] Loaded /long/path/to/query/Filename.qlx.

Wenn sie jedoch wie folgt aussieht, ist bei der Verwendung der vorkompilierten Abfragen ein Fehler aufgetreten:

Compiling query plan for /long/path/to/query/Filename.ql.
[42/108 comp 25s] Compiled /long/path/to/query/Filename.ql.

Die Ergebnisse der Analyse sind in diesem Fall zwar gut, aber um eine optimale Leistung zu erzielen, musst du möglicherweise auf eine neuere Version der CodeQL-CLI und/oder des Abfragepakets upgraden.

Wenn du Abfragepakete für die Container registry auf GitHub.com für andere Benutzerinnen veröffentlichst, wird empfohlen, ein neues Release von CodeQL für die Ausführung von codeql pack publish zu verwenden und eine neue Version deines Pakets mit einer upgedateten CodeQL-Version zu veröffentlichen, bevor die verwendete Version älter als sechs Monate ist. Auf diese Weise kannst du sicherstellen, dass Benutzerinnen, die dein Paket verwenden und ihre CodeQL-Version aktuell halten, von den vorkompilierten Abfragen in deinem Paket profitieren.

Wenn du Abfragepakete mit der Absicht veröffentlichst, sie im Zusammenhang mit einer GitHub Enterprise Server-Installation zu verwenden, die die gebündelten CodeQL-Binärdateien verwendet, verwende dieselbe CodeQL-Version für die Ausführung von codeql pack publish. Neuere Versionen können vorkompilierte Abfragen erzeugen, die die in GitHub Enterprise Server verwendete Version möglicherweise nicht erkennt. Deine GitHub Enterprise Server-Administrator*innen können in regelmäßigen Abständen auf eine neuere Version von CodeQL upgraden. Wenn dies der Fall ist, befolge die entsprechenden Anweisungen.

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.