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 organisationseigene Repositorys in GitHub Enterprise Server verfügbar. Dieses Feature erfordert eine Lizenz für GitHub Advanced Security. Weitere Informationen findest du unter Informationen zu GitHub Advanced Security.

Hinweis: In diesem Artikel werden die Features beschrieben, die mit der Version der CodeQL-Aktion und dem zugehörigen CodeQL-CLI-Bundle im ursprünglichen Release dieser Version von GitHub Enterprise Server verfügbar sind.

Wenn dein Unternehmen eine neuere Version der CodeQL-Aktion verwendet, findest du Informationen zu den neuesten Features unter GitHub Enterprise Cloud. Informationen zur Verwendung der neuesten Version findest du unter Konfigurieren von code scanning für deine Appliance.

Informationen zum Konfigurieren von code scanning

Du kannst code scanning mit GitHub Actions in GitHub Enterprise Server 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. In diesem Artikel wird die Ausführung der code scanning in GitHub Enterprise Server mithilfe von Aktionen behandelt. Bevor du die code scanning für ein Repository anpassen kannst, musst du die code scanning konfigurieren, indem du dem Repository einen Workflow für GitHub Actions hinzufügst.

Weitere Informationen findest du unter Konfigurieren der code scanning für ein Repository.

Normalerweise musst du die generierte Workflowdatei für code scanning nicht bearbeiten. Falls erforderlich, kannst du den Workflow jedoch bearbeiten, um einige der Einstellungen anzupassen. Du kannst z. B. den CodeQL analysis workflow von GitHub bearbeiten, um die Häufigkeit der Scans, die zu scannenden Sprachen oder Verzeichnisse und was CodeQL code scanning in deinem Code sucht anzugeben. Möglicherweise musst du auch den CodeQL analysis 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 auf GitHub.com enthält andere code scanning-Workflows, die du verwenden 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.

Das pull_request-Ereignis wird nicht ausgelöst, wenn der Pull Request über einen privaten Fork geöffnet wurde. 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 your GitHub Enterprise Server instance 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. Du gibst das Betriebssystem mithilfe einer entsprechenden Bezeichnung als zweites Element in einem aus zwei Elementen bestehenden Array nach self-hosted an.

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. Du musst sicherstellen, dass Git bei deinen selbstgehosteten Runnern 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 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
  • JavaScript/TypeScript
  • Python
  • Ruby

Hinweise:

  • Die CodeQL-Analyse für Ruby ist derzeit als Betaversion verfügbar. Während der Betaphase ist die Analyse von Ruby weniger umfassend als die CodeQL-Analyse für andere Sprachen.
  • 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.

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 Enterprise Server 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.

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.

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.

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

Wenn du eine Kombination zusätzlicher Abfragen ausführen möchtest, musst du den Wert von 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 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

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

Du kannst die Datei auch verwenden, um die Standardabfragen zu deaktivieren 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 }}
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.

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'

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#, 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, 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."