Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

Diese Version von GitHub Enterprise wurde eingestellt am 2023-01-18. Es wird keine Patch-Freigabe vorgenommen, auch nicht für kritische Sicherheitsprobleme. Für bessere Leistung, verbesserte Sicherheit und neue Features aktualisiere auf die neueste Version von GitHub Enterprise. Wende dich an den GitHub Enterprise-Support, um Hilfe zum Upgrade zu erhalten.

Konfigurieren des CodeQL-Runners in deinem CI-System

Du kannst konfigurieren, wie der CodeQL runner den Code in deinem Projekt überprüft und die Ergebnisse auf GitHub hochlädt.

Code scanning ist für organisationseigene Repositorys in GitHub Enterprise Server verfügbar. Dieses Feature erfordert eine Lizenz für GitHub Advanced Security. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Hinweis: Der CodeQL runner ist veraltet. Ab Version 3.0 von GitHub Enterprise Server kannst du die Version 2.6.3 von CodeQL CLI installieren, um CodeQL runner zu ersetzen.

Weitere Informationen findest du unter Veraltung des CodeQL-Runners. Informationen zum Migrieren zu CodeQL CLI findest du unter Migrieren vom CodeQL-Runner zur CodeQL-CLI.

Hinweis: Dein Websiteadministrator muss code scanning für your GitHub Enterprise Server instance aktivieren, damit du dieses Feature verwenden kannst. Weitere Informationen findest du unter Konfigurieren von code scanning für deine Appliance.

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

Hinweis: Wenn du Code mit einem Drittanbietertool analysieren und die Ergebnisse als Pull-Request-Überprüfungen anzeigen möchtest, musst du den upload-Befehl ausführen und das --ref-Flag verwenden, um den Pull Request anstelle des Branchs anzugeben. Der Verweis entspricht refs/pull/<PR-number>/head oder refs/pull/<PR-number>/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

Hinweis: Verwende javascript zum Analysieren von Code, der in JavaScript, TypeScript oder beiden Sprachen geschrieben wurde.

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.

AbfrageauflistungBeschreibung
security-extendedAbfragen aus der Standardsammlung sowie Abfragen zu niedrigeren Schweregraden und Genauigkeit
security-and-qualityAbfragen 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.

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.

FlagErforderlichEingabewert
--repositoryName des zu initialisierenden Repositorys
--github-urlURL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdinLiest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--languagesDurch Kommas getrennte Liste der zu analysierenden Sprachen. Der CodeQL runner erkennt und analysiert standardmäßig alle unterstützten Sprachen im Repository.
--queriesDurch 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-filePfad zur benutzerdefinierten Konfigurationsdatei
--codeql-pathPfad 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-dirVerzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--tools-dirVerzeichnis, in dem CodeQL-Tools und andere Dateien zwischen Ausführungen gespeichert werden. Die Standardeinstellung ist ein Unterverzeichnis des Stammverzeichnisses.
--checkout-pathPfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--debugKeine. Gibt eine ausführlichere Ausgabe aus.
--trace-process-nameErweitert, nur Windows. Name des Prozesses, in den ein Windows-Tracer dieses Prozesses injiziert wird.
--trace-process-levelErweitert, nur Windows. Anzahl der nächsthöheren Ebenen des übergeordneten Prozesses, in den ein Windows-Tracer dieses Prozesses injiziert wird.
-h, --helpKeine. 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.

FlagErforderlichEingabewert
--languageZu kompilierende Sprache. Der CodeQL runner kompiliert standardmäßig die kompilierte Sprache mit den meisten Dateien.
--temp-dirVerzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--debugKeine. Gibt eine ausführlichere Ausgabe aus.
-h, --helpKeine. Zeigt Hilfe für den Befehl an.

analyze

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

FlagErforderlichEingabewert
--repositoryName des zu analysierenden Repositorys
--commitSHA des zu analysierenden Commits. In Git und Azure DevOps entspricht dies dem Wert von git rev-parse HEAD. In Jenkins entspricht dies $GIT_COMMIT.
--refName 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-urlURL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdinLiest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--checkout-pathPfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--no-uploadKeine. Sorgt dafür, dass der CodeQL runner keine Ergebnisse mehr in GitHub Enterprise Server hochlädt.
--output-dirVerzeichnis, in dem die SARIF-Ausgabedateien gespeichert werden. Die Standardeinstellung entspricht dem Verzeichnis temporärer Dateien.
--ramMenge des beim Ausführen von Abfragen zu verwendenden Arbeitsspeichers. Die Standardeinstellung legt fest, dass der gesamte verfügbare Arbeitsspeicher verwendet wird.
--no-add-snippetsKeine. Schließt Codeausschnitte aus der SARIF-Ausgabe aus.
--categoryKategorie, 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.
--threadsAnzahl der beim Ausführen von Abfragen zu verwendenden Threads. Die Standardeinstellung legt fest, dass alle verfügbaren Kerne verwendet werden.
--temp-dirVerzeichnis, in dem temporäre Dateien gespeichert werden. Der Standardwert lautet ./codeql-runner.
--debugKeine. Gibt eine ausführlichere Ausgabe aus.
-h, --helpKeine. Zeigt Hilfe für den Befehl an.

upload

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

Hinweis: Wenn du Code mit dem CodeQL-Runner analysierst, lädt der analyze-Befehl standardmäßig SARIF-Ergebnisse hoch. Du kannst den upload-Befehl zum Hochladen von SARIF-Ergebnissen verwenden, die von anderen Tools generiert wurden.

FlagErforderlichEingabewert
--sarif-fileHochzuladende SARIF-Datei oder Verzeichnis, das mehrere SARIF-Dateien enthält
--repositoryName des analysierten Repositorys
--commitSHA des analysierten Commits. In Git und Azure DevOps entspricht dies dem Wert von git rev-parse HEAD. In Jenkins entspricht dies $GIT_COMMIT.
--refName 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-urlURL der GitHub-Instanz, in der dein Repository gehostet wird
--github-auth-stdinLiest das GitHub Apps-Token oder personal access token aus der Standardeingabe.
--checkout-pathPfad zum Check-Out deines Repositorys. Die Standardeinstellung ist das aktuelle Arbeitsverzeichnis.
--debugKeine. Gibt eine ausführlichere Ausgabe aus.
-h, --helpKeine. Zeigt Hilfe für den Befehl an.