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.
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
--queries
+
-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
$ /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.
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.
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. |