14 KiB
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
.exealsimage/pngdeklariert 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 gleichenScanAdapter-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/:
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-typevon 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
-
Interface
ScanAdapterdefinieren- 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
- Type-Definitionen:
- Commit:
01/av-layer1: define ScanAdapter interface in packages/storage
- Files:
-
MagicBytesScanAdapterimplementieren- 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
- Files:
-
Allow-List-Defaults definieren
- Files:
packages/storage/src/scan/allowList.ts(neu) - Aktion:
- Defaults pro Context:
Avatar:image/png,image/jpeg,image/webpMediaLibrary: 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: nurapplication/pdf+ bilderKbAsset: bilder +application/pdf
- Env-override möglich via
STORAGE_SCAN_ALLOWLIST_<CONTEXT>(comma-separated)
- Defaults pro Context:
- Commit:
01/av-layer1: define default allow-lists per upload context
- Files:
-
Upload-Pfade einhängen
- Files: alle Upload-Handler/Routes (per
rgermitteln — 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
- Pro Upload-Handler vor S3-Put:
- Commit:
01/av-layer1: enforce magic-bytes scan in N upload paths
- Files: alle Upload-Handler/Routes (per
-
AuditEvent pro Reject
- Files: existierender
auditLog-Pfad (Prisma-ModelAuditEvento.ä.) - Aktion: bei Reject einen AuditEvent loggen —
type: 'upload.rejected.scan',userId,tenantId,declaredMimeType,detectedMimeType,filename,reason. - Commit:
01/av-layer1: audit-log upload rejections
- Files: existierender
-
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
- Files:
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
- Echtes PNG mit declared
- Integration-Tests: je Upload-Route ein POST mit Bad-File → 415, kein S3-Put
- E2E-Tests (Playwright):
- Profile-Page: Upload eines
.exe, das als.pngumbenannt wurde → User sieht Fehlermeldung - Email-Compose: Anhang mit falschem MIME → Fehler
- Profile-Page: Upload eines
- Coverage-Target:
magicBytesScanAdapter.ts100%, 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.tsmitScanAdapter-InterfaceMagicBytesScanAdapterimplementiert 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.mderstellt- Unit-Test-Coverage 100% für Adapter
- E2E-Smoke (Bad-File-Upload) grün
pnpm lint,pnpm typecheck,pnpm testgrü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 auftrue) 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
dompurifyServer-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-purposefür Upload-Pfad-Inventur — Brief: "Finde alle Upload-Handler/Routes im Codebase (apps/web/app/routes/**, alle Form-Action-Handler mitmultipart/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) inpackages/storage/test/fixtures/ablegen." - Verification:
general-purposefür Acceptance-Criteria + Staging-Smoke. - Code-Review:
gsd-code-reviewernach Phase-Abschluss; explizit Security-Aspekte.
Staging-Deployment-Steps
- Branch
agent/01-av-layer1pushen. - Coolify-Auto-Deploy.
- Smoke-Tests via Browser:
- Profile-Avatar-Upload mit legitimem PNG → erfolg
- Profile-Avatar-Upload mit
.exeumbenannt zu.png→ 415-Error sichtbar - Email-Attachment mit
.zip→ erfolg - Form-Upload mit
.zip(nicht in Allow-List) → 415-Error
- Staging-AuditLog auf neue
upload.rejected.scan-Events prüfen. - 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.tslebt aber nur auf deragent/01-supabase-removalbranch und ist nicht auf main. Wenn ich die scan-Integration HIER mache, müsste ich entweder (a) gegen das altesupabaseService.ts(legacy auf main) wiren und das in #18 erneut migrieren = doppelte Arbeit, oder (b)agent/01-supabase-removalin 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 erstagent/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, nichtimage/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
f7165dc0lefthook fix (Precursor). - 2026-05-17 01:20 —
b6674c66Step 1:packages/storage/src/scan/pre-upload-types.tsmitPreUploadScanAdapter,ScanContext,PreUploadScanInput/Result, bounded reason-string-union,PreUploadAllowList. Re-export viascan/index.ts. - 2026-05-17 01:26 —
f654a710Step 2+3:MagicBytesScanAdaptermit file-type@22,allow-list.tsmit 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.tsaus #18 (existiert nur auf agent/01-supabase-removal, nicht auf main). Sobald #18 merged ist, rebase + Steps 4-6 (Wire scan in storeFile mit optionalscanContext, 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 weilFileObject-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 (.exeals.png→ erwartetes 415) bleibt für staging-validation offen.