scan.ts · Source

scan.tsapps/worker/src/processors/files/steps/scan.tsraw ← steps3,391 B← Back to the app
1/**
2 * apps/worker — files pipeline: virus scan step (TASK-0102 §3).
3 *
4 * Scans the LOCAL TEMP COPY (the original object is never executed or parsed
5 * by anything but the metadata parsers):
6 *
7 *   - `CLAMD_SOCKET` set  → clamd LOCAL protocol `zCONTSCAN` over the unix
8 *     socket (what `clamdscan` does — verified by strace).
9 *   - `CLAMAV_HOST` set   → clamd REMOTE protocol `zINSTREAM` over TCP.
10 *   - neither set         → dev mode: WARN + skip,
11 *     `scanReport { engine: "none", skipped: true, reason }`.
12 *
13 * INFECTED is reported via the returned ScanReport (the finalize step
14 * transitions the row VIRUS_DETECTED, emits `file.virus_detected`, notifies
15 * admins — NO thumbnails, NO search index, NO `file.uploaded`).
16 *
17 * Production fail-closed: `assertScannerConfigured` is called at worker boot
18 * (index.ts) — `NODE_ENV=production` with no scanner refuses to start.
19 */
20import { readFile } from "node:fs/promises";
21import {
22  getClamdVersion,
23  scanFileViaSocket,
24  scanStreamViaTcp,
25  type ScanReport
26} from "../../../lib/clamav.js";
27import { RetryableError } from "../errors.js";
28import type { FilePipelineContext } from "../types.js";
29import type { WorkerEnv } from "../../../config.js";
30import { getLogger } from "../../../logger.js";
31 
32const log = getLogger("files.scan");
33 
34/** Worker boot gate (TASK-0102 §3): production requires a scanner. */
35export function assertScannerConfigured(env: WorkerEnv): void {
36  if (env.NODE_ENV === "production" && !env.CLAMD_SOCKET && !env.CLAMAV_HOST) {
37    throw new Error(
38      "worker refusing to boot: NODE_ENV=production requires a ClamAV scanner " +
39        "(set CLAMD_SOCKET or CLAMAV_HOST/CLAMAV_PORT) — fail closed (TASK-0102 §3)"
40    );
41  }
42}
43 
44export interface ScanOutcome {
45  report: ScanReport;
46  infected: boolean;
47}
48 
49/** Run the scan step. Throws RetryableError on clamd transport failure. */
50export async function scanStep(ctx: FilePipelineContext): Promise<ScanOutcome> {
51  const { env } = ctx;
52 
53  if (!env.CLAMD_SOCKET && !env.CLAMAV_HOST) {
54    log.warn("file scan skipped (CLAMD_SOCKET not configured)");
55    return {
56      report: {
57        engine: "none",
58        scanned: false,
59        infected: false,
60        skipped: true,
61        reason: "CLAMD_SOCKET not configured (dev mode)"
62      },
63      infected: false
64    };
65  }
66 
67  let report: ScanReport;
68  if (env.CLAMD_SOCKET) {
69    report = await scanFileViaSocket(env.CLAMD_SOCKET, ctx.temp.path, env.CLAMAV_TIMEOUT_MS);
70  } else {
71    const buffer = await readFile(ctx.temp.path);
72    report = await scanStreamViaTcp(env.CLAMAV_HOST, env.CLAMAV_PORT, buffer, env.CLAMAV_TIMEOUT_MS);
73  }
74 
75  if (report.error) {
76    // clamd transport failure / timeout → RETRYABLE (backoff, 3 attempts).
77    throw new RetryableError(`clamav scan failed: ${report.error}`);
78  }
79 
80  // Best effort: attach the engine version to the report (spec: scanReport
81  // carries { engine, version, infected, signature }).
82  if (report.scanned) {
83    report.version = await getClamdVersion({
84      socket: env.CLAMD_SOCKET,
85      host: env.CLAMAV_HOST,
86      port: env.CLAMAV_PORT
87    });
88  }
89 
90  if (report.scanned && report.infected) {
91    log.error(
92      { fileId: ctx.job.fileId, signature: report.signature },
93      "VIRUS DETECTED — quarantining file (no thumbs/index/event)"
94    );
95  }
96  return { report, infected: report.scanned && report.infected };
97}
98