pompelmi 1.17.0 → 1.19.0

package/src/Watcher.js

@@ -7,44 +7,79 @@ const { Verdict } = require('./verdicts.js');
 
 const DEBOUNCE_MS = 300;
 
+function quarantineFile(filePath, quarantineDir, virus) {
+  try {
+    fs.mkdirSync(quarantineDir, { recursive: true });
+    const basename    = path.basename(filePath);
+    const destBase    = path.join(quarantineDir, basename + '.quarantined');
+    const destJson    = destBase + '.json';
+    const sha256      = (() => { try { return require('crypto').createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); } catch { return ''; } })();
+
+    fs.renameSync(filePath, destBase);
+
+    const sidecar = {
+      originalPath: filePath,
+      virus: virus || '',
+      timestamp: new Date().toISOString(),
+      sha256,
+    };
+    fs.writeFileSync(destJson, JSON.stringify(sidecar, null, 2));
+
+    return destBase;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Watch a directory for new/modified files and scan each one automatically.
  * Uses fs.watch (no dependencies) with a 300 ms debounce.
  *
  * @param {string} dirPath
- * @param {object} [options] - Passed to scan() (host, port, socket, timeout, retries, retryDelay)
+ * @param {object} [options] - Passed to scan() (host, port, socket, timeout, retries, retryDelay).
+ *   Also accepts `quarantine` (string path) to enable auto-quarantine of infected files.
  * @param {{ onClean?: Function, onMalicious?: Function, onError?: Function }} [callbacks]
  * @returns {import('fs').FSWatcher}
  */
 function watch(dirPath, options = {}, { onClean, onMalicious, onError } = {}) {
-    const timers = new Map();
+  const { quarantine: quarantineDir, ...scanOptions } = options;
+  const timers = new Map();
+
+  if (quarantineDir) {
+    fs.mkdirSync(quarantineDir, { recursive: true });
+  }
 
-    return fs.watch(dirPath, { recursive: true }, (_eventType, filename) => {
-        if (!filename) return;
+  return fs.watch(dirPath, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
 
-        const fullPath = path.join(dirPath, filename);
+    const fullPath = path.join(dirPath, filename);
 
-        if (timers.has(fullPath)) clearTimeout(timers.get(fullPath));
+    if (timers.has(fullPath)) clearTimeout(timers.get(fullPath));
 
-        timers.set(fullPath, setTimeout(async () => {
-            timers.delete(fullPath);
+    timers.set(fullPath, setTimeout(async () => {
+      timers.delete(fullPath);
 
-            if (!fs.existsSync(fullPath)) return;
+      if (!fs.existsSync(fullPath)) return;
 
-            let stat;
-            try { stat = fs.statSync(fullPath); } catch { return; }
-            if (!stat.isFile()) return;
+      let stat;
+      try { stat = fs.statSync(fullPath); } catch { return; }
+      if (!stat.isFile()) return;
 
-            try {
-                const verdict = await scan(fullPath, options);
-                if (verdict === Verdict.Clean)          onClean     && onClean(fullPath);
-                else if (verdict === Verdict.Malicious) onMalicious && onMalicious(fullPath);
-                else                                    onError     && onError(new Error(`ScanError for ${fullPath}`), fullPath);
-            } catch (err) {
-                onError && onError(err, fullPath);
-            }
-        }, DEBOUNCE_MS));
-    });
+      try {
+        const verdict = await scan(fullPath, scanOptions);
+        if (verdict === Verdict.Clean) {
+          onClean && onClean(fullPath);
+        } else if (verdict === Verdict.Malicious) {
+          if (quarantineDir) quarantineFile(fullPath, quarantineDir, '');
+          onMalicious && onMalicious(fullPath);
+        } else {
+          onError && onError(new Error(`ScanError for ${fullPath}`), fullPath);
+        }
+      } catch (err) {
+        onError && onError(err, fullPath);
+      }
+    }, DEBOUNCE_MS));
+  });
 }
 
-module.exports = { watch };
+module.exports = { watch, quarantineFile };

package/src/index.js

@@ -8,5 +8,9 @@ const { notify }                                      = require('./WebhookNotifi
 const { createScanner }                               = require('./ScanEmitter.js');
 const { generateDashboard }                           = require('./Dashboard.js');
 const { generateShareCard }                           = require('./ShareCard.js');
+const { generateScorecard }                           = require('./Scorecard.js');
+const { createCache }                                 = require('./ScanCache.js');
+const { createPolicy }                                = require('./Policy.js');
+const { createMultiEngine }                           = require('./MultiEngine.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard, generateScorecard, createCache, createPolicy, createMultiEngine };

package/src/index.mjs

@@ -13,7 +13,11 @@ export const {
   createScanner,
   generateDashboard,
   generateShareCard,
+  generateScorecard,
   notify,
   Verdict,
+  createCache,
+  createPolicy,
+  createMultiEngine,
 } = pompelmi;
 export default pompelmi;

package/types/index.d.ts

@@ -73,11 +73,14 @@ export declare function scanStream(stream: Readable, options?: ScanOptions): Pro
 /**
  * Recursively scan every file under dirPath.
  * Per-file errors are caught and collected without aborting the full scan.
+ * Use scanDirectory.stream() for async-iterable progress events.
  */
 export declare function scanDirectory(
   dirPath: string,
   options?: ScanOptions
-): Promise<DirectoryScanResult>;
+): Promise<DirectoryScanResult> & {
+  stream(dirPath: string, options?: ScanOptions): AsyncIterable<DirectoryScanEvent>;
+};
 
 /**
  * Express / Fastify middleware that scans multer-uploaded files
@@ -142,14 +145,22 @@ export interface WatchCallbacks {
   onError?: (err: Error, filePath?: string) => void;
 }
 
+/** Options for watch() — extends ScanOptions with quarantine support */
+export interface WatchOptions extends ScanOptions {
+  /** Path to a quarantine directory. Infected files are moved here automatically. */
+  quarantine?: string;
+}
+
 /**
  * Watch a directory for new/modified files and scan each automatically.
  * Uses fs.watch with a 300 ms debounce. No dependencies.
+ * When `options.quarantine` is set, infected files are moved to that directory
+ * with a `.quarantined` extension and a sidecar JSON file.
  * Returns an FSWatcher; call .close() to stop watching.
  */
 export declare function watch(
   dirPath: string,
-  options?: ScanOptions,
+  options?: WatchOptions,
   callbacks?: WatchCallbacks
 ): FSWatcher;
 
@@ -266,3 +277,244 @@ export declare function generateShareCard(
   scanResults: ScanRow[] | DirectoryScanResult,
   options?: ShareCardOptions
 ): string;
+
+/** Input configuration for generateScorecard */
+export interface ScorecardConfig {
+  /** Whether virus scanning is enabled */
+  scanEnabled?: boolean;
+  /** Array of allowed MIME types (non-empty = pass) */
+  mimeTypeAllowlist?: string[];
+  /** Maximum file size in bytes (positive = pass) */
+  fileSizeLimit?: number;
+  /** Whether files are written to disk before scanning (false = pass) */
+  diskWriteBeforeScan?: boolean;
+  /** What to do on scan error: 'reject' = pass, anything else = fail */
+  scanErrorBehavior?: 'reject' | string;
+  /** What to do when clamd is unavailable: 'reject' = pass, anything else = fail */
+  clamdUnavailableBehavior?: 'reject' | string;
+  /** Whether TLS is enabled on the upload endpoint */
+  tlsEnabled?: boolean;
+}
+
+/** A single check result in a scorecard */
+export interface ScorecardFinding {
+  check: string;
+  status: 'pass' | 'fail';
+  weight: number;
+}
+
+/** Result returned by generateScorecard */
+export interface ScorecardResult {
+  /** Letter grade A–F */
+  grade: 'A' | 'B' | 'C' | 'D' | 'F';
+  /** Numeric score 0–100 */
+  score: number;
+  /** Per-check results */
+  findings: ScorecardFinding[];
+  /** Actionable recommendations for failed checks */
+  recommendations: string[];
+}
+
+/**
+ * Analyse a project's upload security configuration and return a grade A–F.
+ *
+ * @example
+ * const scorecard = await generateScorecard({
+ *   scanEnabled: true,
+ *   mimeTypeAllowlist: ['image/jpeg', 'image/png'],
+ *   fileSizeLimit: 10 * 1024 * 1024,
+ *   diskWriteBeforeScan: false,
+ *   scanErrorBehavior: 'reject',
+ *   clamdUnavailableBehavior: 'reject',
+ *   tlsEnabled: true,
+ * });
+ * console.log(scorecard.grade); // 'A'
+ */
+export declare function generateScorecard(config?: ScorecardConfig): Promise<ScorecardResult>;
+
+// ─── ScanCache ────────────────────────────────────────────────────────────────
+
+/** Options for createCache() */
+export interface CacheOptions {
+  /** Entry TTL in milliseconds (default: 3600000 = 1 hour) */
+  ttl?: number;
+  /** Maximum number of entries before LRU eviction (default: 1000) */
+  maxSize?: number;
+  /** Storage backend: 'memory' or 'file' (default: 'memory') */
+  storage?: 'memory' | 'file';
+  /** Path for file-backed storage (default: './.pompelmi-cache.json') */
+  filePath?: string;
+}
+
+/** Cache hit/miss statistics */
+export interface CacheStats {
+  hits: number;
+  misses: number;
+  size: number;
+  hitRate: number;
+}
+
+/** SHA256-based scan result cache */
+export interface ScanCache {
+  /** Scan a file by path, returning a cached result if available */
+  scan(filePath: string, options?: ScanOptions): Promise<VerdictValue>;
+  /** Scan an in-memory Buffer, returning a cached result if available */
+  scanBuffer(buffer: Buffer, options?: ScanOptions): Promise<VerdictValue>;
+  /** Return cache statistics */
+  stats(): CacheStats;
+  /** Clear all cache entries */
+  clear(): void;
+  /** Remove a specific entry by its SHA256 hash */
+  delete(sha256: string): void;
+}
+
+/**
+ * Create a SHA256-based scan result cache.
+ * Skips rescanning files with known-clean or known-malicious hashes.
+ * Supports LRU eviction and optional file-backed persistence.
+ */
+export declare function createCache(options?: CacheOptions): ScanCache;
+
+// ─── Policy ───────────────────────────────────────────────────────────────────
+
+/** Options for createPolicy() */
+export interface PolicyRules {
+  /** ClamAV connection options for virus scanning */
+  scan?: ScanOptions;
+  /** Maximum allowed file size in bytes */
+  maxSize?: number;
+  /** Allowlist of MIME types (e.g. ['image/jpeg', 'application/pdf']) */
+  allowedMimeTypes?: string[];
+  /** Allowlist of file extensions (e.g. ['.jpg', '.pdf']) */
+  allowedExtensions?: string[];
+  /** Reject encrypted archives (default: false) */
+  rejectEncrypted?: boolean;
+  /** Behaviour when clamd is unavailable: 'reject' | 'allow' | 'throw' (default: 'reject') */
+  onScannerUnavailable?: 'reject' | 'allow' | 'throw';
+}
+
+/** Metadata passed to policy.check() */
+export interface FileMeta {
+  filename?: string | null;
+  mimeType?: string | null;
+  size?: number;
+}
+
+/** Details about the file that was checked */
+export interface PolicyDetails {
+  size: number;
+  mimeType: string | null;
+  extension: string | null;
+  virusName: string | null;
+}
+
+/** Result returned by policy.check() */
+export interface PolicyResult {
+  allowed: boolean;
+  reason:
+    | null
+    | 'file_too_large'
+    | 'mime_not_allowed'
+    | 'extension_not_allowed'
+    | 'encrypted_archive'
+    | 'virus_detected'
+    | 'scanner_unavailable';
+  verdict: VerdictValue;
+  details: PolicyDetails;
+}
+
+/** A compiled scan policy */
+export interface ScanPolicy {
+  /** Apply all policy rules to a buffer */
+  check(buffer: Buffer, meta?: FileMeta): Promise<PolicyResult>;
+  /** Express/Fastify middleware — rejects with HTTP 403 on policy violation */
+  middleware(): RequestHandler;
+  /** NestJS CanActivate guard */
+  nestGuard(): { canActivate(context: unknown): Promise<boolean> };
+}
+
+/**
+ * Create a unified scan policy combining size, MIME, extension, and virus checks.
+ */
+export declare function createPolicy(rules?: PolicyRules): ScanPolicy;
+
+// ─── MultiEngine ─────────────────────────────────────────────────────────────
+
+/** ClamAV engine configuration */
+export interface ClamAVEngineConfig {
+  type: 'clamav';
+  host?: string;
+  port?: number;
+  socket?: string;
+  timeout?: number;
+}
+
+/** VirusTotal engine configuration */
+export interface VirusTotalEngineConfig {
+  type: 'virustotal';
+  apiKey: string;
+  /** Minimum number of engine detections to flag as malicious (default: 1) */
+  threshold?: number;
+}
+
+export type EngineConfig = ClamAVEngineConfig | VirusTotalEngineConfig;
+
+/** Per-engine result */
+export interface EngineResult {
+  name: string;
+  verdict: VerdictValue;
+  detections?: number;
+  virus?: string;
+  error?: string;
+}
+
+/** Result returned by multi-engine scan */
+export interface MultiEngineResult {
+  verdict: VerdictValue;
+  consensus: 'any' | 'all' | 'majority';
+  engines: EngineResult[];
+}
+
+/** Options for createMultiEngine() */
+export interface MultiEngineOptions {
+  engines: EngineConfig[];
+  /** How to combine engine verdicts (default: 'any') */
+  consensus?: 'any' | 'all' | 'majority';
+}
+
+/** Multi-engine scanner */
+export interface MultiEngine {
+  scan(filePath: string): Promise<MultiEngineResult>;
+  scanBuffer(buffer: Buffer): Promise<MultiEngineResult>;
+}
+
+/**
+ * Create a multi-engine scanner combining ClamAV and/or VirusTotal.
+ * The consensus mode controls how engine verdicts are combined.
+ */
+export declare function createMultiEngine(options?: MultiEngineOptions): MultiEngine;
+
+// ─── scanDirectory.stream ─────────────────────────────────────────────────────
+
+/** Progress event emitted by scanDirectory.stream() */
+export interface ScanProgressEvent {
+  type: 'progress';
+  scanned: number;
+  total: number;
+  file: string;
+}
+
+/** Per-file result event emitted by scanDirectory.stream() */
+export interface ScanResultEvent {
+  type: 'result';
+  file: string;
+  verdict: VerdictValue | null;
+}
+
+/** Final summary event emitted by scanDirectory.stream() */
+export interface ScanCompleteEvent {
+  type: 'complete';
+  summary: DirectoryScanResult;
+}
+
+export type DirectoryScanEvent = ScanProgressEvent | ScanResultEvent | ScanCompleteEvent;