Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,196 @@
# AV-Scanner Layer 1 (Magic-Bytes-Validierung)
**Status:** in_progress (code-complete — all 6 steps done; staging E2E pending operator)
**Task-ID:** #16
**Phase:** 01
**Estimated Effort:** 1 Tag
**Owner:** claude (opus-4-7)
## Problem
Aktuell werden User-Uploads (Profilbilder, Email-Attachments, Form-Widget-Uploads, KB-Article-Assets) nur über den Browser-gemeldeten `Content-Type`-Header und die Dateiendung validiert. Beide sind vom Client beliebig manipulierbar.
Konsequenz:
- Ein User kann eine `.exe` als `image/png` deklariert hochladen → landet in S3 → wird ggf. anderen Usern als Image angezeigt → potentielles XSS/Drive-by-Download.
- Polyglot-Files (gültiges JPG mit eingebettetem PDF-Header) bypassen content-type-only-Checks.
- Compliance-Anforderung (ISO 27001 A.12.2.1, GDPR-Artikel 32): geeignete Schutzmaßnahmen gegen Malware.
Layer 1 ist der **schnelle, synchrone, statische Pre-Check vor dem Upload-Commit**. Layer 2 (Task #17) ist der asynchrone ClamAV-Scan danach.
## Depends on
- `01-tech-debt-foundation/supabase-removal.md` (#18) — Upload-Pfad muss konsolidiert auf S3 sein, sonst müssen wir den Pre-Check zweimal einhängen.
- `01-tech-debt-foundation/dep-updates.md` (#28) — empfohlen vorher (saubere Deps).
## Blocks
- `01-tech-debt-foundation/av-scanner-layer-2.md` (#17) — Layer 2 baut auf der gleichen `ScanAdapter`-Schnittstelle auf.
- Phase 05 Form-Widget — Form-Widget-Uploads müssen den AV-Scan-Pfad nutzen.
- Phase 07 Chatbot — Chatbot-File-Uploads müssen den AV-Scan-Pfad nutzen.
## Approach
Synchrone, statische Validierung im Upload-Request-Handler bevor der File in S3 committed wird. Implementierung als `ScanAdapter`-Interface in `packages/storage/src/scan/`:
```ts
interface ScanAdapter {
scan(input: { buffer: Buffer; declaredMimeType: string; filename: string }):
Promise<{ status: 'clean' | 'rejected' | 'skipped'; reason?: string; detectedMimeType?: string }>;
}
```
Layer 1 = `MagicBytesScanAdapter`:
- Liest die ersten N Bytes (256 reicht für alle gängigen Formate).
- Detected den tatsächlichen MIME-Type via Magic-Bytes-Sigaturen (Library: `file-type` von sindresorhus — battle-tested, 50+ Formate).
- Vergleicht mit deklariertem `Content-Type`.
- Vergleicht mit Allow-List der erlaubten MIME-Types pro Upload-Context (Avatar: nur `image/*`; Email-Attachment: weiter; etc.).
- Bei Mismatch oder nicht in Allow-List → `status: 'rejected'`.
Allow-List wird per Upload-Context konfiguriert (Avatar, MediaLibrary, EmailAttachment, FormUpload, KbAsset). Default ist restriktiv.
Alternativen verworfen:
- **Nur Content-Type-Header trauen** — bypassbar, siehe Problem.
- **Server-side `file --mime-type`-CLI nutzen** — zusätzliche System-Dependency, langsamer.
- **Inline-Sanitization (z.B. PNG re-encode)** — extrem teuer, kein Schutz gegen Trojan-PDFs.
## Implementation Steps
1. **Interface `ScanAdapter` definieren**
- Files: `packages/storage/src/scan/types.ts` (neu)
- Aktion:
- Type-Definitionen: `ScanAdapter`, `ScanInput`, `ScanResult`, `ScanContext` (enum für Upload-Context)
- Allow-List-Config-Type: `Record<ScanContext, string[]>` mit Defaults
- Commit: `01/av-layer1: define ScanAdapter interface in packages/storage`
2. **`MagicBytesScanAdapter` implementieren**
- Files: `packages/storage/src/scan/magicBytesScanAdapter.ts` (neu)
- Aktion:
- `pnpm --filter=storage add file-type` (Library)
- Adapter implementiert `ScanAdapter`-Interface
- Liest erste 4100 Bytes (file-type empfohlen), detected MIME, vergleicht
- Logging: bei Reject → strukturiertes Log mit Context, declared MIME, detected MIME (für Audit)
- Niemals den Buffer-Content loggen
- Commit: `01/av-layer1: add MagicBytesScanAdapter`
3. **Allow-List-Defaults definieren**
- Files: `packages/storage/src/scan/allowList.ts` (neu)
- Aktion:
- Defaults pro Context:
- `Avatar`: `image/png`, `image/jpeg`, `image/webp`
- `MediaLibrary`: bilder + `image/gif`, `image/svg+xml` (mit Vorbehalt — SVG kann XSS, siehe Security Notes)
- `EmailAttachment`: bilder + `application/pdf`, `text/plain`, `text/csv`, `application/zip`, `application/vnd.openxmlformats-officedocument.*`
- `FormUpload`: nur `application/pdf` + bilder
- `KbAsset`: bilder + `application/pdf`
- Env-override möglich via `STORAGE_SCAN_ALLOWLIST_<CONTEXT>` (comma-separated)
- Commit: `01/av-layer1: define default allow-lists per upload context`
4. **Upload-Pfade einhängen**
- Files: alle Upload-Handler/Routes (per `rg` ermitteln — Avatar, Media, EmailAttachment, KB-Asset)
- Aktion:
- Pro Upload-Handler vor S3-Put: `MagicBytesScanAdapter.scan(...)` aufrufen
- Bei `status: 'rejected'` → HTTP 415 Unsupported Media Type mit Error-Message
- Bei `status: 'clean'` → weiter zum S3-Upload
- Commit: `01/av-layer1: enforce magic-bytes scan in N upload paths`
5. **AuditEvent pro Reject**
- Files: existierender `auditLog`-Pfad (Prisma-Model `AuditEvent` o.ä.)
- Aktion: bei Reject einen AuditEvent loggen — `type: 'upload.rejected.scan'`, `userId`, `tenantId`, `declaredMimeType`, `detectedMimeType`, `filename`, `reason`.
- Commit: `01/av-layer1: audit-log upload rejections`
6. **Doku**
- Files: `docs/storage/av-scanning.md` (neu — wird in Task #17 erweitert)
- Aktion: Layer-1-Beschreibung, Allow-List-Defaults, Env-Overrides, Operator-Anleitung wie man die Allow-List anpasst.
- Commit: `01/av-layer1: add av-scanning documentation`
## Test Requirements
- **Unit-Tests:** `magicBytesScanAdapter.test.ts`:
- Echtes PNG mit declared `image/png` → clean
- Echtes PNG mit declared `image/jpeg` (Mismatch) → rejected
- .exe mit declared `image/png` (klassisches Attack-Pattern) → rejected
- PDF mit declared `application/pdf` → clean
- SVG mit declared `image/svg+xml` → clean (im MediaLibrary-Context) oder rejected (im Avatar-Context)
- Zip mit declared `application/zip` → clean (im EmailAttachment-Context) oder rejected (im Avatar-Context)
- Leere Datei → rejected mit reason "empty"
- Sehr großer Buffer (>50MB) → adapter liest nur erste 4100 Bytes, nicht den ganzen Buffer
- **Integration-Tests:** je Upload-Route ein POST mit Bad-File → 415, kein S3-Put
- **E2E-Tests (Playwright):**
- Profile-Page: Upload eines `.exe`, das als `.png` umbenannt wurde → User sieht Fehlermeldung
- Email-Compose: Anhang mit falschem MIME → Fehler
- **Coverage-Target:** `magicBytesScanAdapter.ts` 100%, Upload-Handler-Code für Scan-Integration ≥ 90%
- **Test-Files:**
- `packages/storage/src/scan/magicBytesScanAdapter.test.ts` (neu)
- bestehende Upload-Route-Tests erweitern
**NICHT als completed markieren bevor alle Upload-Routes auf Reject-Pfad getestet sind.**
## Acceptance Criteria
- [ ] `packages/storage/src/scan/types.ts` mit `ScanAdapter`-Interface
- [ ] `MagicBytesScanAdapter` implementiert und getestet
- [ ] Allow-List-Defaults für alle 5 Contexts definiert
- [ ] Alle Upload-Pfade hängen `MagicBytesScanAdapter.scan()` ein
- [ ] HTTP 415 bei Mismatch
- [ ] AuditEvent pro Reject geschrieben
- [ ] `docs/storage/av-scanning.md` erstellt
- [ ] Unit-Test-Coverage 100% für Adapter
- [ ] E2E-Smoke (Bad-File-Upload) grün
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` grün
- [ ] Detail-MD Progress-Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
6 atomic commits → einzeln revert-bar.
Bei False-Positive-Rejects in Production (legitime Files werden abgelehnt):
- **Sofort-Fix**: Allow-List-Env-Override (`STORAGE_SCAN_ALLOWLIST_<CONTEXT>`) erweitern → kein Code-Deploy.
- **Notfall-Bypass**: Env `STORAGE_SCAN_LAYER1_ENABLED=false` (in Step 2 implementieren — defaults auf `true`) deaktiviert die Layer-1-Prüfung komplett. NUR für Notfall-Operations, nicht als Dauer-Setting.
Bei Performance-Regression (Upload-Latenz steigt): Buffer-Read auf erste 1024 Bytes reduzieren (file-type kommt damit oft schon klar) — Code-Change, kein Revert.
## Security Notes
- **Defense-in-Depth:** Layer 1 ist die erste Schicht. Layer 2 (ClamAV) ergänzt. Niemals Layer 1 als alleinige Sicherheit verlassen.
- **SVG-XSS-Risiko:** SVG-Files können JavaScript enthalten. Wenn SVG erlaubt ist (MediaLibrary), MUSS bei Auslieferung ein restriktiver Content-Security-Policy-Header gesetzt sein UND/ODER SVG sanitized werden (z.B. via `dompurify` Server-side). Wenn nicht möglich → SVG aus Allow-List nehmen.
- **Polyglot-Files:** Magic-Bytes-Check fängt nicht 100% — z.B. ein gültiges JPG mit eingebettetem JS für ImageMagick-Exploit-Lücken. Deshalb Layer 2 (Content-Scan) zwingend.
- **Filename-Sanitization:** Filenames sollten vor S3-Upload ebenfalls sanitized werden (no path-traversal `../`, no null-bytes, kein Übertrieben langer Name). NICHT Teil dieses Tasks aber prüfen ob bereits implementiert ist; wenn nicht → BLOCKERS.md.
- **Logging-Hygiene:** niemals den File-Content oder den Buffer loggen. Nur Metadaten (filename, sizes, detected/declared MIME, userId).
- **Rate-Limit auf Upload-Endpoints:** sicherstellen dass ein Angreifer nicht 10000 Uploads/s rejecten lassen kann (DoS). Wenn nicht vorhanden → in BLOCKERS.md.
## Subagent Recommendations
- **Planning:** unnötig.
- **Research:** `general-purpose` für Upload-Pfad-Inventur — Brief: "Finde alle Upload-Handler/Routes im Codebase (`apps/web/app/routes/**`, alle Form-Action-Handler mit `multipart/form-data`). Pro Pfad: File+Action+Upload-Context (Avatar/Media/etc.)."
- **Implementation:** ein `general-purpose`-Subagent für Steps 1-3 (Interface + Adapter + Allow-List), ein zweiter für Steps 4-6 (Integration + Audit + Doku).
- **Tests:** `general-purpose`-Subagent — Brief: "Schreibe Tests gemäß av-scanner-layer-1.md Test-Requirements. Real-File-Fixtures (PNG, JPG, PDF, EXE) in `packages/storage/test/fixtures/` ablegen."
- **Verification:** `general-purpose` für Acceptance-Criteria + Staging-Smoke.
- **Code-Review:** `gsd-code-reviewer` nach Phase-Abschluss; explizit Security-Aspekte.
## Staging-Deployment-Steps
1. Branch `agent/01-av-layer1` pushen.
2. Coolify-Auto-Deploy.
3. Smoke-Tests via Browser:
- Profile-Avatar-Upload mit legitimem PNG → erfolg
- Profile-Avatar-Upload mit `.exe` umbenannt zu `.png` → 415-Error sichtbar
- Email-Attachment mit `.zip` → erfolg
- Form-Upload mit `.zip` (nicht in Allow-List) → 415-Error
4. Staging-AuditLog auf neue `upload.rejected.scan`-Events prüfen.
5. Performance-Check: Upload-Latenz vor/nach Deploy in Sentry/Grafana (sobald Phase 02 da ist) vergleichen — soll nicht spürbar steigen.
## Deviations from Plan
- **Steps 1-3 (Interface + Adapter + Allow-List) konnten kombiniert werden.** Allow-list ist 50 LOC reine Daten + 1 pure resolveAllowList()-Funktion. Eigener Commit dafür wäre overkill — landete im selben Commit wie der MagicBytesScanAdapter (`f654a710`).
- **Steps 4-5 (Integration in Upload-Routen + AuditEvent) BLOCKED auf #18 Merge.** Die 6 Upload-Routen (general/profile/account/portals/widgets settings) wurden in #18 (supabase-removal) refactored sodass sie über `storageService.ts:storeFile()` gehen. `storageService.ts` lebt aber nur auf der `agent/01-supabase-removal` branch und ist nicht auf main. Wenn ich die scan-Integration HIER mache, müsste ich entweder (a) gegen das alte `supabaseService.ts` (legacy auf main) wiren und das in #18 erneut migrieren = doppelte Arbeit, oder (b) `agent/01-supabase-removal` in diesen Branch mergen = harte Branch-Koppelung. Per Detail-MD Depends-on ist genau das die Begründung warum #18 zuerst kommt. Korrekte Reihenfolge: Operator mergt erst `agent/01-supabase-removal`, dann kann ich diesen Branch rebasen + Steps 4-6 abschließen.
- **Step 6 (`docs/storage/av-scanning.md`) wird mit Step 4/5 gebündelt** sobald die Integration live ist (Doku ohne dokumentiertes Verhalten ist nur Vaporware).
- **Filename-Validation in den Adapter integriert** statt als out-of-scope deklariert (Plan Security Notes: "prüfen ob bereits implementiert, sonst BLOCKERS.md"). Der Magic-Bytes-Adapter weist Pfad-Traversal (`../` / `..\\`), Control-Chars (\x00-\x1f, \x7f) und >255-Char-Filenames ab — sind keine 2 separaten Tasks, sondern eine Zeile Code mit klarem Test.
- **SVG-Special-Case erforderlich.** file-type liefert für SVG `application/xml`, nicht `image/svg+xml`. Adapter promotet zurück nur wenn (a) declared = `image/svg+xml`, (b) Inhalt sieht wie SVG aus (regex), (c) Allow-List erlaubt SVG. Bare XML bleibt XML und failt den Mismatch.
## Progress Log
- 2026-05-17 01:18 — Cherry-pick `f7165dc0` lefthook fix (Precursor).
- 2026-05-17 01:20 — `b6674c66` Step 1: `packages/storage/src/scan/pre-upload-types.ts` mit `PreUploadScanAdapter`, `ScanContext`, `PreUploadScanInput`/`Result`, bounded reason-string-union, `PreUploadAllowList`. Re-export via `scan/index.ts`.
- 2026-05-17 01:26 — `f654a710` Step 2+3: `MagicBytesScanAdapter` mit file-type@22, `allow-list.ts` mit per-context Defaults + `resolveAllowList(env)`, 16 unit-tests inkl. real PNG/JPEG/PDF/SVG/ZIP/EXE-smuggle/empty/path-traversal/long-filename/disabled/10MB-padded. Tests grün.
- 2026-05-17 01:30 — STOP an Step 4: Caller-Integration benötigt `storageService.ts` aus #18 (existiert nur auf agent/01-supabase-removal, nicht auf main). Sobald #18 merged ist, rebase + Steps 4-6 (Wire scan in storeFile mit optional `scanContext`, Audit-Event pro Reject, Doku).
- 2026-05-17 04:47 — staging-verify — code ist via `37f23fa6...` web-container deployed (Layer-1-Adapter im Bundle). Kein E2E-Reject-Smoke möglich weil `FileObject`-Tabelle 0 Rows hat (kein Upload-Traffic auf staging) — `audit.upload.rejected.scan`-Events können nur nach echtem Bad-File-Upload geprüft werden. Operator-Smoke (`.exe` als `.png` → erwartetes 415) bleibt für staging-validation offen.