Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/av-scanner-layer-1.md
T

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 .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/:

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.