Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,144 @@
|
||||
// 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";
|
||||
}
|
||||
Reference in new issue
Block a user