Erstellen und Arbeiten mit CodeQL-Paketen

Sie können CodeQL Pakete verwenden, um Abfragen und Bibliotheken zu erstellen, zu teilen, darauf zu basieren und CodeQL auszuführen.

Wer kann dieses Feature verwenden?

CodeQL ist für die folgenden Repositorytypen verfügbar:

In diesem Artikel

Informationen über CodeQL-Pakete und CodeQL CLI

          CodeQL Pakete werden verwendet, um Abfragen und Bibliotheken zu erstellen, zu teilen, davon abhängig zu sein und auszuführen CodeQL .

Sie können den pack Befehl im CodeQL CLI Befehl verwenden, um Pakete zu erstellen CodeQL , Abhängigkeiten zu Paketen hinzuzufügen und Abhängigkeiten zu installieren oder zu aktualisieren. Sie können Pakete auch mit dem CodeQL Befehl veröffentlichen und herunterladenpack.

Erstellen eines Pakets CodeQL

Sie können ein CodeQL Paket erstellen, indem Sie den folgenden Befehl aus dem Checkout-Stammverzeichnis Ihres Projekts ausführen:

codeql pack init <scope>/<pack>

Dabei müssen Sie festlegen:

  •         `<scope>`: der Name der Organisation oder des GitHub Benutzerkontos, für die Sie veröffentlichen möchten.

  •         `<pack>`: Name des Pakets, das Sie erstellen.

Der codeql pack init Befehl 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

Hinweis

CodeQL-Modellpakete liegen derzeit als öffentliche Vorschau vor und können noch geändert werden. Modellpakete werden für die C/C++, C#, Java/Kotlin, Python, Ruby und Rust-Analyse unterstützt.

Der CodeQL-Modell-Editor in der CodeQL-Erweiterung für Visual Studio Code unterstützt Modellierungsabhängigkeiten für C#, Java/Kotlin, Python und Ruby.

Modellpakete können zum Erweitern code scanning der Analyse verwendet werden, 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 zur code scanning Analyse hinzugefügt. Weitere Informationen zu CodeQL Modellpaketen und Datenerweiterungen finden Sie unter Using the CodeQL model editor.

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. 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 finden Sie unter Verwenden der semantischen Versionsverwaltung in der NPM Dokumentation und unter Spezifikation zur semantischen Versionsverwaltung.

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

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

Hinweis

Dies wird nur für CodeQL Abfrage- und Bibliothekspakete unterstützt.

Sie können Abhängigkeiten von CodeQL Paketen mithilfe des Befehls codeql pack addhinzufü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.

Hinweis

  • Durch Ausführen der Befehle codeql pack add und codeql pack install wird die codeql-pack.lock.yml-Datei generiert oder aktualisiert. Diese Datei sollte in die Versionskontrolle eingecheckt werden. Die codeql-pack.lock.yml-Datei enthält die genauen Versionsnummern, die vom Paket verwendet werden. Weitere Informationen finden Sie unter Informationen zu codeql-pack.lock.yml-Dateien.
  • Standardmäßig installiert codeql pack install Abhängigkeiten von der Container registry auf GitHub.com. Sie können Abhängigkeiten aus einer GitHub Enterprise ServerContainer registry Datei installieren, indem Sie eine qlconfig.yml Datei erstellen. Weitere Informationen finden Sie in der Dokumentation unter GitHub Enterprise Server.

Organisieren der Verzeichnisstruktur eines CodeQL Pakets

Ein CodeQL-Paket muss eine Datei enthalten, die qlpack.yml genannt wird und sich im Stammverzeichnis befindet. In der qlpack.yml Datei muss das name: Feld über einen Wert verfügen, der dem Format folgt <scope>/<pack>, wobei <scope> es sich um die GitHub Organisation oder das Benutzerkonto handelt, in der das Paket veröffentlicht wird und <pack> der Name des Pakets ist.

Darüber hinaus enthalten Abfragepakete und Bibliothekspakete mit CodeQL Tests eine codeql-pack.lock.yml Datei, die die aufgelösten Abhängigkeiten des Pakets enthält. 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.

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 Quell-Repository verfügbar ist und Sie Änderungen auf einem paket basieren müssen, das aus dem Container registryPaket heruntergeladen wurde, beachten Sie, dass diese Pakete nach dem Herunterladen nicht geändert oder angepasst werden sollen, und ihr Format kann sich in Zukunft ohne große Ankündigung ändern. 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 Fällen werden sie von CodeQL gegenüber der geänderten QL-Quelle bevorzugt verwendet.