Referenz zu CodeQL-Abfragepaketen

CodeQL Packkompatibilität

Wenn ein Abfragepaket veröffentlicht wird, enthält es vorkompilierte Darstellungen aller Darin enthaltenen Abfragen, um die Analysegeschwindigkeit zu erhöhen. Wenn die Version dieser CodeQL Analyse jedoch über 6 Monate neuer als die ausgeführte codeql pack publishVersion ist, kann es erforderlich sein, die Abfragen aus der Quelle während der Analyse zu kompilieren und den Prozess erheblich zu verlangsamen.

Ein Paket, das mit dem neuesten öffentlichen Release von CodeQL veröffentlicht wurde, kann von der Version von CodeQL verwendet werden, die von code scanning und GitHub Actions verwendet wird, obwohl diese oft ein etwas älterer Release ist.

Wenn Ihre Analyse Zeilen wie die folgenden enthält, dann verwendet CodeQL erfolgreich vorkompilierte Abfragen:

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

Wenn Ihre Analyse stattdessen Zeilen enthält, die wie die folgenden aussehen, dann hat CodeQL die Abfragen manuell aus dem Quellcode neu kompiliert:

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

Damit Benutzer Ihres Abfragepakets vorkompilierte Abfragen nutzen können, empfehlen wir, zum Veröffentlichen Ihrer Pakete eine aktuelle Version von CodeQL zu verwenden. Darüber hinaus sollten Sie alle 6 Monate eine neue Version Ihres Pakets mit einer aktualisierten CodeQL Version veröffentlichen.

Wenn Sie Abfragepakete mit der Absicht veröffentlichen, sie in einer GitHub Enterprise Server Installation zu verwenden, die die gebündelten CodeQL Binärdateien verwendet, verwenden Sie dieselbe CodeQL Version, um sie auszuführen codeql pack publish.

qlpack.yml-Dateien

Beim Ausführen abfragebezogener Befehle sucht zuerst in gleichgeordneten Elementen des Installationsverzeichnisses CodeQL (und deren Unterverzeichnisse) nach qlpack.yml Dateien, und überprüft dann den Paketcache auf heruntergeladene CodeQL Pakete. Dies bedeutet, dass, wenn Ihre lokalen Pakete im Installationsverzeichnis Pakete mit demselben Namen im Paketcache außer Kraft setzen, damit Sie ihre lokalen Änderungen testen können.

Die Metadaten in jeder qlpack.yml Datei geben an CodeQL , wie Sie Abfragen im Paket kompilieren, welche Bibliotheken das Paket benötigt, und wo Sie Abfragesuitedefinitionen finden können.

Der Inhalt des CodeQL Pakets (Abfragen oder Bibliotheken, die in CodeQL der Analyse verwendet werden) ist im selben Verzeichnis enthalten wie qlpack.yml, oder seine Unterverzeichnisse.

Das Verzeichnis, das die qlpack.yml Datei enthält, dient als Stammverzeichnis für den Inhalt des CodeQL Pakets. Das heißt, für alle .ql- und .qll-Dateien im Paket löst CodeQL alle Importanweisungen relativ zu dem Verzeichnis auf, das die Datei qlpack.yml im Stammverzeichnis 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 Geltungsbereich des Pakets, wo das CodeQL Paket veröffentlicht wird, und den Namen des Pakets, der mit alphanumerischen Zeichen und Bindestrichen definiert wird. Es muss eindeutig sein, da CodeQL keine Unterscheidung zwischen CodeQL Paketen mit identischen Namen möglich ist. Verwenden Sie den Packnamen, um Abfragen anzugeben, die mit database analyze ausgeführt werden sollen, und um Abhängigkeiten zwischen CodeQL-Packs 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. Beispiel:

  version: 0.0.0
  

dataExtensions

• Erforderlich für Modellpakete.
• Enthält eine Liste von Globmustern, die angeben, wo sich Datenerweiterungsdateien relativ zum Stamm des Abfragepakets oder Bibliothekspakets befinden.

dependencies

• Erforderlich für Abfrage- und Bibliothekspakete, die Paketabhängigkeiten für andere Pakete definieren CodeQL . Modellpakete können keine Abhängigkeiten definieren und stattdessen extensionTargets verwenden.

• 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. 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 angibt, dass dieses CodeQL-Paket von der Version der Abhängigkeit abhängt, die sich im selben Arbeitsbereich befindet. Weitere Informationen finden Sie unter CodeQL-Arbeitsbereiche.

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

  defaultSuite:
    queries: .
    exclude:
      precision: medium
  

extensionTargets

• Erforderlich für Modellpakete.
• Deklariert, auf welche Abfrage die Erweiterungen im Modellpaket angewendet werden. Das Erweiterungspaket fügt seine Datenerweiterungen in jedes Paket ein, das im extensionTargets Schlüsselverzeichnis benannt ist, wenn das Paket in den angegebenen Versionsbereich fällt und in der Auswertung verwendet wird.

groups

• Dies ist 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 Paket im angegebenen Arbeitsbereich ist in der Liste enthalten, wenn:

  • Es befindet sich in mindestens einer der Gruppen, die ohne Minuszeichen aufgeführt sind (diese Bedingung wird automatisch erfüllt, wenn keine Gruppen ohne Minuszeichen aufgeführt sind).
  • 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 standardabfragepakete unterstützt, die im CodeQL CLI-Bundle enthalten sind.
• Diese Option wird für CodeQL Pakete, die aus der GitHub Containerregistrierung heruntergeladen wurden, nicht unterstützt.

tests

• Optional für Pakete, die CodeQL Tests enthalten. 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, die CodeQL Tests enthalten.

• Definiert den CodeQL Sprachextraktor, der beim Ausführen der CodeQL Tests des Pakets verwendet werden soll. Weitere Informationen zum Testen von Abfragen findest du unter Testen benutzerdefinierter Abfragen. Beispiel:

  extractor: javascript-typescript
  

authors

• Dies ist optional.

• Definiert Metadaten, die auf der Seite "Verpackungssuche" im Abschnitt "Pakete" des Kontos angezeigt werden, in dem das CodeQL Paket veröffentlicht wird. Beispiel:

  authors: author1@github.com,author2@github.com
  

license

• Dies ist optional.

• Definiert Metadaten, die auf der Seite "Verpackungssuche" 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

• Dies ist optional.

• Definiert Metadaten, die auf der Seite "Verpackungssuche" 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, Schließen. Verwenden Sie stattdessen die dependencies-Eigenschaft.

• Zuvor verwendet, um die Namen aller CodeQL Pakete zu definieren, von denen dieses CodeQL Paket abhängig ist, als Array. 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 Datenbank, die mit einer anderen Version der CodeQL CLI CLI erstellt wurde, mit der aktuellen Version der CLI kompatibel ist. Beispiel:

  upgrades: .
  

warnOnImplicitThis

• Dies ist 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. Beispiel:

  warnOnImplicitThis: true
  

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 selben CodeQL-Arbeitsbereich wie das Paket verfügbar sein. Weitere Informationen zu CodeQL Arbeitsbereichen und zum Auflösen von Abhängigkeiten aus der Quelle finden Sie unter CodeQL-Arbeitsbereiche.

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.

Beispiel für benutzerdefinierte CodeQL Pakete

Sie sollten Dateien für benutzerdefinierte Abfragen und Tests in separaten Paketen speichern und benutzerdefinierte Pakete in bestimmten Ordnern für jede Zielsprache organisieren.

CodeQL Pakete für benutzerdefinierte Bibliotheken

Ein benutzerdefiniertes Paket mit benutzerdefinierten CodeQL C++-Bibliotheken ohne Abfragen oder Tests kann eine qlpack.yml Datei enthalten, die Folgendes enthält:

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

wobei codeql/cpp-all der Name des CodeQL-Pakets für die C/C++-Analyse ist, das im Repository CodeQL 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 CodeQL Bibliotheksdatei (eine Datei mit einer .qll Erweiterung), die in diesem Paket definiert ist, ist für Abfragen verfügbar, die in jedem Abfragepaket definiert sind, das dieses Paket in den Abhängigkeitenblock einschließt.

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

CodeQL Pakete für benutzerdefinierte Abfragen

Ein benutzerdefiniertes Paket mit benutzerdefinierten CodeQL C++-Abfragen und -Bibliotheken enthält möglicherweise eine qlpack.yml Datei mit:

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

wobei codeql/cpp-all der Name des CodeQL Pakets für die C/C++-Analyse ist, das im Repository CodeQL 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, das benutzerdefinierte CodeQL Bibliotheken für C++ enthält. Jede CodeQL bibliotheksdatei (eine Datei mit einer .qll Erweiterung), die in diesem Paket definiert ist, ist für Abfragen im my-github-user/my-custom-queries Paket verfügbar.

CodeQL Pakete für benutzerdefinierte Tests

Für benutzerdefinierte CodeQL Pakete, die Testdateien enthalten, müssen Sie auch eine extractor Eigenschaft einschließen, damit der test run Befehl weiß, wie Testdatenbanken erstellt werden. 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-kotlin
tests: .

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

Beispielpakete CodeQL im CodeQL Repository

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

• Kernbibliothekspaket für die Sprache, mit dem Datenbankschema, das von der Sprache verwendet wird, sowie 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: Zeigt 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 für CodeQL CLI intern und sollten nur im zentralen CodeQL-Abfragepaket 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 Abfrage-Pack 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 dem Quellcode findest du unter Quellcode-Abhängigkeiten.

• suites: Gibt das Verzeichnis an, das „bekannte“ Abfrage-Suites enthält.

• defaultSuiteFile: Der Name der standardmäßigen Abfrage-Suite-Datei, die verwendet wird, wenn keine Abfrage-Suite angegeben ist.

Tests für das Kern-CodeQLPaket

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 hängt von den kernen CodeQL Abfrage- und Bibliothekspaketen für C++ ab.

• extractor: Hier wird festgelegt, dass alle Tests denselben C++-Extraktor verwenden, um die Datenbank für die Tests zu erstellen.

• tests: Hier wird der Ort der Tests angegeben. 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.