Erstellen und Arbeiten mit CodeQL-Paketen

Informationen zu CodeQL-Paketen und der CodeQL CLI

CodeQL-Pakete werden verwendet, um CodeQL-Abfragen und -Bibliotheken zu erstellen, zu teilen, auszuführen und sie als Abhängigkeiten zu nutzen. CodeQL-Pakete enthalten Abfragen, Bibliotheksdateien, Abfragesammlungen und Metadaten. Mit CodeQL-Paketen und den Paketverwaltungsbefehlen in der CodeQL CLI kannst du deine benutzerdefinierten Abfragen veröffentlichen und in deine Codebaseanalyse integrieren.

Es gibt drei Typen von CodeQL Paketen: Abfragepakete, Bibliothekspakete und Modellpakete.

• Abfragepakete sind zum Ausführen konzipiert. Wenn ein Abfragepaket veröffentlicht wird, enthält das Paket zusätzlich zu den Abfragequellen alle transitiven Abhängigkeiten und vorkompilierte Darstellungen jeder Abfrage. 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 separat kompiliert.

• Modellpakete können verwendet werden, um die code scanning-Analyse zu erweitern, um Abhängigkeiten einzuschließen, die standardmäßig nicht unterstützt werden. Modellpakete befinden sich derzeit in beta und können geändert werden. Während der beta stehen Modellpakete für die Java/Kotlin-Analyse zur Verfügung. Weitere Informationen zum Erstellen eigener Modellpakete findest du unter Erstellen eines CodeQL.

Du kannst den pack-Befehl in der CodeQL CLI verwenden, um CodeQL-Pakete zu erstellen, Abhängigkeiten zu Paketen hinzuzufügen und Abhängigkeiten zu installieren oder zu aktualisieren. Du kannst CodeQL-Pakete auch mithilfe des pack-Befehls veröffentlichen und herunterladen. Weitere Informationen finden Sie unter Veröffentlichen und Verwenden von CodeQL-Paketen.

Weitere Informationen zur Kompatibilität zwischen veröffentlichten Abfragepaketen und verschiedenen CodeQL-Releases 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. Die Basisabfragepakete, die im CodeQL CLI-Bundle enthalten sind, die aber andernfalls auch heruntergeladen werden können, sind:

• codeql/cpp-queries
• codeql/csharp-queries
• codeql/go-queries
• codeql/java-queries
• codeql/javascript-queries
• codeql/python-queries
• codeql/ruby-queries

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.

Erstellen eines CodeQL-Pakets

Du kannst ein CodeQL-Paket erstellen, indem du den folgenden Befehl über den Check-Out-Stamm deines Projekts ausführst:

codeql pack init <scope>/<pack>

Dabei musst du Folgendes festlegen:

• <scope>: Name der GitHub-Organisation oder des Benutzerkontos, in die bzw. das du veröffentlichen möchtest

• <pack>: Name des Pakets, das du erstellst

Der Befehl codeql pack init erstellt die Verzeichnisstruktur und Konfigurationsdateien für ein CodeQL-Paket. Der Befehl erstellt standardmäßig ein Abfragepaket. Wenn du ein Bibliothekspaket erstellen möchtest, musst du die qlpack.yml-Datei bearbeiten, um die Datei explizit als Bibliothekspaket zu deklarieren, indem du die Eigenschaft library:true einschließt.

Erstellen eines CodeQL-Modellpakets

Modellpakete können verwendet werden, um die code scanning-Analyse zu erweitern, um Bibliotheken und Frameworks zu erkennen, die standardmäßig nicht unterstützt werden. Modellpakete verwenden Datenerweiterungen, die als YAML implementiert werden und beschreiben, wie Daten für neue Abhängigkeiten hinzugefügt werden. Wenn ein Modellpaket angegeben wird, werden die Datenerweiterungen in diesem Paket automatisch der code scanning hinzugefügt. Weitere Informationen zu CodeQL-Paketen findest du unter Verwenden des CodeQL-Modell-Editors.

Ein Modellpaket ist ein CodeQL Paket mit den folgenden Merkmalen in der qlpack.yml Datei:

• Dieses definiert library: true.
• Es hat keine Abhängigkeiten.
• Es hat mindestens eine extensionTargets.
• Es verfügt über eine dataExtensions Eigenschaft, die auf eine oder mehrere Datenerweiterungsdateien verweist.

Ein Modellpaket fügt seine angegebenen Datenerweiterungen in jedes Abfragepaket ein, das in extensionTargets benannt ist, wenn es in den angegebenen Versionsbereich fällt. Zum Beispiel:

name: my-repo/my-java-model-pack
version: 1.2.3
extensionTargets:
  codeql/java-all: ~1.2.3
  codeql/util: ~4.5.6
dataExtensions:
  - models/**/*.yml

In diesem Beispiel fügt das Modellpaket alle Datenerweiterungen in models/**/ ein Abfragepaket codeql/java-all mit einer Version von 1.2.3 bis zu einschließlich 1.3.0 ein, und in ein Abfragepaket codeql/util mit einer Version von 4.5.6 bis zu einschließlich 4.6.0. Weitere Informationen findest du unter Using semantic versioning (Verwenden der semantischen Versionsverwaltung) in der NPM-Dokumentation und unter Semantic versioning specification (Spezifikation zur semantischen Versionsverwaltung).

Nachdem Sie ein Modellpaket erstellt haben, können Sie es auf die gleiche Weise veröffentlichen wie andere CodeQL-Pakete. Weitere Informationen finden Sie unter Veröffentlichen und Verwenden von CodeQL-Paketen. Anschließend können Sie veröffentlichte Modellpakete in einer code scanning-Analyse mit der Option --model-packs verwenden. Weitere Informationen finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.

Installieren von und Hinzufügen von Abhängigkeiten zu einem CodeQL-Paket

Du kannst CodeQL-Paketen mit dem codeql pack add-Befehl Abhängigkeiten hinzufügen. Du musst den Bereich, den Namen und (optional) einen kompatiblen Versionsbereich angeben.

codeql pack add <scope>/<name>@x.x.x <scope>/<other-name>

Wenn du keinen Versionsbereich angibst, wird die neueste Version hinzugefügt. Andernfalls wird die neueste Version hinzugefügt, die den angeforderten Bereich erfüllt.

Dieser Befehl aktualisiert die qlpack.yml-Datei mit den angeforderten Abhängigkeiten und lädt sie in den Paketcache herunter. Beachte, dass mit diesem Befehl die Datei neu formatiert wird und alle Kommentare entfernt werden.

Du kannst die qlpack.yml-Datei auch manuell bearbeiten, um Abhängigkeiten einzuschließen, und dann kannst du die Abhängigkeiten mit dem folgenden Befehl installieren:

codeql pack install

Mit diesem Befehl werden alle Abhängigkeiten in den freigegebenen Cache auf dem lokalen Datenträger heruntergeladen.

Anpassen eines heruntergeladenen CodeQL-Pakets

Die empfohlene Methode, mit Änderungen an einem Paket zu experimentieren, besteht darin, das Repository mit dem Quellcode zu klonen.

Wenn kein Quellrepository verfügbar ist und du grundlegende Änderungen an einem Paket vornehmen musst, das aus der Container registry heruntergeladen wurde, solltest du beachten, dass diese Pakete nicht für Änderungen oder Anpassungen nach dem Herunterladen konzipiert sind und sich ihr Format in Zukunft ohne große Ankündigung ändern kann. Es wird empfohlen, nach dem Herunterladen eines Pakets die folgenden Schritte auszuführen, wenn du den Inhalt ändern musst:

• Ändere den Namen des Pakets in qlpack.yml, um Verwechslungen mit den Ergebnissen des nicht geänderten Pakets zu vermeiden.

• Entferne alle Dateien namens *.qlx in der entpackten Verzeichnisstruktur. Diese Dateien enthalten vorkompilierte Versionen der Abfragen, und in einigen Situationen verwendet CodeQL sie anstelle der geänderten QL-Quelle.