Informationen zu CodeQL-Paketen

Informationen zu CodeQL-Paketen

CodeQL-Pakete werden verwendet, um CodeQL-Abfragen und -Bibliotheken zu erstellen, zu teilen, auszuführen und sie als Abhängigkeiten zu nutzen. Du kannst deine eigenen CodeQL-Pakete veröffentlichen und von anderen Personen erstellte Pakete herunterladen. CodeQL-Pakete enthalten Abfragen, Bibliotheksdateien, Abfragesammlungen und Metadaten.

Es gibt zwei Arten von CodeQL-Paketen: Abfragepakete und Bibliothekspakete.

• Abfragepakete sind zum Ausführen konzipiert. Wenn ein Abfragepaket veröffentlicht wird, enthält es alle transitiven Abhängigkeiten und und einem Kompilierungscache. Dadurch wird konsistentes und effizientes Ausführen der Abfragen im Paket sichergestellt.

• Bibliothekspakete sind zum Verwenden durch Abfragepakete oder andere Bibliothekspakete konzipiert und enthalten selbst keine Abfragen. Die Bibliotheken werden nicht , und beim Veröffentlichen des Pakets ist kein Kompilierungscache enthalten.

Du kannst die Paketverwaltungsbefehle in der CodeQL CLI verwenden, um CodeQL-Pakete zu erstellen, Abhängigkeiten zu Paketen hinzuzufügen und Abhängigkeiten zu installieren oder zu aktualisieren. Weitere Informationen findest du unter Erstellen von und Arbeiten mit CodeQL-Paketen. Du kannst CodeQL-Pakete auch mit der CodeQL CLI veröffentlichen und herunterladen. Weitere Informationen findest du unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Die CodeQL-Standardpakete für alle unterstützten Sprachen werden im Container registry veröffentlicht. Das CodeQL-Repository enthält Quelldateien für die CodeQL-Standardpakete für alle unterstützten Sprachen.

CodeQL-Paketstruktur

Ein CodeQL-Paket muss in seinem Stammverzeichnis eine Datei namens qlpack.yml enthalten. In der Datei qlpack.yml muss das Feld name: einen Wert mit dem Format von <scope>/<pack> aufweisen, wobei <scope> der GitHub-Organisation oder dem -Benutzerkonto entspricht, in der oder dem das Paket veröffentlicht wird. Bei <pack> handelt es sich um den Namen des Pakets. Darüber hinaus enthalten Abfragepakete und Bibliothekspakete mit CodeQL-Tests eine codeql-pack.lock.yml-Datei mit den aufgelösten Abhängigkeiten des Pakets. Diese Datei wird während eines Aufrufs des Befehls codeql pack install generiert, soll nicht manuell bearbeitet werden und sollte deinem Versionskontrollsystem hinzugefügt werden.

Die anderen Dateien und Verzeichnisse innerhalb des Pakets sollten logisch organisiert sein. Hier findest du ein häufiges Beispiel:

• Abfragen werden in Verzeichnissen für bestimmte Kategorien organisiert.

• Abfragen für bestimmte Produkte, Bibliotheken und Frameworks werden in ihren eigenen Verzeichnissen der obersten Ebene organisiert.

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 du deine lokalen Änderungen testen kannst.

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

  version: 0.0.0
  

dependencies

• Erforderlich für Pakete, 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 Beispiel:

  dependencies:
    codeql/cpp-all: ^0.0.2`
  

defaultSuiteFile

• Required by packs that export a set of default queries to run.
• Defines the path to a query suite file relative to the package root, containing all of the queries that are run by default when this pack is passed to the codeql database analyze command. Supported from CLI version v2.6.0 and onwards. Only one of defaultSuiteFile or defaultSuite can be defined. For example:

  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
  

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
• Definiert den Pfad zu einem Verzeichnis im Paket, das die Abfragesammlungen enthält, die du der relativ zum Paketverzeichnis definierten CodeQL CLI bereitstellen möchtest. CodeQL-Paketbenutzer*innen können in diesem Verzeichnis gespeicherten, bekannten Sammlungen ausführen, indem sie den Paketnamen ohne dessen vollständigen Pfad angeben. Dies wird für aus der Containerregistrierung heruntergeladene CodeQL-Pakete nicht unterstützt. Weitere Informationen zu Abfragesammlungen findest du unter Erstellen von CodeQL-Abfragesammlungen. Beispiel:

  suites: octo-org-query-suites
  

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 von benutzerdefinierten Abfragen. 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 findest du 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 Verwende 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: .
  

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

Beispiele für benutzerdefinierte CodeQL-Pakete

Wenn du benutzerdefinierte Abfragen oder Tests schreibst, solltest du sie in benutzerdefinierten CodeQL-Paketen speichern. Versuche der Einfachheit halber, jedes Paket logisch zu organisieren. Weitere Informationen findest du unter CodeQL-Paketstruktur. Speichere Dateien für Abfragen und Tests in separaten Paketen, und organisiere nach Möglichkeit benutzerdefinierte Pakete in bestimmten Ordnern für jede Zielsprache. Dies ist besonders nützlich, wenn du deine CodeQL-Pakete veröffentlichen möchtest, 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
suites: my-custom-suites

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.

Die Eigenschaft suites gibt ein Verzeichnis an, in dem bekannte Abfragesammlungen gefunden werden können. Diese Sammlungen können in der Befehlszeile verwendet werden, indem nur auf ihren Namen und nicht auf den vollständigen Pfad verwiesen wird. Weitere Informationen zu Abfragesammlungen findest du unter Erstellen von CodeQL-Abfragesammlungen.

CodeQL-Pakete für benutzerdefinierte Tests

Für benutzerdefinierte CodeQL-Pakete mit Testdateien musst du auch eine extractor-Eigenschaft einschließen, damit der Befehl test run weiß, wie Testdatenbanken erstellt werden sollen. Du kannst 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 von benutzerdefinierten 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 siehst du 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 QL-Basispaket 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 siehst du 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.