Problembehandlung für den CodeQL-Workflow

Erstellen von detaillierten Protokollen für das Debuggen

Um eine detailliertere Protokollierungsausgabe zu generieren, kannst du die Schrittdebugprotokollierung aktivieren. Weitere Informationen findest du unter Aktivieren der Debugprotokollierung.

Erstellen von CodeQL-Debugartefakten

Du kannst Artefakte abrufen, um CodeQL zu debuggen. Die Debugartefakte werden in den Workflow hochgeladen und als Artefakt namens debug-artifacts ausgeführt. Die Daten enthalten die CodeQL-Protokolle, CodeQL-Datenbanken und alle SARIF-Dateien, die vom Workflow erstellt wurden.

Diese Artefakte helfen beim Debuggen von Problemen mit CodeQL code scanning. Wenn du den GitHub-Support kontaktierst, kannst du diese Daten anfordern.

Erstellen von CodeQL-Debugartefakten mithilfe eines Workflow-Flags

Du kannst CodeQL-Debugartefakte mithilfe eines Flags in deinem Workflow erstellen. Ändere dazu den init-Schritt deiner CodeQL-Analyseworkflow-Datei, und lege debug: true fest.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Fehler bei einem automatischen Build für eine kompilierte Sprache

Führe die folgenden Problembehandlungsschritte aus, wenn bei einem automatischen Build von Code für eine kompilierte Sprache in deinem Projekt ein Fehler auftritt.

• Entferne den autobuild-Schritt aus deinem code scanning-Workflow, und füge bestimmte Buildschritte hinzu. Weitere Informationen zum Bearbeiten des Workflows findest du unter Anpassen der Codeüberprüfung. Weitere Informationen zum Ersetzen des autobuild-Schritts findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen.

• Wenn dein Workflow die zu analysierenden Sprachen nicht explizit angibt, erkennt CodeQL implizit die unterstützten Sprachen in deiner Codebasis. Bei dieser Konfiguration mit den kompilierten Sprachen C/C++, C# und Java analysiert CodeQL nur die Sprache mit den meisten Quelldateien. Bearbeite den Workflow, und füge eine Matrix mit den Sprachen hinzu, die du analysieren möchtest. Der standardmäßige CodeQL-Analyseworkflow verwendet eine solche Matrix.

  Die folgenden Extrakte aus einem Workflow zeigen, wie du eine Matrix innerhalb der Auftragsstrategie verwenden kannst, um Sprachen anzugeben, und verweise dann auf jede Sprache innerhalb des Schritts "CodeQL":

  jobs:
    analyze:
      permissions:
        security-events: write
        actions: read
      ...
      strategy:
        fail-fast: false
        matrix:
          language: ['csharp', 'cpp', 'javascript']
  
      steps:
      ...
        - name: Initialize CodeQL
          uses: github/codeql-action/init@v2
          with:
            languages: ${{ matrix.language }}
  

  Weitere Informationen zum Bearbeiten des Workflows findest du unter Anpassen der Codeüberprüfung.

Während des Builds wurde kein Code gefunden

Wenn bei deinem Workflow der Fehler No source code was seen during the build oder The process '/opt/hostedtoolcache/CodeQL/0.0.0-20200630/x64/codeql/codeql' failed with exit code 32 auftritt, weist dies darauf hin, dass CodeQL deinen Code nicht überwachen konnte. Es gibt mehrere Gründe für einen solchen Fehler:

1. Das Repository darf keinen Quellcode enthalten, der in Sprachen geschrieben ist, die von CodeQL unterstützt werden. Überprüfe die Liste der unterstützten Sprachen, und entferne den CodeQL-Workflow, wenn dies der Fall sein sollte. Weitere Informationen findest du unter Informationen zu Codescans mit CodeQL.

2. Die automatische Spracherkennung hat eine unterstützte Sprache identifiziert, aber es gibt keinen analysierbaren Code dieser Sprache im Repository. Ein typisches Beispiel hierfür ist, dass der Spracherkennungsdienst eine Datei findet (z. B. .h- oder .gyp-Datei), die einer bestimmten Programmiersprache zugeordnet ist, aber kein ausführbarer Code im Repository vorhanden ist. Um das Problem zu beheben, kannst du die zu analysierenden Sprachen manuell definieren, indem du die Liste der Sprachen in der language-Matrix aktualisierst. Bei der folgenden Konfiguration wird beispielsweise nur Go und JavaScript analysiert.

   strategy:
     fail-fast: false
     matrix:
       # Override automatic language detection by changing the list below.
       # Supported options are listed in a comment in the default workflow.
       language: ['go', 'javascript']
   

   Weitere Informationen findest du im Workflowextrakt unter Fehler bei einem automatischen Build für eine kompilierte Sprache weiter oben.

3. Dein code scanning-Workflow analysiert eine kompilierte Sprache (C, C++, C# oder Java), aber der Code wurde nicht kompiliert. Standardmäßig enthält der CodeQL-Analyseworkflow einen autobuild-Schritt. Dieser Schritt stellt jedoch einen bestmöglichen Vorgang dar und ist beim Kompilieren deines Codes in Abhängigkeit deiner spezifischen Buildumgebung möglicherweise nicht erfolgreich. Bei der Kompilierung kann auch ein Fehler auftreten, wenn du den autobuild-Schritt entfernt und keine Buildschritte manuell eingeschlossen hast. Weitere Informationen zum Angeben der Buildschritte findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen.

4. Dein Workflow analysiert eine kompilierte Sprache (C, C++, C# oder Java), aber Teile deines Builds werden zwischengespeichert, um die Leistung zu verbessern (am wahrscheinlichsten bei Buildsystemen wie Gradle oder Bazel). Da CodeQL die Aktivität des Compilers beobachtet, um die Datenflüsse in einem Repository nachvollziehen zu können, erfordert CodeQL einen vollständigen Build, um eine Analyse durchzuführen.

5. Dein Workflow analysiert eine kompilierte Sprache (C, C++, C# oder Java), aber die Kompilierung erfolgt nicht zwischen den Schritten init und analyze im Workflow. CodeQL erfordert, dass dein Build zwischen diesen beiden Schritten erfolgt, um die Aktivität des Compilers beobachten und die Analyse durchführen zu können.

6. Der kompilierte Code (in C, C++, C# oder Java) wurde erfolgreich kompiliert, aber CodeQL konnte die Compileraufrufe nicht erkennen. Folgende Ursachen sind am häufigsten anzutreffen:

   • Dein Buildvorgang wurde in einem separaten Container für CodeQL ausgeführt. Weitere Informationen findest du unter Ausführen der CodeQL-Codeüberprüfung in einem Container.
   • Beim Build wurde ein verteiltes Buildsystem außerhalb von GitHub Actions und ein Daemonprozess verwendet.
   • CodeQL kennt den von dir verwendeten spezifischen Compiler nicht.

   Bei .NET Framework-Projekten und bei C#-Projekten, für die du entweder dotnet build oder msbuild verwendest, solltest du beim Kompilieren deines Codes /p:UseSharedCompilation=false im run-Schritt deines Workflows angeben.

   Die folgende Konfiguration für C# übergibt das Flag beispielsweise während des ersten Buildschritts.

   - run: |
       dotnet build /p:UseSharedCompilation=false
   

   Wenn ein anderes Problem mit deinem spezifischen Compiler oder deiner Konfiguration auftritt, wende dich an deine Unternehmensbesitzer*innen.

Weitere Informationen zum Angeben der Buildschritte findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen.

Die Anzahl der gescannten Codezeilen ist niedriger als erwartet

Für kompilierte Sprachen wie C/C++, C#, Go und Java überprüft CodeQL nur Dateien, die während der Analyse erstellt werden. Aus diesem Grund ist die Anzahl der gescannten Codezeilen niedriger als erwartet, wenn Teile des Quellcodes nicht ordnungsgemäß kompiliert werden. Dies kann verschiedene Ursachen haben:

1. Das CodeQL-Feature autobuild verwendet Heuristiken, um den Code in einem Repository zu kompilieren. Manchmal führt dieser Ansatz jedoch zu einer unvollständigen Analyse eines Repositorys. Wenn beispielsweise mehrere build.sh-Befehle in einem einzelnen Repository vorhanden sind, wird die Analyse möglicherweise nicht abgeschlossen, da der autobuild-Schritt nur einen der Befehle ausführt und daher einige Quelldateien möglicherweise nicht kompiliert werden.
2. Einige Compiler funktionieren nicht mit CodeQL und können Probleme beim Analysieren des Codes verursachen. Beispielsweise verwendet Project Lombok nicht öffentliche Compiler-APIs zum Ändern des Compilerverhaltens. Die in diesen Compileränderungen verwendeten Annahmen gelten nicht für den Java-Extractor von CodeQL, sodass der Code nicht analysiert werden kann.

Wenn bei deiner CodeQL-Analyse weniger Codezeilen als erwartet überprüft werden, gibt es verschiedene Ansätze, um sicherzustellen, dass alle erforderlichen Quelldateien kompiliert werden.

Ersetzen des autobuild-Schritts

Ersetze den autobuild-Schritt durch dieselben Buildbefehle, die du in der Produktion verwenden würdest. Auf diese Weise wird sichergestellt, dass CodeQL genau weiß, wie die ganzen Quelldateien kompiliert werden müssen, die du überprüfen möchtest. Weitere Informationen findest du unter Konfigurieren des CodeQL-Workflows für kompilierte Sprachen.

Überprüfen der Kopie der Quelldateien in der CodeQL-Datenbank

Durch das Überprüfen der Kopie des Quellcodes, der in der CodeQL-Datenbank enthalten ist, kannst du möglicherweise nachvollziehen, warum einige Quelldateien nicht analysiert wurden. Ändere den init-Schritt deiner CodeQL-Workflowdatei, und lege debug: true fest, um die Datenbank über deinen Actions-Workflow abzurufen.

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    debug: true

Dadurch wird die Datenbank als Aktionsartefakt hochgeladen, das du auf deinen lokalen Computer herunterladen kannst. Weitere Informationen findest du unter Speichern von Workflowdaten als Artefakte.

Das Artefakt enthält eine archivierte Kopie der Quelldateien namens src.zip, die von CodeQL überprüft wurden. Wenn du die Quellcodedateien im Repository und die Dateien in src.zip vergleichst, erkennst du, welche Dateitypen fehlen. Wenn du weißt, welche Dateitypen nicht analysiert werden, ist es einfacher zu verstehen, wie du den Workflow für die CodeQL-Analyse ändern musst.

In generiertem Code gefundene Warnungen

Bei kompilierten Sprachen wie Java, C, C++ und C# analysiert CodeQL den gesamten Code, der während der Workflowausführung erstellt wurde. Um den Umfang des analysierten Codes einzuschränken, kompilier nur den Code, den du analysieren möchtest, indem du deine eigenen Buildschritte in einem run-Block angibst. Durch die Angabe deiner eigenen Buildschritte mithilfe der Filter paths und paths-ignore für die Ereignisse pull_request und push kannst du die Schritte wie gewünscht kombinieren, um sicherzustellen, dass dein Workflow nur ausgeführt wird, wenn der bestimmte Code geändert wird. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Für Sprachen wie Go, JavaScript, Python und TypeScript, die CodeQL ohne Kompilierung des Quellcodes analysiert, kannst du zusätzliche Konfigurationsoptionen angeben, um den Umfang des zu analysierenden Codes zu begrenzen. Weitere Informationen findest du unter Anpassen der Codeüberprüfung.

Extraktionsfehler in der Datenbank

Das CodeQL-Team arbeitet ständig an kritischen Extraktionsfehlern, um sicherzustellen, dass alle Quelldateien überprüft werden. Die CodeQL-Extractors generieren während der Datenbankerstellung jedoch gelegentlich Fehler. CodeQL stellt Informationen zu Extraktionsfehlern und Warnungen bereit, die während der Datenbankerstellung in einer Protokolldatei generiert wurden. Die Extraktionsdiagnoseinformationen geben einen Hinweis auf die allgemeine Datenbankintegrität. Die meisten Extractorfehler wirken sich nicht erheblich auf die Analyse aus. Eine kleine Anzahl von Extraktorfehlern ist normal und weist in der Regel auf einen guten Analysestatus hin.

Wenn jedoch für die überwiegende Mehrheit der während der Datenbankerstellung kompilierten Dateien Extractorfehler angezeigt werden, solltest du die Fehler genauer untersuchen, um herauszufinden, warum einige Quelldateien nicht ordnungsgemäß extrahiert wurden.

Der Build dauert zu lange

Wenn die Ausführung deines Builds mit der CodeQL-Analyse zu lange dauert, gibt es mehrere Ansätze, um die Buildzeit zu reduzieren.

Erhöhen des Arbeitsspeichers oder der Kerne

Wenn du selbstgehostete Runner für die Ausführung der CodeQL-Analyse verwendest, kannst du den Arbeitsspeicher oder die Anzahl der Kerne für diese Runner erhöhen.

Verwenden von Matrixbuilds zum Parallelisieren der Analyse

Der standardmäßige CodeQL-Analyseworkflow verwendet eine Matrix von Sprachen, wodurch die Analyse jeder Sprache parallel erfolgt. Wenn du die zu analysierenden Sprachen direkt im Schritt „Initialize CodeQL“ (CodeQL initialisieren) angegeben hast, erfolgt die Analyse jeder Sprache sequenziell. Um die Analyse mehrerer Sprachen zu beschleunigen, ändere deinen Workflow so, dass eine Matrix verwendet wird. Weitere Informationen findest du im Workflowextrakt unter Fehler bei einem automatischen Build für eine kompilierte Sprache weiter oben.

Reduzieren der Menge an Code, der in einem einzelnen Workflow analysiert wird

Die Analysezeit ist in der Regel proportional zur Menge des analysierten Codes. Du kannst die Analysezeit reduzieren, indem du die Menge des gleichzeitig zu analysierenden Codes reduzierst. Schließe hierzu Testcode aus, oder teile die Analyse in mehrere Workflows auf, die gleichzeitig jeweils nur eine Teilmenge deines Codes analysieren.

Bei kompilierten Sprachen wie Java, C, C++ und C# analysiert CodeQL den gesamten Code, der während der Workflowausführung erstellt wurde. Um den Umfang des analysierten Codes einzuschränken, kompilier nur den Code, den du analysieren möchtest, indem du deine eigenen Buildschritte in einem run-Block angibst. Durch die Angabe deiner eigenen Buildschritte mithilfe der Filter paths und paths-ignore für die Ereignisse pull_request und push kannst du die Schritte wie gewünscht kombinieren, um sicherzustellen, dass dein Workflow nur ausgeführt wird, wenn der bestimmte Code geändert wird. Weitere Informationen findest du unter Workflowsyntax für GitHub Actions.

Für Sprachen wie Go, JavaScript, Python und TypeScript, die CodeQL ohne Kompilierung des Quellcodes analysiert, kannst du zusätzliche Konfigurationsoptionen angeben, um den Umfang des zu analysierenden Codes zu begrenzen. Weitere Informationen findest du unter Anpassen der Codeüberprüfung.

Wenn du deine Analyse wie zuvor beschrieben in mehrere Workflows aufteilst, solltest du weiterhin mindestens einen Workflow verwenden, der nach einem schedule ausgeführt wird und den gesamten Codes in deinem Repository analysiert. Da CodeQL die Datenflüsse zwischen Komponenten analysiert, werden einige komplexe Sicherheitsverhaltensweisen möglicherweise nur bei einem vollständigen Build erkannt.

Ausführung nur während eines schedule-Ereignisses

Wenn die Ausführung deiner Analyse während push- oder pull_request-Ereignissen noch zu langsam ist, solltest du nur eine Analyse für das schedule-Ereignis auslösen. Weitere Informationen findest du unter Grundlegendes zu GitHub Actions.

Überprüfen, welche Abfragen der Workflow ausführt

Standardmäßig stehen für jede Sprache drei Hauptabfragesammlungen zur Verfügung. Wenn du den CodeQL-Datenbankbuild optimiert hast und der Prozess noch zu lang ist, kannst du die Anzahl der ausgeführten Abfragen verringern. Die Standardabfragesammlung wird automatisch ausgeführt. Sie enthält die schnellsten Sicherheitsabfragen mit den niedrigsten Raten falsch positiver Ergebnisse.

Möglicherweise werden zusätzlich zu den Standardabfragen weitere Abfragen oder Abfragesammlungen ausgeführt. Überprüfe, ob der Workflow eine zusätzliche Abfragesammlung oder zusätzliche Abfragen definiert, die mit dem queries-Element ausgeführt werden sollen. Du kannst die zusätzliche Abfragesammlung oder Abfragen testweise deaktivieren. Weitere Informationen findest du unter Anpassen der Codeüberprüfung.

Fehler: „Server error“ (Serverfehler)

Führe den Workflow erneut aus, wenn bei der Ausführung eines Workflows für das code scanning aufgrund eines Serverfehlers ein Fehler auftritt. Wenn das Problem weiterhin besteht, wende dich an den deine Unternehmensbesitzer*innen.

Fehler: „Out of disk“ (Nicht genügend freier Speicherplatz auf dem Datenträger) oder „Out of memory“ (Nicht genügend Arbeitsspeicher)

Bei sehr großen Projekten kann CodeQL auf dem Datenträger oder Arbeitsspeicher auf dem Läufer ausgeführt werden. Versuche, den Arbeitsspeicher auf dem Runner zu erhöhen, wenn dieses Problem auftritt.

Fehler: „ist keine QL-Datei, QLS-Datei, kein Verzeichnis und keine Abfragepaketspezifikation“

Dieser Fehler wird angezeigt, wenn CodeQL die benannte Abfrage, die benannte Abfragesammlung oder das benannte Abfragepaket nicht am im Workflow angeforderten Speicherort finden kann. Für diesen Fehler gibt es zwei häufige Ursachen.

• Der Workflow enthält einen Rechtschreibfehler.
• Eine Ressource, auf die der Workflow nach Pfad verweist, wurde umbenannt, gelöscht oder an einen neuen Speicherort verschoben.

Nach der Überprüfung des Speicherorts der Ressource kannst du den Workflow aktualisieren und den richtigen Speicherort angeben.

Warnung: „Git Checkout HEAD^2 is no longer necessary“ (Git-Check-Out HEAD^2 ist nicht mehr erforderlich)

Wenn du einen alten CodeQL-Workflow verwendest, erhältst du möglicherweise die folgende Warnung in der Ausgabe von der Aktion „Initialize CodeQL“ (CodeQL initialisieren):

Warning: 1 issue was detected with this workflow: git checkout HEAD^2 is no longer
necessary. Please remove this step as Code Scanning recommends analyzing the merge
commit for best results.

Behebe dieses Problem, indem du die folgenden Zeilen aus dem CodeQL-Workflow entfernst. Diese Zeilen waren in den ersten Versionen des CodeQL-Workflows im Abschnitt steps des Analyze-Auftrags enthalten.

        with:
          # We must fetch at least the immediate parents so that if this is
          # a pull request then we can checkout the head.
          fetch-depth: 2

      # If this run was triggered by a pull request event, then checkout
      # the head of the pull request instead of the merge commit.
      - run: git checkout HEAD^2
        if: ${{ github.event_name == 'pull_request' }}

Der überarbeitete Abschnitt steps des Workflows sieht wie folgt aus:

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      # Initializes the CodeQL tools for scanning.
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v2

      ...

Weitere Informationen zum Bearbeiten der CodeQL-Workflowdatei findest du unter Anpassen der Codeüberprüfung.