Shuffle/docs/adr/0003-ci-runner-sicherheit.md

# ADR-0003: CI-Sicherheit – Fork-PRs und der Runner `docker-host`

- **Status:** Teilweise angenommen (Chris, 2026-11-04): Betriebsregel unten gilt; Maßnahmen A und B sowie die Frage „öffentlich oder privat“ sind noch offen, Issue #43
- **Datum:** 2026-11-03

## Kontext
Das Repo ist öffentlich. Der Runner `shuffle-mac-runner` (Label `docker-host`) läuft auf Chris' Mac mit Docker-in-Docker;
die Jobs `supabase-tests` und `e2e` sprechen den dind-Daemon per TCP an (`DOCKER_HOST=tcp://<Gateway>:2375`, ohne TLS).
Wer dort Code ausführt, hat Root-Äquivalent im dind (Container mit Host-Mounts, Zugriff auf alles, was der dind sieht).

Bei `on: pull_request` wird die Workflow-Datei aus dem PR-Head gelesen. Ein Fork-PR kann Bedingungen wie
`head.repo.full_name == github.repository` entfernen oder ein beliebiges `runs-on:` setzen. **Ein `if:` in `ci.yml` schützt
daher nicht** und kein Inhalt des Repos kann einen Fork-PR daran hindern, `runs-on: docker-host` anzufordern.

Stand der Prüfung (Forgejo 8.0.3+gitea-1.22.0, Runner v5.0.4): Die Freigabe-Logik wurde im Quelltext von Forgejo v8.0.3
gelesen (`services/actions/notifier_helper.go`, Funktion `ifNeedApproval`). Es gab **keinen Live-Test** mit einem Fork-PR;
das Verhalten des Runners und die Aussagen zu Runner-Konfiguration stammen aus Doku-Kenntnis. Prüfschritte stehen unten.

## Was Forgejo 8.0.3 bietet
| Mechanismus | Verfügbarkeit | Bewertung |
|---|---|---|
| Freigabe für Fork-PR-Workflows (`need approval`) | Eingebaut, **keine Repo-Einstellung zum Ein-/Ausschalten**. Entscheidet über den ganzen Lauf. Laut Quelltext v8.0.3 braucht ein Fork-PR (Event `pull_request`) Freigabe, außer der Nutzer hat Schreibrecht oder es gibt im Repo schon einen freigegebenen Lauf dieses Nutzers. | Hauptschutz mit Lücke, siehe Absatz unter der Tabelle. |
| Nutzer `restricted` (Administration -> Benutzerkonten; `app.ini` `[service] DEFAULT_USER_IS_RESTRICTED` für neue Konten, **unverifiziert**) | Eingebaut | Erzwingt die Freigabe bei jedem Lauf (Quelltext). Nebenwirkung vermutlich: keine Sicht auf öffentliche Repos ohne Zuordnung (**unverifiziert**), siehe C.2. |
| `pull_request_target` | Läuft mit Workflow aus dem Base-Branch | Nicht verwenden, um PR-Code auf `docker-host` zu bauen (klassische Pwn-Request-Lücke). |
| Runner-Scoping (Instanz/Organisation/Nutzer/Repo) | Eingebaut | Begrenzt, *welche Repos* den Runner nutzen, nicht *welche Events*. Hilft hier nicht gegen Fork-PRs im selben Repo. |
| Runner-Labels | Eingebaut | Jeder Workflow darf jedes Label anfordern. Kein Schutz. |
| Event-/Repo-Filter im Runner (`runner.yaml`) | Nicht vorhanden | -- |
| Repo privat stellen | Eingebaut | Beseitigt das Problem (Fremde können keine PRs öffnen), kostet Öffentlichkeit. |
| Forks instanzweit verbieten (`app.ini`, Forgejo-Doku prüfen: `[repository] DISABLE_FORKS`/ähnlich) | In 8.0.3 nicht verifiziert | Nur als Prüfpunkt. |

**Vertrauenslücke der Freigabe:** Eine einzige Freigabe vertraut dem Nutzer dauerhaft. Für alle künftigen PRs dieses Nutzers im
Repo (nicht nur für diesen PR) laufen Fork-PR-Workflows ohne weitere Freigabe, auch nach einem Push mit manipuliertem Workflow.
Eine Freigabe ist also faktisch die Entscheidung „diesem Nutzer vertraue ich den Runner an“.

## Entscheidung (Vorschlag)
Verteidigung in drei Schichten; nur die erste lässt sich im Repo ausdrücken, der Rest braucht Chris:

1. **Repo (umgesetzt):** Der `if:`-Guard an `supabase-tests` und `e2e` hält nur einen unveränderten, bereits freigegebenen
   Fork-PR von `docker-host` fern. Er verhindert weder das Warten auf Freigabe (die gilt für den ganzen Lauf, das Job-`if`
   wird erst danach ausgewertet) noch einen manipulierten Lauf. Die Kommentare in `ci.yml` sagen das.
2. **Forgejo (Chris):** Fork-PR-Läufe auf diesem Runner **nicht freigeben**, solange er nicht isoliert ist (3.) oder das Repo
   nicht privat ist. Grund: Eine Freigabe gilt für alle künftigen PRs des Nutzers im Repo. Fremde Beiträge lokal prüfen oder als
   Branch ins Haupt-Repo übernehmen.
3. **Runner/Mac (Chris):** Blast Radius des dind begrenzen (siehe Anleitung).

Solange 2. und 3. nicht erledigt sind, gilt `docker-host` als **nicht für externe Beiträge geeignet**. Empfehlung: vor dem
ersten externen Beitrag, spätestens vor Release, entweder 3. umsetzen oder das Repo privat stellen.

## Betriebsregel (angenommen, Chris, 2026-11-04)
**Fork-PR-Läufe werden nie freigegeben. Fremde Beiträge werden lokal geprüft und als Branch ins Haupt-Repo übernommen**
(dort läuft die CI ohne Freigabe, weil Schreibrecht besteht). Das ist die einfachste wirksame Regel und kostet nichts; sie ist
eine Disziplin-Regel, kein technischer Schutz: Eine einzige Freigabe vertraut dem Nutzer den Runner dauerhaft an (siehe
Vertrauenslücke).

Weiterhin offen und vor dem ersten externen Beitrag, spätestens vor dem Release zu entscheiden: Prüfung A (Verhalten live prüfen),
Maßnahme B (Runner isolieren) oder das Repo privat stellen. Issue #43 bleibt bis dahin offen.

## Anleitung für Chris (nicht automatisiert; nichts davon wurde ausgeführt)

### A. Verhalten prüfen (10 Minuten, empfohlen als Erstes)
1. Zweites Forgejo-Konto ohne Schreibrecht anlegen (oder Test-Nutzer), Repo forken, im Fork `ci.yml` ändern
   (`if:`-Zeilen entfernen, harmlosen Schritt `echo hallo` ergänzen), PR gegen `main` öffnen.
2. Erwartung: Lauf steht auf „Wartet auf Freigabe“ und startet erst nach Klick auf **Freigeben** (PR-Seite bzw. Actions-Lauf).
   Falls er ohne Freigabe startet (Quelltext sagt anderes): Das Repo sofort privat stellen (Einstellungen -> Repository -> Sichtbarkeit) und
   Runner pausieren (B.3), dann Forgejo-Version/Doku prüfen.
3. Zweiten Push im selben PR machen: Läuft er jetzt ohne erneute Freigabe? Dann ist „einmal freigegeben, immer freigegeben“ bestätigt.
4. Aufräumen: Testkonto und Fork **löschen** (dauerhaft vertrautes Konto!). Falls das nicht geht: mindestens `restricted` setzen und
   Anmeldung verbieten (Administration -> Benutzerkonten).

Hinweis: Der Test mit `restricted` (jeder Lauf einzeln freigegeben) ist eventuell nicht durchführbar, weil eingeschränkte Nutzer
vermutlich keine öffentlichen Repos ohne Zuordnung sehen (**unverifiziert**, siehe C.2). Dann entfällt er; die Quelltext-Aussage bleibt.

### B. Auf dem Mac (Runner/dind)
1. Labels sind keine Grenze: Ein Fork-PR kann `runs-on: docker-host` selbst setzen. Eine Trennung `docker` / `docker-host` im
   Workflow schützt deshalb nichts, und `container.network`/`valid_volumes` der Runner-Konfiguration gelten für den ganzen
   Runner, nicht je Label. Schutz bieten nur Freigabe, ein Daemon/VM ohne Wertvolles (Punkt 2) oder ein privates Repo. Sollen
   `docker` und `docker-host` unterschiedlich exponiert sein, braucht es getrennte Runner-Registrierungen mit eigener
   Konfiguration, idealerweise auf getrennten Hosts. Prüfen kannst du, ob ein `docker`-Job den dind erreicht
   (`curl -s -m 3 http://<Default-Gateway>:2375/version`, Gateway wie in `ci.yml` aus `/proc/net/route`); antwortet er,
   gilt die Warnung für alle Jobs des Runners.
2. Wirksam: Runner in eine Wegwerf-VM (z. B. Lima/Colima/UTM) oder auf einen separaten Rechner/Hetzner-Server verlagern, ohne
   Host-Mounts, ohne Zugriff aufs LAN, ohne Zugangsdaten und ohne persönliche Daten auf dem Mac. Ziel: Ein Ausbruch aus dem dind
   trifft nichts Wertvolles. Eigenes Registrierungs-Token verwenden; `.runner` und Token nicht ins Repo und nicht in Logs.
3. Notbremse: Runner-Prozess auf dem Mac beenden (z. B. `launchctl unload` des Dienstes oder Prozess/Container stoppen; der genaue Weg hängt von der Einrichtung ab, **unverifiziert**). In Forgejo (Einstellungen -> Actions -> Runner) gibt es in 8.0.3 evtl. nur Bearbeiten/Löschen statt Deaktivieren (**unverifiziert**); Löschen macht den Runner unbrauchbar, bis er neu registriert wird.
4. Runner nur für dieses Repo registrieren (Repo-Scope statt Instanz-/Nutzer-Scope), damit andere Repos ihn nicht ansprechen können.

### C. In Forgejo
1. Fork-PR-Läufe nicht freigeben (siehe Entscheidung 2.).
2. Fremde Konten als `restricted` zu führen ist mit Vorsicht zu genießen: Eingeschränkte Nutzer sehen vermutlich keine öffentlichen
   Repos ohne explizite Zuordnung (**unverifiziert**). Dann könnten sie keinen Fork/PR anlegen, d. h. `restricted` sperrt externe
   Beiträge faktisch aus. Das ist eine Alternative zum Repo-privat-Stellen, kein Mittel für „jeder Lauf einzeln freigeben“.
   Erst mit dem Testkonto aus A prüfen.
3. Optional: Branch-Schutz für `main` mit geschützten Dateimustern (UI-Bezeichnung in 8.0.3 **unverifiziert**, bei
   Gitea „Protected file patterns“) `.forgejo/**;e2e/**;supabase/config.toml`. Achtung, vermutlich blockiert das auch das
   Mergen von PRs, die solche Dateien ändern, also auch deine eigenen CI-PRs (**unverifiziert**); nur nutzen, wenn du dafür eine
   Ausnahme (Admin-Merge/Whitelist) hast, sonst weglassen. Es schützt nur `main`, nicht die PR-Läufe.
4. Repo privat stellen, wenn externe Beiträge nicht gewollt sind (löst das Problem vollständig).
5. Runner-Token rotieren (Registrierungs-Token ist kein Dauer-Geheimnis, das `.runner` auf dem Mac enthält das Laufzeit-Token):
   Runner in Forgejo (Einstellungen -> Actions -> Runner) löschen, im selben Dialog ein neues Registrierungs-Token erzeugen, den
   Runner auf dem Mac mit `forgejo-runner register` neu registrieren und die alte `.runner` löschen. Vorschlag: alle 3 Monate
   sowie sofort bei Verdacht. Token nie in Chats, Logs oder ins Repo kopieren.

## Konsequenzen
- Fork-PRs bekommen ohne Freigabe kein CI (der ganze Lauf wartet, mit allen Jobs). Eine Freigabe vertraut dem Nutzer den ganzen
  Runner dauerhaft an. Fremde Beiträge daher als Branch ins Haupt-Repo übernehmen (dort läuft CI ohne Freigabe, weil Schreibrecht).
- Externe Beiträge laufen nicht auf `docker-host`, bis der Runner isoliert ist oder das Repo privat ist.
- Der `if:`-Guard ändert daran nichts (siehe Entscheidung 1).
- Offen: Ergebnis der Prüfung A und Umsetzung B. Bis dahin Issue #43 nicht schließen.