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 dieselbeScanAdapter-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:
docker-compose.yml-Serviceclamavmit Imageclamav/clamav:stable, Volume für Signature-DB, Health-Check.ClamAVScanAdapterinpackages/storage/src/scan/— implementiertScanAdapteraus Task #16.- BullMQ-Job
scan.fileder im Worker-Pod läuft, nicht im Web-Pod (CPU-intensiv). - 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. - Quarantäne-Mechanismus bei Hit: S3-Object wird in einen
quarantine/-Prefix verschoben, DB-Row markiert mitquarantined: 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
-
Docker-Compose-Service
clamavhinzufügen- Files:
docker-compose.yml(root), ggf.docker-compose.dev.ymlunddocker-compose.prod.yml - Aktion:
plus Named-Volume
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-stoppedclamav-db. Erster Start dauert lange (Signatur-Download via freshclam). - Commit:
01/av-layer2: add clamav container to docker-compose
- Files:
-
ClamAVScanAdapterimplementieren- 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) → returnstatus: 'skipped', log warning. - Scan: Stream-basiert (kein Buffer im Memory). Bei Hit → return
status: 'rejected'+reason: <signature-name>. - Env:
CLAMAV_HOST(defaultclamav),CLAMAV_PORT(default3310),CLAMAV_TIMEOUT_MS(default30000).
- Commit:
01/av-layer2: add ClamAVScanAdapter
- Files:
-
BullMQ-Job
scan.filedefinieren- 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-Statuscompleted-with-warning. - Concurrency-Limit pro Worker: 4 (CPU-intensiv).
- Job-Payload:
- Commit:
01/av-layer2: add scan.file bullmq job
- Files:
-
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 OKmitscanStatus: 'pending'. UI zeigt einen "Wird geprüft"-Badge bis Scan abgeschlossen. - Commit:
01/av-layer2: enqueue scan jobs after upload
-
Quarantäne-Mechanismus
- Files:
packages/storage/src/quarantine.ts(neu), DB-Migration fürmedia.quarantinedundmedia.scanResult(wenn nicht schon da) - Aktion:
quarantineFile(s3Key): kopiert das Object inquarantine/<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
- Files:
-
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
- Files:
-
AuditEvent pro Scan-Ergebnis
- Files: existierender AuditEvent-Pfad
- Aktion: bei jedem Scan-Outcome (
clean/rejected/skipped) einen AuditEvent. Beirejected: severitywarning, includes Signature-Name. Beiskipped: severityinfo, includes Reason (z.B. "clamav-unreachable"). - Commit:
01/av-layer2: audit-log scan results
-
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
- Files:
-
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
- Files:
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
- Mock-clamd-Server (ggf.
- 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 mitscanStatus: 'pending', Job retry-loop bricht ab, Status wirdskipped
- 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.tsjob: ≥ 85%
- Test-Files:
packages/storage/src/scan/clamAVScanAdapter.test.tsapps/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 indocker-compose.ymlmit Health-CheckClamAVScanAdapterimplementiert + getestetscan.fileBullMQ-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.mderweitertpnpm lint,pnpm typecheck,pnpm testgrü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=falsedeaktiviert 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
freshclamregelmäß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-purposefür: "Recherchiere clamscan-npm-Library, ClamAV-Docker-Image-Operator-Best-Practices, EICAR-Integration-Test-Patterns. Liefere konkrete Code-Snippets." - Implementation:
general-purposefür Steps 1+2 (Container + Adapter)general-purposefür Steps 3+4 (Job + Enqueue)general-purposefür Steps 5-7 (Quarantäne + Notification + Audit)- Step 8 optional, kann auch von einem weiteren Subagent gemacht werden oder in Backlog
- Tests:
general-purposefür Test-Suite inkl. CI-Container-Setup - Verification:
general-purposefür Acceptance-Criteria + Staging-EICAR-Test - Code-Review:
gsd-code-reviewernach Phase-Abschluss, explizit Container-Security + Quarantäne-Pfad
Staging-Deployment-Steps
- Branch
agent/01-av-layer2pushen. - 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
- Coolify-Auto-Deploy des Boilerplate-Codes.
- 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 mitpending, dannskipped. Container wieder starten.
- Audit-Log + Worker-Logs auf Staging prüfen.
- Performance: Worker-CPU-Auslastung beobachten bei Upload-Burst.
- Docker-Compose-Snippet für Production-Hetzner-Server in
docs/deployment.mdergä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 (keinavScanStatus,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 committedinfra/clamav/dir in the repo yet):clamav/clamav:1.0, named volumeboilerplate-clamav-sigdb, attached to thecoolifynetwork, no published host ports, milter disabled,clamdcheck.shhealthcheck with 600s start_period. Brought up withdocker compose up -d. Freshclam pulledmain.cvd v63(3.29M sigs),daily.cld v28003(355k sigs),bytecode.cvd v339(80 sigs); containerhealthyafter ~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 asboilerplate-clamav:3310. Operator step still pending: flip web/api/workerCLAMAV_HOST=boilerplate-clamav,CLAMAV_PORT=3310,AV_LAYER_2_ENABLED=truevia Coolify env-update (Coolify-controller URL not yet known to this agent), plus the deferred Prisma migration that adds theFileObject.scanStatus/quarantinedAtcolumns.