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.

Anpassen der Codeüberprüfung

In this article

Du kannst anpassen, wie GitHub Code in deinem Projekt auf Sicherheitsrisiken und Fehler überprüft.

Who can use this feature

People with write permissions to a repository can customize code scanning for the repository.

Code scanning ist für alle öffentlichen Repositorys auf GitHub.com verfügbar. Code scanning ist auch für private organisationseigene Repositorys verfügbar, die GitHub Enterprise Cloud nutzen und im Besitz einer Lizenz für GitHub Advanced Security sind. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Informationen zum Konfigurieren von code scanning

Du kannst code scanning mit GitHub Actions in GitHub oder auf deinem Continuous Integration(CI)-System ausführen.

Weitere Informationen findest du unter Informationen zu GitHub Actions oder Informationen zu CodeQL code scanning auf dem CI-System. Sowohl das Standardsetup als auch die erweiterten Setups für code scanning werden mithilfe von GitHub Actions ausgeführt.

Das Standardsetup ermittelt automatisch die beste code scanning-Konfiguration für dein Repository, während du das erweiterte Setup verwenden kannst, um einen code scanning-Workflow anzupassen. Weitere Informationen findest du unter Konfigurieren der code scanning für ein Repository. In diesem Artikel wird die Konfiguration des erweiterten Setups für die code scanning behandelt.

Mithilfe des erweiterten Setups kannst du Workflows wie den CodeQL analysis workflow von GitHub bearbeiten, um Folgendes anzugeben: die Häufigkeit der Scans, die zu scannenden Sprachen oder Verzeichnisse und das Suchziel der code scanning in deinem Code.

Möglicherweise musst du auch den Workflow bearbeiten, wenn du bestimmte Befehle verwendest, um deinen Code zu kompilieren.

Die CodeQL-Analyse ist nur eine Art von code scanning, die du in GitHub durchführen kannst.

GitHub Marketplace enthält andere code scanning-Workflows, die du verwenden kannst. Du findest eine Auswahl dieser Workflows auf der Seite „Erste Schritte mit code scanning“, auf die du über die Registerkarte Sicherheit zugreifen kannst. Die in diesem Artikel angegebenen konkreten Beispiele beziehen sich auf die CodeQL analysis workflow-Datei. Bearbeiten eines code scanning-Workflows

In GitHub werden Workflowdateien im .github/workflows-Verzeichnis des Repositorys gespeichert.

Du findest einen Workflow, den du hinzugefügt hast, indem du nach seinem Dateinamen suchst. Beispielsweise ist der Name der Workflowdatei für CodeQL code scanning standardmäßig auf codeql-analysis.yml festgelegt. Navigiere in deinem Repository zu der Workflow-Datei, die du bearbeiten möchtest.

  1. Klicke zum Öffnen des Workflow-Editors oben rechts in der Dateiansicht auf .
  2. Schaltfläche zum Editieren der Workflow-Datei Nachdem du die Datei bearbeitet hast, klicke auf Starr commit (Commit starten), und fülle das Formular „Commit changes“ (Änderungen committen) aus.
  3. Du kannst einen Commit direkt in den aktuellen Branch committen oder einen neuen Branch erstellen und einen Pull Request starten. Durchführen des Commits der Aktualisierung in den codeql.yml-Workflow Weitere Informationen zum Bearbeiten von Workflowdateien findest du unter Informationen zu GitHub Actions.

Konfigurieren der Häufigkeit

Du kannst den CodeQL analysis workflow konfigurieren, um Code na Zeitplan zu überprüfen oder wenn bestimmte Ereignisse in einem Repository auftreten.

Scanning code on every push to the repository, and every time a pull request is created, prevents developers from introducing new vulnerabilities and errors into the code.

Das Überprüfen von Code nach einem Zeitplan informiert dich über die neuesten Sicherheitsrisiken und Fehler, die GitHub, Sicherheitsexperten und die Community entdecken, auch wenn Entwickler das Repository nicht aktiv verwalten. Überprüfen bei Push

Standardmäßig wird vom CodeQL analysis workflow das on.push-Ereignis dazu verwendet, bei jeder Pushübertragung zum Standardbranch des Repositorys sowie zu geschützten Branches eine Codeüberprüfung auszulösen.

Damit code scanning auf einem bestimmten Branch ausgelöst wird, muss der Workflow in diesem Branch vorhanden sein. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions. Wenn du beim Pushen eine Überprüfung durchführst, werden die Ergebnisse auf der Registerkarte Sicherheit für das Repository angezeigt.

Weitere Informationen findest du unter Verwalten von Codeüberprüfungswarnungen für dein Repository. Wenn eine on:push-Überprüfung ein Ergebnis zurückgibt, das einem offenen Pull Request zugeordnet werden kann, werden diese Warnungen für den Pull Request automatisch am gleichen Ort wie andere Pull Request-Warnungen 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 Pull Requests findest du unter Selektieren von code scanning-Warnungen in Pull Requests. Überprüfen von Pull Requests

Im Standard-CodeQL analysis workflow wird das pull_request-Ereignis dazu verwendet, eine Codeüberprüfung bei Pull Requests auszulösen, die sich auf den Standardbranch beziehen.

Wenn ein Pull Request von einem privaten Fork ausgeht, wird das pull_request-Ereignis nur ausgelöst, wenn du in den Repositoryeinstellungen die Option „Run workflows from fork pull requests“ (Workflows von forkbasierten Pull Requests ausführen) ausgewählt hast. Weitere Informationen findest du unter Verwalten von Einstellungen für GitHub Actions für ein Repository. Weitere Informationen zum pull_request-Event findest du unter Ereignisse, die Workflows auslösen.

Wenn du Pull Requests scannst, 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 den pull_request-Trigger verwendest, der so konfiguriert ist, dass anstelle des HEAD-Commits der Mergecommit des Pull Requests überprüft wird, führt dies zu effizienteren und genaueren Ergebnissen als eine HEAD-Überprüfung für den Branch bei jedem Pushvorgang.

Wenn du jedoch ein CI/CD-System verwendest, das nicht für das Auslösen bei Pull Requests konfiguriert werden kann, kannst du trotzdem den on:push-Trigger verwendest. Von code scanning werden die Ergebnisse dann offenen Pull Requests für den Branch zugeordnet. Die Warnungen werden als Anmerkungen für den Pull Request hinzugefügt. Weitere Informationen findest du unter Überprüfen bei Push. Definieren der Schweregrade, die einen Fehler bei der Pull Request-Überprüfung verursachen

Standardmäßig führen bei der Überprüfung von Pull Requests nur Warnungen mit dem Schweregrad Error oder dem Sicherheitsschweregrad Critical oder High zu einem Fehler, und eine Überprüfung mit Warnungen mit niedrigeren Schweregraden ist weiterhin erfolgreich.

Du kannst die Stufen von Warnungsschweregraden und Sicherheitsschweregraden in deinen Repositoryeinstellungen ändern, die bei der Überprüfung von Pull Requests zu einem Fehler führen. Weitere Informationen zu Schweregradstufen findest du unter Informationen zu Codeüberprüfungswarnungen. 1. Navigiere auf GitHub.com zur Hauptseite des Repositorys. 1. Klicke unter dem Repositorynamen auf Einstellungen. Schaltfläche „Repositoryeinstellungen“

  1. Klicke im Abschnitt „Sicherheit“ auf der Randleiste auf Codesicherheit und -analyse.

Verwende unter „Code Scanning“ (Codeüberprüfung) rechts neben „Check Failure“ (Überprüfungsfehler) das Dropdownmenü, um den Schweregrad auszuwählen, den du als Auslöser für einen Pull Request-Überprüfungsfehler festlegen möchtest.

  1. Überprüfen der Fehlereinstellung Vermeiden unnötiger Überprüfungen von Pull Requests

Möglicherweise möchtest du verhindern, dass ein Codescan für bestimmte Pull Requests ausgelöst wird, die sich auf den Standardbranch beziehen, und zwar unabhängig davon, welche Dateien geändert wurden.

Du kannst dies konfigurieren, indem du im code scanning-Workflow on:pull_request:paths-ignore oder on:pull_request:paths festlegst. Wenn die einzigen Änderungen in einem Pull Request z. B. Dateien mit den Dateierweiterungen .md oder .txt sind, kannst du das folgende paths-ignore-Array verwenden.

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

Hinweise

Durch on:pull_request:paths-ignore und on:pull_request:paths werden Bedingungen festgelegt, die bestimmen, ob die Aktionen im Workflow bei einem Pull Request ausgeführt werden.

  • Es wird nicht bestimmt, welche Dateien analysiert werden, wenn die Aktionen tatsächlich ausgeführt werden. Wenn ein Pull Request 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 im Pull Request 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 findest du unter Angeben von Verzeichnissen zum Überprüfen. Verwende für CodeQL code scanning-Workflowdateien nicht die Schlüsselwörter paths-ignore oder paths mit dem on:push-Ereignis, da dies wahrscheinlich zu fehlenden Analysen führt.
  • Für genaue Ergebnisse müssen von CodeQL code scanning neue Änderungen mit der Analyse des vorherigen Commits verglichen werden können.

Weitere Informationen dazu, wie mithilfe von on:pull_request:paths-ignore und on:pull_request:paths ermittelt wird, wann ein Workflow für einen Pull Request ausgeführt wird, findest du unter Workflowsyntax für GitHub Actions.

Scannen nach einem Zeitplan

Wenn du den standardmäßigen CodeQL analysis workflow ausführst, überprüft der Workflow zusätzlich zu den von Ereignissen ausgelösten Überprüfungen einmal wöchentlich den Code in deinem Repository.

Um diesen Zeitplan anzupassen, bearbeite den cron-Wert im Workflow. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Hinweis: Von GitHub werden nur geplante Aufträge ausgeführt, die sich in Workflows im Standardbranch befinden.

Das Ändern des Zeitplans in einem Workflow in einem anderen Branch hat erst dann eine Auswirkung, wenn du den Branch mit dem Standardbranch zusammenführst.

Beispiel

Im folgenden Beispiel wird ein CodeQL analysis workflow für ein bestimmtes Repository angezeigt, das einen Standardbranch mit der Bezeichnung main und einen geschützten Branch mit der Bezeichnung protected aufweist.

Dieser Workflow scannt Folgendes:

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

Jeden Pushvorgang in den Standardbranch und den geschützten Branch

  • Jeden Pull Request an den Standardbranch
  • Den Standardbranch jeden Montag um 14:20 UTC
  • Angeben eines Betriebssystems

Wenn dein Code ein bestimmtes Betriebssystem zum Kompilieren benötigt, kannst du das Betriebssystem in deinem CodeQL analysis workflow konfigurieren.

Bearbeite den Wert jobs.analyze.runs-on, um das Betriebssystem für den Computer anzugeben, auf dem die code scanning-Aktionen ausgeführt werden. Wenn du einen selbstgehosteten Runner für die Codeüberprüfung verwenden möchtest, kannst du ein Betriebssystem mithilfe einer geeigneten Bezeichnung als zweites Element in einem aus zwei Elementen bestehenden Array nach self-hosted angeben.

jobs:
  analyze:
    name: Analyze
    runs-on: [ubuntu-latest]

CodeQL code scanning unterstützt die neuesten Versionen von Ubuntu, Windows und macOS.

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

Typische Werte für diese Einstellung sind daher: ubuntu-latest, windows-latestund macos-latest. Weitere Informationen findest du unter Auswählen des Runners für einen Auftrag und Verwenden von Bezeichnungen mit selbstgehosteten Runnern. Wenn du einen selbstgehosteten Runner verwendest, musst du sicherstellen, dass Git in der Variable PATH enthalten ist. Weitere Informationen findest du unter Informationen zu selbstgehosteten Runnern und Hinzufügen selbstgehosteter Runner.

Empfohlene Spezifikationen (RAM, CPU-Kerne und Datenträger) zum Ausführen der CodeQL-Analyse auf selbstgehosteten Computern findest du unter Empfohlene Hardwareressourcen zum Ausführen von CodeQL.

Angeben des Speicherorts für CodeQL-Datenbanken

Im Allgemeinen musst du dir keine Gedanken darüber machen, wo CodeQL analysis workflow-Datenbanken vom CodeQL platziert werden, da in späteren Schritten automatisch Datenbanken ermittelt werden, die in vorherigen Schritten erstellt wurden.

Wenn du jedoch einen benutzerdefinierten Workflowschritt schreibst, der es erforderlich macht, dass sich die CodeQL-Datenbank an einem bestimmten Speicherort des Datenträgers befindet, z. B. zum Hochladen der Datenbank als Workflowartefakt, kannst du diesen Speicherort mithilfe des Parameters db-location unter der Aktion init angeben. Vom CodeQL analysis workflow wird erwartet, dass der im Parameter db-location angegebene Pfad beschreibbar ist und entweder nicht vorhanden oder ein leeres Verzeichnis ist.

- uses: github/codeql-action/init@v2
  with:
    db-location: '${{ github.workspace }}/codeql_dbs'

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. Nicht notwendig ist dies für Aufträge, die auf Runnern ausgeführt werden, die auf GitHub gehostet werden und die bei jeder Ausführung eine neue Instanz und ein bereinigtes Dateisystem abrufen. Weitere Informationen findest du unter Informationen zu auf GitHub gehosteten Runnern. Wenn dieser Parameter nicht verwendet wird, werden vom CodeQL analysis workflow-Datenbanken an einem eigenständig gewählten temporären Speicherort erstellt.

Ändern der analysierten Sprachen

Von CodeQL code scanning wird in den unterstützten Sprachen geschriebener Code automatisch erkannt.

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

Hinweise:

  • Die CodeQL-Analyse für Kotlin ist derzeit als Betaversion verfügbar. Während der Betaphase ist die Analyse von Kotlin weniger umfassend als die CodeQL-Analyse für andere Sprachen.
  • Verwende java zum Analysieren von Code, der in Java, Kotlin oder beiden Sprachen geschrieben wurde.
  • 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.

Die CodeQL analysis workflow-Standarddatei enthält eine Matrix namens language, in der die analysierten Sprachen in deinem Repository aufgeführt sind.

Von CodeQL wird diese Matrix automatisch gefüllt, wenn du code scanning einem Repository hinzufügst. Mithilfe der language-Matrix wird CodeQL dahin gehend optimiert, dass die einzelnen Analysen parallel ausgeführt werden. Aufgrund der Leistungsvorteile der Parallelisierung von Builds wird empfohlen, dass alle Workflows diese Konfiguration übernehmen. Weitere Informationen zu Matrizen findest du unter Verwenden einer Matrix für deine Aufträge. 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.

Wenn die language-Matrix vom Workflow verwendet wird, wird CodeQL hartcodiert, sodass nur die Sprachen in der Matrix analysiert werden.

Um die Sprachen zu ändern, die du analysieren möchtest, bearbeite den Wert der Matrixvariablen. Du kannst eine Sprache entfernen, um zu verhindern, dass sie analysiert wird, oder du kannst eine Sprache hinzufügen, die beim Konfigurieren der code scanning nicht im Repository vorhanden war. Wenn das Repository beispielsweise anfänglich nur JavaScript enthielt, als die code scanning konfiguriert wurde, und du später Python-Code hinzugefügt hast, musst du der Matrix python hinzufügen. Wenn dein Workflow keine Matrix mit der Bezeichnung language enthält, wird CodeQL so konfiguriert, dass die Analyse sequenziell ausgeführt wird.

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

Wenn du keine Sprachen im Workflow angibst, erkennt CodeQL automatisch alle unterstützten Sprachen im Repository und versucht, diese zu analysieren. Wenn du ohne Verwendung einer Matrix auswählen möchtest, welche Sprachen analysiert werden sollen, kannst du den languages-Parameter unter der init-Aktion verwenden.

- uses: github/codeql-action/init@v2
  with:
    languages: cpp, csharp, python

Analysieren von Python-Abhängigkeiten

Bei auf GitHub gehosteten Runnern, die nur Linux verwenden, wird vom CodeQL analysis workflow versucht, Python-Abhängigkeiten automatisch zu installieren, sodass mehr Ergebnisse für die CodeQL-Analyse bereitgestellt werden.

Du kannst dieses Verhalten steuern, indem du den Parameter setup-python-dependencies für die Aktion angibst, die vom Schritt „Initialisieren von CodeQL“ aufgerufen wird. Dieser Parameter ist standardmäßig auf true festgelegt. Wenn das Repository Code enthält, der in Python geschrieben wurde, werden im Rahmen des Schritts „Initialisieren von CodeQL“ die erforderlichen Abhängigkeiten auf dem Runner installiert, der auf GitHub gehostetet wird.

  • Wenn die automatische Installation erfolgreich verläuft, wird die Umgebungsvariable CODEQL_PYTHON von der Aktion auf die ausführbare Python-Datei festgelegt, die die Abhängigkeiten enthält. Wenn das Repository keine Python-Abhängigkeiten aufweist oder die Abhängigkeiten auf unerwartete Weise angegeben werden, erhältst du eine Warnung, und die Aktion wird mit den verbleibenden Aufträgen fortgesetzt.

  • Die Aktion kann auch dann erfolgreich ausgeführt werden, wenn Probleme beim Interpretieren von Abhängigkeiten auftreten, aber die Ergebnisse sind dann möglicherweise unvollständig. Alternativ dazu kannst du Python-Abhängigkeiten manuell auf jedem Betriebssystem installieren.

Du musst setup-python-dependencies hinzufügen und auf false festlegen. Außerdem musst du CODEQL_PYTHON auf die ausführbare Python-Datei festlegen, die die Abhängigkeiten enthält, wie in diesem Workflowausschnitt gezeigt:

jobs:
  CodeQL-Build:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ];
          then pip install -r requirements.txt;
          fi
          # Set the `CODEQL-PYTHON` environment variable to the Python executable
          # that includes the dependencies
          echo "CODEQL_PYTHON=$(which python)" >> $GITHUB_ENV
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2
        with:
          languages: python
          # Override the default behavior so that the action doesn't attempt
          # to auto-install Python dependencies
          setup-python-dependencies: false

Konfigurieren einer Kategorie für die Analyse

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.

Wenn du keinen category-Parameter im Workflow angibst, wird von GitHub ein Kategoriename für dich generiert, der auf dem Namen der Workflowdatei, die die Aktion auslöst, dem Aktionsnamen und allen Matrixvariablen basiert.

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      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"

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, os: linux} erzeugen die Kategorie .github/workflows/codeql-analysis.yml:analyze/language:javascript/os:linux.
  • Der category-Wert wird als Eigenschaft <run>.automationDetails.id in SARIF v2.1.0 angezeigt.

Weitere Informationen findest du unter SARIF-Unterstützung für code scanning. Die Details des runAutomationDetails-Objekts in der SARIF-Datei werden, sofern enthalten, von der angegebenen Kategorie nicht überschrieben.

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.

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 findest du unter Verwenden einer benutzerdefinierten Konfigurationsdatei und Ausschließen bestimmter Abfragen aus der Analyse weiter unten.

Du kannst zusätzliche Abfragen ausführen, wenn sie Teil eines CodeQL-Pakets (Beta) sind, das in der GitHub Container registry oder einem QLPaket veröffentlich wurde, das in einem Repository gespeichert ist. Weitere Informationen findest du unter Informationen zu code scanning 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 (Beta) zu installieren und die Standardabfragesammlung oder Abfragen für diese Pakete auszuführen.
  • queries, um eine einzelne .ql-Datei, ein Verzeichnis mit mehreren .ql-Dateien, eine .qls-Definitionsdatei für eine Abfragesammlung oder eine beliebige Kombination anzugeben. Weitere Informationen zur Definition von Abfragesammlungen findest du unter Erstellen von CodeQL-Abfragesammlungen.

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

Es wird nicht empfohlen, direkt aus dem Repository github/codeql auf Abfragesammlungen wie z. B. github/codeql/cpp/ql/src@main zu verweisen. Solche Abfragen müssten neu kompiliert werden und sind möglicherweise nicht mit der Version von CodeQL kompatibel, die derzeit auf GitHub Actions aktiv ist, was zu Fehlern bei der Analyse führen kann.

Verwenden von CodeQL-Abfragepaketen

Hinweis: Die CodeQL-Paketverwaltungsfunktionen, einschließlich CodeQL-Paketen, befinden sich derzeit in der Betaphase und können noch geändert werden.

Füge zum Hinzufügen mindestens eines CodeQL-Abfragepakets (Beta) im Abschnitt uses: github/codeql-action/init@v2 des Workflows einen with: packs:-Eintrag 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 Authentifizierung in einem Workflow und Verschlüsselte Geheimnisse.

Hinweis: Bei Workflows, mit denen CodeQL-Datenbanken für mehrere Sprachen generiert werden, musst du stattdessen die CodeQL-Abfragepakete in einer Konfigurationsdatei angeben.

Weitere Informationen findest du nachstehend 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 von GitHub und die Standardabfragen oder die Abfragesammlung für jede Packausführung heruntergeladen: 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.
- uses: github/codeql-action/init@v2
  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 du eine bestimmte Version eines zu verwendenden Abfragepakets angibst, denke daran, dass die von dir angegebene Version möglicherweise zu alt wird, um effizient von der CodeQL-Standard-Engine verwendet zu werden, die 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 Paketkompatibilität findest du unter Informationen zur Kompatibilität von CodeQL-Paketen.

Herunterladen von CodeQL-Paketen aus GitHub Enterprise Server

Wenn dein Workflow Pakete verwendet, die auf einer GitHub Enterprise Server-Installation veröffentlicht wurden, musst du deinem Workflow mitteilen, wo sie zu finden sind.

Möglich ist dies über die registries-Eingabe der Aktion github/codeql-action/init@v2. Diese Eingabe akzeptiert eine Liste mit den Eigenschaften url, packages und token, wie unten gezeigt. Die Paketmuster in der Registrierungsliste werden in der angegebenen Reihenfolge überprüft, daher solltest das spezifischste Paketmuster in der Regel zuerst angeben.

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

    

Bei den Werten für token muss es sich um ein personal access token (classic) handeln, das durch die GitHub-Instanz generiert wurde, von der du mit der Berechtigung read:packages einen Download durchführst. Beachte das | nach dem Eigenschaftsnamen registries.

Dies ist wichtig, da GitHub Actions-Eingaben nur Zeichenfolgen akzeptieren können. Mit dem | wird der nachfolgende Text in eine Zeichenfolge umgewandelt, die später von der github/codeql-action/init@v2-Aktion geparst wird. Verwenden von Abfragen in QL-Paketen

Füge zum Hinzufügen mindestens einer Abfrage innerhalb des Abschnitts uses: github/codeql-action/init@v2 des Workflows einen with: queries:-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.

- uses: github/codeql-action/init@v2
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

Abfragesammlungen sind Sammlungen von Abfragen, die in der Regel nach Zweck oder Sprache gruppiert sind. 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. Die security-extended- und security-and-quality-Abfragesuites für JavaScript enthalten experimentelle Abfragen. Weitere Informationen findest du unter Informationen zu code scanning-Warnungen.

Arbeiten mit benutzerdefinierten Konfigurationsdateien

Wenn du auch eine Konfigurationsdatei für benutzerdefinierte Einstellungen verwendest, werden alle in deinem Workflow angegebenen zusätzlichen Pakete oder Abfragen anstelle der in der Konfigurationsdatei angegebenen Komponenten verwendet.

Wenn du eine Kombination zusätzlicher Pakete oder Abfragen ausführen möchtest, musst du den Wert von packs oder queries im Workflow mit dem Symbol + als Präfix versehen. Weitere Informationen findest du unter Erstellen einer benutzerdefinierten Konfigurationsdatei. Im folgenden Beispiel wird mit dem Symbol + sichergestellt, dass die angegebenen zusätzlichen Pakete und Abfragen zusammen mit allen angegebenen Komponenten in der Konfigurationsdatei verwendet werden, auf die verwiesen wird.

Verwenden einer benutzerdefinierten Konfigurationsdatei

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

Eine benutzerdefinierte Konfigurationsdatei ist eine alternative Möglichkeit, zusätzliche Pakete und Abfragen anzugeben, die ausgeführt werden sollen.

Du kannst die Datei auch verwenden, um die Standardabfragen zu deaktivieren, bestimmte Abfragen auszuschließen oder einzuschließen und um festzulegen, welche Verzeichnisse während der Analyse überprüft werden sollen. Verwende in der Workflowdatei den config-file-Parameter der init-Aktion, um den Pfad zur Konfigurationsdatei anzugeben, die du verwenden möchtest.

In diesem Beispiel wird die Konfigurationsdatei ./.github/codeql/codeql-config.yml geladen. 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

- uses: github/codeql-action/init@v2
  with:
    config-file: ./.github/codeql/codeql-config.yml

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.

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

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

Angeben von CodeQL-Abfragepaketen

Hinweis: Die CodeQL-Paketverwaltungsfunktionen, einschließlich CodeQL-Paketen, befinden sich derzeit in der Betaphase und können noch geändert werden.

Du gibst CodeQL-Abfragepakete in einem Array an.

Beachte, dass sich das Format von dem Format unterscheidet, das von der Workflowdatei verwendet wird.

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

version und 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 du über einen Workflow verfügst, mit dem mehrere CodeQL-Datenbanken generiert werden, kannst du in einer benutzerdefinierten Konfigurationsdatei beliebige auszuführende CodeQL-Abfragepakete angeben, indem du eine geschachtelte Zuordnung von Paketen verwendest.

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

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. Optional kannst du jedem Arrayelement einen Namen geben, wie in den folgenden Beispielkonfigurationsdateien gezeigt.

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

Weitere Informationen zu zusätzlichen Abfragen findest du oben unter Ausführen zusätzlicher Abfragen. Deaktivieren der Standardabfragen

Wenn du nur benutzerdefinierte Abfragen ausführen möchtest, kannst du 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. Um die ID einer Abfrage zu ermitteln, kannst du in der Liste der Warnungen auf der Registerkarte „Sicherheit“ auf die jeweilige Warnung klicken. Dadurch wird die Seite mit den Details zur Warnung geöffnet.

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

Das Feld Rule ID enthält die Abfrage-ID. Weitere Informationen über die Seite mit den Warnungsdetails findest du unter Informationen zu code scanning-Warnungen.

Tipps:

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 findest du im Abschnitt Beispielkonfigurationsdateien.

Weitere Informationen zur Verwendung von exclude- und include-Filtern in deiner benutzerdefinierten Konfigurationsdatei findest du unter Erstellen von CodeQL-Abfragesammlungen.

Informationen zu den Abfragemetadaten, nach denen du filtern kannst, findest du unter Metadaten für CodeQL-Abfragen.

Angeben der zu scannenden Verzeichnisse

Für die von CodeQL unterstützten interpretierten Sprachen (Python, Ruby und JavaScript/TypeScript) kannst du code scanning auf Dateien in bestimmten Verzeichnissen beschränken, indem du der Konfigurationsdatei ein paths-Array hinzufügst.

Du kannst die Dateien in bestimmten Verzeichnissen von der Analyse ausschließen, indem du ein paths-ignore-Array hinzufügst.

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

Hinweis:

Die Schlüsselwörter paths und paths-ignore, die im Kontext der code scanning-Konfigurationsdatei verwendet werden, sollten nicht mit den gleichen Schlüsselwörtern verwechselt werden, wenn diese für on.<push|pull_request>.paths in einem Workflow verwendet werden.

  • 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 findest du 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ägstriche eingeschlossen sein, und du kannst ** 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. Du musst alle Zeichenfolgen in Anführungszeichen einschließen, die ein *-Zeichen enthalten.

Wenn du bei kompilierten Sprachen code scanning auf bestimmte Verzeichnisse in deinem Projekt beschränken möchtest, musst du die entsprechenden Buildschritte im Workflow angeben.

Welche Befehle du verwenden musst, um ein Verzeichnis aus dem Buildvorgang auszuschließen, hängt von deinem Buildsystem ab. Weitere Informationen findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen. Du kannst kleine Teile eines Monorepositorys schnell analysieren, wenn du Code in bestimmten Verzeichnissen änderst.

Du musst sowohl Verzeichnisse in den Buildschritten ausschließen als auch die Schlüsselwörter paths-ignore und paths für on.<push|pull_request> in deinem 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 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'

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 QL pack (run queries in the my-queries directory)
    uses: ./my-queries
packs:
  - codeql/java-queries
query-filters:
- exclude:
    problem.severity:
      - warning
      - recommendation

Konfigurieren von code scanning für kompilierte Sprachen

Für die unterstützten kompilierten Sprachen kannst du den Code mithilfe der autobuild-Aktion im CodeQL analysis workflow erstellen. So wird vermieden, dass du explizite Buildbefehle für C/C++, C#, Go, Kotlin, und Java angeben musst. 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.

Wenn bei autobuild ein Fehler auftritt oder du andere Quelldateien als die durch den Prozess autobuild erstellten Dateien analysieren möchtest, musst du den Schritt autobuild aus dem Workflow entfernen und manuell Buildschritte hinzufügen. Für C/C++-, C#-, Go, Kotlin- und Java-Projekte analysiert CodeQL den Quellcode, der von den von dir angegebenen Buildschritten erstellt wird. Weitere Informationen zum Konfigurieren von CodeQL code scanning für kompilierte Sprachen findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen.

Hochladen von code scanning-Daten in GitHub

You can display code analysis from a third-party tool in GitHub by adding the upload-sarif action to your workflow.

Du kannst Codeanalysedaten mit der Aktion upload-sarif hochladen. Weitere Informationen findest du unter Hochladen einer SARIF-Datei in GitHub. For more information, see "Uploading a SARIF file to GitHub."