Workflowkonfigurationsoptionen für die Codeüberprüfung

Bearbeiten Sie Ihre Workflowdatei, um zu konfigurieren, wie das erweiterte Setup den Code in Ihrem Projekt auf Sicherheitsrisiken und Fehler überprüft.

Wer kann dieses Feature verwenden?

Benutzer*innen mit Schreibzugriff if advanced setup is already enabled

In diesem Artikel

Hinweis

Der Websiteadministrator muss code scanning aktivieren, damit du dieses Feature verwenden kannst. Wenn du GitHub Actions zum Überprüfen deines Codes verwenden möchtest, muss der Websiteadministrator auch GitHub Actions aktivieren und die erforderliche Infrastruktur einrichten. Weitere Informationen finden Sie unter Konfigurieren der Codeüberprüfung für Ihre Anwendung.

Hinweis

In diesem Artikel werden die Features beschrieben, die in der Version der CodeQL-Aktion und dem zugehörigen CodeQL CLI-Bundle im ursprünglichen Release dieser Version von GitHub Enterprise Server enthalten sind. Wenn dein Unternehmen eine neuere Version der CodeQL-Aktion verwendet, findest du Informationen zu den neuesten Features in der GitHub Enterprise Cloud-Version dieses Artikels. Informationen zum Verwenden der aktuellen Version findest du unter Konfigurieren der Codeüberprüfung für Ihre Anwendung.

Voraussetzungen

Sie müssen die erweiterte Einrichtung verwenden code scanning und in der Lage sein, die Workflowdatei zu bearbeiten, in der Ihre Konfiguration definiert ist.

Die in diesem Artikel aufgeführten Beispiele beziehen sich auf die CodeQL-Analyseworkflow Datei. Standardmäßig ist diese Datei an .github/workflows/codeql-analysis.yml festgelegt.

Scanhäufigkeit

Sie können den Code für die CodeQL-Analyseworkflow Überprüfung in einem Zeitplan oder beim Auftreten bestimmter Ereignisse in einem Repository konfigurieren.

Das Scannen von Code bei jedem Pushvorgang zum Repository und jedes Mal, wenn eine Pullanforderung erstellt wird, verhindert, dass Entwickler neue Sicherheitsrisiken und Fehler in den Code einführen. Das Scannen von Code in einem Zeitplan informiert Sie über die neuesten Sicherheitsrisiken und Fehler, die GitHubSicherheitsforscher und die Community entdecken, auch wenn Entwickler das Repository nicht aktiv verwalten.

Überprüfen bei Push

Standardmäßig wird das CodeQL-Analyseworkflowon:push Ereignis verwendet, um einen Codescan auf jedem Push an die Standardverzweigung des Repositorys und alle geschützten Verzweigungen auszulösen. Damit code scanning er in einer angegebenen Verzweigung ausgelöst werden kann, muss der Workflow in dieser Verzweigung vorhanden sein. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.

Wenn Sie auf Push scannen, werden die Ergebnisse auf der Security Registerkarte für Ihr Repository angezeigt. Weitere Informationen finden Sie unter Bewertung von Code-Scanning-Warnungen für Ihr Repository.

Wenn eine on:push-Überprüfung ein Ergebnis zurückgibt, das einer offenen Pullanforderung zugeordnet werden kann, werden diese Warnungen für die Pullanforderung automatisch am gleichen Ort wie andere Pullanforderungswarnungen angezeigt. Die Warnungen werden identifiziert, indem die vorhandene Analyse des HEAD des Branch mit der Analyse für den Zielbranch verglichen wird. Weitere Informationen zu code scanning Warnungen in Pullanforderungen finden Sie unter Filtern von Codescanbenachrichtigungen in Pull-Anforderungen.

Überprüfen von Pullanforderungen

          CodeQL-Analyseworkflow Standardmäßig wird das `pull_request` Ereignis verwendet, um einen Codescan für Pullanforderungen für die Standardverzweigung auszulösen. 
          Das `pull_request` Ereignis wird nicht ausgelöst, wenn die Pullanforderung aus einer privaten Verzweigung geöffnet wurde.

Weitere Informationen zum Ereignis pull_request finden Sie unter Ereignisse zum Auslösen von Workflows.

Wenn Sie Pullanforderungen scannen, werden die Ergebnisse in einer Pullanforderungsüberprüfung als Warnungen angezeigt. Weitere Informationen finden Sie unter Filtern von Codescanbenachrichtigungen in Pull-Anforderungen.

Wenn du den pull_request-Trigger verwendest, der so konfiguriert ist, dass anstelle des HEAD-Commits der Mergecommit der Pullanforderung überprüft wird, führt dies zu effizienteren und genaueren Ergebnissen als eine HEAD-Überprüfung für den Branch bei jedem Pushvorgang. Wenn Sie jedoch ein CI/CD-System verwenden, das nicht zum Auslösen von Pullanforderungen konfiguriert werden kann, können Sie den on:push Trigger weiterhin verwenden und code scanning die Ergebnisse zuordnen, um Pullanforderungen in der Verzweigung zu öffnen und die Warnungen als Anmerkungen zur Pullanforderung hinzuzufügen. Weitere Informationen finden Sie unter Überprüfen bei Push.

Vermeiden unnötiger Überprüfungen von Pullanforderungen

Möglicherweise möchten Sie verhindern, dass ein Codescan für bestimmte Pullanforderungen ausgelöst wird, die sich auf den Standardbranch beziehen, und zwar unabhängig davon, welche Dateien geändert wurden. Sie können dies konfigurieren, indem Sie den Workflow angeben oder on:pull_request:paths im code scanning Workflow angebenon:pull_request:paths-ignore. Wenn die einzigen Änderungen in einer Pullanforderung z. B. Dateien mit den Dateierweiterungen .md oder .txt sind, können Sie das folgende paths-ignore-Array verwenden.

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

Hinweis

          `on:pull_request:paths-ignore` und `on:pull_request:paths` legen Bedingungen fest, die bestimmen, ob die Aktionen im Workflow bei einer Pullanforderung ausgeführt werden. Es wird nicht bestimmt, welche Dateien analysiert werden, wenn die Aktionen _tatsächlich_ ausgeführt werden. Wenn eine Pullanforderung alle Dateien enthält, die nicht mit `on:pull_request:paths-ignore` oder `on:pull_request:paths` übereinstimmen, führt der Workflow die Aktionen aus und überprüft alle Dateien, die in der Pullanforderung geändert wurden, einschließlich der mit `on:pull_request:paths-ignore` oder `on:pull_request:paths` übereinstimmenden, es sei denn, die Dateien wurden ausgeschlossen. Informationen zum Ausschließen von Dateien aus der Analyse finden Sie unter [Angeben von Verzeichnissen zum Überprüfen](#specifying-directories-to-scan).

Weitere Informationen dazu, wie on:pull_request:paths-ignore und on:pull_request:paths verwendet werden, um zu bestimmen, wann ein Workflow für eine Pullanforderung ausgeführt wird, finden Sie unter Workflowsyntax für GitHub Actions.

Scannen nach einem Zeitplan

Wenn Sie die Standardeinstellung CodeQL-Analyseworkflowverwenden, scannt der Workflow den Code in Ihrem Repository einmal pro Woche, zusätzlich zu den durch Ereignisse ausgelösten Scans. Um diesen Zeitplan anzupassen, bearbeite den cron-Wert für das on.schedule-Ereignis im Workflow. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.

Hinweis

Dieses Ereignis löst nur dann eine Workflowausführung aus, wenn die Workflowdatei im Standardbranch vorhanden ist.

Beispiel

Das folgende Beispiel zeigt einen CodeQL-Analyseworkflow für ein bestimmtes Repository mit einem Standardzweig namens main und einer geschützten Verzweigung, die aufgerufen wird protected.

YAML
on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '20 14 * * 1'

Dieser Workflow scannt Folgendes:

  • Jeden Pushvorgang in den Standardbranch und den geschützten Branch
  • Jede Pullanforderung an den Standardbranch
  • Den Standardbranch jeden Montag um 14:20 UTC

Betriebssystem

Hinweis

  • Bei der Codeüberprüfung von Swift-Code werden standardmäßig macOS-Runner verwendet.
  • Code scanning von Swift-Code werden für Runner, die Teil einerActions Runner Controller (ARC) sind, nicht unterstützt, da ARC-Runner nur Linux verwenden und Swift macOS-Runner erfordert. Sie können jedoch eine Mischung aus ARC-Runnern und selbst gehosteten macOS-Runnern haben. Weitere Informationen finden Sie unter Actions Runner Controller (Steuerung für Aktionsläufer).

Wenn Ihr Code ein bestimmtes Betriebssystem zum Kompilieren benötigt, können Sie das Betriebssystem in Ihrem CodeQL-AnalyseworkflowBetriebssystem konfigurieren. Bearbeiten Sie den Wert, um jobs.analyze.runs-on das Betriebssystem für den Computer anzugeben, auf dem Ihre code scanning Aktionen ausgeführt werden. Sie geben das Betriebssystem an, indem Sie eine entsprechende Bezeichnung als zweites Element in einem Zwei-Element-Array nach .self-hosted

YAML
jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

          CodeQL
          code scanning unterstützt die neuesten Versionen von Ubuntu, Windows und macOS. Typische Werte für diese Einstellung sind daher: `ubuntu-latest`, `windows-latest`und `macos-latest`. Weitere Informationen findest du unter [AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job) und [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners).

          Sie müssen sicherstellen, dass Git sich in der PATH-Variablen auf Ihren selbst gehosteten Läufern befindet. Weitere Informationen findest du unter [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) und [AUTOTITLE](/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners).

Empfohlene Spezifikationen (RAM, CPU-Kerne und Datenträger) für die Ausführung der CodeQL Analyse finden Sie unter Empfohlene Hardwareressourcen zum Ausführen von CodeQL.

          CodeQL Datenbankspeicherort

Im Allgemeinen müssen Sie sich keine Gedanken darüber machen, wo die Datenbanken platziert CodeQL werden, da die späteren Schritte automatisch Datenbanken finden, die CodeQL-Analyseworkflow mit vorherigen Schritten erstellt wurden. Wenn Sie jedoch einen benutzerdefinierten Workflowschritt schreiben, der erfordert, dass sich die CodeQL Datenbank an einem bestimmten Datenträgerspeicherort befindet, z. B. zum Hochladen der Datenbank als Workflowartefakt, können Sie diesen Speicherort mithilfe des db-location Parameters unter der init Aktion angeben.

YAML
- uses: github/codeql-action/init@v4
  with:
    db-location: '${{ github.runner_temp }}/my_location'

Es CodeQL-Analyseworkflow wird erwartet, dass der angegebene db-location Pfad schreibbar ist und entweder nicht vorhanden ist oder ein leeres Verzeichnis ist. Wenn du diesen Parameter in einem Auftrag verwendest, der auf einem selbstgehosteten Runner ausgeführt oder für den ein Docker-Container verwendet wird, ist es die Verantwortung des Benutzers, sicherzustellen, dass das ausgewählte Verzeichnis zwischen den Ausführungen gelöscht wird oder dass die Datenbanken entfernt werden, sobald sie nicht mehr benötigt werden. Dies ist nicht erforderlich für Aufträge, die auf - GitHubgehosteten Läufern ausgeführt werden, die bei jeder Ausführung eine neue Instanz und ein sauberes Dateisystem erhalten. Weitere Informationen finden Sie unter Von GitHub gehostete Runner.

Wenn dieser Parameter nicht verwendet wird, erstellt die CodeQL-Analyseworkflow Datenbank an einem temporären Speicherort ihrer eigenen Wahl. Derzeit ist ${{ github.runner_temp }}/codeql_databasesder Standardwert .

Zu analysierende Sprachen

          CodeQL
          code scanning unterstützt Code, der in den folgenden Sprachen geschrieben wurde:
  • C/C++
  • C#
  • OK
  • Java/Kotlin
  • JavaScript/TypeScript
  • Python
  • Ruby
  • Swift

Hinweis

  • Verwenden Sie java-kotlin zum Analysieren von Code, der in Java, Kotlin oder beiden Sprachen geschrieben wurde.
  • Verwenden Sie javascript-typescript zum Analysieren von Code, der in JavaScript, TypeScript oder beiden Sprachen geschrieben wurde.

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

          CodeQL verwendet die folgenden Sprachbezeichner:
SpracheIdentifierOptionale alternative Bezeichner (falls vorhanden)
C/C++c-cpp
          `c` oder `cpp` |

| C# | csharp | | | Go | go | | Java/Kotlin | java-kotlin | java oder kotlin | | JavaScript/TypeScript | javascript-typescript | javascript oder typescript | | Python | python | | Ruby | ruby | | | Swift | swift |

Hinweis

Wenn du einen der alternativen Bezeichner angibst, entspricht dies der Verwendung des Standardsprachenbezeichners. Wenn Sie z. B. javascript anstelle von javascript-typescript angeben, wird die Analyse von TypeScript-Code nicht ausgeschlossen. Stattdessen kannst du eine benutzerdefinierte Konfigurationsdatei verwenden, um Dateien mithilfe der Einstellung paths-ignore von der Analyse auszuschließen. Weitere Informationen findest du unter Verwenden einer benutzerdefinierten Konfigurationsdatei und Angeben von Verzeichnissen zum Überprüfen.

Diese Sprachbezeichner können als Argumente für die Eingabe von languages der Aktion init verwendet werden. Es wird empfohlen, lediglich eine Sprache als Argument zur Verfügung zu stellen:

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: javascript-typescript

Die Standarddatei CodeQL-Analyseworkflow , die nach dem Konfigurieren des erweiterten Setups für die Codeüberprüfung mit CodeQL erstellt wurde, definiert eine Matrix, die eine Eigenschaft mit dem Namen language enthält, die die Sprachen in Ihrem Repository auflistet, die analysiert werden. Diese Matrix wurde automatisch mit unterstützten Sprachen aufgefüllt, die in deinem Repository erkannt wurden. Die Verwendung der language Matrix ermöglicht es CodeQL , jede Sprachanalyse parallel auszuführen und die Analyse für jede Sprache anzupassen. In einer einzelnen Analyse wird der Name der Sprache aus der Matrix der Aktion init als Argument für die Eingabe von languages bereitgestellt. Es wird empfohlen, dass alle Workflows diese Konfiguration übernehmen. Weitere Informationen zu Matrizen findest du unter Varianten von Aufgaben in einem Workflow ausführen.

YAML
- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}

Wenn Ihr Workflow die language Matrix verwendet, CodeQL werden die Sprachen in der Matrix nur analysiert. Bearbeite die Matrixkonfiguration, um die zu analysierenden Sprachen zu ändern. Du kannst eine Sprache entfernen, damit diese nicht analysiert wird. 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. Sie können auch eine Sprache hinzufügen, die bei der code scanning Konfiguration nicht im Repository vorhanden war. Wenn das Repository z. B. zunächst nur JavaScript enthielt, als code scanning konfiguriert wurde, und Sie später Python-Code hinzugefügt haben, müssen Sie der Matrix hinzufügen python .

YAML
jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

Für kompilierte Sprachen kann die Matrix zudem verwendet werden, um zu konfigurieren, welcher Buildmodus für die Analyse verwendet werden soll, indem der Wert der Eigenschaft build-mode geändert wird. Weitere Informationen zu Buildmodi findest du unter CodeQL-Codeüberprüfung für kompilierte Sprachen.

Wenn Ihr Workflow keine Argumente für die languages Eingabe der init Aktion bereitstellt, ist sie CodeQL so konfiguriert, dass Analysen sequenziell ausgeführt werden. In diesem Fall CodeQL erkennt und versucht, alle unterstützten Sprachen im Repository zu analysieren. Abhängig von der Größe des Repositorys und der Anzahl der Sprachen kann das lang dauern. Wenn die Analyse für eine Sprache in diesem Modus fehlschlägt, schlägt die Analyse für alle Sprachen fehl. Daher wird diese Konfiguration nicht empfohlen.

Hinweis

Bei der sequenziellen Analyse der Sprachen wird der Standardbuildmodus für jede Sprache verwendet. Wenn du einen expliziten autobuild-Schritt angibst, wird dieser von jeder Sprache verwendet, die den autobuild-Modus unterstützt, während andere Sprachen ihren Standardmodus verwenden. Wenn eine komplexere Buildmoduskonfiguration erforderlich ist, musst du eine Matrix konfigurieren.

Warnungsschweregrade für Überprüfungsfehler

Sie können Regelsätze verwenden, um zu verhindern, dass Pull Requests zusammengeführt werden, wenn eine der folgenden Bedingungen erfüllt ist:

  • Ein Pflichttool entdeckt eine code scanning-Warnung mit einem Schweregrad, der im Regelsatz definiert ist.
  • Die Analyse eines erforderlichen Tools wird noch ausgeführt.
  • Für das Repository ist kein erforderliches Tool konfiguriert.

Weitere Informationen finden Sie unter Festlegen des Zusammenführungsschutzes für Codeüberprüfung. Weitere allgemeine Informationen zu Regelsätzen findest du unter Informationen zu Regelsätzen.

Analysekategorie

Verwende category, um zwischen mehreren Analysen für dasselbe Tool und denselben Commit zu unterscheiden, die jedoch für verschiedene Sprachen oder Teile des Codes ausgeführt werden. Die Kategorie, die du im Workflow angibst, wird in die SARIF-Ergebnisdatei aufgenommen.

Dieser Parameter ist besonders nützlich, wenn du mit Monorepos arbeitest und mehrere SARIF-Dateien für verschiedene Komponenten des Monorepo besitzen.

YAML
    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v4
      with:
        # Optional. Specify a category to distinguish between multiple analyses
        # for the same tool and ref. If you don't use `category` in your workflow,
        # GitHub will generate a default category name for you
        category: "my_category"

Wenn Sie keinen Parameter in Ihrem Workflow angeben category , GitHub wird ein Kategoriename für Sie generiert, basierend auf dem Namen der Workflowdatei, die die Aktion auslöst, den Aktionsnamen und alle Matrixvariablen. Beispiel:

  • Der Workflow .github/workflows/codeql-analysis.yml und die Aktion analyze erzeugen die Kategorie .github/workflows/codeql.yml:analyze.
  • Der Workflow .github/workflows/codeql-analysis.yml, die Aktion analyze und die Matrixvariablen {language: javascript-typescript, os: linux} erzeugen die Kategorie .github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux.

Der category-Wert wird als Eigenschaft <run>.automationDetails.id in SARIF v2.1.0 angezeigt. Weitere Informationen finden Sie unter SARIF-Unterstützung für die Codeüberprüfung.

Die Details des runAutomationDetails-Objekts in der SARIF-Datei werden, sofern enthalten, von der angegebenen Kategorie nicht überschrieben.

          CodeQL Modellpakete

Wenn Ihre Codebasis von einer Bibliothek oder einem Framework abhängt, die von den Standardabfragen CodeQLnicht erkannt wird, können Sie die CodeQL Abdeckung in Ihrem code scanning Workflow erweitern, indem Sie veröffentlichte CodeQL Modellpakete angeben. Weitere Informationen zum Erstellen von eigenen Modellpaketen findest du unter Erstellen und Arbeiten mit CodeQL-Paketen.

Hinweis

CodeQL-Modellpakete liegen derzeit als öffentliche Vorschau vor und können noch geändert werden. Modellpakete werden für die C/C++, C#, Java/Kotlin, Python, und Ruby-Analyse unterstützt.

Der CodeQL-Modell-Editor in der CodeQL-Erweiterung für Visual Studio Code unterstützt Modellierungsabhängigkeiten für C#, Java/Kotlin, Python und Ruby.

Verwenden von CodeQL Modellpaketen

Wenn Sie ein oder mehrere veröffentlichte CodeQL Modellpakete hinzufügen möchten, geben Sie diese innerhalb des with: packs: Eintrags im uses: github/codeql-action/init@v4 Abschnitt des Workflows an. In packs gibst du mindestens ein Paket an, das verwendet werden soll. Optional kannst du angeben, welche Version heruntergeladen werden soll. Wenn du keine Version angibst, wird die neueste Version heruntergeladen. Wenn du Pakete verwenden möchtest, die nicht öffentlich verfügbar sind, musst du die Umgebungsvariable GITHUB_TOKEN auf ein Geheimnis festlegen, das Zugriff auf die Pakete hat. Weitere Informationen findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows und Verwenden von Geheimnissen in GitHub-Aktionen.

YAML
- uses: github/codeql-action/init@v4
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: security-extended
    packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack

In diesem Beispiel werden die Standardabfragen für Java sowie die Abfragen aus einer Version ausgeführt, die größer oder gleich 7.8.9 und kleiner als 7.9.0 des Abfragepakets my-company/my-java-queries ist. Die Abhängigkeiten, die in der neuesten Version des Modellpakets my-repo/my-java-model-pack modelliert sind, stehen sowohl für die Standardabfragen als auch für die in my-company/my-java-queries zur Verfügung.

Nicht standardmäßige 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.

Tipp

Du kannst außerdem die Abfragen angeben, die du von der Analyse ausschließen oder in die Analyse einbeziehen möchtest. Dies erfordert die Verwendung einer benutzerdefinierten Konfigurationsdatei. Weitere Informationen finden Sie unter Benutzerdefinierte Konfigurationsdateien und Ausschließen bestimmter Abfragen aus der folgenden Analyse .

Sie können zusätzliche Abfragen ausführen, wenn diese Teil eines CodeQL-Pakets sind, das in der GitHub Container registry oder einem -Paket veröffentlich wurde, das in einem Repository gespeichert ist. Weitere Informationen finden Sie unter Informationen zu Codescans mit CodeQL.

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 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. Weitere Informationen zu Definitionen von Abfragesammlungen findest du unter [Erstellen von CodeQL-Abfragesammlungen](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/).

Du kannst sowohl packs als auch queries in demselben Workflow verwenden.

Verwenden von Abfragepaketen

Um ein oder CodeQL mehrere Abfragepakete hinzuzufügen, fügen Sie einen with: packs: Eintrag im uses: github/codeql-action/init@v4 Abschnitt des Workflows hinzu. In packs gibst du mindestens ein Paket an, das verwendet werden soll. Optional kannst du angeben, welche Version heruntergeladen werden soll. Wenn du keine Version angibst, wird die neueste Version heruntergeladen. Wenn du Pakete verwenden möchtest, die nicht öffentlich verfügbar sind, musst du die Umgebungsvariable GITHUB_TOKEN auf ein Geheimnis festlegen, das Zugriff auf die Pakete hat. Weitere Informationen findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows und Verwenden von Geheimnissen in GitHub-Aktionen.

Hinweis

Für Workflows, die Datenbanken für mehrere Sprachen generieren CodeQL , müssen Sie stattdessen die CodeQL Abfragepakete in einer Konfigurationsdatei angeben. Weitere Informationen finden Sie weiter unten unter Angeben von CodeQL Abfragepaketen .

Im folgenden Beispiel ist scope die Organisation oder das persönliche Konto, die/das das Paket veröffentlicht hat. Wenn der Workflow ausgeführt wird, werden die vier CodeQL Abfragepakete heruntergeladen GitHub und die Standardabfragen oder Abfragesuite für jedes Pack ausgeführt:

  • Die neueste Version von pack1 wird heruntergeladen, und alle Standardabfragen werden ausgeführt.
  • Version 1.2.3 von pack2 wird heruntergeladen, und alle Standardabfragen werden ausgeführt.
  • Die neueste Version von 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 in path/to/queries gefundenen Abfragen werden ausgeführt.
YAML
- uses: github/codeql-action/init@v4
  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

Wenn Sie eine bestimmte Version eines zu verwendenden Abfragepakets angeben, achten Sie darauf, dass die angegebene Version möglicherweise zu alt wird, um effizient vom Standardmodul CodeQL verwendet zu werden, das von der CodeQL Aktion verwendet wird. Wenn du eine genaue Abfragepaketversion angeben musst, solltest du regelmäßig überprüfen, ob die angeheftete Version des Abfragepakets aktualisiert werden muss, um eine optimale Leistung sicherzustellen.

Weitere Informationen zur Kompatibilität von Paketen findest du unter Referenz zu CodeQL-Abfragepaketen.

Herunterladen von Paketen CodeQL von GitHub Enterprise Server

Wenn Ihr Workflow Pakete verwendet, die in einer GitHub Enterprise Server Installation veröffentlicht werden, müssen Sie Ihrem Workflow mitteilen, wo sie zu finden sind. Dazu können Sie die registries Eingabe der github/codeql-action/init@v4 Aktion verwenden. Diese Eingabe akzeptiert eine Liste mit den Eigenschaften url, packages und token, wie unten gezeigt.

YAML
- uses: github/codeql-action/init@v4
  with:
    registries: |
      # URL to the container registry, usually in this format
      - url: https://containers.GHEHOSTNAME1/v2/

        # List of package glob patterns to be found at this registry
        packages:
          - my-company/*
          - my-company2/*

        # Token, which should be stored as a secret
        token: ${{ secrets.GHEHOSTNAME1_TOKEN }}

      # URL to the default container registry
      - url: https://ghcr.io/v2/
        # Packages can also be a string
        packages: "*/*"
        token: ${{ secrets.GHCR_TOKEN }}

Die Paketmuster in der Registrierungsliste werden in der angegebenen Reihenfolge überprüft, daher solltest das spezifischste Paketmuster in der Regel zuerst angeben. Die Werte müssen token von personal access token (classic) der GitHub-Instanz generiert werden, aus der Sie mit der read:packages Berechtigung herunterladen.

Beachte das | nach dem Eigenschaftsnamen registries. Dies ist wichtig, da GitHub Actions Eingaben nur Zeichenfolgen akzeptieren können. Die Verwendung des | nachfolgenden Texts wird in eine Zeichenfolge konvertiert, die später von der github/codeql-action/init@v4 Aktion analysiert wird.

Verwenden von Abfragen in QL-Paketen

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

Du kannst auch Abfragesammlungen im Wert von queries angeben. Abfragesammlungen sind Sammlungen von Abfragen, die in der Regel nach Zweck oder Sprache gruppiert sind.

YAML
- uses: github/codeql-action/init@v4
  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 }}

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

AbfrageauflistungBeschreibung
security-extendedAbfragen aus der Standardsuite sowie Abfragen mit geringerem Schweregrad und Genauigkeit
security-and-qualityAbfragen von security-extended, sowie zusätzliche Abfragen zur Verwaltbarkeit und Zuverlässigkeit

Weitere Informationen findest du unter CodeQL-Abfragesammlungen.

Jede dieser Abfragesammlungen enthält eine andere Teilmenge der Abfragen, die sich im integrierten CodeQL-Abfragepaket für diese Sprache befinden. Die Abfragesammlungen werden automatisch mithilfe der Metadaten für jede Abfrage generiert. Weitere Informationen findest du unter Metadaten für CodeQL-Abfragen.

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.

Arbeiten mit benutzerdefinierten Konfigurationsdateien

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. Weitere Informationen finden Sie unter benutzerdefinierte Konfigurationsdateien.

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.

YAML
- uses: github/codeql-action/init@v4
  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

Benutzerdefinierte Konfigurationsdateien

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, spezifische Abfragen auszuschließen oder einzuschließen 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.

YAML
- uses: github/codeql-action/init@v4
  with:
    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 können Sie 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

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.

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

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

Angeben von CodeQL Abfragepaketen

Sie geben Abfragepakete in einem Array an CodeQL . Beachten Sie, dass sich das Format von dem Format unterscheidet, das von der Workflowdatei verwendet wird.

YAML
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]. Sowohl version als auch path sind optional. version ist der SemVer-Versionsbereich. Wenn dieser fehlt, wird die neueste Version verwendet. Weitere Informationen zu SemVer-Bereichen findest du in der SemVer-Dokumentation auf der npm-Website.

Wenn Sie über einen Workflow verfügen, der mehrere CodeQL Datenbanken generiert, können Sie alle CodeQL Abfragepakete angeben, die in einer benutzerdefinierten Konfigurationsdatei mit einer geschachtelten Zuordnung von Paketen ausgeführt werden sollen.

YAML
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

Erweitern der CodeQL Abdeckung mit Bedrohungsmodellen

Hinweis

Gefahrenmodelle befinden sich derzeit in der öffentliche Vorschau. Änderungen sind vorbehalten. Während der öffentliche Vorschau werden Gefahrenmodelle nur durch die Analyse für Java/Kotlin und C# unterstützt.

Das Standard-Gefahrenmodell enthält Remotequellen nicht vertrauenswürdiger Daten. Sie können das CodeQL Bedrohungsmodell erweitern, um lokale Quellen nicht vertrauenswürdiger Daten (z. B. Befehlszeilenargumente, Umgebungsvariablen, Dateisysteme und Datenbanken) einzuschließen, indem Sie in einer benutzerdefinierten Konfigurationsdatei angeben threat-models: local . Wenn Sie das Gefahrenmodell erweitern, wird auch das Standard-Gefahrenmodell verwendet.

Angeben zusätzlicher Abfragen

Du gibst zusätzliche Abfragen in einem queries-Array an. 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.

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

Optional kannst du jedem Arrayelement einen Namen geben, wie in den folgenden Beispielkonfigurationsdateien gezeigt. Weitere Informationen zu zusätzlichen Abfragen finden Sie oben unter "Nicht standardmäßige Abfragen ".

Deaktivieren der Standardabfragen

Wenn Sie nur benutzerdefinierte Abfragen ausführen möchten, können Sie die Standardsicherheitsabfragen mit disable-default-queries: true deaktivieren.

Ausschließen bestimmter Abfragen aus der Analyse

Du kannst exclude- und include-Filter in deine benutzerdefinierte Konfigurationsdatei einfügen, um die Abfragen festzulegen, die du bei der Analyse ausschließen oder einbeziehen möchtest.

Dies ist nützlich, wenn du bestimmte Abfragen ausschließen möchtest:

  • Bestimmte Abfragen aus den Standardsammlungen (security, security-extended und security-and-quality)
  • Spezifische Abfragen, deren Ergebnisse für dich nicht relevant sind
  • Alle Abfragen, die Warnungen und Empfehlungen generieren

Du kannst exclude-Filter ähnlich denen in der Konfigurationsdatei unten verwenden, um Abfragen auszuschließen, die du aus der Standardanalyse entfernen möchtest. In der folgenden Beispielkonfigurationsdatei werden sowohl die js/redundant-assignment- als auch die js/useless-assignment-to-local-Abfragen aus der Analyse ausgeschlossen.

YAML
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 Security Registerkarte klicken. Dadurch wird die Seite mit den Warnungsdetails geöffnet. Das Feld Rule ID enthält die Abfrage-ID. Weitere Informationen zur Seite mit den Warnungsdetails finden Sie unter Informationen zu Codeüberprüfungswarnungen.

Tipp

  • 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.

Ein weiteres Beispiel zur Veranschaulichung der Verwendung dieser Filter finden Sie im Abschnitt Beispielkonfigurationsdateien.

Weitere Informationen zur Verwendung von exclude- und include-Filtern in Ihrer benutzerdefinierten Konfigurationsdatei finden Sie unter Erstellen von CodeQL-Abfragesammlungen. Informationen zu den Abfragemetadaten, nach denen Sie filtern können, finden Sie unter Metadaten für CodeQL-Abfragen.

Angeben der zu scannenden Verzeichnisse

Wenn Codebases analysiert werden, ohne den Code zu erstellen, können Sie auf Dateien in bestimmten Verzeichnissen einschränken code scanning , indem Sie der Konfigurationsdatei ein paths Array hinzufügen. Außerdem können Sie die Dateien in bestimmten Verzeichnissen von der Analyse ausschließen, indem Sie ein paths-ignore-Array hinzufügen. Sie können diese Option verwenden, wenn Sie die CodeQL Aktionen für eine interpretierte Sprache (Python, Ruby und JavaScript/TypeScript) ausführen oder wenn Sie eine kompilierte Sprache analysieren, ohne den Code zu erstellen (derzeit unterstützt für C# und Java).

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

Hinweis

  • Die paths im paths-ignore Kontext der code scanning Konfigurationsdatei verwendeten Schlüsselwörter sollten nicht mit den gleichen Schlüsselwörtern verwechselt werden, wenn sie in einem Workflow verwendet werden on.<push|pull_request>.paths . 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. Weitere Informationen finden Sie unter Workflowsyntax für GitHub Actions.
  • Die Filtermusterzeichen ?, +, [, ] und ! werden nicht unterstützt und werden literal wörtlich abgeglichen.
          `**`-Zeichen dürfen sich nur am Anfang oder Ende einer Zeile befinden oder müssen in Schrägstrichen eingeschlossen sein. Sie dürfen `**` und andere Zeichen nicht mischen. Beispielsweise stellen die Zeichenfolgen `foo/**`, `**/foo` und `foo/**/bar` zulässige Syntax dar, `**foo` aber nicht. Du kannst jedoch einzelne Sternchen zusammen mit anderen Zeichen verwenden, wie im Beispiel gezeigt. Sie müssen alle Zeichenfolgen in Anführungszeichen einschließen, die ein `*`-Zeichen enthalten.

Für die Analyse, in der Code erstellt wird, müssen Sie die entsprechenden Buildschritte im Workflow angeben, wenn Sie auf bestimmte Verzeichnisse in Ihrem Projekt beschränken code scanning möchten. Welche Befehle Sie verwenden müssen, um ein Verzeichnis aus dem Buildvorgang auszuschließen, hängt von Ihrem Buildsystem ab. Weitere Informationen finden Sie unter CodeQL-Codeüberprüfung für kompilierte Sprachen.

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.

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 finden Sie unter Nichtstandardabfragen.

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 CodeQL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript CodeQL pack (run queries from an external repo)
    uses: octo-org/javascript-codeql-pack@main
  - name: Use an external query (run a single query from an external CodeQL pack)
    uses: octo-org/python-codeql-pack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls

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

Die folgende Konfigurationsdatei führt nur Abfragen aus, die Warnungen mit dem Schweregrad „Fehler“ generieren. Die Konfiguration wählt zunächst alle Standardabfragen, alle Abfragen in ./my-queries sowie die Standardsammlung in codeql/java-queries aus und schließt dann alle Abfragen aus, die Warnungen oder Empfehlungen generieren.

queries:
  - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Konfigurationsdetails

Wenn Sie zusätzliche Konfigurationsdetails in der Workflowdatei angeben möchten, können Sie die config Eingabe des init Befehls der CodeQL Aktion verwenden. Der Wert dieser Eingabe muss eine YAML-Zeichenfolge sein, die dem konfigurationsdateiformat folgt, das in benutzerdefinierten Konfigurationsdateien oben dokumentiert ist.

Beispielkonfiguration

In diesem Schritt in einer GitHub Actions Workflowdatei wird eine config Eingabe verwendet, um die Standardabfragen zu deaktivieren, die security-extended Abfragesuite hinzuzufügen und Abfragen auszuschließen, die mit cwe-020markiert sind.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: |
      disable-default-queries: true
      threat-models: local
      queries:
        - uses: security-extended
      query-filters:
        - exclude:
            tags: /cwe-020/

Du kannst denselben Ansatz verwenden, um gültige Konfigurationsoptionen in der Workflowdatei anzugeben.

Tipp

Mithilfe von GitHub Actions Variablen können Sie eine Konfiguration für mehrere Repositorys freigeben. Ein Vorteil dieses Ansatzes ist, dass du die Konfiguration an einem zentralen Ort aktualisieren kannst, ohne die Workflowdatei zu bearbeiten.

Im folgenden Beispiel vars.CODEQL_CONF handelt es sich um eine GitHub Actions Variable. Ihr Wert kann der Inhalt einer beliebigen gültigen Konfigurationsdatei sein. Weitere Informationen finden Sie unter Speichern von Informationen in Variablen.

- uses: github/codeql-action/init@v4
  with:
    languages: ${{ matrix.language }}
    config: ${{ vars.CODEQL_CONF }}

Kompilierte Sprachen

Für kompilierte Sprachen können Sie entscheiden, wie die Aktion eine CodeQL Datenbank für die CodeQL Analyse erstellt. Informationen zu den verfügbaren Buildoptionen findest du unter CodeQL-Codeüberprüfung für kompilierte Sprachen.

Datenupload

          GitHub kann Codeanalysedaten anzeigen, die extern von einem Drittanbietertool generiert werden. Du kannst Codeanalysedaten mit der Aktion `upload-sarif` hochladen. Weitere Informationen finden Sie unter [AUTOTITLE](/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github).