Konfigurieren des CodeQL-Runners in deinem CI-System

Informationen zum Konfigurieren des CodeQL-code scanning in deinem CI-System

Du kannst den CodeQL runner verwenden, um das code scanning in dein CI-System zu integrieren. Weitere Informationen findest du unter Ausführen von CodeQL runner im CI-System.

Im Allgemeinen rufst du den CodeQL runner wie folgt auf.

$ /path/to-runner/codeql-runner-OS  

/path/to-runner/ hängt davon ab, wohin du den CodeQL runner in deinem CI-System heruntergeladen hast. codeql-runner-OS hängt vom verwendeten Betriebssystem ab. Es gibt drei Versionen des CodeQL runner für die jeweiligen Betriebssysteme: codeql-runner-linux (Linux), codeql-runner-macos (macOS) und codeql-runner-win (Windows).

Um die Art anzupassen, wie der CodeQL runner deinen Code überprüft, kannst du Flags wie --languages und --queries verwenden oder benutzerdefinierte Einstellungen in einer separaten Konfigurationsdatei angeben.

Überprüfen von Pull Requests

Durch das Überprüfen des Codes beim Erstellen eines Pull Requests wird verhindert, dass Entwickler*innen neue Sicherheitsrisiken und Fehler in den Code einbauen.

Führe zum Überprüfen eines Pull Requests den analyze-Befehl aus, und verwendest du das --ref-Flag, um den Pull Request anzugeben. Der Verweis entspricht refs/pull/<PR-number>/head oder refs/pull/<PR-number>/merge, je nachdem, ob du den HEAD-Commit des Pull-Request-Branchs oder einen Mergecommit mit dem Basisbranch ausgecheckt hast.

$ /path/to-runner/codeql-runner-linux analyze --ref refs/pull/42/merge

Überschreiben der automatischen Spracherkennung

Der CodeQL runner erkennt und überprüft den in den unterstützten Sprachen geschriebenen Code automatisch.

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Python

Weitere Informationen findest du in der Dokumentation zur CodeQL-Website: Unterstützte Sprachen und Frameworks.

Wenn Ihr Repository Code in mehreren der unterstützten Sprachen enthält, können Sie auswählen, welche Sprachen Sie analysieren möchten. Es gibt mehrere Gründe, warum Sie verhindern möchten, dass eine Sprache analysiert wird. Das Projekt kann z. B. Abhängigkeiten in einer anderen Sprache als der Haupttextkörper des Codes aufweisen, und Sie möchten möglicherweise keine Warnungen für diese Abhängigkeiten anzeigen.

Führe den init-Befehl mit dem --languages-Flag gefolgt von einer durch Kommas getrennten Liste der Sprachschlüsselwörter aus, um die automatische Spracherkennung außer Kraft zu setzen. Die Schlüsselwörter für die unterstützten Sprachen sind cpp, csharp, go, java, javascript, und python.

$ /path/to-runner/codeql-runner-linux init --languages cpp,java

Ausführen zusätzlicher Abfragen

Wenn du CodeQL zum Überprüfen von Code verwendest, generiert die CodeQL-Analyse-Engine eine Datenbank anhand des Codes und führt Abfragen darin aus. Die CodeQL-Analyse verwendet einen standardmäßigen Abfragesatz, aber du kannst zusätzlich zu den Standardabfragen weitere auszuführende Abfragen angeben.

Alle zusätzlichen Abfragen, die du ausführen möchtest, müssen zu einem QL-Paket in einem Repository gehören. Weitere Informationen findest du unter Informationen zu code scanning mit CodeQL.

Du kannst eine einzelne QL-Datei, ein Verzeichnis mit mehreren QL-Dateien, eine QLS-Definitionsdatei für eine Abfragesammlung oder eine beliebige Kombination angeben. Weitere Informationen zur Definition von Abfragesammlungen findest du unter Erstellen von CodeQL-Abfragesammlungen.

Die folgenden Abfragesuiten sind in CodeQL code scanning integriert und stehen zur Verwendung zur Verfügung.

Abfrageauflistung	Beschreibung
security-extended	Abfragen aus der Standardsammlung sowie Abfragen zu niedrigeren Schweregraden und Genauigkeit
security-and-quality	Abfragen von security-extended, sowie zusätzliche Abfragen zur Verwaltbarkeit und Zuverlässigkeit

Wenn du eine Abfragesuite angibst, wird das CodeQL-Analysemodul den Standardsatz von Abfragen und alle zusätzlichen Abfragen ausführen, die in der zusätzlichen Abfragesuite definiert sind.

Übergib eine durch Kommas getrennte Liste von Pfaden an das --queries-Flag des init-Befehls, um eine oder mehrere Abfragen hinzuzufügen. Du kannst zusätzliche Abfragen auch in einer Konfigurationsdatei angeben.

Wenn du auch für benutzerdefinierte Einstellungen eine Konfigurationsdatei verwendest und zusätzliche Abfragen mit dem --queries-Flag angibst, verwendet der CodeQL runner die mit dem --queries-Flag angegebenen zusätzlichen Abfragen anstelle der Anfragen in der Konfigurationsdatei. Wenn du eine Kombination aus den mit dem Flag und in der Konfigurationsdatei angegebenen zusätzlichen Abfragen ausführen möchtest, stelle dem an --queries übergebenen Wert das +-Symbol voran. Weitere Informationen findest du unter Verwenden einer benutzerdefinierten Konfigurationsdatei.

Im folgenden Beispiel wird mit dem +-Symbol sichergestellt, dass der CodeQL runner die zusätzlichen Abfragen zusammen mit den in der referenzierten Konfigurationsdatei angegebenen Abfragen verwendet.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml 
    --queries +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main

Verwenden einer benutzerdefinierten Konfigurationsdatei

Du kannst benutzerdefinierte Einstellungen in einer separaten Konfigurationsdatei angeben, anstatt zusätzliche Informationen an die CodeQL runner-Befehle zu übergeben.

Die Konfigurationsdatei ist eine YAML-Datei. Wie in den folgenden Beispielen veranschaulicht verwendet sie eine Syntax ähnlich der Workflowsyntax für GitHub Actions. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Verwende das --config-file-Flag des init-Befehls, um die Konfigurationsdatei anzugeben. Der Wert von --config-file entspricht dem Pfad zur Konfigurationsdatei, die du verwenden möchtest. In diesem Beispiel wird die Konfigurationsdatei .github/codeql/codeql-config.yml geladen.

$ /path/to-runner/codeql-runner-linux init --config-file .github/codeql/codeql-config.yml

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

Beispielkonfigurationsdateien

Diese Konfigurationsdatei fügt die Abfragesammlung security-and-quality zur Liste der Abfragen hinzu, die von CodeQL beim Scannen deines Codes ausgeführt werden. Weitere Informationen zu den verfügbaren Abfragesammlungen findest du unter Ausführen zusätzlicher Abfragen.

name: "My CodeQL config"

queries:
  - uses: security-and-quality

Die folgende Konfigurationsdatei deaktiviert die Standardabfragen und gibt stattdessen eine Reihe von benutzerdefinierten Abfragen an, die ausgeführt werden sollen. Außerdem wird CodeQL so konfiguriert, dass Dateien im Verzeichnis src (relativ zum Stammverzeichnis) überprüft werden. Ausgenommen davon sind das Verzeichnis src/node_modules und Dateien, deren Name auf .test.js endet. Dateien in src/node_modules und Dateien mit Namen, die auf .test.js enden, werden daher von der Analyse ausgeschlossen.

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'

Konfigurieren von code scanning für kompilierte Sprachen

Für die kompilierten Sprachen C/C++, C# und Java erstellt CodeQL den Code, bevor er analysiert wird. Für diese Sprachen analysiert CodeQL die Quelldateien in deinem Repository, die erstellt werden. Für jede dieser Sprachen kannst du autobuild deaktivieren und stattdessen benutzerdefinierte Buildbefehle verwenden, um nur die Dateien zu analysieren, die von diesen benutzerdefinierten Befehlen erstellt werden.

Für viele gängige Buildsysteme kann der CodeQL runner den Code automatisch kompilieren. Führe autobuild zwischen den Schritten init und analyze aus, um den Code automatisch zu kompilieren. Beachte, dass du zunächst möglicherweise manuell ein Buildtool installieren musst, wenn dein Repository eine bestimmte Version dieses Buildtools erfordert.

Der autobuild-Prozess versucht immer nur eine kompilierte Sprache für ein Repository zu kompilieren. Die automatisch für die Analyse ausgewählte Sprache ist die Sprache mit den meisten Dateien. Verwende das --language-Flag des autobuild-Befehls, wenn du eine Sprache explizit auswählen möchtest.

$ /path/to-runner/codeql-runner-linux autobuild --language csharp

Wenn der autobuild-Befehl deinen Code nicht kompilieren kann, kannst du die Buildschritte zwischen den Schritten init und analyze selbst ausführen. Weitere Informationen findest du unter Ausführen von CodeQL runner im CI-System.

Hochladen von code scanning-Daten in GitHub

Wenn du den analyze-Befehl ausführst, lädt der CodeQL runner standardmäßig Ergebnisse des code scanning hoch. Mithilfe des upload-Befehls kannst du SARIF-Dateien auch separat hochladen.

Nachdem du die Daten hochgeladen hast, zeigt GitHub die Warnungen in deinem Repository an.

• Wenn du die Daten in einen Pull Request hochgeladen hast (z. B. --ref refs/pull/42/merge oder --ref refs/pull/42/head), werden die Ergebnisse als Warnungen in einer Pull-Request-Überprüfung angezeigt. Weitere Informationen findest du unter Selektieren von Codeüberprüfungswarnungen in Pull Requests.
• Wenn du Daten in einen Branch hochgeladen hast (z. B. --ref refs/heads/my-branch), werden die Ergebnisse auf der Registerkarte Sicherheit für dein Repository angezeigt. Weitere Informationen findest du unter Verwalten von Codeüberprüfungswarnungen für dein Repository.

CodeQL runner-Befehlsreferenz

Der CodeQL runner unterstützt die folgenden Befehle und Flags.

init

Initialisiert den CodeQL runner und erstellt eine CodeQL-Datenbank für jede zu analysierende Sprache.

Flag	Erforderlich	Eingabewert
--repository	✓	Name des zu initialisierenden Repositorys
--github-url	✓	URL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdin	✓	Liest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--languages		Durch Kommas getrennte Liste der zu analysierenden Sprachen. Der CodeQL runner erkennt und analysiert standardmäßig alle unterstützten Sprachen im Repository.
--queries		Durch Kommas getrennte Liste zusätzlicher Abfragen, die ausgeführt werden sollen, zusätzlich zur Standardsammlung von Sicherheitsabfragen. Hiermit wird die queries-Einstellung in der benutzerdefinierten Konfigurationsdatei überschrieben.
--config-file		Pfad zur benutzerdefinierten Konfigurationsdatei
--codeql-path		Pfad zu einer Kopie der ausführbaren Datei der CodeQL-CLI, die verwendet werden soll. Der CodeQL runner lädt standardmäßig eine Kopie herunter.
--temp-dir		Verzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--tools-dir		Verzeichnis, in dem CodeQL-Tools und andere Dateien zwischen Ausführungen gespeichert werden. Die Standardeinstellung ist ein Unterverzeichnis des Stammverzeichnisses.
--checkout-path		Pfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--debug		Keine. Gibt eine ausführlichere Ausgabe aus.
--trace-process-name		Erweitert, nur Windows. Name des Prozesses, in den ein Windows-Tracer dieses Prozesses injiziert wird.
--trace-process-level		Erweitert, nur Windows. Anzahl der nächsthöheren Ebenen des übergeordneten Prozesses, in den ein Windows-Tracer dieses Prozesses injiziert wird.
-h, --help		Keine. Zeigt Hilfe für den Befehl an.

autobuild

Versucht, den Code für die kompilierten Sprachen C/C++, C# und Java zu kompilieren. Für diese Sprachen kompiliert CodeQL den Code vor dessen Analyse. Führe autobuild zwischen den Schritten init und analyze aus.

Flag	Erforderlich	Eingabewert
--language		Zu kompilierende Sprache. Der CodeQL runner kompiliert standardmäßig die kompilierte Sprache mit den meisten Dateien.
--temp-dir		Verzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--debug		Keine. Gibt eine ausführlichere Ausgabe aus.
-h, --help		Keine. Zeigt Hilfe für den Befehl an.

analyze

Analysiert den Code in den CodeQL-Datenbanken und lädt Ergebnisse in GitHub Enterprise Server hoch.

Flag	Erforderlich	Eingabewert
--repository	✓	Name des zu analysierenden Repositorys
--commit	✓	SHA des zu analysierenden Commits. In Git und Azure DevOps entspricht dies dem Wert von git rev-parse HEAD. In Jenkins entspricht dies $GIT_COMMIT.
--ref	✓	Name des zu analysierenden Verweises (z. B. refs/heads/main oder refs/pull/42/merge). In Git oder Jenkins entspricht dies dem Wert von git symbolic-ref HEAD. In Azure DevOps entspricht dies $(Build.SourceBranch).
--github-url	✓	URL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdin	✓	Liest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--checkout-path		Pfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--no-upload		Keine. Sorgt dafür, dass der CodeQL runner keine Ergebnisse mehr in GitHub Enterprise Server hochlädt.
--output-dir		Verzeichnis, in dem die SARIF-Ausgabedateien gespeichert werden. Die Standardeinstellung entspricht dem Verzeichnis temporärer Dateien.
--ram		Menge des beim Ausführen von Abfragen zu verwendenden Arbeitsspeichers. Die Standardeinstellung legt fest, dass der gesamte verfügbare Arbeitsspeicher verwendet wird.
--no-add-snippets		Keine. Schließt Codeausschnitte aus der SARIF-Ausgabe aus.
--category		Kategorie, die in die SARIF-Ergebnisdatei für diese Analyse aufgenommen werden soll. Eine Kategorie kann verwendet werden, um mehrere Analysen für dasselbe Tool und denselben Commit zu unterscheiden, die jedoch für verschiedene Sprachen oder Teile des Codes ausgeführt werden. Dieser Wert wird in der <run>.automationDetails.id-Eigenschaft in SARIF v2.1.0 angezeigt.
--threads		Anzahl der beim Ausführen von Abfragen zu verwendenden Threads. Die Standardeinstellung legt fest, dass alle verfügbaren Kerne verwendet werden.
--temp-dir		Verzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--debug		Keine. Gibt eine ausführlichere Ausgabe aus.
-h, --help		Keine. Zeigt Hilfe für den Befehl an.

upload

Lädt SARIF-Dateien in GitHub Enterprise Server hoch.

Flag	Erforderlich	Eingabewert
--sarif-file	✓	Hochzuladende SARIF-Datei oder Verzeichnis, das mehrere SARIF-Dateien enthält
--repository	✓	Name des analysierten Repositorys
--commit	✓	SHA des analysierten Commits. In Git und Azure DevOps entspricht dies dem Wert von git rev-parse HEAD. In Jenkins entspricht dies $GIT_COMMIT.
--ref	✓	Name des analysierten Verweises (z. B. refs/heads/main oder refs/pull/42/merge). In Git oder Jenkins entspricht dies dem Wert von git symbolic-ref HEAD. In Azure DevOps entspricht dies $(Build.SourceBranch).
--github-url	✓	URL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdin	✓	Liest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--checkout-path		Pfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--debug		Keine. Gibt eine ausführlichere Ausgabe aus.
-h, --help		Keine. Zeigt Hilfe für den Befehl an.