Minimale Berechtigungen für Workflow und einzelne Jobs

GITHUB_TOKEN ermöglicht GitHub Actions die Authentifizierung für Vorgänge in einem Repository. Mit dem Schlüssel permissions legst du die Berechtigungen für den gesamten Workflow oder für einzelne Jobs fest, damit jede Aufgabe nur die benötigten Fähigkeiten erhält.

Als Ausgangspunkt empfiehlt GitHub, die Standardberechtigung von GITHUB_TOKEN auf das Lesen von Repository-Inhalten zu setzen und sie zu erweitern, wenn ein bestimmter Job mehr benötigt. Liest ein Workflow nur Dateien aus, braucht er nicht aus Bequemlichkeit Schreibzugriff.

Berechtigungen sollten zum Vorgang passen: Zum Erstellen eines Issues ist issues: write erforderlich; andere Aufgaben können andere Rechte benötigen. Du kannst eine Grundlage für den Workflow festlegen und die Berechtigungen des ausführenden Jobs anpassen. Erweitere nicht alle Jobs, um einen örtlich begrenzten Bedarf zu lösen.

Auch Actions können über den Kontext github.token auf das Token zugreifen, selbst wenn es ihnen nicht als Eingabe übergeben wird. Beschränke deshalb die Berechtigungen und prüfe, welche Actions in jedem Job ausgeführt werden. Dass secrets.GITHUB_TOKEN nicht ausdrücklich übergeben wird, beweist nicht, dass eine Action keinen Zugriff auf das Token hat.

Beispiel für einen Workflow mit Lesezugriff

Die folgende Vorlage wird bei Änderungen an main ausgelöst und gewährt Lesezugriff auf Repository-Inhalte. Ersetze vor der Verwendung actions/checkout@<VERIFIZIERTER_VOLLSTÄNDIGER_SHA> durch einen echten, überprüften vollständigen SHA; der Platzhalter ist keine ausführbare Referenz.

Anpassbare Vorlage: Ersetze den Platzhalter vor dem Speichern und Ausführen des Workflows durch einen überprüften vollständigen SHA.

name: Änderungen prüfen

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  pruefen:
    runs-on: ubuntu-latest
    steps:
      - name: Code auschecken
        uses: actions/checkout@<VERIFIZIERTER_VOLLSTÄNDIGER_SHA>

      - name: Prüfungen ausführen
        run: ./scripts/check.sh

Das Fixieren einer Action auf einen vollständigen SHA verringert das Risiko, dass ein Tag auf ein anderes Ziel verweist, beweist aber nicht, dass der Code sicher ist. Prüfe, ob der SHA zum erwarteten Repository gehört, und kontrolliere den Code der verwendeten Actions. GitHub stellt Abhängigkeits-Lockdateien als stärkeren Schutz dar als das alleinige Fixieren von SHAs.

Richte die Berechtigungen nach der tatsächlichen Aufgabe aus. Wenn du keinen Zugriff auf das Repository brauchst, prüfe, ob contents: read erforderlich ist. Fügst du einen Schreibvorgang hinzu, ermittle die benötigte Berechtigung und gewähre sie dem betreffenden Job, statt den Zugriff für den gesamten Workflow zu erweitern.

Schreibzugriff nur dem benötigten Job gewähren

Zum Erstellen eines Issues mit GitHub CLI benötigt ein Job die Berechtigung issues: write. Das von GitHub dokumentierte Beispiel setzt diese Berechtigung für den Job und übergibt das Token über die Umgebungsvariable GH_TOKEN an das Tool.

name: Issue erstellen

on:
  workflow_dispatch:

jobs:
  issue-erstellen:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Issue mit GitHub CLI erstellen
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh issue create --title "Automatisierte Aufgabe" --body "Workflow-Ergebnis überprüfen."

Schreibe Geheimnisse nicht direkt in Workflow-Dateien und gib sie nicht in Protokollen aus. GitHub weist darauf hin, dass automatisches Maskieren bei umgewandelten Werten nicht garantiert ist. Wenn ein Zugangsschlüssel ungeschützt in einem Protokoll erscheint, lösche das betroffene Protokoll und rotiere den Schlüssel.

Falls GITHUB_TOKEN nicht die erforderlichen Berechtigungen bietet, dokumentiert GitHub Alternativen: ein Installationstoken einer GitHub App oder ein als Geheimnis gespeichertes persönliches Zugriffstoken. Wende das Prinzip der geringsten Berechtigungen an und beschränke, wer auf diese Zugangsdaten zugreifen kann.

Externe Pull Requests und privilegierte Aufgaben

Inhalte externer Pull Requests müssen als nicht vertrauenswürdige Eingaben behandelt werden: Die einreichende Person kann den Code, Skripte und Abhängigkeiten kontrollieren, die während der Tests ausgeführt werden. GitHub Security Lab weist darauf hin, dass das Ereignis pull_request bei Anfragen aus Forks standardmäßig Schreibberechtigungen und den Zugriff auf Geheimnisse des Ziel-Repositorys blockiert.

pull_request_target wird im Kontext des Ziel-Repositorys ausgeführt und kann Schreibberechtigungen sowie Zugriff auf Geheimnisse haben. Das Risiko entsteht, wenn dieser privilegierte Kontext mit dem Abrufen und Ausführen externen Codes kombiniert wird: Skripte, Tests und Paketinstallationen, die von der einreichenden Person kontrolliert werden, können Code in der Workflow-Umgebung ausführen.

Führe keinen nicht vertrauenswürdigen Code in einem privilegierten Job aus. pull_request_target kann für klar begrenzte Aufgaben wie das Setzen von Labels oder Kommentaren geeignet sein, sofern der Workflow keinen von der Pull Request kontrollierten Code ausführt. Ein expliziter Checkout allein beweist keine Ausnutzung: Inhalte können auch als passive Daten behandelt werden, dürfen aber keine Build-, Test- oder Installationsprozesse steuern.

Nutze zum Testen externen Codes einen nicht privilegierten Workflow mit pull_request. Wenn du anschließend ein Ergebnis mit Schreibberechtigungen veröffentlichen musst, kannst du die Tests mithilfe von workflow_run von dieser Aufgabe trennen. Artefakte aus der Pull Request bleiben nicht vertrauenswürdige Daten: Ein privilegierter Workflow kann die benötigten Informationen lesen, darf aber keine daraus stammenden Binärdateien oder Skripte ausführen.

Prüfe auch Pull Requests, die bereits geöffnet waren, als du einen anfälligen Workflow geändert hast. GitHub Security Lab warnt, dass eine ausstehende Anfrage möglicherweise weiterhin die beim Öffnen vorhandene Workflow-Version verwendet; sie muss eventuell geschlossen oder kontrolliert aktualisiert werden.

Pull requests externos y tareas privilegiadas El contenido de un pull request externo debe tratarse como entrada no confiable: quien lo presenta puede controlar código, scripts y d...
Redaktionelle Illustration von BytePreview

Eingaben, Actions und Geheimnisse

Daten aus einer Pull Request können über Workflow-Ausdrücke in die Shell gelangen. Um das Risiko einer Injection zu verringern, empfiehlt GitHub, den externen Wert in einer zwischengeschalteten Umgebungsvariablen zu speichern und diese Variable im Skript zu verwenden, statt den Wert direkt in den Befehl einzusetzen.

Auch Actions von Drittanbietern müssen überprüft werden. Jobs können Informationen oder Ressourcen gemeinsam nutzen, und eine kompromittierte Action kann das Token und verfügbare Geheimnisse beeinträchtigen. Prüfe den Code jeder Action und stelle sicher, dass sie Geheimnisse weder an unerwartete Ziele sendet noch in Protokolle schreibt.

Für Workflows, die auf kompatible Cloud-Dienste zugreifen, empfiehlt GitHub, OIDC zur Authentifizierung in Betracht zu ziehen, statt langlebige Zugangsdaten als Geheimnisse zu speichern. Wenn ein Job Geheimnisse aus einer Umgebung benötigt, kannst du erforderliche Prüfer festlegen, sodass der Zugriff von einer Genehmigung abhängt.

Beschränke die verfügbaren Geheimnisse auf das Notwendige und überprüfe ihre Verwendung. Das Maskieren von Protokollen hilft, ersetzt aber nicht die Trennung von vertrauenswürdigem und nicht vertrauenswürdigem Code; rotiere Zugangsdaten, wenn sie offengelegt wurden.

Prüfliste für einen bestehenden Workflow

Ermittle zuerst das Ereignis, das jeden Job auslöst, und verfolge dann die Zusammenhänge zwischen Berechtigungen, Actions, Geheimnissen und Eingabedaten. Suche nicht nur nach secrets.GITHUB_TOKEN: Eine Action kann über github.token auf das Token zugreifen.

  • Kann der Job mit Lese- statt Schreibzugriff funktionieren?
  • Ist die Schreibberechtigung auf den Job beschränkt, der den Vorgang ausführt?
  • Verarbeitet ein privilegierter Workflow Code oder Artefakte aus einer externen Pull Request?
  • Sind Actions auf überprüfte vollständige SHAs fixiert, und wird ihr Code kontrolliert?
  • Gelangen externe Werte über zwischengeschaltete Umgebungsvariablen in die Shell?
  • Sind Geheimnisse unverzichtbar, und wird verhindert, dass sie in Protokollen erscheinen?

Achte in öffentlichen Repositorys besonders auf selbst gehostete Runner. GitHub warnt, dass nicht vertrauenswürdiger Code sie dauerhaft kompromittieren kann. Die von GitHub gehosteten Runner beschreibt das Unternehmen dagegen als saubere, kurzlebige virtuelle Maschinen. Diese Beschreibung ist keine Garantie für selbst gehostete Runner und hebt die Notwendigkeit, Berechtigungen und Geheimnisse einzuschränken, nicht auf.

Als Betriebsregel gilt die Kombination aus Lesen als Standard, Schreiben nach Bedarf und Isolierung externen Codes. Prüfe nach einem Workflow-Test die Protokolle darauf, ob sensible Informationen offengelegt wurden, und rotiere kompromittierte Zugangsdaten.