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

14 KiB

AV-Scanner Layer 2 (ClamAV)

Status: in_progress (container staging-deployed with EICAR detection green; DB tracking columns + user notification + admin restore UI still deferred; app-side CLAMAV_HOST/AV_LAYER_2_ENABLED env-flip pending operator) Task-ID: #17 Phase: 01 Estimated Effort: 2-3 Tage Owner: claude (opus-4-7)

Problem

Layer 1 (Magic-Bytes, Task #16) fängt Type-Mismatch und groben Polyglot-Missbrauch ab, kann aber keine bekannten Malware-Signaturen detektieren. Ein legitim aussehendes PDF mit eingebettetem JS-Exploit oder eine ZIP mit Trojan-Payload geht ungeprüft durch.

Layer 2 ergänzt:

  • Bekannte Malware-Signaturen (ClamAV-Signaturen-DB, freshclam-aktuell)
  • Heuristische Erkennung (Trojaner, Worm, PUA)
  • Archive-Inspection (in ZIPs reinschauen)

Anforderung: asynchron, nicht-blockierend. Layer 1 ist synchron (User bekommt sofort Feedback). Layer 2 läuft im Hintergrund nach erfolgreichem Upload — bei Treffer wird der File quarantäniert + Owner benachrichtigt + AuditEvent geschrieben.

Depends on

  • 01-tech-debt-foundation/av-scanner-layer-1.md (#16) — Layer 2 nutzt dieselbe ScanAdapter-Schnittstelle. Layer 1 muss zuerst stehen.
  • BullMQ muss als Worker-Queue verfügbar sein — bereits im Boilerplate vorhanden.

Blocks

  • Phase 02 — keine direkte Blockade, aber Sentry-Wiring für Scan-Errors ist sinnvoller wenn Layer 2 da ist.
  • Phase 05 Form-Widget und Phase 07 Chatbot — Uploads sollten beide Layer durchlaufen.

Approach

ClamAV läuft als separater Container (docker-compose-Service). Boilerplate connected via clamdscan-Protokoll (TCP, default Port 3310).

Komponenten:

  1. docker-compose.yml-Service clamav mit Image clamav/clamav:stable, Volume für Signature-DB, Health-Check.
  2. ClamAVScanAdapter in packages/storage/src/scan/ — implementiert ScanAdapter aus Task #16.
  3. BullMQ-Job scan.file der im Worker-Pod läuft, nicht im Web-Pod (CPU-intensiv).
  4. Health-Check vor jedem Scan: wenn ClamAV nicht erreichbar → Adapter loggt Warning, gibt status: 'skipped' zurück, blockiert NICHT den Upload. Audit-Counter tracked die Skip-Rate.
  5. Quarantäne-Mechanismus bei Hit: S3-Object wird in einen quarantine/-Prefix verschoben, DB-Row markiert mit quarantined: true, User-Notification.

Alternativen verworfen:

  • ClamAV synchron im Upload-Pfad — zu langsam (mehrere Sekunden pro File), schlechte UX.
  • ClamAV als Library (statt Container) — Signatur-Updates via freshclam sind operational komplex ohne Container.
  • Cloud-AV-Service (z.B. VirusTotal) — externe API, Daten-Privacy-Risiko (User-Files raus), Kosten pro Scan.

Implementation Steps

  1. Docker-Compose-Service clamav hinzufügen

    • Files: docker-compose.yml (root), ggf. docker-compose.dev.yml und docker-compose.prod.yml
    • Aktion:
      clamav:
        image: clamav/clamav:stable
        volumes:
          - clamav-db:/var/lib/clamav
        ports:
          - "3310:3310"
        healthcheck:
          test: ["CMD", "clamdscan", "--ping", "1"]
          interval: 30s
          timeout: 5s
          retries: 3
        restart: unless-stopped
      
      plus Named-Volume clamav-db. Erster Start dauert lange (Signatur-Download via freshclam).
    • Commit: 01/av-layer2: add clamav container to docker-compose
  2. ClamAVScanAdapter implementieren

    • Files: packages/storage/src/scan/clamAVScanAdapter.ts (neu)
    • Aktion:
      • pnpm --filter=storage add clamscan (Node.js-Wrapper für clamdscan-Protokoll)
      • Adapter implementiert ScanAdapter-Interface
      • Health-Check: vor Scan ein clamd PING. Bei Timeout (>2s) → return status: 'skipped', log warning.
      • Scan: Stream-basiert (kein Buffer im Memory). Bei Hit → return status: 'rejected' + reason: <signature-name>.
      • Env: CLAMAV_HOST (default clamav), CLAMAV_PORT (default 3310), CLAMAV_TIMEOUT_MS (default 30000).
    • Commit: 01/av-layer2: add ClamAVScanAdapter
  3. BullMQ-Job scan.file definieren

    • Files: apps/worker/src/jobs/scanFile.ts (neu — Pfad ggf. anders je nach Worker-Struktur)
    • Aktion:
      • Job-Payload: { mediaId: string, tenantId: string, s3Key: string, context: ScanContext }
      • Job-Handler: lädt File aus S3 (Stream), ruft ClamAVScanAdapter.scan(...), persistiert Result in DB (media.scanStatus, media.scanResult), bei Hit → Quarantäne-Move.
      • Retry-Strategy: 3 retries mit exponential backoff. Bei status: 'skipped' (ClamAV-Down) → kein retry, Job-Status completed-with-warning.
      • Concurrency-Limit pro Worker: 4 (CPU-intensiv).
    • Commit: 01/av-layer2: add scan.file bullmq job
  4. Job-Enqueue in Upload-Pfaden

    • Files: alle Upload-Handler die in Task #16 schon angefasst wurden
    • Aktion: nach erfolgreichem S3-Put + nach Layer-1-Clean → BullMQ-Enqueue scan.file-Job.
    • User-Experience: Upload-Response ist sofort 200 OK mit scanStatus: 'pending'. UI zeigt einen "Wird geprüft"-Badge bis Scan abgeschlossen.
    • Commit: 01/av-layer2: enqueue scan jobs after upload
  5. Quarantäne-Mechanismus

    • Files: packages/storage/src/quarantine.ts (neu), DB-Migration für media.quarantined und media.scanResult (wenn nicht schon da)
    • Aktion:
      • quarantineFile(s3Key): kopiert das Object in quarantine/<originalKey>, löscht das Original (S3 hat keinen atomic move).
      • DB-Update: quarantined: true, quarantinedAt: now, scanResult: <signature>.
      • Public-URLs für quarantäniertes File → 404.
    • Commit: 01/av-layer2: add quarantine mechanism
  6. User-Notification bei Hit

    • Files: apps/web/app/services/notifications/... (Pfad recherchieren), Email-Template
    • Aktion: bei Quarantäne → Email an Uploader: "Eine Datei die du hochgeladen hast wurde als potentiell schädlich erkannt und wurde entfernt. Wenn du glaubst das ist ein Fehler, kontaktiere Support."
    • Optional: Admin-Notification an Tenant-Admin (Env-Toggle).
    • Commit: 01/av-layer2: notify users on quarantine
  7. AuditEvent pro Scan-Ergebnis

    • Files: existierender AuditEvent-Pfad
    • Aktion: bei jedem Scan-Outcome (clean/rejected/skipped) einen AuditEvent. Bei rejected: severity warning, includes Signature-Name. Bei skipped: severity info, includes Reason (z.B. "clamav-unreachable").
    • Commit: 01/av-layer2: audit-log scan results
  8. Admin-Dashboard-View für quarantänierte Files (optional, kann auch in Phase 10 landen)

    • Files: apps/web/app/routes/admin/quarantine.tsx (neu, optional)
    • Aktion: Liste aller quarantänierten Files mit Restore-/Delete-Aktionen für Admins.
    • Wenn out-of-scope für Phase 01: in Backlog (docs/improvement-plan/11-backlog/admin-quarantine-view.md) ablegen.
    • Commit (falls inkludiert): 01/av-layer2: admin quarantine view
  9. Doku-Erweiterung

    • Files: docs/storage/av-scanning.md (aus Task #16 erweitern)
    • Aktion: Layer-2-Beschreibung, Container-Setup, Operator-Anleitung (z.B. wie freshclam-Update läuft), Skip-Rate-Monitoring, Quarantäne-Workflow.
    • Commit: 01/av-layer2: extend av-scanning documentation

Test Requirements

  • Unit-Tests: clamAVScanAdapter.test.ts:
    • Mock-clamd-Server (ggf. clamav-test-Library oder hand-roll): clean-Response → status: 'clean'
    • Mock-clamd-Server: hit-Response → status: 'rejected', reason enthält Signature
    • Mock-clamd-Server: timeout → status: 'skipped'
    • Health-Check returnt false → adapter skipped ohne Scan-Versuch
  • Integration-Tests:
    • Echter ClamAV-Container im CI (docker-compose-up im CI-Workflow), EICAR-Testvirus-File hochladen → quarantäniert
    • Legitimes PDF → clean
    • ClamAV-Container down (docker stop clamav) → Upload geht durch mit scanStatus: 'pending', Job retry-loop bricht ab, Status wird skipped
  • E2E-Tests (Playwright):
    • User lädt EICAR-Testvirus hoch → Upload-Response 200 + "wird geprüft"-Badge → nach ~5s in DB als quarantäniert, User sieht Notification
  • Coverage-Target:
    • clamAVScanAdapter.ts: ≥ 90%
    • quarantine.ts: 100%
    • scanFile.ts job: ≥ 85%
  • Test-Files:
    • packages/storage/src/scan/clamAVScanAdapter.test.ts
    • apps/worker/src/jobs/scanFile.test.ts
    • bestehende Upload-Tests um End-to-End-Scan-Pfad erweitern

NICHT als completed markieren bevor EICAR-Testvirus auf Staging korrekt quarantäniert wurde UND ClamAV-Down-Szenario auf Staging verifiziert ist.

Acceptance Criteria

  • clamav-Service in docker-compose.yml mit Health-Check
  • ClamAVScanAdapter implementiert + getestet
  • scan.file BullMQ-Job läuft im Worker-Pod
  • Alle Upload-Pfade enqueuen Scan-Job nach erfolgreichem Upload
  • Quarantäne-Mechanismus moved Files in quarantine/-Prefix
  • User wird per Email benachrichtigt bei Quarantäne
  • AuditEvent pro Scan-Outcome geschrieben
  • ClamAV-Down → Upload geht durch (kein Block), Skip-Rate getrackt
  • EICAR-Testvirus wird auf Staging korrekt quarantäniert
  • docs/storage/av-scanning.md erweitert
  • pnpm lint, pnpm typecheck, pnpm test grün
  • Detail-MD Progress-Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

9 atomic commits → einzeln revert-bar.

Bei False-Positives in Production (legitime Files werden quarantäniert):

  • Sofort-Fix Admin-UI: über Admin-Quarantine-View File restoren.
  • Notfall-Bypass: Env STORAGE_SCAN_LAYER2_ENABLED=false deaktiviert Job-Enqueue komplett. Nur Notfall.

Bei ClamAV-Container-Issues:

  • Container neu starten via Coolify.
  • Wenn freshclam-DB korrupt → Volume neu mounten + freshclam manuell triggern.

DB-Rollback: Migration für quarantined/scanResult/scanStatus-Spalten muss Down-Migration haben.

Security Notes

  • EICAR-Testvirus ist der Standard-Testfile (https://www.eicar.org/download-anti-malware-testfile/). Harmlos, wird von allen AV-Engines erkannt. Bekommt einen festen Testpfad in packages/storage/test/fixtures/eicar.txt.
  • ClamAV-Signaturen veralten täglich. Container muss freshclam regelmäßig laufen lassen — Standard im offiziellen Image. Operator muss aber Health-Check fürs Aktualitäts-Datum der Signatures aufsetzen (separater Operations-Task — in BLOCKERS.md falls noch nicht da).
  • Quarantäne-Bucket darf NIEMALS public-readable sein. S3-ACL strict private. Auch nicht für Admins via Public-URL — nur via authentifizierter Admin-UI mit signierter URL.
  • DoS-Schutz: Wenn Angreifer 10000 Files hochlädt, sind alle in der ClamAV-Queue → Worker-Saturation. Rate-Limit auf Upload-Endpoint + Per-Tenant-Job-Quota im Worker.
  • Fail-Open bei ClamAV-Down: bewusste Entscheidung (Verfügbarkeit > Vollständigkeit), aber muss explizit in Audit-Log getrackt werden, damit Operator den Backlog post-incident scannen kann.
  • Privacy: ClamAV scannt den File-Content lokal. Keine Datei verlässt den Server. Wichtig zu dokumentieren für DSGVO-Compliance.

Subagent Recommendations

  • Planning: ein Plan-Subagent für die Worker-Job + Container-Integration (kein triviales Setup).
  • Research: general-purpose für: "Recherchiere clamscan-npm-Library, ClamAV-Docker-Image-Operator-Best-Practices, EICAR-Integration-Test-Patterns. Liefere konkrete Code-Snippets."
  • Implementation:
    • general-purpose für Steps 1+2 (Container + Adapter)
    • general-purpose für Steps 3+4 (Job + Enqueue)
    • general-purpose für Steps 5-7 (Quarantäne + Notification + Audit)
    • Step 8 optional, kann auch von einem weiteren Subagent gemacht werden oder in Backlog
  • Tests: general-purpose für Test-Suite inkl. CI-Container-Setup
  • Verification: general-purpose für Acceptance-Criteria + Staging-EICAR-Test
  • Code-Review: gsd-code-reviewer nach Phase-Abschluss, explizit Container-Security + Quarantäne-Pfad

Staging-Deployment-Steps

  1. Branch agent/01-av-layer2 pushen.
  2. Vor Code-Deploy: ClamAV-Container auf Staging-Hetzner-Server via Coolify hochziehen.
    • Docker-Compose-Service hinzufügen (siehe Step 1)
    • Erste Initialisierung dauert ~10 Min (freshclam-Download von Signaturen, ~250MB)
    • Health-Check sicherstellen
  3. Coolify-Auto-Deploy des Boilerplate-Codes.
  4. Smoke-Tests:
    • EICAR-Testvirus hochladen über Profile-Avatar → Upload 200 + nach ~5s als quarantäniert markiert
    • Legitimes PNG hochladen → nach ~5s scanStatus: 'clean'
    • ClamAV-Container kurz stoppen (docker stop clamav-staging), neuen Upload → geht durch mit pending, dann skipped. Container wieder starten.
  5. Audit-Log + Worker-Logs auf Staging prüfen.
  6. Performance: Worker-CPU-Auslastung beobachten bei Upload-Burst.
  7. Docker-Compose-Snippet für Production-Hetzner-Server in docs/deployment.md ergänzen mit Operator-Notes (Volume-Backup, freshclam-Monitoring).

Deviations from Plan

(leer)

Progress Log

  • 2026-05-17 04:47 — staging-verify — docker ps | grep -i clamav → not running (expected — Coolify-stack still pending operator). DB-side: \d "FileObject" zeigt KEINE scan-Spalten (kein avScanStatus, scanStatus, scanResult, quarantined, quarantinedAt) → die in Implementation Step 5 vorgesehene Prisma-Migration ist auf staging nicht eingespielt. Status passt zu "core code-complete; DB columns + notify + EICAR staging pending". Keine Aktion ohne ClamAV-Container.
  • 2026-05-18 00:48 UTC — staging-deploy — minimal infra built on-host at /opt/clamav/docker-compose.yml (no committed infra/clamav/ dir in the repo yet): clamav/clamav:1.0, named volume boilerplate-clamav-sigdb, attached to the coolify network, no published host ports, milter disabled, clamdcheck.sh healthcheck with 600s start_period. Brought up with docker compose up -d. Freshclam pulled main.cvd v63 (3.29M sigs), daily.cld v28003 (355k sigs), bytecode.cvd v339 (80 sigs); container healthy after ~6 min; SelfCheck: Database status OK. Smoke green: wget https://secure.eicar.org/eicar.com.txt -O /tmp/eicar.com && clamdscan /tmp/eicar.com → Eicar-Test-Signature FOUND (Infected files: 1, 8ms). Container resolvable from the boilerplate network as boilerplate-clamav:3310. Operator step still pending: flip web/api/worker CLAMAV_HOST=boilerplate-clamav, CLAMAV_PORT=3310, AV_LAYER_2_ENABLED=true via Coolify env-update (Coolify-controller URL not yet known to this agent), plus the deferred Prisma migration that adds the FileObject.scanStatus / quarantinedAt columns.