# Erstellen von CodeQL-Abfragesammlungen Du kannst Abfragesammlungen für Abfragen erstellen, die du häufig in deinen CodeQL-Analysen verwendest. Sie können Abfragesammlungen für die Abfragen erstellen, die Sie häufig in Ihren CodeQL-Analysen verwenden möchten. Weitere Informationen finden Sie unter [CodeQL-Abfragesammlungen](/de/code-security/concepts/code-scanning/codeql/codeql-query-suites). > \[!NOTE] > Alle angepassten Abfragen, die Sie zu einer Abfrage-Suite hinzufügen möchten, müssen sich in einem [CodeQL-Paket](/de/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs) befinden und die richtigen Abfrage-Metadaten enthalten. Weitere Informationen finden Sie unter [Schreiben von benutzerdefinierten Abfragen für die CodeQL CLI](/de/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/writing-and-sharing-custom-queries-for-the-codeql-cli). ## Suchen nach Abfragen, die einer Abfragesammlung hinzugefügt werden sollen Beim Erstellen einer Abfragesammlung musst du zunächst die Speicherorte der Abfragen angeben, die du auswählen möchtest. Du kannst Folgendes verwenden, um den Speicherort einer oder mehrerer Abfragen zu definieren: * Eine `query` Anweisung: Weist CodeQL an, nach einer oder mehreren angegebenen `.ql` Dateien zu suchen: ```yaml - query: ``` Das Argument muss einem oder mehreren Dateipfaden entsprechen, relativ zum CodeQL-Paket, das die Sammlungsdefinition enthält. * Eine `queries` Anweisung: Weist CodeQL an, ein Verzeichnis rekursiv nach `.ql` Dateien zu durchsuchen: ```yaml - queries: ``` Der Pfad des Verzeichnisses muss relativ zum Stamm des CodeQL-Pakets sein, das die Sammlungsdefinitionsdatei enthält. Um die Abfragen relativ zu einem anderen CodeQL-Paket zu finden, füge ein `from`-Feld hinzu: ```yaml - queries: from: version: ^x.y.z ``` Das `version`-Feld ist optional und gibt einen Bereich kompatibler Versionen dieses CodeQL-Pakets an. Wenn du keine Version angibst, wird die aktuellste Version des Pakets verwendet. * A `qlpack` Anweisung: Weist CodeQL an, Abfragen in der Standardsuite des benannten Pakets CodeQL aufzulösen: ```yaml - qlpack: version: ^x.y.z ``` Die Standardsammlung eines Abfragepakets enthält eine empfohlene Gruppe von Abfragen innerhalb dieses Abfragepakets. Nicht alle Abfragepakete verfügen über eine Standardsammlung. Wenn das angegebene Abfragepaket keine Standardsammlung definiert, wird die qlpack-Anweisung in alle Abfragen innerhalb des Pakets aufgelöst. Das `version`-Feld ist optional und gibt einen Bereich kompatibler Versionen dieses CodeQL-Pakets an. Wenn du keine Version angibst, wird die aktuellste Version des Pakets verwendet. > \[!NOTE] > Wenn Pfadnamen in den Definitionen der Abfrage-Suite erscheinen, müssen sie immer mit einem Schrägstrich, `/`, als Verzeichnistrennzeichen angegeben werden. Dadurch wird sichergestellt, dass Abfragesammlungsdefinitionen auf allen Betriebssystemen funktionieren. Du musst deiner Sammlungsdefinition mindestens eine `query`-, `queries`- oder `qlpack`-Anweisung hinzufügen, da andernfalls keine Abfragen ausgewählt werden. Wenn die Sammlung keine weiteren Anweisungen enthält, werden alle Abfragen ausgewählt, die in der Liste der Dateien, im angegebenen Verzeichnis oder im genannten CodeQL-Paket gefunden werden. Wenn weitere Filteranweisungen vorhanden sind, werden nur Abfragen ausgewählt, die den durch diese Anweisungen auferlegten Einschränkungen entsprechen. ## Filtern der Abfragen in einer Abfragesammlung Nachdem du durch Angeben von `query`-, `queries`- oder `qlpack`-Anweisungen die anfänglichen Abfragen definiert hast, die deiner Sammlung hinzugefügt werden sollen, kannst du `include`- und `exclude`-Anweisungen hinzufügen. Diese Anweisungen definieren Auswahlkriterien basierend auf bestimmten Eigenschaften: * Wenn du eine `include`-Anweisung für eine Reihe von Abfragen ausführst, werden alle Abfragen, die deinen Bedingungen entsprechen, in der Auswahl beibehalten, und Abfragen, die nicht übereinstimmen, werden entfernt. * Wenn du eine `exclude`-Anweisung für eine Reihe von Abfragen ausführst, werden alle Abfragen, die deinen Bedingungen entsprechen, aus der Auswahl entfernt, und Abfragen, die nicht übereinstimmen, werden beibehalten. Die Reihenfolge deiner Filteranweisungen ist wichtig. Die erste Filteranweisung, die nach den Suchanweisungen angezeigt wird, bestimmt, ob die Abfragen standardmäßig ein- oder ausgeschlossen werden. Wenn der erste Filter `include` entspricht, sind die anfänglich gefundenen Abfragen nur dann Teil der Sammlung, wenn sie mit einem expliziten `include`-Filter übereinstimmen. Wenn der erste Filter `exclude` entspricht, sind die anfänglich gefundenen Abfragen Teil der Sammlung, es sei denn, sie werden explizit ausgeschlossen. Nachfolgende Anweisungen werden in der angegebenen Reihenfolge ausgeführt, und Anweisungen, die später in der Datei erscheinen, haben Vorrang vor den vorherigen Anweisungen. `include`-Anweisungen können daher von späteren `exclude`-Anweisungen überschrieben werden, die mit derselben Abfrage übereinstimmen. Ebenso kann eine `exclude`-Anweisung von einer späteren `include`-Anweisung überschrieben werden. Für beide Anweisungen ist das Argument ein Einschränkungsblock, also eine YAML-Zuordnung, die die Einschränkungen darstellt. Jede Einschränkung ist ein Zuordnungseintrag, wobei der Schlüssel in der Regel eine Abfragemetadateneigenschaft ist. Der Wert kann Folgendes sein: * Eine einzelne Zeichenfolge * Ein in `/` eingeschlossener [regulärer Ausdruck](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/regex/Pattern.html) * Eine Liste mit Zeichenfolgen, regulären Ausdrücken oder beidem Um einer Einschränkung zu entsprechen, muss ein Metadatenwert mit einer der Zeichenfolgen oder einem der regulären Ausdrücke übereinstimmen. Wenn mehrere Metadatenschlüssel vorhanden sind, muss jeder Schlüssel abgeglichen werden. Dies sind die verfügbaren Standardmetadatenschlüssel: `description`, `id`, `kind`, `name`, `tags`, `precision` und `problem.severity`. Weitere Informationen über die Eigenschaften von Abfrage-Metadaten finden Sie unter [Metadaten für CodeQL Abfragen](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/#metadata-for-codeql-queries). Zusätzlich zu Metadatentags können die Schlüssel im Einschränkungsblock auch Folgendes sein: * ``` `query filename`: Entspricht der letzten Pfadkomponente des Abfragedateinamens ``` * ``` `query path`: Entspricht dem Pfad zur Abfragedatei relativ zum einschließenden CodeQL-Paket ``` * ``` `tags contain`: Eine der angegebenen Übereinstimmungszeichenfolgen muss mit einer der durch Leerzeichen getrennten Komponenten des Werts der `@tags`-Metadateneigenschaft übereinstimmen. ``` * ``` `tags contain all`: Jede der angegebenen Übereinstimmungszeichenfolgen muss mit einer der Komponenten der `@tags`-Metadateneigenschaft übereinstimmen. ``` ### Beispiele für das Filtern, welche Abfragen ausgeführt werden Ein häufiger Anwendungsfall besteht darin, eine Abfragesammlung zu erstellen, die alle Abfragen in einem CodeQL-Paket ausführt (mit Ausnahme einiger spezifischer Abfragen, die Benutzer\*innen nicht ausführen möchten). Allgemein wird empfohlen, nach der Abfrage `id` zu filtern, bei der es sich um einen eindeutigen und stabilen Bezeichner für jede Abfrage handelt. Die folgenden drei Abfragesammlungsdefinitionen sind semantisch identisch und filtern nach der Abfrage `id`: Dieser Filter stimmt mit allen Abfragen in der Standardsammlung von `codeql/cpp-queries` überein (mit Ausnahme der beiden Abfragen mit den ausgeschlossenen Bezeichnern): ```yaml - qlpack: codeql/cpp-queries - exclude: id: - cpp/cleartext-transmission - cpp/cleartext-storage-file ``` In diesem Beispiel wird für jede Abfrage eine separate `exclude`-Anweisung verwendet: ```yaml - qlpack: codeql/cpp-queries - exclude: id: cpp/cleartext-transmission - exclude: id: cpp/cleartext-storage-file ``` In diesem Beispiel schließt ein regulärer Ausdruck die gleichen beiden Abfragen aus. Außerdem werden alle zukünftigen Abfragen ausgeschlossen, die der Sammlung mit Bezeichnern hinzugefügt werden, die mit `cpp/cleartext-` beginnen: ```yaml - qlpack: codeql/cpp-queries - exclude: id: - /^cpp\/cleartext-.*/ ``` Verwende Folgendes, um eine Sammlung zu definieren, die alle Abfragen in der Standardsammlung des CodeQL-Pakets `codeql/cpp-queries` auswählt und dann so optimiert, dass nur Sicherheitsabfragen eingeschlossen werden: ```yaml - qlpack: codeql/cpp-queries - include: tags contain: security ``` Verwende Folgendes, um eine Sammlung zu definieren, die alle Abfragen mit `@kind problem` und `@precision high` aus dem Verzeichnis `my-custom-queries` auswählt: ```yaml - queries: my-custom-queries - include: kind: problem precision: very-high ``` Beachte, dass sich die folgende Abfragesammlungsdefinition anders verhält als die obige Definition. Diese Definition wählt Abfragen aus, die `@kind problem`*oder* sind `@precision very-high`: ```yaml - queries: my-custom-queries - include: kind: problem - include: precision: very-high ``` Verwende Folgendes, um eine Sammlung zu erstellen, die alle Abfragen mit `@kind problem` aus dem `my-custom-queries`-Verzeichnis auswählt (mit Ausnahme der Abfragen mit `@problem.severity recommendation`): ```yaml - queries: my-custom-queries - include: kind: problem - exclude: problem.severity: recommendation ``` Verwende Folgendes, um eine Sammlung zu erstellen, die alle Abfragen mit `@tag security` und `@precision high` oder `very-high` aus dem CodeQL-Paket `codeql/cpp-queries` auswählt: ```yaml - queries: . from: codeql/cpp-queries - include: tags contain: security precision: - high - very-high ``` > \[!NOTE] > Sie können den `codeql resolve queries /path/to/suite.qls`-Befehl verwenden, um zu sehen, welche Abfragen von einer Suite-Definition für Abfragen ausgewählt werden. Weitere Informationen finden Sie unter [Abfragen auflösen](/de/code-security/codeql-cli/codeql-cli-manual/resolve-queries). ## Wiederverwenden vorhandener Abfragesammlungsdefinitionen Vorhandene Abfragesammlungsdefinitionen können wiederverwendet werden, indem Folgendes angegeben wird: * Eine `import` Anweisung: Fügt die Abfragen, die von einer zuvor definierten `.qls` Datei ausgewählt wurden, zur aktuellen Suite hinzu: ```yaml - import: ``` Der Pfad zur importierten Sammlung muss relativ zum CodeQL-Paket sein, das die aktuelle Sammlungsdefinition enthält. Wenn sich die importierte Abfragesammlung in einem anderen QL-Paket befindet, kannst du Folgendes verwenden: ```yaml - import: from: version: ^x.y.z ``` Das `version`-Feld ist optional und gibt einen Bereich kompatibler Versionen dieses CodeQL-Pakets an. Wenn du keine Version angibst, wird die aktuellste Version des Pakets verwendet. Mithilfe einer `import`-Anweisung hinzugefügte Abfragen können unter Verwendung von nachfolgenden `exclude`-Anweisungen gefiltert werden. * Eine `apply` Anweisung: Fügt alle Anweisungen aus einer zuvor definierten `.qls` Datei zur aktuellen Suite hinzu. Die Anweisungen in der angewendeten `.qls`-Datei werden so ausgeführt, als ob sie anstelle von `apply` angezeigt würden. Alle `include`- und `exclude`-Anweisungen aus der angewendeten Sammlung gelten auch für Abfragen, die durch frühere Anweisungen hinzugefügt wurden: ```yaml - apply: ``` Die `apply`-Anweisung kann auch verwendet werden, um eine in einer `.yml`-Datei gespeicherte Gruppe wiederverwendbarer Bedingungen auf mehrere Abfragedefinitionen anzuwenden. Weitere Informationen findest du in den folgenden [Beispielen](#reusability-examples). ### Beispiele für Wiederverwendbarkeit Um dieselben Bedingungen in mehreren Abfragesammlungsdefinitionen zu verwenden, erstelle eine separate `.yml`-Datei mit deinen Anweisungen. Speichere beispielsweise Folgendes in einer Datei namens `reusable-instructions.yml`: ```yaml - include: kind: - problem - path-problem tags contain: security precision: - high - very-high ``` Füge demselben CodeQL-Paket `reusable-instructions.yml` als aktuelle Abfragesammlung hinzu. Verwende dann in einer oder mehreren Abfragesammlungen die `apply`-Anweisung, um die wiederverwendbaren Anweisungen auf die aktuelle Sammlung anzuwenden. Beispiel: ```yaml - queries: queries/cpp/custom - apply: reusable-instructions.yml ``` Dadurch werden die Abfragen in `queries/cpp/custom` gefiltert, um nur diejenigen einzuschließen, die den Bedingungen für die Wiederverwendung entsprechen. Du kannst auch eine Sammlungsdefinition auch mithilfe von `reusable-instructions.yml` für Abfragen in einem anderen CodeQL-Paket erstellen. Wenn sich die `.qls`-Datei im gleichen CodeQL-Paket befindet wie die Abfragen, kannst du unmittelbar nach der `from`-Anweisung ein `apply`-Feld hinzufügen: ```yaml # load queries from the default suite of my-org/my-other-custom-queries - qlpack: my-org/my-other-custom-queries # apply the reusable instructions from the my-org/my-custom-instructions CodeQL pack - apply: reusable-instructions.yml from: my-org/my-custom-instructions version: ^1.2.3 # optional ``` Ein häufiger Anwendungsfall für eine `import`-Anweisung besteht darin, einen weiteren Filter auf Abfragen aus einer anderen Abfragesammlung anzuwenden. Diese Sammlung filtert beispielsweise weiter die `cpp-security-and-quality`-Sammlung und schließt `low`- und `medium`-Genauigkeitsabfragen aus: ```yaml - import: codeql-suites/cpp-security-and-quality.qls from: codeql/cpp-queries - exclude: precision: - low - medium ``` Wenn du aus einer anderen Sammlung importierte Abfragen einschließen (`include`) möchtest, ist die Syntax etwas anders: ```yaml - import: codeql-suites/cpp-security-and-quality.qls from: codeql/cpp-queries - exclude: {} - include: precision: - very-high - high ``` Beachte die leere `exclude`-Anweisung. Dies ist erforderlich, um sicherzustellen, dass die nachfolgende `include`-Anweisung Abfragen aus der importierten Sammlung filtern kann. ## Benennen einer Abfragesammlung Du kannst durch Angeben einer `description`-Anweisung einen Namen für deine Abfragesammlung festlegen: ```yaml - description: ``` ## Speichern einer Abfragesammlung Speichere deine Abfragesammlung mit der Erweiterung `.qls`, und füge sie einem CodeQL-Paket hinzu. Weitere Informationen finden Sie unter [Anpassen der Analyse mit CodeQL-Paketen](/de/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#custom-codeql-packs). ## Verwenden von Abfragesammlungen mit CodeQL Du kannst Abfragesammlungen in der Befehlszeile für jeden Befehl angeben, der `.qls`-Dateien akzeptiert. Beispielsweise kannst du die von einer Sammlungsdefinition ausgewählten Abfragen mit `query compile` kompilieren oder die Abfragen in einer Analyse mit `database analyze` verwenden. Weitere Informationen zur Analyse von CodeQL Datenbanken finden Sie unter [Analysieren des Codes mit CodeQL-Abfragen](/de/code-security/codeql-cli/getting-started-with-the-codeql-cli/analyzing-your-code-with-codeql-queries). ## Weiterführende Lektüre * ``` [CodeQL Abfragen](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/#codeql-queries) ```