Anpassen des Codeüberprüfungsworkflows mit CodeQL – Teil 1

  • 10 Minuten

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

Wenn Sie CodeQL zum Überprüfen von Code verwenden, generiert die CodeQL-Analyse-Engine eine Datenbank aus dem Code und führt Abfragen dafür aus. Bei der CodeQL-Analyse wird eine Standardgruppe von Abfragen verwendet. Sie können jedoch zusätzlich zu den Standardabfragen weitere auszuführende Abfragen angeben.

Sie können zusätzliche Abfragen ausführen, wenn sie Teil eines CodeQL-Pakets (Beta) sind, das in der GitHub-Containerregistrierung veröffentlicht wurde, oder ein QL-Paket, das in einem Repository gespeichert ist.

Es gibt zwei Optionen, um anzugeben, welche Abfragen Sie mit der CodeQL-Codeüberprüfung ausführen möchten:

  • Verwenden des Workflows für die Codeüberprüfung
  • Verwenden einer benutzerdefinierten Konfigurationsdatei

In dieser Lerneinheit erfahren Sie, wie Sie eine Workflowdatei zum Verweisen auf zusätzliche Abfragen bearbeiten, Abfragen aus Abfragepaketen verwenden und Abfragen aus einer Workflowdatei und einer benutzerdefinierten Konfigurationsdatei kombinieren.

Angeben zusätzlicher Abfragen in einer Workflowdatei

Hier finden Sie die verfügbaren Optionen zum Angeben der zusätzlichen Abfragen, die Sie ausführen möchten:

  • packs, um ein oder mehrere CodeQL-Abfragepakete (Beta) zu installieren und die Standardabfragesammlung oder Abfragen für diese Pakete auszuführen
  • queries, um eine einzelne .ql-Datei, ein Verzeichnis mit mehreren .ql-Dateien, eine .qls-Definitionsdatei für eine Abfragesammlung oder eine beliebige Kombination anzugeben

Sie können sowohl Pakete als auch Abfragen im gleichen Workflow verwenden.

Es wird nicht empfohlen, direkt aus dem github/codeql-Repository auf Abfragesammlungen wie github/codeql/cpp/ql/src@main zu verweisen. Solche Abfragen können möglicherweise nicht mit der gleichen CodeQL-Version kompiliert werden, die für Ihre anderen Abfragen verwendet wird, was zu Fehlern während der Analyse führen kann.

Verwenden von CodeQL-Abfragepaketen

Hinweis

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

Um mindestens ein CodeQL-Abfragepaket (Beta) hinzuzufügen, fügen Sie im Abschnitt uses: github/codeql-action/init@v1 des Workflows einen with: packs:-Eintrag hinzu. In Paketen können Sie mindestens ein Paket angeben, das verwendet werden soll. Optional können Sie angeben, welche Version heruntergeladen werden soll. Wenn Sie keine Version angeben, wird die neueste Version heruntergeladen. Wenn Sie Pakete verwenden möchten, die nicht öffentlich verfügbar sind, müssen Sie die Umgebungsvariable GITHUB_TOKEN auf ein Geheimnis festlegen, das Zugriff auf die Pakete besitzt.

Im folgenden Beispiel ist der Bereich die Organisation oder das persönliche Konto, die bzw. das das Paket veröffentlicht hat. Wenn der Workflow ausgeführt wird, werden die drei CodeQL-Abfragepakete von GitHub heruntergeladen und die Standardabfragen oder die Abfragesammlung für jedes Paket ausgeführt. Im folgenden Beispiel werden die einzelnen Pakete in der Liste basierend auf ihren Spezifikationen heruntergeladen:

  • Die neueste Version von pack1 wurde heruntergeladen, und alle Standardabfragen wurden ausgeführt.
  • Version 1.2.3 von pack2 wird heruntergeladen, und alle Standardabfragen werden ausgeführt.
  • Die neueste Version davon pack3 , die mit Version 3.2.1 kompatibel ist, wird heruntergeladen, und alle Abfragen werden ausgeführt.
  • Version 4.5.6 von pack4 wird heruntergeladen, und nur die Abfragen, die im Pfad/zu/Abfragen gefunden wurden, werden ausgeführt.
- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

Hinweis

Für Workflows, die CodeQL-Datenbanken für mehrere Sprachen generieren, müssen Sie stattdessen die CodeQL-Abfragepakete in einer Konfigurationsdatei angeben.

Verwenden von Abfragen in QL-Paketen

Um eine oder mehrere Abfragen hinzuzufügen, fügen Sie innerhalb des Abschnitts uses: github/codeql-action/init@v3 des Workflows einen with: queries:-Eintrag hinzu. Wenn sich die Abfragen in einem privaten Repository befinden, verwenden Sie den Parameter external-repository-token, um ein Token anzugeben, das Zugriff zum Auschecken des privaten Repositorys hat.

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Sie können auch Abfragesammlungen im Wert von queriesangeben. Abfragesammlungen sind Sammlungen von Abfragen, die in der Regel nach Zweck oder Sprache gruppiert sind.

Die folgenden Abfragesammlungen sind in die CodeQL-Codeüberprüfung integriert und stehen zur Verwendung zur Verfügung:

Abfragesammlung Beschreibung
security-extended Abfragen aus der Standardsuite sowie Abfragen mit geringerem Schweregrad und Genauigkeit
security-and-quality Abfragen aus security-extended, plus Wartungsbarkeits- und Zuverlässigkeitsabfragen

Jede dieser Abfragesammlungen enthält eine andere Teilmenge der Abfragen, die im integrierten CodeQL-Abfragepaket für diese Sprache enthalten sind. Die Abfragesammlungen werden automatisch mithilfe der Metadaten für jede Abfrage generiert.

Wenn Sie eine Abfragesammlung angeben, führt die CodeQL-Analyse-Engine zusätzlich zu den Standardabfragen die in der Sammlung enthaltenen Abfragen aus.

Kombinieren von Abfragen aus einer Workflowdatei und einer benutzerdefinierten Konfigurationsdatei

Wenn Sie auch eine Konfigurationsdatei für benutzerdefinierte Einstellungen verwenden, werden alle in Ihrem Workflow angegebenen zusätzlichen Pakete oder Abfragen anstelle der in der Konfigurationsdatei angegebenen Komponenten verwendet. Wenn Sie die kombinierte Gruppe zusätzlicher Pakete oder Abfragen ausführen möchten, stellen Sie dem Wert von packs oder queries im Workflow das Symbol + voran.

Im folgenden Beispiel stellt das +-Symbol sicher, dass die angegebenen zusätzlichen Pakete und Abfragen zusammen mit allen angegebenen Komponenten in der Konfigurationsdatei verwendet werden, auf die verwiesen wird:

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries