Erstellen von CodeQL-Abfragesammlungen

Sie können Abfragesammlungen für die Abfragen erstellen, die Sie häufig in Ihren CodeQL Analysen verwenden möchten. Weitere Informationen findest du unter CodeQL-Abfragesammlungen.

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: Gibt CodeQL an, nach einer oder mehreren angegebenen .ql Dateien zu suchen:

  - query: <path-to-query>
  

  Das Argument muss ein oder mehrere Dateipfade sein, relativ zu dem Paket CodeQL, das die Suite-Definition enthält.

• Eine queries Anweisung: Gibt CodeQL an, ein Verzeichnis rekursiv nach .ql Dateien zu scannen:

  - queries: <path-to-subdirectory>
  

  Der Pfad des Verzeichnisses muss relativ zum Stamm des CodeQL Pakets sein, das die Suitedefinitionsdatei enthält. Um die Abfragen relativ zu einem anderen CodeQL Paket zu finden, fügen Sie ein from Feld hinzu:

  - queries: <path-to-subdirectory>
    from: <ql-pack-name>
    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.

• Eine qlpack Anweisung: Gibt CodeQL an, Abfragen in der Standardsuite des benannten CodeQL Pakets aufzulösen:

  - qlpack: <qlpack-name>
    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.

Du musst deiner Sammlungsdefinition mindestens eine query-, queries- oder qlpack-Anweisung hinzufügen, da andernfalls keine Abfragen ausgewählt werden. Wenn die Suite keine weiteren Anweisungen enthält, werden alle Abfragen aus der Liste der Dateien, im angegebenen Verzeichnis oder im benannten CodeQL Paket ausgewählt. 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
• 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 zu Abfragemetadateneigenschaften finden Sie unter Metadaten für CodeQL Abfragen.

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: Stimmt mit dem Pfad zur Abfragedatei relativ zu ihrem übergeordneten CodeQL Pack überein.
• 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 gängiger Anwendungsfall besteht darin, eine Abfragesuite zu erstellen, die alle Abfragen in einem CodeQL Paket ausführt, mit Ausnahme einiger spezifischer Abfragen, die der Benutzer nicht ausführen möchte. 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):

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

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

- qlpack: codeql/cpp-queries
- exclude:
    id:
      - /^cpp\/cleartext-.*/

Um eine Suite zu definieren, die alle Abfragen in der Standardsuite des codeql/cpp-queriesCodeQL Pakets auswählt, und diese dann so verfeinern, dass sie nur Sicherheitsabfragen enthalten, verwenden Sie Folgendes:

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

- 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 problemoder sind @precision very-high:

- 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):

- queries: my-custom-queries
- include:
    kind: problem
- exclude:
    problem.severity: recommendation

Um eine Suite zu erstellen, die alle Abfragen mit @tag security und @precision high oder very-high aus dem codeql/cpp-queriesCodeQL Paket auswählt, verwenden Sie Folgendes:

- queries: .
  from: codeql/cpp-queries
- include:
    tags contain: security
    precision:
    - high
    - very-high

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:

  - import: <path-to-query-suite>
  

  Der Pfad zur importierten Suite muss relativ zum CodeQL Paket mit der aktuellen Suitedefinition sein. Wenn sich die importierte Abfragesammlung in einem anderen QL-Paket befindet, kannst du Folgendes verwenden:

  - import: <path-to-query-suite>
    from: <ql-pack>
    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:

  - apply: <path-to-query-suite>
  

  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.

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:

- include:
    kind:
    - problem
    - path-problem
    tags contain: security
    precision:
    - high
    - very-high

Fügen Sie reusable-instructions.yml demselben CodeQL Paket wie Ihre aktuelle Abfragesuite hinzu. Verwende dann in einer oder mehreren Abfragesammlungen die apply-Anweisung, um die wiederverwendbaren Anweisungen auf die aktuelle Sammlung anzuwenden. Beispiel:

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

Sie können auch eine Suite-Definition mithilfe von Abfragen mit reusable-instructions.yml in einem anderen CodeQL-Paket erstellen. Wenn sich die .qls Datei im selben CodeQL Paket wie die Abfragen befindet, können Sie direkt nach der from Anweisung ein apply Feld hinzufügen:

# 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:

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

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

- description: <name-of-query-suite>

Speichern einer Abfragesammlung

Speichern Sie Ihre Abfragesammlung in einer Datei mit der Erweiterung .qls und fügen Sie sie einer CodeQL hinzu Paket Weitere Informationen findest du unter Anpassen der Analyse mit CodeQL-Paketen.

Verwenden von Abfragesuiten 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 zum Analysieren von CodeQL Datenbanken finden Sie unter Analyzing your code with CodeQL queries.

Weiterführende Lektüre

• CodeQL Fragen