pompelmi 1.17.0 → 1.19.0

package/src/ClamAVScanner.js

@@ -137,4 +137,44 @@ async function scanDirectory(dirPath, options = {}) {
     return { clean, malicious, errors };
 }
 
+async function* streamDirectory(dirPath, options = {}) {
+    if (typeof dirPath !== 'string') {
+        throw new Error('dirPath must be a string');
+    }
+    if (!fs.existsSync(dirPath)) {
+        throw new Error(`Directory not found: ${dirPath}`);
+    }
+
+    const entries = fs.readdirSync(dirPath, { recursive: true });
+    const files = entries
+        .map(entry => path.join(dirPath, entry))
+        .filter(fullPath => fs.statSync(fullPath).isFile());
+
+    const total   = files.length;
+    let   scanned = 0;
+    const summary = { clean: [], malicious: [], errors: [] };
+
+    for (const filePath of files) {
+        let verdict;
+        try {
+            verdict = await scan(filePath, options);
+        } catch {
+            verdict = null;
+        }
+
+        scanned++;
+
+        if (verdict === Verdict.Clean)          summary.clean.push(filePath);
+        else if (verdict === Verdict.Malicious) summary.malicious.push(filePath);
+        else                                    summary.errors.push(filePath);
+
+        yield { type: 'progress', scanned, total, file: filePath };
+        yield { type: 'result',   file: filePath, verdict };
+    }
+
+    yield { type: 'complete', summary };
+}
+
+scanDirectory.stream = streamDirectory;
+
 module.exports = { scan, scanBuffer, scanStream, scanDirectory };

package/src/MultiEngine.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const https  = require('https');
+const http   = require('http');
+const crypto = require('crypto');
+const fs     = require('fs');
+const { scan, scanBuffer } = require('./ClamAVScanner.js');
+const { Verdict }          = require('./verdicts.js');
+
+// ── VirusTotal helpers ──────────────────────────────────────────────────────
+
+function vtRequest(method, urlStr, headers, body) {
+    return new Promise((resolve, reject) => {
+        const url  = new URL(urlStr);
+        const mod  = url.protocol === 'https:' ? https : http;
+        const opts = {
+            method,
+            hostname: url.hostname,
+            path:     url.pathname + url.search,
+            headers,
+        };
+        const req = mod.request(opts, (res) => {
+            const chunks = [];
+            res.on('data', c => chunks.push(c));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(Buffer.concat(chunks).toString()));
+                } catch {
+                    resolve({});
+                }
+            });
+        });
+        req.on('error', reject);
+        if (body) req.write(body);
+        req.end();
+    });
+}
+
+// Multipart form-data upload for VirusTotal /files endpoint
+function vtUpload(apiKey, buffer) {
+    return new Promise((resolve, reject) => {
+        const boundary = crypto.randomBytes(16).toString('hex');
+        const CRLF     = '\r\n';
+        const pre  = Buffer.from(
+            `--${boundary}${CRLF}` +
+            `Content-Disposition: form-data; name="file"; filename="upload"${CRLF}` +
+            `Content-Type: application/octet-stream${CRLF}${CRLF}`
+        );
+        const post = Buffer.from(`${CRLF}--${boundary}--${CRLF}`);
+        const body = Buffer.concat([pre, buffer, post]);
+
+        const opts = {
+            method:   'POST',
+            hostname: 'www.virustotal.com',
+            path:     '/api/v3/files',
+            headers:  {
+                'x-apikey':       apiKey,
+                'Content-Type':   `multipart/form-data; boundary=${boundary}`,
+                'Content-Length': body.length,
+            },
+        };
+
+        const req = https.request(opts, (res) => {
+            const chunks = [];
+            res.on('data', c => chunks.push(c));
+            res.on('end', () => {
+                try { resolve(JSON.parse(Buffer.concat(chunks).toString())); }
+                catch { resolve({}); }
+            });
+        });
+        req.on('error', reject);
+        req.write(body);
+        req.end();
+    });
+}
+
+async function vtScanBuffer(apiKey, buffer, threshold = 1) {
+    try {
+        // Upload file
+        const upload = await vtUpload(apiKey, buffer);
+        const id     = upload && upload.data && upload.data.id;
+        if (!id) return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: 'no analysis id' };
+
+        // Poll for result (up to 60s)
+        for (let i = 0; i < 12; i++) {
+            await new Promise(r => setTimeout(r, 5000));
+            const report = await vtRequest('GET',
+                `https://www.virustotal.com/api/v3/analyses/${id}`,
+                { 'x-apikey': apiKey }, null
+            );
+            const status = report && report.data && report.data.attributes && report.data.attributes.status;
+            if (status === 'completed') {
+                const stats      = report.data.attributes.stats || {};
+                const detections = (stats.malicious || 0) + (stats.suspicious || 0);
+                const verdict    = detections >= threshold ? Verdict.Malicious : Verdict.Clean;
+                return { name: 'virustotal', verdict, detections };
+            }
+        }
+        return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: 'timeout' };
+    } catch (err) {
+        return { name: 'virustotal', verdict: Verdict.ScanError, detections: 0, error: err.message };
+    }
+}
+
+// ── ClamAV engine wrapper ───────────────────────────────────────────────────
+
+async function clamavScanFile(config, filePath) {
+    try {
+        const verdict = await scan(filePath, config);
+        return { name: 'clamav', verdict };
+    } catch (err) {
+        return { name: 'clamav', verdict: Verdict.ScanError, error: err.message };
+    }
+}
+
+async function clamavScanBuffer(config, buffer) {
+    try {
+        const verdict = await scanBuffer(buffer, config);
+        return { name: 'clamav', verdict };
+    } catch (err) {
+        return { name: 'clamav', verdict: Verdict.ScanError, error: err.message };
+    }
+}
+
+// ── Consensus logic ─────────────────────────────────────────────────────────
+
+function applyConsensus(results, consensus) {
+    const verdicts = results.map(r => r.verdict);
+    const malCount = verdicts.filter(v => v === Verdict.Malicious).length;
+    const total    = verdicts.length;
+
+    let final;
+    if (consensus === 'all') {
+        final = malCount === total ? Verdict.Malicious : Verdict.Clean;
+    } else if (consensus === 'majority') {
+        final = malCount > total / 2 ? Verdict.Malicious : Verdict.Clean;
+    } else {
+        // 'any' (default)
+        final = malCount > 0 ? Verdict.Malicious : Verdict.Clean;
+    }
+
+    // If no conclusive result but errors exist, propagate ScanError
+    if (final === Verdict.Clean && verdicts.every(v => v === Verdict.ScanError)) {
+        final = Verdict.ScanError;
+    }
+
+    return final;
+}
+
+// ── Public factory ──────────────────────────────────────────────────────────
+
+function createMultiEngine(config = {}) {
+    const { engines = [], consensus = 'any' } = config;
+
+    async function _runEnginesOnBuffer(buffer) {
+        return Promise.all(engines.map(async (engine) => {
+            if (engine.type === 'virustotal') {
+                if (!engine.apiKey) return { name: 'virustotal', verdict: Verdict.ScanError, error: 'no apiKey' };
+                return vtScanBuffer(engine.apiKey, buffer, engine.threshold ?? 1);
+            }
+            // clamav
+            return clamavScanBuffer(engine, buffer);
+        }));
+    }
+
+    async function scanMultiBuffer(buffer) {
+        if (!Buffer.isBuffer(buffer)) throw new Error('buffer must be a Buffer');
+        const engineResults = await _runEnginesOnBuffer(buffer);
+        const verdict = applyConsensus(engineResults, consensus);
+        return { verdict, consensus, engines: engineResults };
+    }
+
+    async function scanMultiFile(filePath) {
+        if (typeof filePath !== 'string') throw new Error('filePath must be a string');
+        const buffer = fs.readFileSync(filePath);
+        const engineResults = await Promise.all(engines.map(async (engine) => {
+            if (engine.type === 'virustotal') {
+                if (!engine.apiKey) return { name: 'virustotal', verdict: Verdict.ScanError, error: 'no apiKey' };
+                return vtScanBuffer(engine.apiKey, buffer, engine.threshold ?? 1);
+            }
+            return clamavScanFile(engine, filePath);
+        }));
+        const verdict = applyConsensus(engineResults, consensus);
+        return { verdict, consensus, engines: engineResults };
+    }
+
+    return { scan: scanMultiFile, scanBuffer: scanMultiBuffer };
+}
+
+module.exports = { createMultiEngine };

package/src/Policy.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const path = require('path');
+const { scanBuffer } = require('./ClamAVScanner.js');
+const { Verdict }    = require('./verdicts.js');
+
+const REASONS = {
+    FILE_TOO_LARGE:      'file_too_large',
+    MIME_NOT_ALLOWED:    'mime_not_allowed',
+    EXT_NOT_ALLOWED:     'extension_not_allowed',
+    ENCRYPTED:           'encrypted_archive',
+    VIRUS_DETECTED:      'virus_detected',
+    SCANNER_UNAVAILABLE: 'scanner_unavailable',
+};
+
+// Minimal magic-byte check for encrypted ZIP (central directory encrypted flag)
+function looksEncrypted(buffer) {
+    // ZIP local file header signature: 50 4B 03 04
+    // General-purpose bit flag word at offset 6; bit 0 = encryption
+    if (buffer.length < 8) return false;
+    if (buffer[0] === 0x50 && buffer[1] === 0x4B &&
+        buffer[2] === 0x03 && buffer[3] === 0x04) {
+        const flags = buffer.readUInt16LE(6);
+        return (flags & 0x01) !== 0;
+    }
+    return false;
+}
+
+function createPolicy(rules = {}) {
+    const {
+        scan: scanOpts           = undefined,
+        maxSize                  = null,
+        allowedMimeTypes         = null,
+        allowedExtensions        = null,
+        rejectEncrypted          = false,
+        onScannerUnavailable     = 'reject',
+    } = rules;
+
+    async function check(buffer, meta = {}) {
+        const { filename = null, mimeType = null, size = buffer.length } = meta;
+        const details = { size, mimeType, extension: null, virusName: null };
+
+        if (filename) {
+            details.extension = path.extname(filename).toLowerCase();
+        }
+
+        // 1. Size check
+        if (maxSize !== null && size > maxSize) {
+            return { allowed: false, reason: REASONS.FILE_TOO_LARGE, verdict: Verdict.ScanError, details };
+        }
+
+        // 2. MIME type check
+        if (allowedMimeTypes && mimeType) {
+            if (!allowedMimeTypes.includes(mimeType)) {
+                return { allowed: false, reason: REASONS.MIME_NOT_ALLOWED, verdict: Verdict.ScanError, details };
+            }
+        }
+
+        // 3. Extension check
+        if (allowedExtensions && details.extension) {
+            if (!allowedExtensions.includes(details.extension)) {
+                return { allowed: false, reason: REASONS.EXT_NOT_ALLOWED, verdict: Verdict.ScanError, details };
+            }
+        }
+
+        // 4. Encrypted archive check
+        if (rejectEncrypted && looksEncrypted(buffer)) {
+            return { allowed: false, reason: REASONS.ENCRYPTED, verdict: Verdict.ScanError, details };
+        }
+
+        // 5. Virus scan
+        if (scanOpts !== undefined) {
+            let verdict;
+            try {
+                verdict = await scanBuffer(buffer, scanOpts);
+            } catch (err) {
+                if (onScannerUnavailable === 'allow') {
+                    return { allowed: true, reason: null, verdict: Verdict.ScanError, details };
+                }
+                if (onScannerUnavailable === 'throw') {
+                    throw err;
+                }
+                // 'reject'
+                return { allowed: false, reason: REASONS.SCANNER_UNAVAILABLE, verdict: Verdict.ScanError, details };
+            }
+
+            if (verdict === Verdict.Malicious) {
+                return { allowed: false, reason: REASONS.VIRUS_DETECTED, verdict: Verdict.Malicious, details };
+            }
+
+            return { allowed: true, reason: null, verdict, details };
+        }
+
+        return { allowed: true, reason: null, verdict: Verdict.Clean, details };
+    }
+
+    function middleware() {
+        return async function policyMiddleware(req, res, next) {
+            let file = null;
+            if (req.file) {
+                file = req.file;
+            } else if (req.files) {
+                const files = Array.isArray(req.files)
+                    ? req.files
+                    : Object.values(req.files).flat();
+                file = files[0] || null;
+            }
+
+            if (!file) return next();
+
+            const buffer   = file.buffer;
+            const filename = file.originalname || null;
+            const mimeType = file.mimetype || null;
+            const size     = buffer ? buffer.length : (file.size || 0);
+
+            try {
+                const result = await check(buffer || Buffer.alloc(0), { filename, mimeType, size });
+                if (!result.allowed) {
+                    return res.status(403).json({ error: result.reason });
+                }
+                next();
+            } catch (err) {
+                next(err);
+            }
+        };
+    }
+
+    function nestGuard() {
+        return {
+            canActivate: async (context) => {
+                const req    = context.switchToHttp().getRequest();
+                const res    = context.switchToHttp().getResponse();
+                const file   = req.file || (req.files && (Array.isArray(req.files) ? req.files[0] : Object.values(req.files).flat()[0]));
+                if (!file) return true;
+
+                const buffer   = file.buffer;
+                const filename = file.originalname || null;
+                const mimeType = file.mimetype || null;
+                const size     = buffer ? buffer.length : (file.size || 0);
+
+                const result = await check(buffer || Buffer.alloc(0), { filename, mimeType, size });
+                if (!result.allowed) {
+                    res.status(403).json({ error: result.reason });
+                    return false;
+                }
+                return true;
+            },
+        };
+    }
+
+    return { check, middleware, nestGuard };
+}
+
+module.exports = { createPolicy };

package/src/ScanCache.js

@@ -0,0 +1,136 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs     = require('fs');
+const { scan, scanBuffer } = require('./ClamAVScanner.js');
+
+function sha256ofBuffer(buf) {
+    return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function sha256ofFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto.createHash('sha256');
+        const stream = fs.createReadStream(filePath);
+        stream.on('error', reject);
+        stream.on('data', chunk => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+    });
+}
+
+function createCache(options = {}) {
+    const ttl      = options.ttl      ?? 3600000;
+    const maxSize  = options.maxSize  ?? 1000;
+    const storage  = options.storage  || 'memory';
+    const filePath = options.filePath || './.pompelmi-cache.json';
+
+    // LRU map: key = sha256, value = { verdict, expiresAt }
+    // Insertion order tracks LRU; on hit we re-insert to move to back.
+    let store = new Map();
+    let hits   = 0;
+    let misses = 0;
+    let writeTimer = null;
+
+    // ── file storage bootstrap ──────────────────────────────────────────────────
+    if (storage === 'file') {
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            const now = Date.now();
+            for (const [k, v] of Object.entries(raw)) {
+                if (v.expiresAt > now) store.set(k, v);
+            }
+        } catch {
+            // file absent or invalid — start with empty cache
+        }
+    }
+
+    function _persist() {
+        if (storage !== 'file') return;
+        if (writeTimer) return;
+        writeTimer = setTimeout(() => {
+            writeTimer = null;
+            const obj = {};
+            for (const [k, v] of store) obj[k] = v;
+            const tmp = filePath + '.tmp';
+            try {
+                fs.writeFileSync(tmp, JSON.stringify(obj));
+                fs.renameSync(tmp, filePath);
+            } catch { /* non-fatal */ }
+        }, 500);
+    }
+
+    function _get(sha) {
+        const entry = store.get(sha);
+        if (!entry) return null;
+        if (Date.now() > entry.expiresAt) {
+            store.delete(sha);
+            return null;
+        }
+        // Move to end (LRU: most-recently-used = last)
+        store.delete(sha);
+        store.set(sha, entry);
+        return entry.verdict;
+    }
+
+    function _set(sha, verdict) {
+        if (store.has(sha)) store.delete(sha); // re-insert at end
+        if (store.size >= maxSize) {
+            // evict oldest (first) entry
+            store.delete(store.keys().next().value);
+        }
+        store.set(sha, { verdict, expiresAt: Date.now() + ttl });
+        _persist();
+    }
+
+    async function scanWithCache(filePath, opts = {}) {
+        const sha = await sha256ofFile(filePath);
+        const cached = _get(sha);
+        if (cached !== null) { hits++; return cached; }
+        misses++;
+        const verdict = await scan(filePath, opts);
+        _set(sha, verdict);
+        return verdict;
+    }
+
+    async function scanBufferWithCache(buffer, opts = {}) {
+        const sha = sha256ofBuffer(buffer);
+        const cached = _get(sha);
+        if (cached !== null) { hits++; return cached; }
+        misses++;
+        const verdict = await scanBuffer(buffer, opts);
+        _set(sha, verdict);
+        return verdict;
+    }
+
+    function stats() {
+        const total = hits + misses;
+        return {
+            hits,
+            misses,
+            size: store.size,
+            hitRate: total === 0 ? 0 : hits / total,
+        };
+    }
+
+    function clear() {
+        store = new Map();
+        hits = 0;
+        misses = 0;
+        _persist();
+    }
+
+    function del(sha) {
+        store.delete(sha);
+        _persist();
+    }
+
+    return {
+        scan:        scanWithCache,
+        scanBuffer:  scanBufferWithCache,
+        stats,
+        clear,
+        delete:      del,
+    };
+}
+
+module.exports = { createCache };

package/src/Scorecard.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const CHECKS = [
+  {
+    key: 'scanEnabled',
+    check: 'Virus scanning enabled',
+    weight: 30,
+    pass: c => c.scanEnabled === true,
+    recommendation: 'Enable virus scanning by integrating pompelmi into your upload handler.',
+  },
+  {
+    key: 'mimeTypeAllowlist',
+    check: 'MIME type allowlist',
+    weight: 20,
+    pass: c => Array.isArray(c.mimeTypeAllowlist) && c.mimeTypeAllowlist.length > 0,
+    recommendation: 'Define an explicit MIME type allowlist to reject unexpected file types.',
+  },
+  {
+    key: 'fileSizeLimit',
+    check: 'File size limit',
+    weight: 10,
+    pass: c => typeof c.fileSizeLimit === 'number' && c.fileSizeLimit > 0,
+    recommendation: 'Set a maximum file size limit to prevent resource exhaustion.',
+  },
+  {
+    key: 'diskWriteBeforeScan',
+    check: 'No disk write before scan',
+    weight: 15,
+    pass: c => c.diskWriteBeforeScan === false,
+    recommendation: 'Scan files in-memory before writing to disk to avoid storing malware even temporarily.',
+  },
+  {
+    key: 'scanErrorBehavior',
+    check: 'Scan error behavior is reject',
+    weight: 10,
+    pass: c => c.scanErrorBehavior === 'reject',
+    recommendation: 'Set scanErrorBehavior to "reject" — failing open on scan errors is a security risk.',
+  },
+  {
+    key: 'clamdUnavailableBehavior',
+    check: 'clamd unavailable behavior is reject',
+    weight: 10,
+    pass: c => c.clamdUnavailableBehavior === 'reject',
+    recommendation: 'Set clamdUnavailableBehavior to "reject" — if clamd is down, deny uploads rather than allowing them through.',
+  },
+  {
+    key: 'tlsEnabled',
+    check: 'TLS enabled on upload endpoint',
+    weight: 5,
+    pass: c => c.tlsEnabled === true,
+    recommendation: 'Enable TLS (HTTPS) on your upload endpoint to protect files in transit.',
+  },
+];
+
+function scoreToGrade(score) {
+  if (score >= 90) return 'A';
+  if (score >= 75) return 'B';
+  if (score >= 60) return 'C';
+  if (score >= 45) return 'D';
+  return 'F';
+}
+
+async function generateScorecard(config = {}) {
+  const maxScore = CHECKS.reduce((s, c) => s + c.weight, 0);
+  let earned = 0;
+  const findings = [];
+  const recommendations = [];
+
+  for (const def of CHECKS) {
+    const passed = def.pass(config);
+    findings.push({ check: def.check, status: passed ? 'pass' : 'fail', weight: def.weight });
+    if (passed) {
+      earned += def.weight;
+    } else {
+      recommendations.push(def.recommendation);
+    }
+  }
+
+  const score = Math.round((earned / maxScore) * 100);
+  const grade = scoreToGrade(score);
+
+  return { grade, score, findings, recommendations };
+}
+
+module.exports = { generateScorecard };