Veröffentlichen und Verwenden von CodeQL-Paketen

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 in 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 mit deinem bevorzugten Text-Editor unter Linux/macOS eine ~/.codeql/qlconfig.yml-Datei oder unter Windows ein %HOMEPATH%\.codeql\qlconfig.yml-Datei, und füge Einträge hinzu, um anzugeben, welche Registrierung für mindestens ein Paketnamenmuster verwendet werden soll. In der folgenden qlconfig.yml-Datei werden beispielsweise alle Pakete der Container registry unter https://GHE_HOSTNAME zugeordnet, mit Ausnahme von den mit codeql/\* oder der other-org/*-Organisation übereinstimmenden Paketen, die der Container registry auf GitHub.com zugeordnet werden:

registries:
- packages:
  - 'codeql/*'
  - 'other-org/*'
  # Container registry on GitHub.com
  url: https://ghcr.io/v2/
- packages: '*'
  # Container registry hosted at `https://GHE_HOSTNAME`
  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 eine codeql-workspace.yml-Datei eingefügt 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 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 codeql pack publish, codeql pack download und codeql database analyze jetzt verwenden, um Pakete in GitHub Enterprise Server zu verwalten.

Authentifizieren bei GitHub-Container registries

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

Authentifizieren bei Container registries auf GitHub.com

Du kannst dich auf zwei Arten bei der Container registry 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.

Authentifizieren bei Container registries in GitHub Enterprise Server

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

Ü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 Registrierungsauthentifizierungszeichenfolge 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 Container registry ist. Dadurch wird sichergestellt, dass jedes Token nur an die von Ihnen angegebene Container registry übergeben wird.

Die folgende Registrierungsauthentifizierungszeichenfolge gibt beispielsweise an, dass sich die CodeQL CLI wie folgt authentifizieren soll:

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

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

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

Note

In diesem Artikel werden die Features beschrieben, die im CodeQL CLI 2.13.5-Bundle im ursprünglichen Release von GitHub Enterprise Server 3.10 enthalten sind.

Wenn dein Websiteadministrator deine CodeQL CLI auf eine neuere Version aktualisiert hat, findest du in der GitHub Enterprise Cloud-Version dieses Artikels Informationen über die neuesten Features.

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 das <scope>/<pack>-Format verwenden, wobei <scope> die GitHub-Organisation, in die Sie veröffentlichen möchten, und <pack> der Name des Pakets 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.

Ausführung von `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.

Note

Wenn du Modellpakete auf dem GitHub-Container registry veröffentlichst, um die Abdeckung auf alle Repositorys in einer Organisation als Teil einer Standardeinrichtungskonfiguration zu erweitern, musst du sicherstellen, dass Repositorys, die Codeüberprüfung 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.

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

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>: Name der GitHub-Organisation, von der Sie das Paket herunterladen möchtest
<pack>: Name des Pakets, das Sie herunterladen möchten
@x.x.x: 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 Abfragepakets angeben, das heruntergeladen werden soll, sollten Sie daran denken, dass Sie möglicherweise zu einer neueren Version des Abfragepakets wechseln müssen, wenn Sie Ihre Version von CodeQL auf eine höhere Version aktualisieren. 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 finden Sie unter Informationen zur CodeQL-Paketkompatibilität.

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>: CodeQL-Datenbank, die analysiert werden soll
<scope>: Name der GitHub-Organisation, in die das Paket veröffentlicht wird
<pack>: Name des Pakets, das Sie verwenden
@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. Sie können 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>

Note

Der Befehl codeql pack download speichert das heruntergeladene Paket an einem internen Speicherort, der nicht für lokale Änderungen vorgesehen ist. Unerwartetes (und schwer zu behebendes) Verhalten kann auftreten, wenn das Paket nach dem Herunterladen geändert wird. Weitere Informationen zur Anpassung von Paketen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

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 Benutzer eines veröffentlichten Abfragepakets können Sie überprüfen, ob CodeQL die darin vorkompilierten Abfragen verwendet, indem Sie die Terminalausgabe einer Analyseausführung überprüfen, 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, müssen Sie möglicherweise ein Upgrade auf eine neuere Version der CodeQL CLI und/oder des Abfragepakets ausführen.

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

Wenn Sie Abfragepakete mit der Absicht veröffentlichen, sie im Zusammenhang mit einer GitHub Enterprise Server-Installation zu verwenden, die die gebündelten CodeQL-Binärdateien verwendet, verwenden Sie 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. Ihre GitHub Enterprise Server-Administrator können in regelmäßigen Abständen auf eine neuere Version von CodeQL upgraden. Wenn dies der Fall ist, befolgen Sie die entsprechenden Anweisungen.

Informationen zu `qlpack.yml`-Dateien

Beim Ausführen abfragebezogener Befehle sucht CodeQL zunächst in gleichgeordneten Elementen des Installationsverzeichnisses und deren Unterverzeichnissen nach qlpack.yml-Dateien. Anschließend wird der Paketcache auf heruntergeladene CodeQL-Pakete überprüft. Dies bedeutet, dass die lokalen Pakete im Installationsverzeichnis beim lokalen Entwickeln von Abfragen Pakete mit demselben Namen im Paketcache überschreiben, sodass Sie Ihre lokalen Änderungen testen können.

Die Metadaten in jeder qlpack.yml-Datei teilen CodeQL mit, wie Abfragen im Paket kompiliert werden sollen, von welchen Bibliotheken das Paket abhängig ist und wo Abfragesammlungsdefinitionen zu finden sind.

Der Inhalt des CodeQL-Pakets ist im selben Verzeichnis wie qlpack.yml oder den Unterverzeichnissen enthalten. Dabei handelt es sich um in der CodeQL-Analyse verwendete Abfragen oder Bibliotheken.

Das Verzeichnis mit der Datei qlpack.yml dient als Stammverzeichnis für den Inhalt des CodeQL-Pakets. Das heißt, dass CodeQL alle Importanweisungen für alle .ql- und .qll-Dateien im Paket relativ zu dem Verzeichnis auflöst, das die qlpack.yml-Datei im Stamm des Pakets enthält.

`qlpack.yml`-Eigenschaften

Die folgenden Eigenschaften werden in qlpack.yml-Dateien unterstützt.

`name`

Erforderlich für alle Pakete
Definiert den Umfang des Pakets, wo das CodeQL-Paket veröffentlicht wird und den Namen des Pakets, der mit alphanumerischen Zeichen und Bindestrichen definiert wird. Er muss eindeutig sein, da CodeQL nicht zwischen CodeQL-Paketen mit identischen Namen unterscheiden kann. Verwenden Sie den Packnamen, um Abfragen anzugeben, die mit database analyze ausgeführt werden sollen, und um Abhängigkeiten zwischen CodeQL-Paketen zu definieren (siehe Beispiele unten). Beispiel:
```
name: octo-org/security-queries
```

`version`

Erforderlich für alle veröffentlichten Pakete
Definiert eine semantische Version für dieses CodeQL-Paket, die der SemVer v2.0.0-Spezifikation entsprechen muss Zum Beispiel:
```
version: 0.0.0
```

`dependencies`

Erforderlich für Abfrage- und Bibliothekspakete, die CodeQL-Paketabhängigkeiten in anderen Pakete definieren.
Definiert eine Zuordnung der Packverweise zum semantischen Versionsbereich, der mit diesem Paket kompatibel ist. Unterstützt für CodeQL CLI-Versionen v2.6.0 und höher Zum Beispiel:
```
dependencies:
  codeql/cpp-all: ^0.0.2
```
Wenn Sie unsicher sind oder es keine Rolle spielt, welche Version verwendet werden soll, können Sie "*" verwenden, was bedeutet, dass jede Version dieser Abhängigkeit mit diesem Paket kompatibel ist. In der Praxis wird dies in der Regel in die höchste veröffentlichte Version der Abhängigkeit aufgelöst.

Es gibt einen speziellen Versionsplatzhalter, ${workspace}, der anzeigt, dass dieses CodeQL-Paket von der Version der Abhängigkeit abhängt, die sich im selben Arbeitsbereich befindet. Weitere Informationen finden Sie unter Informationen zu CodeQL-Arbeitsbereichen.

`defaultSuiteFile`

Erforderlich für Pakete, die Standardabfragen zum Ausführen exportieren
Definiert den Pfad zu einer Abfragesammlungsdatei relativ zum Paketstamm, die alle Abfragen enthält, die standardmäßig ausgeführt werden, wenn dieses Paket an den Befehl codeql database analyze übergeben wird. Unterstützt für CLI-Version v2.6.0 und höher. Nur defaultSuiteFile oder defaultSuite kann definiert werden. Beispiel:
```
defaultSuiteFile: cpp-code-scanning.qls
```

`defaultSuite`

Erforderlich für Pakete, die Standardabfragen zum Ausführen exportieren
Definiert eine Inline-Abfragesammlung mit allen Abfragen, die standardmäßig ausgeführt werden, wenn dieses Paket an den Befehl codeql database analyze übergeben wird. Unterstützt für CLI-Version v2.6.0 und höher. Nur defaultSuiteFile oder defaultSuite kann definiert werden. Zum Beispiel:
```
defaultSuite:
  queries: .
  exclude:
    precision: medium
```

`groups`

Optional.
Definiert logische Gruppierungen von Paketen in einem CodeQL-Arbeitsbereich. Die Verwendung von Gruppen ist eine Möglichkeit, Packvorgänge auf Teilmengen von Paketen in einem Arbeitsbereich anzuwenden. Beispielsweise wird das folgende Paket als Teil der java- und experimental-Gruppen definiert:
```
groups:
  - java
  - experimental
```
Beim Ausführen von codeql pack publish --groups java,-experimental werden alle Pakete in der java-Gruppe veröffentlicht, mit Ausnahme der experimental-Pakete. Sie können den codeql pack ls --groups [-]<group>[,[-]<group>...]-Befehl ausführen, um die Pakete in einem Arbeitsbereich aufzulisten, der mit der angegebenen Gruppe übereinstimmt.

Ein CodeQL im angegebenen Arbeitsbereich ist dann in der Liste enthalten, wenn:
- Es sich in mindestens einer der Gruppen befindet, die ohne Minuszeichen aufgeführt sind (diese Bedingung wird automatisch erfüllt, wenn keine Gruppen ohne Minuszeichen aufgeführt werden).
- Es sich in keiner Gruppe befindet, die mit einem Minuszeichen aufgeführt ist.

`library`

Erforderlich für Bibliothekspakete
Definiert einen booleschen Wert, der angibt, ob es sich bei diesem Paket um ein Bibliothekspaket handelt. Bibliothekspakete enthalten keine Abfragen und werden nicht kompiliert. Für Abfragepakete kann dieses Feld ignoriert oder explizit auf false festgelegt werden. Beispiel:
```
library: true
```

`suites`

Optional für Pakete, die Abfragesammlungen definieren Auf diese Weise können Benutzer Abfragesammlungen ausführen, die im angegebenen Verzeichnis gespeichert sind, indem du den Paketnamen angibst, ohne den vollständigen Pfad anzugeben.
Wird derzeit nur für die standardmäßigen Abfragepakete unterstützt, die im CodeQL CLI-Paket enthalten sind.
Diese Option wird für aus der GitHub-Containerregistrierung heruntergeladene CodeQL-Pakete nicht unterstützt.

`tests`

Optional für Pakete mit CodeQL-Tests. Wird für Pakete ohne Tests ignoriert
Definiert den Pfad zu einem Verzeichnis innerhalb des Pakets mit den Tests, der relativ zum Paketverzeichnis definiert ist. Verwende ., um das gesamte Paket anzugeben. Alle Abfragen in diesem Verzeichnis werden als Tests ausgeführt, wenn test run mit der Option --strict-test-discovery ausgeführt wird. Diese Abfragen werden von Abfragesammlungsdefinitionen ignoriert, die die Anweisungen queries oder qlpack verwenden, um alle Abfragen in einem bestimmten Paket abzufragen. Wenn diese Eigenschaft fehlt, wird . angenommen. Beispiel:
```
tests: .
```

`extractor`

Erforderlich für alle Pakete mit CodeQL-Tests
Definiert den CodeQL-Sprachextraktor, der beim Ausführen der CodeQL-Tests im Paket verwendet werden soll. Weitere Informationen zum Testen von Abfragen findest du unter Testen benutzerdefinierter Abfragen. Zum Beispiel:
```
extractor: javascript
```

`authors`

Optional.
Definiert Metadaten, die auf der Paketsuchseite im Abschnitt Pakete des Kontos angezeigt werden, in dem das CodeQL-Paket veröffentlicht wird Beispiel:
```
authors: author1@github.com,author2@github.com
```

`license`

Optional.
Definiert Metadaten, die auf der Paketsuchseite im Abschnitt Pakete des Kontos angezeigt werden, in dem das CodeQL-Paket veröffentlicht wird Eine Liste der zulässigen Lizenzen finden Sie unter SPDX-Lizenzliste in der SPDX-Spezifikation. Beispiel:
```
license: MIT
```

`description`

Optional.
Definiert Metadaten, die auf der Paketsuchseite im Abschnitt Pakete des Kontos angezeigt werden, in dem das CodeQL-Paket veröffentlicht wird Beispiel:
```
description: Human-readable description of the contents of the CodeQL pack.
```

`libraryPathDependencies`

Optional, veraltet Verwenden Sie stattdessen die dependencies-Eigenschaft.
Wurde zuvor verwendet, um die Namen von CodeQL-Paketen als Array zu definieren, von denen dieses CodeQL-Paket abhängig ist. Dadurch erhält das Paket Zugriff auf alle Bibliotheken, Datenbankschemas und Abfragesammlungen, die in der Abhängigkeit definiert sind. Beispiel:
```
libraryPathDependencies: codeql/javascript-all
```

`dbscheme`

Nur für die Basissprachpakete erforderlich
Definiert den Pfad zum Datenbankschema für alle Bibliotheken und Abfragen, die für diese CodeQL-Sprache geschrieben wurden (siehe Beispiel unten). Beispiel:
```
dbscheme: semmlecode.python.dbscheme
```

`upgrades`

Nur für die Basissprachpakete erforderlich
Definiert den Pfad zu einem Verzeichnis innerhalb des Pakets mit Datenbankupgradeskripts, der relativ zum Paketverzeichnis definiert ist. Datenbankupgrades werden intern verwendet, um sicherzustellen, dass eine mit einer anderen Version der CodeQL CLI erstellte Datenbank mit der aktuellen Version der CLI kompatibel ist. Beispiel:
```
upgrades: .
```

`warnOnImplicitThis`

Optional. Wird standardmäßig auf false festgelegt, wenn die Eigenschaft warnOnImplicitThis nicht definiert ist.
Definiert einen booleschen Wert, der angibt, ob der Compiler Warnungen zu Memberprädikataufrufen ausgeben soll, die implizite this-Anrufempfänger enthalten, also keine expliziten Empfänger. Verfügbar seit CodeQL CLI v2.13.2. Zum Beispiel:
```
warnOnImplicitThis: true
```

Informationen zu `codeql-pack.lock.yml`-Dateien

codeql-pack.lock.yml-Dateien speichern die Versionen der aufgelösten transitiven Abhängigkeiten eines CodeQL-Pakets. Diese Datei wird mit dem Befehl codeql pack install erstellt, wenn sie noch nicht vorhanden ist, und sollte deinem Versionskontrollsystem hinzugefügt werden. Der Abschnitt dependencies der Datei qlpack.yml enthält Versionsbereiche, die mit dem Paket kompatibel sind. Die Datei codeql-pack.lock.yml sperrt die Versionen für bestimmte Abhängigkeiten. Dadurch wird sichergestellt, dass beim Ausführen von codeql pack install in diesem Paket immer dieselben Versionen von Abhängigkeiten abgerufen werden, auch wenn neuere kompatible Versionen vorhanden sind.

Beispielsweise geschieht Folgendes, wenn eine qlpack.yml-Datei die folgenden Abhängigkeiten enthält:

dependencies:
  codeql/cpp-all: ^0.1.2
  my-user/my-lib: ^0.2.3
  other-dependency/from-source: "*"

Der Inhalt der Datei codeql-pack.lock.yml sieht in etwa wie folgt aus:

dependencies:
  codeql/cpp-all:
    version: 0.1.4
  my-user/my-lib:
    version: 0.2.4
  my-user/transitive-dependency:
    version: 1.2.4

Die Abhängigkeit codeql/cpp-all ist für Version 0.1.4 gesperrt. Die Abhängigkeit my-user/my-lib ist für Version 0.2.4 gesperrt. Die transitive Abhängigkeit my-user/transitive-dependency ist nicht in der Datei qlpack.yml angegeben und für Version 1.2.4 gesperrt. other-dependency/from-source fehlt in der Sperrdatei, da sie aus der Quelle aufgelöst wird. Diese Abhängigkeit muss im gleichen CodeQL-Arbeitsbereich wie das Paket verfügbar sein. Weitere Informationen zu CodeQL-Arbeitsbereichen und zum Auflösen von Abhängigkeiten aus der Quelle findest du unter Informationen zu CodeQL-Arbeitsbereichen.

In den meisten Fällen ist die Datei codeql-pack.lock.yml nur für Abfragepakete relevant, da Bibliothekspakete nicht ausführbar sind und ihre transitiven Abhängigkeiten in der Regel nicht behoben werden müssen. Eine Ausnahme sind Bibliothekspakete mit Tests. In diesem Fall wird die Datei codeql-pack.lock.yml verwendet, damit die Tests immer mit den gleichen Versionen von Abhängigkeiten ausgeführt werden, um falsch positive Fehler bei nicht übereinstimmenden Abhängigkeiten zu vermeiden.

Beispiele für benutzerdefinierte CodeQL-Pakete

Wenn Sie benutzerdefinierte Abfragen oder Tests schreiben, sollten Sie sie in benutzerdefinierten CodeQL-Paketen speichern. Versuchen Sie der Einfachheit halber, jedes Paket logisch zu organisieren. Weitere Informationen finden Sie unter Erstellen und Arbeiten mit CodeQL-Paketen. Speichern Sie Dateien für Abfragen und Tests in separaten Paketen, und organisieren Sie nach Möglichkeit benutzerdefinierte Pakete in bestimmten Ordnern für jede Zielsprache. Dies ist besonders nützlich, wenn Sie Ihre CodeQL-Pakete veröffentlichen möchten, damit sie für andere freigegeben oder für die Codeüberprüfung verwendet werden können. Weitere Informationen finden Sie unter Informationen zu Codescans mit CodeQL.

CodeQL-Pakete für benutzerdefinierte Bibliotheken

Ein benutzerdefiniertes CodeQL-Paket mit benutzerdefinierten C++-Bibliotheken ohne Abfragen oder Tests kann eine qlpack.yml-Datei mit Folgendem enthalten:

name: my-github-user/my-custom-libraries
version: 1.2.3
library: true
dependencies:
  codeql/cpp-all: ^0.1.2

Dabei ist codeql/cpp-all der Name des CodeQL-Pakets für die C/C++-Analyse, das im CodeQL-Repository enthalten ist. Der Versionsbereich ^0.1.2 gibt an, dass dieses Paket mit allen Versionen von codeql/cpp-all kompatibel ist, die 0.1.2 oder höher und unter 0.2.0 sind. Jede in diesem Paket definierte CodeQL-Bibliotheksdatei steht für Abfragen zur Verfügung, die in einem Abfragepaket definiert sind, das dieses Paket in seinem Abhängigkeitsblock enthält. Eine Bibliotheksdatei ist eine Datei mit einer .qll-Erweiterung.

Die Eigenschaft library gibt an, dass dieses Paket ein Bibliothekspaket ist und keine Abfragen enthält.

CodeQL-Pakete für benutzerdefinierte Abfragen

Ein benutzerdefiniertes CodeQL-Paket mit benutzerdefinierten C++-Abfragen und -Bibliotheken kann eine qlpack.yml-Datei mit Folgendem enthalten:

name: my-github-user/my-custom-queries
version: 1.2.3
dependencies:
  codeql/cpp-all: ^0.1.2
  my-github-user/my-custom-libraries: ^1.2.3

Dabei ist codeql/cpp-all der Name des CodeQL-Pakets für die C/C++-Analyse, das im CodeQL-Repository enthalten ist. Der Versionsbereich ^0.1.2 gibt an, dass dieses Paket mit allen Versionen von codeql/cpp-all kompatibel ist, die 0.1.2 oder höher und unter 0.2.0 sind. my-github-user/my-custom-libraries ist der Name eines CodeQL-Pakets mit benutzerdefinierten CodeQL-Bibliotheken für C++. Jede in diesem Paket definierte CodeQL-Bibliotheksdatei ist für Abfragen im Paket my-github-user/my-custom-queries verfügbar. Eine Bibliotheksdatei ist eine Datei mit einer .qll-Erweiterung.

CodeQL-Pakete für benutzerdefinierte Tests

Für benutzerdefinierte CodeQL-Pakete mit Testdateien müssen Sie auch eine extractor-Eigenschaft einschließen, damit der Befehl test run weiß, wie Testdatenbanken erstellt werden sollen. Sie können auch die Eigenschaft tests angeben.

Die folgende qlpack.yml-Datei gibt an, dass my-github-user/my-query-tests von my-github-user/my-custom-queries mit einer Version größer oder gleich 1.2.3 und niedriger als 2.0.0 abhängig ist. Außerdem wurde deklariert, dass die CLI den extractor von Java beim Erstellen von Testdatenbanken verwenden soll. Die tests: .-Zeile deklariert, dass alle .ql-Dateien im Paket als Tests ausgeführt werden sollen, wenn codeql test run mit der --strict-test-discovery-Option ausgeführt wird. In der Regel enthalten Testpakete keine version-Eigenschaft. Dadurch wird verhindert, dass diese versehentlich veröffentlicht werden.

name: my-github-user/my-query-tests
dependencies:
  my-github-user/my-custom-queries: ^1.2.3
extractor: java
tests: .

Weitere Informationen zum Ausführen von Tests findest du unter Testen benutzerdefinierter Abfragen.

Beispiele für CodeQL-Pakete im CodeQL-Repository

Jede der Sprachen im CodeQL-Repository verfügt über vier CodeQL-Hauptpakete:

Das Basisbibliothekspaket für die Sprache mit dem von der Sprache verwendeten Datenbankschema, CodeQL-Bibliotheken und Abfragen unter <language>/ql/lib
Das Basisabfragepaket für die Sprache, das die Standardabfragen für die Sprache sowie deren Abfragesammlungen unter <language>/ql/src enthält
Tests für die Basissprachbibliotheken und -abfragen unter <language>/ql/test
Beispielabfragen für die Sprache unter <language>/ql/examples

Basisbibliothekspaket

Hier sehen Sie eine qlpack.yml-Beispieldatei für die C/C++-Analysebibliotheken des Basissprachpakets:

name: codeql/cpp-all
version: x.y.z-dev
dbscheme: semmlecode.cpp.dbscheme
library: true
upgrades: upgrades

Einige zusätzliche Hinweise zu den folgenden Eigenschaften:

library: Gibt an, dass es sich um ein Bibliothekspaket ohne ausführbare Abfragen handelt. Es soll nur als Abhängigkeit für andere Pakete verwendet werden.
dbscheme und upgrades: Diese Eigenschaften sind CodeQL CLI-intern und sollten nur im Basisabfragepaket CodeQL für eine Sprache definiert werden.

Basisabfragepaket

Hier siehst du eine qlpack.yml-Beispieldatei für C/C++-Analyseabfragen des Basisabfragepakets:

name: codeql/cpp-queries
version: x.y.z-dev
dependencies:
    codeql/cpp-all: "*"
    codeql/suite-helpers: "*"
suites: codeql-suites
defaultSuiteFile: codeql-suites/cpp-code-scanning.qls

Einige zusätzliche Hinweise zu den folgenden Eigenschaften:

dependencies: Dieses Abfragepaket ist abhängig von codeql/cpp-all und codeql/suite-helpers. Da diese Abhängigkeiten aus der Quelle aufgelöst werden, spielt es keine Rolle, mit welcher Version des CodeQL-Pakets sie kompatibel sind. Weitere Informationen zum Auflösen von Abhängigkeiten aus der Quelle findest du unter Quellabhängigkeiten.
suites: gibt das Verzeichnis mit bekannten Abfragesammlungen an.
defaultSuiteFile: Der Name der Standardabfragesammlungsdatei, die verwendet wird, wenn keine Abfragesammlung angegeben ist

Tests für das CodeQL-Basispaket

Hier sehen Sie eine qlpack.yml-Beispieldatei für C/C++-Analysetests des Basistestpakets:

name: codeql/cpp-tests
dependencies:
  codeql/cpp-all: "*"
  codeql/cpp-queries: "*"
extractor: cpp
tests: .

Einige zusätzliche Hinweise zu den folgenden Eigenschaften:

dependencies: Dieses Paket ist abhängig von der CodeQL-Basisabfrage und den Bibliothekspaketen für C++.
extractor: Gibt an, dass alle Tests denselben C++-Extraktor zum Erstellen der Datenbank für die Tests verwenden
tests: Gibt den Standort der Tests an. In diesem Fall befinden sich die Tests im Stammordner und in allen Unterordnern des Pakets.
version: Es gibt keine version-Eigenschaft für das Testpaket. Dadurch wird verhindert, dass Testpakete versehentlich veröffentlicht werden.

Veröffentlichen und Verwenden von CodeQL-Paketen

Wer kann dieses Feature verwenden?

In diesem Artikel