Anpassen des Codescanworkflows mit CodeQL – Teil 2

  • 8 Minuten

Codeüberprüfungsworkflows, die CodeQL verwenden, verfügen über verschiedene Konfigurationsoptionen, die Sie an die speziellen Anforderungen Ihrer Organisation anpassen können.

In dieser Lerneinheit prüfen wir, wie man auf zusätzliche Abfragen in einer benutzerdefinierten Konfigurationsdatei verweisen kann.

Zusätzliche Abfragen in einer benutzerdefinierten Konfigurationsdatei

Eine benutzerdefinierte Konfigurationsdatei ist eine alternative Möglichkeit, zusätzliche Pakete und Abfragen anzugeben, die ausgeführt werden sollen. Sie können die Datei auch verwenden, um die Standardabfragen zu deaktivieren und anzugeben, welche Verzeichnisse während der Analyse gescannt werden sollen.

Verwenden Sie in der Workflowdatei den config-file-Parameter der init-Aktion, um den Pfad zur Konfigurationsdatei anzugeben, die Sie verwenden möchten. In diesem Beispiel wird die Konfigurationsdatei ./.github/codeql/codeql-config.yml geladen.

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

Die Konfigurationsdatei kann sich in dem Repository befinden, das Sie analysieren, oder in einem externen Repository. Mithilfe eines externen Repositorys können Sie Konfigurationsoptionen für mehrere Repositorys an einem zentralen Ort angeben. Wenn Sie auf eine Konfigurationsdatei verweisen, die sich in einem externen Repository befindet, können Sie die OWNER/REPOSITORY/FILENAME@BRANCH-Syntax verwenden. Beispiel: octo-org/shared/codeql-config.yml@main.

Wenn sich die Konfigurationsdatei in einem externen privaten Repository befindet, verwende den external-repository-token-Parameter der init-Aktion, um ein Token anzugeben, das Zugriff auf das private Repository besitzt.

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Die Einstellungen in der Konfigurationsdatei werden im YAML-Format geschrieben.

Angeben von CodeQL-Abfragepaketen in benutzerdefinierten Konfigurationsdateien

Hinweis

Die CodeQL-Paketverwaltungsfunktionen (einschließlich der CodeQL-Pakete) befinden sich derzeit in der Betaphase und können Änderungen unterliegen.

Sie können CodeQL-Abfragepakete in einem Array angeben. Das Format unterscheidet sich vom Format, das von der Workflowdatei verwendet wird.

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

Das vollständige Format zum Angeben eines Abfragepakets ist scope/name[@version][:path]. version und path sind optional. version ist der SemVer-Versionsbereich. Fehlt dies, wird die neueste Version verwendet.

Wenn Sie über einen Workflow verfügen, der mehrere CodeQL-Datenbanken generiert, können Sie in einer benutzerdefinierten Konfigurationsdatei beliebige auszuführende CodeQL-Abfragepakete angeben, indem Sie eine geschachtelte Zuordnung von Paketen verwenden.

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

Angeben zusätzlicher Abfragen in einer benutzerdefinierten Konfiguration

Sie können zusätzliche Abfragen in einem queries-Array angeben. Jedes Element des Arrays enthält einen uses-Parameter mit einem Wert, der eine einzelne Abfragedatei, ein Verzeichnis mit Abfragedateien oder eine Abfragesammlungs-Definitionsdatei identifiziert.

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

Optional können Sie jedem Arrayelement einen Namen geben, wie in der folgenden Beispielkonfigurationsdatei gezeigt:

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Deaktivieren der Standardabfragen

Wenn Sie nur benutzerdefinierte Abfragen ausführen möchten, können Sie die Standardsicherheitsabfragen mit disable-default-queries: true deaktivieren. Sie sollten dieses Flag auch verwenden, wenn Sie versuchen, eine benutzerdefinierte Abfragesammlung zu erstellen, die eine bestimmte Regel ausschließt. Dadurch wird vermieden, dass alle Abfragen zweimal ausgeführt werden.

Ausschließen bestimmter Abfragen aus der Analyse

Sie können Ihrer benutzerdefinierten Konfigurationsdatei exclude und include Filter hinzufügen, um die Abfragen anzugeben, die Sie ausschließen oder in die Analyse einschließen möchten, z. B.:

  • Bestimmte Abfragen aus den Standardsammlungen (security, security-extended und security-and-quality)
  • Bestimmte Abfragen, deren Ergebnisse Sie nicht interessieren.
  • Alle Abfragen, die Warnungen und Empfehlungen generieren

Sie können exclude Filter ähnlich wie in der Konfiguration verwenden, um Abfragen auszuschließen, die Sie aus der Standardanalyse entfernen möchten. Im folgenden Beispiel einer Konfigurationsdatei werden sowohl die js/redundant-assignment Abfragen als auch die js/useless-assignment-to-local Abfragen aus der Analyse ausgeschlossen.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Um die ID einer Abfrage zu finden, können Sie auf die Warnung in der Liste der Warnungen auf der Registerkarte "Sicherheit" klicken. Dadurch wird die Seite mit den Warnungsdetails geöffnet. Das Feld Regel-ID enthält die Abfrage-ID.

Beachten Sie beim Arbeiten mit dem excludes Filter Folgendes:

  • Die Reihenfolge der Filter ist wichtig. Die erste Filteranweisung, die nach den Anweisungen zu den Abfragen und Abfragepaketen angezeigt wird, bestimmt, ob die Abfragen standardmäßig ein- oder ausgeschlossen werden.
  • Nachfolgende Anweisungen werden in der angegebenen Reihenfolge ausgeführt, und Anweisungen, die später in der Datei erscheinen, haben Vorrang vor den vorherigen Anweisungen.

Angeben der zu scannenden Verzeichnisse

Für die interpretierten Sprachen, die CodeQL unterstützt (Python, Ruby und JavaScript/TypeScript), können Sie Codescans auf Dateien in bestimmten Verzeichnissen beschränken, indem Sie der Konfigurationsdatei ein paths-Array hinzufügen. Sie können die Dateien in bestimmten Verzeichnissen von der Analyse ausschließen, indem Sie ein paths-ignore-Array hinzufügen.

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

Hinweis

  • Die Schlüsselwörter paths und paths-ignore, die im Kontext der Codescan-Konfigurationsdatei verwendet werden, sollten nicht mit den gleichen Schlüsselwörtern verwechselt werden, wenn diese für on.<push|pull_request>.paths in einem Workflow verwendet werden. Wenn sie zum Ändern von on.<push|pull_request> in einem Workflow verwendet werden, bestimmen sie, ob die Aktionen ausgeführt werden, wenn jemand Code in den angegebenen Verzeichnissen ändert.
  • Die Filtermusterzeichen ?, +, [, ] und ! werden nicht unterstützt und literal abgeglichen.
  • **-Zeichen dürfen sich nur am Anfang oder Ende einer Zeile befinden oder müssen in Schrägstriche eingeschlossen sein, und du kannst ** und andere Zeichen nicht mischen. Beispielsweise stellen die Zeichenfolgen foo/**, **/foo und foo/**/bar zulässige Syntax dar, **foo hingegen nicht. Sie können jedoch einzelne Sterne zusammen mit anderen Zeichen verwenden, wie im Beispiel gezeigt. Sie müssen alle Zeichenfolgen in Anführungszeichen einschließen, die ein *-Zeichen enthalten.

Wenn Sie bei kompilierten Sprachen Codescans auf bestimmte Verzeichnisse in Ihrem Projekt beschränken möchten, müssen Sie die entsprechenden Buildschritte im Workflow angeben. Welche Befehle Sie verwenden müssen, um ein Verzeichnis aus dem Buildvorgang auszuschließen, hängt von Ihrem Buildsystem ab.

Sie können kleine Teile eines Monorepositorys schnell analysieren, wenn Sie Code in bestimmten Verzeichnissen ändern. Sie müssen sowohl Verzeichnisse in Ihren Buildschritten ausschließen als auch die Schlüsselwörter paths-ignore und paths für on.<push|pull_request> in Ihrem Workflow verwenden.