Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/storage/src/scan/clamav-scanner.ts
T

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";
}