Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,239 @@
|
||||
# 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: <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.
|
||||
Reference in new issue
Block a user