# 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` 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_` (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_`) 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.