Konfigurieren von Codescans

  • 4 Minuten

Sie können konfigurieren, wie GitHub den Code in Ihrem Projekt auf Sicherheitsrisiken und Fehler scannt. Wenn Sie Ihre eigene Konfiguration auswählen, sparen Sie Zeit und entscheiden über die am besten geeignete Häufigkeit von Codescans für Ihr Projekt. In dieser Lerneinheit lernen Sie die Grundlagen der Codescankonfiguration kennen. Außerdem erfahren Sie, wie Sie die Häufigkeit von Scans konfigurieren und sie so planen, dass sie Ihren Repository- und Entwicklungsanforderungen am besten entsprechen.

Wie in den vorherigen Lerneinheiten erläutert wurde, können Sie Codescans auf GitHub, mit GitHub Actions oder über Ihr CI-System (Continuous Integration) ausführen. Wenn Sie die Option "Erweiterte Einrichtung" auf GitHub auswählen, wird eine anpassbare Workflowdatei generiert, die Sie dann direkt in Ihr Repository übernehmen können. In der Regel müssen Sie diesen Workflow nicht bearbeiten. Bei Bedarf können Sie jedoch einige der Einstellungen anpassen.

Sie können z. B. den CodeQL-Analyseworkflow von GitHub bearbeiten, um die Häufigkeit von Scans, die zu scannenden Sprachen oder Verzeichnisse und die in Ihrem Code durch CodeQL-Codescans zu suchenden Elemente anzugeben. Möglicherweise müssen Sie auch den CodeQL-Analyseworkflow bearbeiten, wenn Sie einen bestimmten Satz von Befehlen verwenden, um Ihren Code zu kompilieren. Die CodeQL-Analyse ist nur eine Art von Codescans, die Sie in GitHub ausführen können. GitHub Marketplace enthält mehrere andere Codescanworkflows.

Wechseln von Standard zu Advanced Code Scanning Setup

Wenn Sie bereits ein Repository für die Codeüberprüfung mit der Standardsetupmethode eingerichtet haben, können Sie in den Einstellungen zum erweiterten Setup wechseln. Navigieren Sie unter (Einstellungen, Codesicherheit und -analyse) zum Abschnitt > (Code-Scan), und wählen Sie dann das Überlaufsymbol mit den drei Punkten (...) aus. Wählen Sie in der Dropdownliste Zum erweiterten Modus wechseln aus. Folgen Sie dann den Anweisungen zum Deaktivieren von CodeQL, und aktivieren Sie sie erneut mit der generierten Workflowdatei des erweiterten Setups.

Bearbeiten des Codeüberprüfungsworkflows

GitHub speichert Workflowdateien im Github/Workflows-Verzeichnis Ihres Repositorys. Sie finden einen Workflow, den Sie hinzugefügt haben, indem Sie nach seinem Dateinamen suchen. Die Workflowdatei für das CodeQL-Code-Scanning heißt beispielsweise standardmäßig codeql-analysis.yml.

Führen Sie die folgenden Schritte aus, um eine Workflowdatei zu bearbeiten:

  1. Um den Workflow-Editor zu öffnen, wählen Sie das Symbol "Bearbeiten" in der oberen rechten Ecke der Dateiansicht aus.

    Screenshot der Schaltfläche

  2. Nehmen Sie Ihre Änderungen vor.

  3. Nachdem Sie die Datei bearbeitet haben, wählen Sie Commit-Änderungen aus, und schließen Sie das Commit-Änderungsformular ab. Sie können einen Commit direkt in den aktuellen Branch committen oder einen neuen Branch erstellen und einen Pull Request starten.

    Screenshot des Commit-Änderungsformulars.

In den folgenden Abschnitten werden einige gängige Konfigurationsoptionen für Codescans beschrieben.

Konfigurieren der Häufigkeit

Eine häufige Bearbeitung der Workflowdatei besteht darin, die Häufigkeit anzupassen, mit der Codescans durchgeführt werden. Sie können den CodeQL-Analyseworkflow so konfigurieren, dass Code nach einem Zeitplan überprüft wird oder wenn bestimmte Ereignisse in einem Repository auftreten. Sie können die Workflowdatei auch bearbeiten, um Code zu scannen, wenn jemand eine Änderung überträgt und wann immer eine Pullanforderung erstellt wird. Durch das Anpassen dieser Häufigkeit können Sie verhindern, dass Entwickler*innen neue Sicherheitsrisiken und Fehler im Code einführen. Das Überprüfen des Codes nach einem Zeitplan stellt sicher, dass Sie stets über die neuesten Sicherheitsrisiken und Fehler informiert sind, die GitHub, Sicherheitsexpert*innen und die Community entdecken – auch wenn das Repository nicht aktiv von Entwickler*innen verwaltet wird.

Scannen bei Pushvorgängen

Standardmäßig verwendet der CodeQL-Analyseworkflow das on:push-Ereignis, um bei jedem Pushvorgang an den Standardbranch des Repositorys und an alle geschützten Branches einen Codescan auszulösen. Damit ein Codescan für einen angegebenen Branch ausgelöst wird, muss der Workflow in diesem Branch vorhanden sein. Wenn Sie auf Push scannen, werden die Ergebnisse auf der Registerkarte "Sicherheit " für Ihr Repository angezeigt.

Wenn eine on:push-Überprüfung ein Ergebnis zurückgibt, das einem offenen Pull Request zugeordnet werden kann, werden diese Warnungen zudem automatisch am gleichen Ort wie andere Pull Request-Warnungen für den Pull Request angezeigt. Die Warnungen werden identifiziert, indem die vorhandene Analyse des HEAD des Branch mit der Analyse für den Zielbranch verglichen wird.

Scannen bei Pull Request

Der CodeQL-Analysestandardworkflow verwendet das pull_request-Ereignis, um einen Codescan bei Pull Requests auszulösen, die sich auf den Standardbranch beziehen. Wenn ein Pull Request aus einem privaten Fork stammt, wird das pull_request-Ereignis nur ausgelöst, wenn Sie in den Repositoryeinstellungen die Option „Workflows aus Fork-Pull Requests ausführen“ ausgewählt haben. Wenn Sie Pull Requests überprüfen, werden die Ergebnisse als Warnungen in einer Pull Request-Überprüfung angezeigt.

Wenn Sie den pull_request-Trigger verwenden, der zum Überprüfen des Pull Request-Mergecommits anstelle des Headcommits konfiguriert ist, führt dies zu effizienteren und genaueren Ergebnissen als die Überprüfung des Head-Abschnitts des Branches bei jedem Pushvorgang. Wenn Sie ein CI/CD-System (Continuous Integration und Continuous Delivery) verwenden, das nicht für das Auslösen bei Pull Requests konfiguriert werden kann, können Sie trotzdem den on:push-Trigger verwenden. Die Codeüberprüfungen ordnen die Ergebnisse dann offenen Pull Requests für den Branch zu und fügen die Warnungen als Anmerkungen für einen Pull Request hinzu.

Definieren der Schweregrade, die einen Fehler bei der Pull Request-Überprüfung verursachen

Standardmäßig verursachen nur Warnungen mit dem Schweregrad Error oder dem Sicherheitsschweregrad Critical oder High einen Fehler bei der Pull Request-Überprüfung. Pull-Anforderungsfehler beenden keine Codeüberprüfung, stellen aber einen Blocker dar, wenn versucht wird, Code zusammenzuführen. Sie finden die Liste der Pull-Anforderungsfehler auf der Registerkarte " Codeüberprüfungsbenachrichtigungen " unter der Sicherheitsstufe Ihres Repositorys. Sie können die Stufen von Warnungs- und Sicherheitsschweregraden, die zu einem Fehler bei der Pull Request-Überprüfung führen, in Ihren Repositoryeinstellungen ändern.

  1. Navigieren Sie auf GitHub.com zur Hauptseite des Repositorys. Wählen Sie unter Ihrem Repositorynamen "Einstellungen" aus.

    Screenshot der Schaltfläche

  2. Wählen Sie in der linken Randleiste codesicherheit und -analyse aus.

    Screenshot der Schaltfläche

  3. Im Abschnitt „Code-Scanning“ unter „Schutzregeln“ verwenden Sie das Dropdown-Menü, um den Schweregrad auszuwählen, bei dem ein Pull-Request-Prüfungsfehler ausgelöst werden soll.

    Screenshot des Dropdownmenüs zur Auswahl des Warnungsschweregrads für den Code-Scan

Vermeiden unnötiger Scans von Pull Requests

Möglicherweise möchten Sie 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. Sie können diese Einstellung konfigurieren, indem Sie on:pull_request:paths-ignore oder on:pull_request:paths im Codeüberprüfungsworkflow angeben. Wenn die einzigen Änderungen in einem Pull Request z. B. Dateien mit den Dateierweiterungen .md oder .txt sind, können Sie das folgende paths-ignore-Array verwenden.

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

Anpassen des Scanzeitplans

Wenn Sie den standardmäßigen CodeQL-Analyseworkflow verwenden, überprüft der Workflow den Code in Ihrem Repository einmal pro Woche an einem zufällig generierten Tag und Uhrzeit zusätzlich zu den Überprüfungen, die durch Ereignisse ausgelöst werden. Um diesen Zeitplan anzupassen, bearbeiten Sie den cron-Wert im Workflow.

Das folgende Beispiel zeigt einen CodeQL-Analyseworkflow für ein Repository mit einem Standardbranch namens main und einem geschützten Branch namens protected:

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
  • Jeden Pull Request an den Standardbranch
  • Den Standardbranch jeden Montag um 14:20 UTC