Sichere Verwendung von pull_request_target

Erfahren Sie mehr über die Sicherheitsrisiken der pull_request_target event.

In diesem Artikel

In diesem Leitfaden können Sie beurteilen, ob Ihr Workflow das pull_request_target Ereignis verwenden und die sicherheitsrelevanten Risiken verstehen soll. Außerdem wird erläutert, welcher Schutz GitHub für actions/checkout v7 und höher standardmäßig gilt, um diese Risiken zu verringern, und wann dieser Schutz bei Bedarf deaktiviert werden sollte.

Lesen Sie pull_request_target, bevor Sie den Code eines Pull Requests aus einem dieser Workflows auschecken oder bevor Sie die Eingabe allow-unsafe-pr-checkout in actions/checkout festlegen.

Die Risiken des pull_request_target Ereignisses

Workflows, die durch pull_request_target ausgelöst werden, werden mit erhöhten Vertrauensrechten ausgeführt: Der Job erhält das GITHUB_TOKEN des Basis-Repositorys, Zugriff auf Geheimnisse auf Repository- und Organisationsebene sowie Schreibzugriff auf den Cache des Standard-Branches. Dies ist dasselbe Vertrauen, das auch Ereignissen wie push entgegengebracht wird, die nur von Mitwirkenden ausgelöst werden können, und genau das macht pull_request_target nützlich für Automatisierungen, die auf Pull Requests aus Forks reagieren, etwa zum Zuweisen von Labels, zur Triage oder zum Veröffentlichen authentifizierter Statusprüfungen.

Um zu verstehen, warum dies standardmäßig sicher ist und wie diese Sicherheit häufig unterbrochen wird, überprüfen Sie pull_request_target auf pull_request.

Das pull_request Ereignis (zusammen mit pull_request_review und pull_request_review_comment) ist ungewöhnlich: Es führt die Workflowdatei aus dem Zusammenführungs-Commit der Pullanforderung aus. Bei einem Pull Request, der aus einem Fork erstellt wurde, stammt dieser Commit von jemandem, der keinen Schreibzugriff auf das Basis-Repository hat. Um nicht vertrauenswürdigen Workflow-Code sicher auszuführen, GitHub beschränkt diese Ereignisse auf ein schreibgeschütztes GITHUB_TOKEN, verweigert den Zugriff auf andere Geheimnisse und wendet Fork-Genehmigungsrichtlinien an, um den Missbrauch von Rechenressourcen zu verhindern. Weitere Informationen findest du unter Ereignisse zum Auslösen von Workflows. Standardmäßig checkt actions/checkout in einem pull_request-Workflow auch den Merge-Commit des Pull Requests aus, sodass der ausgecheckte Code und der ausgeführte Workflow übereinstimmen.

pull_request_target nimmt eine wichtige und subtile Änderung vor: Der Workflow und jeder nachfolgende actions/checkout-Aufruf, der keinen ref angibt, werden aus dem Standard-Branch des Basis-Repositorys und nicht aus dem Pull Request übernommen. Da nur vertrauenswürdiger Code aus dem Standard-Branch ausgeführt wird, ist es sicher, Geheimnisse und ein Token mit Lese- und Schreibzugriff zu gewähren. Standardmäßig wird kein Code aus dem Fork ausgeführt.

Sie gehen ein Risiko ein, wenn der Autor eines Workflows diesen Standardwert außer Kraft setzt, um den Code des Forks auszuführen. Entwickler wählen pull_request_target häufig aus, weil sie die Pullanforderung einer Verzweigung über CI ausführen möchten und Zugriff auf geheime Schlüssel haben, z. B. zum Ausführen von Tests, die eine private Registrierung benötigen. Dazu richten sie actions/checkout auf den Head des Pull Requests statt auf den Standard-Branch, was unsicher ist:

# INSECURE. Provided as an example only.
on:
  pull_request_target:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - name: Test
        run: make test

Der Auscheckschritt allein führt keinen nicht vertrauenswürdigen Code aus. Die Workflowdatei selbst stammt weiterhin aus dem Standard-Branch. Die Sicherheitsanfälligkeit wird durch den nächsten Schritt abgeschlossen, in dem Code ausgeführt wird, der im aktuellen Arbeitsverzeichnis ausgecheckt ist. Hier führt make test ein Makefile aus, das vom Head der Pull-Anfrage stammt. Ein Angreifer muss nur einen Pull Request aus einem Fork öffnen, dessen Makefile (oder Build-Skript, Testbefehl, Abhängigkeit oder Konfigurationsdatei) schädliche Befehle enthält. Diese Befehle werden dann mit den geheimen Schlüsseln und Token des Basis-Repositorys ausgeführt.

Dieses Muster wird als "pwn-Anforderung" bezeichnet und ist die Ursache mehrerer Lieferkettenkompromittierungen. Weitere Informationen finden Sie unter Verhindern von Pwn-Anfragen im GitHub Security Lab. Zu den gängigen verwundbaren Formen gehören:

  • Auschecken des Head- oder Merge-Commits eines Pull Requests in actions/checkout (ref: ${{ github.event.pull_request.head.sha }}, ref: refs/pull/${{ github.event.pull_request.number }}/merge) und anschließendes Erstellen, Testen oder anderweitiges Ausführen des Ergebnisses.
  • repository: auf den Fork (repository: ${{ github.event.pull_request.head.repo.full_name }}) festlegen, um den Branch des Forks direkt abzurufen.
  • Abrufen des Codes des Pull Requests außerhalb von actions/checkout (zum Beispiel mit git fetch, gh pr checkout oder durch Herunterladen eines Artefakts aus einem pull_request-Lauf eines Forks) und anschließendes Ausführen.

Pwn-Anfragen sind auch nicht auf pull_request_target beschränkt. Jedes Ereignis, das mit geheimen Schlüsseln ausgeführt wird, kann eine pwn-Anforderung einführen, wenn es nicht vertrauenswürdigen Code auscheckt oder herunterlädt und ausführt. Beispielsweise ist ein issue_comment oder workflow_run Workflow, der den Code eines Pull Requests eines Forks abruft und ausführt, auf die gleiche Weise anfällig. Ein workflow_run Workflow sollte Artefakte, die von anderen Workflows hochgeladen wurden, als nicht vertrauenswürdige Daten behandeln, da ihr Inhalt aus einem Fork stammen kann.

Entscheiden, ob pull_request_target verwendet werden soll

Einige Workflows müssen den Code von Pull Requests aus Forks mit erhöhtem Vertrauensniveau auschecken, und genau deshalb wurde pull_request_target überhaupt erst geschaffen. Zum Beispiel das Erstellen von Coverage-Berichten, die eine private Artefakt-Registry erfordern, oder das Erstellen und Ausführen authentifizierter Prüfungen für die durch den Pull Request eingeführten Änderungen. Berücksichtigen Sie die folgenden Fragen, bevor Sie pull_request_target verwenden oder das allow-unsafe-pr-checkout-Flag in actions/checkout aktivieren.

  • Können Sie stattdessen verwenden pull_request ? pull_request wird durch dieselben Ereignisse ausgelöst wie pull_request_target und führt den Workflow-Code aus dem Merge-Branch pull_request aus. Dies erfolgt bei Pull Requests aus Forks auf sichere Weise und mit den oben beschriebenen Schutzmaßnahmen. Wenn kein zusätzlicher geheimer Zugriff erforderlich ist, verwenden Sie pull_request. Komplexere Workflows können neu strukturiert werden, um die potenziell gefährliche Behandlung von Pull-Anforderungscode vom Zugriff auf geheime Schlüssel zu trennen. Weitere Informationen finden Sie unter Verhindern von pwn-Anfragen aus dem GitHub Security Lab.

  • Wird der ausgecheckte Code jemals ausgeführt? Dies ist der Fehler, der pwn-Anforderungsrisiken einführt. Am häufigsten geschieht dies mit actions/checkout, indem Sie den Head eines Pull-Requests in das Arbeitsverzeichnis auschecken und ihn anschließend ausführen. Wenn die path Eingabe nicht festgelegt ist, actions/checkout wird der Code in das $GITHUB_WORKSPACE Verzeichnis geschrieben, das in der Regel das Arbeitsverzeichnis ist, in dem nachfolgende Befehle ausgeführt werden. Die Ausführung ist nicht auf Ihre eigenen Schritte beschränkt: Build- und Testbefehle wie npm install und npm run build, sowie Konfigurationsdateien und Abhängigkeiten, die der Code mit sich bringt, können alle vom Angreifer gesteuerten Code ausführen. Für die Ausführung ist kein offensichtlicher Buildschritt erforderlich. Sie müssen sicherstellen, dass der ausgecheckte Code nur als Daten überprüft und nie vor der Verwendung eines pull_request_target Ereignisses ausgeführt wird.

Härtung eines pull_request_target Workflows

Wenn Sie bestätigt haben, dass Sie dies benötigen pull_request_target, wenden Sie diese Steuerelemente an, um die Auswirkungen dieses risikoreichen Ereignisses einzuschränken. Dies gilt unabhängig davon, ob Ihr Workflow Pull-Request-Code auscheckt.

  • Schränken Sie geheime Schlüssel ein. Vergewissern Sie sich, dass für GITHUB_TOKEN nur die geringstmöglichen Berechtigungen festgelegt sind und dass für den Workflow nur die erforderlichen Repository- und Organisationsgeheimnisse verwendet werden. Weitere Informationen findest du unter Verwenden von GITHUB_TOKEN für die Authentifizierung in Workflows.

  • Verstehen sie die Auswirkungen auf das Zwischenspeichern. Abgesehen von den GITHUB_TOKEN und den konfigurierten Geheimnissen haben Workflows, die auf pull_request_target ausgeführt werden, auch Schreibzugriff auf den Cache, der mit anderen Workflows auf dem Standard-Branch gemeinsam genutzt wird. Böswillige Änderungen an diesem Cache aus pull_request_target Ereignissen können sich auf die Ausführung anderer, nicht verwandter Workflows auswirken.

  • Stellen Sie sicher, dass die zugrunde liegende Berechnung isoliert und kurzlebig ist. Wenn selbstgehostete Runner verwendet werden, müssen Sie bestätigen, dass die Runner-Umgebung ordnungsgemäß gegenüber internen Ressourcen abgeschottet ist und nicht über mehrere GitHub Actions Ausführungen hinweg wiederverwendet wird. Weitere Informationen findest du unter Referenz zur sicheren Verwendung.

  • Gate läuft hinter der Genehmigung. pull_request_target Workflows können durch ein erforderliches label abgesichert werden, das nur Benutzer mit Schreibzugriff hinzufügen können. Dies ist in den GitHub Security LabAnleitungen zum Verhindern von Pwn-Anforderungen beschrieben.

  • Setzen Sie GitHub Actions bewährte Sicherheitsverfahren durch. Neben den spezifischen Risiken von pwn-Anforderungen können andere häufige Sicherheitsrisiken, z. B. die Einfügung von Befehlen, vorhanden sein und sich auf den code auswirken, der in diesem privilegierten Ereignis ausgeführt wird. Weitere Informationen finden Sie unter "Schützen Ihrer GitHub Actions und Workflows: Nicht vertrauenswürdige Eingaben aus der GitHub Security Lab. Aktivieren Sie CodeQL für GitHub Actions, um allgemeine GitHub Actions Schwachstellen zu identifizieren und sich proaktiv davor zu schützen. Weitere Informationen findest du unter Konfigurieren des Standardsetups für das Code-Scanning.

Abmelden von integrierten Schutzfunktionen

Wenn Sie die oben genannten Fragen durchgearbeitet und bestätigt haben, dass Ihr Workflow pull_request_target erfordert und sicher nutzt, können Sie den Schutz von actions/checkout deaktivieren. Wenn allow-unsafe-pr-checkout: true als actions/checkout festgelegt wird, können Head-Refs von Pull Requests aus Forks ausgecheckt werden. Tun Sie dies nur, nachdem Sie bestätigt haben, dass der ausgecheckte Code niemals ausgeführt wird. Die Eingabe wird absichtlich benannt, um in der Codeüberprüfung und statischen Analyse leicht zu erkennen.

Dieser Schutz gilt nur für Fork-Pull-Request-Referenzen. Das Auschecken anderer nicht vertrauenswürdiger Code, z. B. ein nicht verwandtes Drittanbieterrepository, das Abrufen von Code mit git fetch oder gh pr checkoutoder das Ausführen eines heruntergeladenen Artefakts, wird von den actions/checkout Prüfungen nicht abgedeckt.

Einschränken der Verwendung von pull_request_target

Repository-, Organisations- und Unternehmensadministratoren können Workflowausführungsschutz verwenden, um zu steuern, welche Ereignisse und Akteure Workflows auslösen können. Wenn ein Repository für pull_request_target keinen legitimen Verwendungszweck hat, wird durch seine Einschränkung das Risiko beseitigt, unabhängig davon, wie einzelne Workflows geschrieben sind.