145 lines
5.2 KiB
TypeScript
145 lines
5.2 KiB
TypeScript
// ClamAV-backed implementation of the StorageScanner contract from
|
|
// ./index.ts. Talks to a clamd daemon via the TCP clamscan protocol
|
|
// (default port 3310). Used by the worker runtime's scan-file job handler.
|
|
|
|
/// <reference path="./clamscan.d.ts" />
|
|
|
|
import type { StorageScanner, StorageScannerInput, StorageScannerResult } from "./index.js";
|
|
|
|
export interface ClamAVScannerConfig {
|
|
host: string;
|
|
port: number;
|
|
/**
|
|
* Connect / scan timeout in ms. clamd can take several seconds on the very
|
|
* first request after boot while it warms up; 30 s is the operational
|
|
* default.
|
|
*/
|
|
timeoutMs: number;
|
|
/**
|
|
* Loader for the upload payload. Returning a Buffer or Readable is fine;
|
|
* clamscan accepts both via scanStream/scanBuffer. The scanner doesn't read
|
|
* the object itself so callers (typically the worker job handler) can plug
|
|
* in any storage backend.
|
|
*/
|
|
loadObject: (input: StorageScannerInput) => Promise<Buffer | NodeJS.ReadableStream>;
|
|
/**
|
|
* Override for the clamscan client constructor. Used by tests; production
|
|
* leaves it unset so the real npm package is loaded lazily.
|
|
*/
|
|
initClient?: (options: { host: string; port: number; timeoutMs: number }) => Promise<ClamScanClient>;
|
|
/**
|
|
* Override for the wall clock. Tests inject a stub to make scannedAt
|
|
* deterministic.
|
|
*/
|
|
now?: () => Date;
|
|
}
|
|
|
|
export interface ClamScanResult {
|
|
isInfected: boolean | null;
|
|
viruses?: readonly string[];
|
|
}
|
|
|
|
export interface ClamScanClient {
|
|
/** Returns true when clamd answers a PING within the configured timeout. */
|
|
isReachable(): Promise<boolean>;
|
|
/** Scan a single in-memory buffer. Throws on transport errors. */
|
|
scanBuffer(buffer: Buffer): Promise<ClamScanResult>;
|
|
/** Scan a stream end-to-end. */
|
|
scanStream(stream: NodeJS.ReadableStream): Promise<ClamScanResult>;
|
|
}
|
|
|
|
const ENGINE = "clamav";
|
|
|
|
export function createClamAVStorageScanner(config: ClamAVScannerConfig): StorageScanner {
|
|
const initClient = config.initClient ?? defaultInitClient;
|
|
let cachedClient: ClamScanClient | undefined;
|
|
|
|
async function getClient(): Promise<ClamScanClient> {
|
|
if (!cachedClient) {
|
|
cachedClient = await initClient({ host: config.host, port: config.port, timeoutMs: config.timeoutMs });
|
|
}
|
|
return cachedClient;
|
|
}
|
|
|
|
return {
|
|
async scanObject(target: StorageScannerInput): Promise<StorageScannerResult> {
|
|
const client = await getClient();
|
|
const reachable = await client.isReachable().catch(() => false);
|
|
if (!reachable) {
|
|
throw new ClamAVUnreachableError(`clamd at ${config.host}:${config.port} is unreachable`);
|
|
}
|
|
|
|
const payload = await config.loadObject(target);
|
|
const result = await scanWithClient(client, payload);
|
|
|
|
if (result.isInfected) {
|
|
const signature = result.viruses?.[0] ?? "unknown";
|
|
return { verdict: "infected", signature, engine: ENGINE };
|
|
}
|
|
return { verdict: "clean", engine: ENGINE };
|
|
},
|
|
};
|
|
}
|
|
|
|
async function scanWithClient(client: ClamScanClient, payload: Buffer | NodeJS.ReadableStream): Promise<ClamScanResult> {
|
|
if (Buffer.isBuffer(payload)) {
|
|
return client.scanBuffer(payload);
|
|
}
|
|
return client.scanStream(payload);
|
|
}
|
|
|
|
async function defaultInitClient({ host, port, timeoutMs }: { host: string; port: number; timeoutMs: number }): Promise<ClamScanClient> {
|
|
// Lazy import so non-worker bundles (the web app, the API) don't try to
|
|
// resolve the native clamscan dependency. The clamscan package exports a
|
|
// factory whose init() returns the client. See clamscan.d.ts in this
|
|
// directory for the (intentionally narrow) module ambient typing.
|
|
const mod = await import("clamscan");
|
|
const Factory = (mod as { default?: unknown }).default ?? mod;
|
|
const factory = typeof Factory === "function" ? new (Factory as new () => { init: (opts: unknown) => Promise<unknown> })() : (Factory as { init: (opts: unknown) => Promise<unknown> });
|
|
const client = (await factory.init({
|
|
removeInfected: false,
|
|
debugMode: false,
|
|
clamdscan: {
|
|
host,
|
|
port,
|
|
timeout: timeoutMs,
|
|
localFallback: false,
|
|
},
|
|
preference: "clamdscan",
|
|
})) as ClamScanLib;
|
|
|
|
return {
|
|
async isReachable() {
|
|
const status = await client.ping();
|
|
return Boolean(status);
|
|
},
|
|
async scanBuffer(buffer) {
|
|
const res = await client.scanBuffer(buffer);
|
|
return { isInfected: res.isInfected, viruses: res.viruses };
|
|
},
|
|
async scanStream(stream) {
|
|
const res = await client.scanStream(stream);
|
|
return { isInfected: res.isInfected, viruses: res.viruses };
|
|
},
|
|
};
|
|
}
|
|
|
|
// Subset of the clamscan npm package surface that we actually use. Avoids a
|
|
// dependency on @types/clamscan and lets the lazy import stay loose.
|
|
interface ClamScanLib {
|
|
ping(): Promise<unknown>;
|
|
scanBuffer(buffer: Buffer): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
|
|
scanStream(stream: NodeJS.ReadableStream): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
|
|
}
|
|
|
|
export class ClamAVUnreachableError extends Error {
|
|
constructor(message: string) {
|
|
super(message);
|
|
this.name = "ClamAVUnreachableError";
|
|
}
|
|
}
|
|
|
|
export function isClamAVUnreachableError(error: unknown): error is ClamAVUnreachableError {
|
|
return error instanceof Error && error.name === "ClamAVUnreachableError";
|
|
}
|