# 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: ```yaml 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: `. - 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/`, löscht das Original (S3 hat keinen atomic move). - DB-Update: `quarantined: true`, `quarantinedAt: now`, `scanResult: `. - 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.