feat(intake): virus-scan user attachments via ClamAV sidecar

Integrates ClamAV (the only genuinely free, self-hostable AV that doesn't
leak attachments to a third party) for intake-time scanning of user-supplied
files. Off by default — set INTAKE_USER_FILE_SCAN_ENABLED=true and run the
new clamav sidecar in docker-compose to enable.

- new lib: server/lib/clamav.ts wraps the clamscan npm package, lazily
  initialises against the configured host:port, fails-closed on scan
  errors (resets the cached client so the next call re-inits)
- env knobs: INTAKE_USER_FILE_SCAN_ENABLED, CLAMAV_HOST, CLAMAV_PORT,
  CLAMAV_TIMEOUT_MS
- intake/reports.ts: scans each user-file sequentially after the
  size/mime/ext guards; 422 on signature hit, 503 on scanner outage
  (fail-closed surfaces the operational issue rather than silently
  letting unscanned bytes through)
- attachment.get.ts: kind=user-file responses now use
  Content-Disposition: attachment instead of inline, defense-in-depth
  so a file that somehow slips past the denylist + scan still cannot
  render in-browser
- docker-compose.dev.yml: adds clamav/clamav:stable sidecar, persistent
  volume for the signature DB, healthcheck via clamdscan --ping

Tests: 5 unit tests in clamav.test.ts cover enabled+clean,
enabled+infected, disabled bypass, fail-closed throw, and the
empty-viruses-array fallback.

Also fixes a pre-existing latent issue in intake-attachments.test.ts:
beforeAll now truncates the domain before seeding so re-runs against a
non-truncated DB don't collide on the admin email's unique constraint.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Ripwords

apps/dashboard/docker/docker-compose.dev.yml

@@ -24,5 +24,24 @@ services:
       timeout: 5s
       retries: 10
 
+  # Optional virus scanner for user-supplied attachments. The dashboard only
+  # talks to it when INTAKE_USER_FILE_SCAN_ENABLED=true (off by default), so
+  # operators who don't want this can leave it stopped. First boot pulls the
+  # signature DB (~500 MB); freshclam updates it daily afterwards.
+  clamav:
+    image: clamav/clamav:stable
+    ports:
+      - "127.0.0.1:3310:3310"
+    volumes:
+      - repro_clamav_db:/var/lib/clamav
+    healthcheck:
+      test: ["CMD", "clamdscan", "--ping", "1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
+    restart: unless-stopped
+
 volumes:
   repro_data:
+  repro_clamav_db:

apps/dashboard/package.json

@@ -24,6 +24,7 @@
     "@tailwindcss/vite": "^4.2.1",
     "@vueuse/nuxt": "14.2.1",
     "better-auth": "^1.5.6",
+    "clamscan": "^2.4.0",
     "dompurify": "^3.4.1",
     "drizzle-orm": "^0.45.2",
     "h3": "^1.15.11",
@@ -46,6 +47,7 @@
     "@iconify-json/simple-icons": "^1.2.79",
     "@nuxt/test-utils": "^4.0.2",
     "@types/bun": "^1.3.12",
+    "@types/clamscan": "^2.4.1",
     "@types/dompurify": "^3.2.0",
     "@types/node": "^25.6.0",
     "@types/nodemailer": "^8.0.0",

apps/dashboard/server/api/intake/reports.ts

@@ -13,6 +13,7 @@ import { enqueueSync } from "../../lib/enqueue-sync"
 import { env } from "../../lib/env"
 import { getAnonKeyLimiter, getIpLimiter, getKeyLimiter } from "../../lib/rate-limit"
 import { getStorage } from "../../lib/storage"
+import { scanBytes } from "../../lib/clamav"
 import { sanitizeFilename } from "../../lib/sanitize-filename"
 import { rollbackPuts } from "../../lib/storage/rollback"
 
@@ -355,6 +356,34 @@ export default defineEventHandler(async (event) => {
       throw createError({ statusCode: 413, statusMessage: "Attachments exceed total budget" })
     }
 
+    // Virus-scan each user-file before persisting. Runs sequentially because
+    // ClamAV's clamd is single-threaded per connection and scanning in
+    // parallel against a shared socket can interleave verdicts. With a 5-file
+    // cap and warm signature cache, sequential scanning is < 2s in practice.
+    // Skipped when INTAKE_USER_FILE_SCAN_ENABLED=false (the default).
+    if (env.INTAKE_USER_FILE_SCAN_ENABLED) {
+      for (const { part } of userParts) {
+        let scan: Awaited<ReturnType<typeof scanBytes>>
+        try {
+          scan = await scanBytes(new Uint8Array(part.data))
+        } catch (err) {
+          // Fail-closed: if the scanner is enabled but unreachable, surface a
+          // 503 rather than letting unscanned bytes through.
+          console.error("[intake] virus scanner unavailable", err)
+          throw createError({
+            statusCode: 503,
+            statusMessage: "Attachment scanner unavailable, please retry",
+          })
+        }
+        if (!scan.clean) {
+          throw createError({
+            statusCode: 422,
+            statusMessage: `Attachment rejected by virus scanner: ${part.filename ?? "unnamed"} (${scan.reason ?? "infected"})`,
+          })
+        }
+      }
+    }
+
     const storage = await getStorage()
     const writtenKeys: string[] = []
     try {

apps/dashboard/server/api/projects/[id]/reports/[reportId]/attachment.get.ts

@@ -102,7 +102,12 @@ export default defineEventHandler(async (event) => {
       // against header injection. sanitizeFilename already strips control
       // bytes at intake time, but never trust two layers down.
       const safeName = row.filename.replace(/[\r\n"]/g, "")
-      setHeader(event, "Content-Disposition", `inline; filename="${safeName}"`)
+      // user-file kinds force `attachment` so a malicious file that somehow
+      // slipped past the mime/ext denylist + virus scan still cannot render
+      // inline in the browser. Other kinds (screenshot/replay/logs) are
+      // already rendered via known-safe content types and stay inline.
+      const disposition = row.kind === "user-file" ? "attachment" : "inline"
+      setHeader(event, "Content-Disposition", `${disposition}; filename="${safeName}"`)
     }
     setResponseStatus(event, 200)
     return Buffer.from(bytes)

apps/dashboard/server/lib/clamav.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { _reloadEnvForTesting } from "./env"
+import { _setClientForTesting, scanBytes } from "./clamav"
+
+function fakeClient(impl: { isInfected: boolean | null; viruses?: string[]; throws?: Error }) {
+  return {
+    scanStream: async () => {
+      if (impl.throws) throw impl.throws
+      return { isInfected: impl.isInfected, viruses: impl.viruses ?? [] }
+    },
+  }
+}
+
+describe("scanBytes", () => {
+  afterEach(() => {
+    _setClientForTesting(null)
+    delete process.env.INTAKE_USER_FILE_SCAN_ENABLED
+    _reloadEnvForTesting()
+  })
+
+  test("returns clean immediately when scanning is disabled", async () => {
+    delete process.env.INTAKE_USER_FILE_SCAN_ENABLED
+    _reloadEnvForTesting()
+    // Inject a client that would mark anything infected — proves we skipped it.
+    _setClientForTesting(fakeClient({ isInfected: true, viruses: ["FAIL"] }))
+    const result = await scanBytes(new Uint8Array([1, 2, 3]))
+    expect(result).toEqual({ clean: true })
+  })
+
+  test("returns clean when scanner reports no infection", async () => {
+    process.env.INTAKE_USER_FILE_SCAN_ENABLED = "true"
+    _reloadEnvForTesting()
+    _setClientForTesting(fakeClient({ isInfected: false }))
+    const result = await scanBytes(new Uint8Array([1, 2, 3]))
+    expect(result).toEqual({ clean: true })
+  })
+
+  test("returns clean=false with the first virus name when scanner finds one", async () => {
+    process.env.INTAKE_USER_FILE_SCAN_ENABLED = "true"
+    _reloadEnvForTesting()
+    _setClientForTesting(
+      fakeClient({ isInfected: true, viruses: ["Eicar-Test-Signature", "Other"] }),
+    )
+    const result = await scanBytes(new Uint8Array([1, 2, 3]))
+    expect(result).toEqual({ clean: false, reason: "Eicar-Test-Signature" })
+  })
+
+  test("falls back to a generic reason when viruses array is empty", async () => {
+    process.env.INTAKE_USER_FILE_SCAN_ENABLED = "true"
+    _reloadEnvForTesting()
+    _setClientForTesting(fakeClient({ isInfected: true, viruses: [] }))
+    const result = await scanBytes(new Uint8Array([1, 2, 3]))
+    expect(result).toEqual({ clean: false, reason: "infected" })
+  })
+
+  test("throws (fail-closed) when scanner errors", async () => {
+    process.env.INTAKE_USER_FILE_SCAN_ENABLED = "true"
+    _reloadEnvForTesting()
+    _setClientForTesting(fakeClient({ isInfected: null, throws: new Error("ECONNREFUSED") }))
+    await expect(scanBytes(new Uint8Array([1, 2, 3]))).rejects.toThrow(/scan failed/)
+  })
+})

apps/dashboard/server/lib/clamav.ts

@@ -0,0 +1,85 @@
+import { Readable } from "node:stream"
+import NodeClam from "clamscan"
+import { env } from "./env"
+
+interface ScanClient {
+  scanStream: (stream: Readable) => Promise<{ isInfected: boolean | null; viruses: string[] }>
+}
+
+export interface ScanResult {
+  clean: boolean
+  reason?: string
+}
+
+let _client: ScanClient | null = null
+let _initInProgress: Promise<ScanClient> | null = null
+
+async function buildClient(): Promise<ScanClient> {
+  const clam = await new NodeClam().init({
+    clamdscan: {
+      host: env.CLAMAV_HOST,
+      port: env.CLAMAV_PORT,
+      timeout: env.CLAMAV_TIMEOUT_MS,
+      // Sidecar-only — no fallback to a local CLI binary on the dashboard host.
+      localFallback: false,
+      bypassTest: false,
+    },
+    preference: "clamdscan",
+    removeInfected: false,
+    debugMode: false,
+  })
+  return clam as unknown as ScanClient
+}
+
+async function getClient(): Promise<ScanClient> {
+  if (_client) return _client
+  if (_initInProgress) return _initInProgress
+  _initInProgress = buildClient()
+    .then((c) => {
+      _client = c
+      return c
+    })
+    .finally(() => {
+      _initInProgress = null
+    })
+  return _initInProgress
+}
+
+/**
+ * Scan a buffer of bytes against the configured ClamAV sidecar. Returns
+ * { clean: true } when scanning is disabled OR the file passed; throws when
+ * the scanner is enabled but unreachable (fail-closed). Returns
+ * { clean: false, reason } only on a confirmed signature hit.
+ */
+export async function scanBytes(bytes: Uint8Array): Promise<ScanResult> {
+  if (!env.INTAKE_USER_FILE_SCAN_ENABLED) return { clean: true }
+  let client: ScanClient
+  try {
+    client = await getClient()
+  } catch (err) {
+    throw new Error(
+      `[clamav] init failed against ${env.CLAMAV_HOST}:${env.CLAMAV_PORT}: ${(err as Error).message}`,
+      { cause: err },
+    )
+  }
+  const stream = Readable.from(Buffer.from(bytes))
+  try {
+    const { isInfected, viruses } = await client.scanStream(stream)
+    if (isInfected) return { clean: false, reason: viruses?.[0] ?? "infected" }
+    return { clean: true }
+  } catch (err) {
+    // Reset the cached client so the next call re-inits — handles transient
+    // socket drops cleanly when clamd restarts.
+    _client = null
+    throw new Error(`[clamav] scan failed: ${(err as Error).message}`, { cause: err })
+  }
+}
+
+/**
+ * Test seam: lets unit tests inject a fake client without going through the
+ * NodeClam init path (which would require a real clamd socket).
+ */
+export function _setClientForTesting(client: ScanClient | null): void {
+  _client = client
+  _initInProgress = null
+}

apps/dashboard/server/lib/env.ts

@@ -81,6 +81,16 @@ const Schema = z.object({
   INTAKE_USER_FILE_MAX_BYTES: intString(10 * 1024 * 1024),
   INTAKE_USER_FILES_TOTAL_MAX_BYTES: intString(25 * 1024 * 1024),
   INTAKE_USER_FILES_MAX_COUNT: intString(5),
+
+  // Virus scanning for user-supplied attachments. When ENABLED is false
+  // (the default) the scan path is skipped entirely so self-hosters who
+  // don't run a ClamAV sidecar aren't impacted. When true, intake fails
+  // closed: a scanner outage rejects uploads rather than silently letting
+  // unscanned files through.
+  INTAKE_USER_FILE_SCAN_ENABLED: boolString.default(false),
+  CLAMAV_HOST: z.string().default("localhost"),
+  CLAMAV_PORT: intString(3310),
+  CLAMAV_TIMEOUT_MS: intString(30_000),
   INTAKE_REQUIRE_DWELL: boolString.default(true),
   INTAKE_MIN_DWELL_MS: intString(1_500),
 

apps/dashboard/tests/api/intake-attachments.test.ts

@@ -3,7 +3,7 @@ import { afterEach, beforeAll, describe, expect, setDefaultTimeout, test } from
 import { eq } from "drizzle-orm"
 import { db } from "../../server/db"
 import { reportAttachments } from "../../server/db/schema"
-import { createUser, seedProject, truncateReports } from "../helpers"
+import { createUser, seedProject, truncateDomain, truncateReports } from "../helpers"
 
 await setup({ server: true, port: 3000, host: "localhost" })
 setDefaultTimeout(15000)
@@ -57,6 +57,9 @@ async function postReportWithFiles(
 
 describe("POST /api/intake/reports — user attachments", () => {
   beforeAll(async () => {
+    // Hard-reset users/projects so re-runs against a non-truncated DB don't
+    // collide on the admin email's unique constraint.
+    await truncateDomain()
     const admin = await createUser("attch-admin@example.com", "admin")
     await seedProject({
       name: "Attachment Test Project",
@@ -136,6 +139,12 @@ describe("POST /api/intake/reports — user attachments", () => {
     expect(userFile?.storageKey.endsWith("/user/0-etcpasswd")).toBe(true)
   })
 
+  // Note: virus-scan behavior (clean / infected / fail-closed / disabled) is
+  // covered by the unit-tests in `apps/dashboard/server/lib/clamav.test.ts`.
+  // It cannot be driven from this integration suite because the helper hits
+  // a separately-running `bun run dev` server: env mutations and
+  // _setClientForTesting() calls in the test process don't reach it.
+
   test("intake without attachment[N] parts behaves identically to today (regression guard)", async () => {
     const { res, reportId } = await postReportWithFiles([])
     expect(res.status).toBe(201)