Skip to main content

Diese Version von GitHub Enterprise Server wurde eingestellt am 2024-03-26. Es wird keine Patch-Freigabe vorgenommen, auch nicht für kritische Sicherheitsprobleme. Für bessere Leistung, verbesserte Sicherheit und neue Features aktualisiere auf die neueste Version von GitHub Enterprise Server. Wende dich an den GitHub Enterprise-Support, um Hilfe zum Upgrade zu erhalten.

Erstellen und Arbeiten mit CodeQL-Paketen

Du kannst CodeQL-Pakete verwenden, um CodeQL-Abfragen und -Bibliotheken zu erstellen, freizugeben, auszuführen oder Abhängigkeiten von diesen zu erstellen.

Wer kann dieses Feature verwenden?

GitHub CodeQL wird nach der Installation auf Benutzerbasis lizenziert. Du kannst CodeQL nur für bestimmte Aufgaben unter den Lizenzeinschränkungen verwenden. Weitere Informationen findest du unter Informationen zur CodeQL-CLI.

Wenn du über eine GitHub Advanced Security-Lizenz verfügst, kannst du CodeQL für eine automatisierte Analyse sowie für Continuous Integration und Continuous Delivery verwenden. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Hinweis: Die CodeQL-Paketverwaltungsfunktionen (einschließlich der CodeQL-Pakete) sind derzeit als Betaversion verfügbar und können noch geändert werden. Während der Betaversion sind CodeQL-Pakete nur mit GitHub-Paketen verfügbar – in der Container registry. Um diese Betafunktion zu verwenden, installiere die neueste Version des CodeQL CLI-Bundles aus https://github.com/github/codeql-action/releases.

Informationen zu CodeQL-Paketen und der CodeQL CLI

Hinweis: In diesem Artikel werden die Features beschrieben, die im CodeQL CLI 2.12.7-Bundle im ursprünglichen Release von GitHub Enterprise Server 3.8 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.

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

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.

Ändern eines vorhandenen QL-Legacypakets zum Erstellen eines CodeQL-Abfragepakets

Wenn du bereits über eine qlpack.yml-Datei verfügst, kannst du sie manuell bearbeiten, um sie in ein CodeQL-Paket zu konvertieren.

  1. Bearbeite die name-Eigenschaft so, dass sie dem Format <scope>/<name> entspricht, wobei <scope> der Name der GitHub-Organisation oder des Benutzerkontos ist, in die bzw. das du veröffentlichen möchtest.

  2. Schließe in der qlpack.yml-Datei eine version-Eigenschaft mit einem SemVer-Bezeichner sowie einen optionalen dependencies-Block ein.

  3. Migriere die Liste der Abhängigkeiten in libraryPathDependencies zum dependencies-Block. Gib den Versionsbereich für jede Abhängigkeit an. Wenn der Bereich nicht wichtig ist oder du dir der Kompatibilität nicht sicher bist, kannst du "\*" angeben. Dies legt fest, dass jede Version akzeptabel ist und standardmäßig die neueste Version verwendet wird, wenn du codeql pack install ausführst.

Weitere Informationen zu den Eigenschaften finden Sie unter Anpassen der Analyse mit CodeQL-Paketen.

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

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

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.

Hinweise:

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

  • codeql pack install installiert Abhängigkeiten standardmäßig über die Container registry auf GitHub.com. Du kannst Abhängigkeiten über eine GitHub Enterprise Server-Container registry installieren, indem du eine qlconfig.yml-Datei erstellst. Weitere Informationen finden Sie unter Veröffentlichen und Verwenden von CodeQL-Paketen in der GitHub Enterprise Server-Dokumentation.