pompelmi 1.17.0 → 1.18.0

package/README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/v/pompelmi.svg" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/pompelmi"><img src="https://img.shields.io/npm/dw/pompelmi" alt="weekly downloads"></a>
+  <a href="https://hub.docker.com/r/pompelmi/scanner"><img src="https://img.shields.io/docker/pulls/pompelmi/scanner" alt="Docker Pulls"></a>
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="zero dependencies">
   <img src="https://img.shields.io/badge/license-ISC-blue" alt="license">
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -73,6 +74,10 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 ## Features
 
 - Standalone CLI — scan files from any terminal with `npx pompelmi scan`
+- **Official Docker image** — `pompelmi/scanner` on Docker Hub: ClamAV + HTTP scan API in one pull ([docs](./docs/docker-image.html))
+- **Security scorecard** — grade your upload security A–F with `npx pompelmi scorecard` ([docs](./docs/scorecard.html))
+- **VS Code extension** — scan files directly from the IDE (scaffold in `packages/vscode/`) ([docs](./docs/vscode.html))
+- **Quarantine mode** — `watch ./uploads --quarantine ./quarantine` auto-moves infected files with sidecar JSON
 - HTML security dashboard — generate beautiful scan reports with `--report` ([docs](./docs/dashboard.html))
 - SVG share card — shareable scan result card with `--share-card` ([docs](./docs/dashboard.html#share-card))
 - GitHub App — one-click installation for organizations, zero-config PR scanning ([docs](./docs/github-app.html))

package/bin/pompelmi.js

@@ -71,12 +71,14 @@ function parseArgs(argv) {
     reportOutput: null,
     shareCard: false,
     shareCardOutput: null,
+    quarantine: null,
+    scorecardConfig: null,
   };
 
   let i = 0;
   while (i < args.length) {
     const a = args[i];
-    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help') {
+    if (a === 'scan' || a === 'watch' || a === 'version' || a === 'help' || a === 'scorecard') {
       opts.command = a;
     } else if (a === '--json') {
       opts.json = true;
@@ -104,6 +106,10 @@ function parseArgs(argv) {
       const next = args[++i];
       if (next && next.endsWith('.svg')) opts.shareCardOutput = next;
       else opts.reportOutput = next;
+    } else if (a === '--quarantine') {
+      opts.quarantine = args[++i];
+    } else if (a === '--config') {
+      opts.scorecardConfig = args[++i];
     } else if (!a.startsWith('-') && opts.command && !opts.target) {
       opts.target = a;
     }
@@ -333,7 +339,9 @@ async function cmdWatch(opts) {
   if (!opts.json && !opts.quiet) await printLogo();
 
   const { watch } = require('../src/Watcher.js');
-  const scanOpts = buildScanOpts(opts);
+  const quarantineDir = opts.quarantine ? path.resolve(opts.quarantine) : null;
+  const watchOpts = { ...buildScanOpts(opts) };
+  if (quarantineDir) watchOpts.quarantine = quarantineDir;
 
   let scanned = 0, clean = 0, infected = 0;
 
@@ -345,7 +353,7 @@ async function cmdWatch(opts) {
 
   status();
 
-  watch(target, scanOpts, {
+  watch(target, watchOpts, {
     onClean(fp) {
       scanned++; clean++;
       if (!opts.quiet) process.stdout.write(`\n\x1b[32m✅ CLEAN\x1b[0m  ${fp}\n`);
@@ -354,6 +362,7 @@ async function cmdWatch(opts) {
     onMalicious(fp) {
       scanned++; infected++;
       process.stdout.write(`\n\x1b[31m🚨 INFECTED\x1b[0m  ${fp}\n`);
+      if (quarantineDir && !opts.quiet) process.stdout.write(`   Quarantined to ${quarantineDir}\n`);
       status();
     },
     onError(err) {
@@ -366,6 +375,44 @@ async function cmdWatch(opts) {
   process.on('SIGINT', () => { process.stdout.write('\n'); process.exit(0); });
 }
 
+async function cmdScorecard(opts) {
+  let config = {};
+  if (opts.scorecardConfig) {
+    const cfgPath = path.resolve(opts.scorecardConfig);
+    if (!fs.existsSync(cfgPath)) {
+      console.error(`Error: config file not found: ${cfgPath}`);
+      process.exit(2);
+    }
+    config = require(cfgPath);
+  }
+
+  const { generateScorecard } = require('../src/Scorecard.js');
+  const scorecard = await generateScorecard(config);
+
+  const gradeColor = { A: '\x1b[32m', B: '\x1b[32m', C: '\x1b[33m', D: '\x1b[33m', F: '\x1b[31m' };
+  const color = gradeColor[scorecard.grade] || '\x1b[0m';
+  const reset = '\x1b[0m';
+
+  if (!opts.quiet) await printLogo();
+
+  console.log(`\n  Upload Security Scorecard\n`);
+  console.log(`  Grade: ${color}${scorecard.grade}${reset}   Score: ${scorecard.score}/100\n`);
+
+  for (const f of scorecard.findings) {
+    const icon = f.status === 'pass' ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+    console.log(`  ${icon}  ${f.check.padEnd(40)} (weight: ${f.weight})`);
+  }
+
+  if (scorecard.recommendations.length > 0) {
+    console.log(`\n  Recommendations:`);
+    for (const r of scorecard.recommendations) {
+      console.log(`    • ${r}`);
+    }
+  }
+
+  console.log('');
+}
+
 function cmdVersion() {
   console.log(pkg.version);
 }
@@ -380,6 +427,7 @@ USAGE
 COMMANDS
   scan <file|dir>    Scan a file or directory for viruses
   watch <dir>        Watch a directory and auto-scan new/modified files
+  scorecard          Grade your upload security configuration (A-F)
   version            Print version number
   help               Show this help message
 
@@ -400,6 +448,10 @@ SCAN OPTIONS
 
 WATCH OPTIONS
   --host, --port, --socket, --timeout   (same as scan)
+  --quarantine <dir>  Move infected files to this directory (auto-created)
+
+SCORECARD OPTIONS
+  --config <file>     Path to a pompelmi.config.js file with your upload config
 
 EXIT CODES
   0   All files clean
@@ -428,6 +480,12 @@ EXAMPLES
 
   # Use with npx (no install required)
   npx pompelmi scan ./uploads
+
+  # Watch a directory with quarantine
+  pompelmi watch ./uploads --quarantine ./quarantine
+
+  # Grade your upload security config
+  npx pompelmi scorecard --config ./pompelmi.config.js
 `);
 }
 
@@ -456,6 +514,11 @@ async function main() {
     await cmdWatch(opts);
     return;
   }
+
+  if (opts.command === 'scorecard') {
+    await cmdScorecard(opts);
+    return;
+  }
 }
 
 main().catch(err => {

package/docker/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      clamav clamav-freshclam curl && \
+    rm -rf /var/lib/apt/lists/* && \
+    sed -i 's/^Example/#Example/' /etc/clamav/freshclam.conf && \
+    mkdir -p /var/lib/clamav /run/clamav /uploads
+
+WORKDIR /app
+RUN npm install -g pompelmi
+
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 3310 8080
+
+ENTRYPOINT ["/entrypoint.sh"]

package/docker/README.md

@@ -0,0 +1,62 @@
+# pompelmi/scanner Docker Image
+
+Official Docker image for pompelmi — ClamAV antivirus scanning for Node.js.
+
+The image ships with:
+- ClamAV + clamd pre-installed
+- freshclam for automatic definition updates on startup
+- A minimal HTTP API server on port 8080
+
+## Quick start
+
+```bash
+docker pull pompelmi/scanner
+docker run -p 8080:8080 pompelmi/scanner
+```
+
+## Scan a file
+
+```bash
+curl -F "file=@./document.pdf" http://localhost:8080/scan
+```
+
+Response:
+
+```json
+{ "verdict": "clean", "file": "document.pdf", "viruses": [] }
+```
+
+For an infected file the verdict is `"malicious"`.
+
+## Endpoints
+
+| Method | Path      | Description                                             |
+|--------|-----------|---------------------------------------------------------|
+| POST   | /scan     | Accepts `multipart/form-data` with a `file` field. Returns `{ verdict, file, viruses }` |
+| GET    | /health   | Returns `{ status: "ok", clamd: "running" }` |
+| GET    | /stats    | Returns scan statistics (total, clean, infected, errors, uptime) |
+
+## Docker Compose
+
+```yaml
+services:
+  pompelmi:
+    image: pompelmi/scanner
+    ports:
+      - "8080:8080"
+    volumes:
+      - /uploads:/uploads
+    restart: unless-stopped
+```
+
+## Environment
+
+The container exposes two ports:
+- **8080** — HTTP scan API
+- **3310** — clamd TCP socket (for direct clamd connections from other containers)
+
+## Building locally
+
+```bash
+docker build -f docker/Dockerfile -t pompelmi/scanner .
+```

package/docker/entrypoint.sh

@@ -0,0 +1,148 @@
+#!/bin/sh
+set -e
+
+# ── Update ClamAV virus definitions ──────────────────────────────────────────
+echo "[pompelmi] Updating ClamAV definitions via freshclam..."
+freshclam --quiet || echo "[pompelmi] freshclam failed — continuing with existing definitions"
+
+# ── Start clamd in background ─────────────────────────────────────────────────
+echo "[pompelmi] Starting clamd..."
+clamd &
+CLAMD_PID=$!
+
+# Wait for clamd socket/port to be ready
+echo "[pompelmi] Waiting for clamd to be ready..."
+for i in $(seq 1 30); do
+  if clamdscan --no-summary /dev/null 2>/dev/null; then
+    echo "[pompelmi] clamd is ready"
+    break
+  fi
+  sleep 1
+done
+
+# ── Stats counters (stored in files for simplicity) ───────────────────────────
+STATS_DIR=/tmp/pompelmi-stats
+mkdir -p "$STATS_DIR"
+echo 0 > "$STATS_DIR/total"
+echo 0 > "$STATS_DIR/clean"
+echo 0 > "$STATS_DIR/infected"
+echo 0 > "$STATS_DIR/errors"
+
+# ── Minimal HTTP server ───────────────────────────────────────────────────────
+# Uses Node.js (already available from the base image)
+node - <<'EOF'
+'use strict';
+
+const http      = require('http');
+const fs        = require('fs');
+const os        = require('os');
+const path      = require('path');
+const { execSync, exec } = require('child_process');
+const { scanBuffer } = require('pompelmi');
+const { Verdict } = require('pompelmi');
+
+const PORT = 8080;
+const STATS = { total: 0, clean: 0, infected: 0, errors: 0, startedAt: new Date().toISOString() };
+
+function parseMultipart(req) {
+  return new Promise((resolve, reject) => {
+    const boundary = (req.headers['content-type'] || '').split('boundary=')[1];
+    if (!boundary) return reject(new Error('Missing multipart boundary'));
+
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('error', reject);
+    req.on('end', () => {
+      const body   = Buffer.concat(chunks);
+      const delim  = Buffer.from('\r\n--' + boundary);
+      const parts  = [];
+      let start    = body.indexOf('--' + boundary);
+
+      while (start !== -1) {
+        const headerEnd = body.indexOf('\r\n\r\n', start);
+        if (headerEnd === -1) break;
+        const headerStr = body.slice(start, headerEnd).toString();
+        const nameMatch = headerStr.match(/name="([^"]+)"/);
+        const fileMatch = headerStr.match(/filename="([^"]+)"/);
+        const dataStart = headerEnd + 4;
+        const nextDelim = body.indexOf(delim, dataStart);
+        const dataEnd   = nextDelim === -1 ? body.indexOf('\r\n--' + boundary + '--', dataStart) : nextDelim;
+        if (dataEnd === -1) break;
+        parts.push({
+          name:     nameMatch  ? nameMatch[1]  : '',
+          filename: fileMatch  ? fileMatch[1]  : '',
+          data:     body.slice(dataStart, dataEnd),
+        });
+        start = body.indexOf('--' + boundary, dataEnd);
+        if (body.slice(start, start + boundary.length + 6).toString().includes('--\r\n')) break;
+      }
+      resolve(parts);
+    });
+  });
+}
+
+function isClamdRunning() {
+  try { execSync('clamdscan --no-summary /dev/null 2>/dev/null'); return true; }
+  catch { return false; }
+}
+
+const server = http.createServer(async (req, res) => {
+  res.setHeader('Content-Type', 'application/json');
+
+  if (req.method === 'GET' && req.url === '/health') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ status: 'ok', clamd: isClamdRunning() ? 'running' : 'unavailable' }));
+  }
+
+  if (req.method === 'GET' && req.url === '/stats') {
+    res.writeHead(200);
+    return res.end(JSON.stringify({ ...STATS, uptime: process.uptime() }));
+  }
+
+  if (req.method === 'POST' && req.url === '/scan') {
+    try {
+      const parts = await parseMultipart(req);
+      const filePart = parts.find(p => p.filename);
+      if (!filePart) {
+        res.writeHead(400);
+        return res.end(JSON.stringify({ error: 'No file field in request' }));
+      }
+
+      STATS.total++;
+      const verdict = await scanBuffer(filePart.data);
+
+      let result;
+      if (verdict === Verdict.Clean) {
+        STATS.clean++;
+        result = { verdict: 'clean', file: filePart.filename, viruses: [] };
+      } else if (verdict === Verdict.Malicious) {
+        STATS.infected++;
+        result = { verdict: 'malicious', file: filePart.filename, viruses: [] };
+      } else {
+        STATS.errors++;
+        result = { verdict: 'error', file: filePart.filename, viruses: [] };
+      }
+
+      res.writeHead(200);
+      return res.end(JSON.stringify(result));
+    } catch (err) {
+      STATS.errors++;
+      res.writeHead(500);
+      return res.end(JSON.stringify({ error: err.message }));
+    }
+  }
+
+  res.writeHead(404);
+  res.end(JSON.stringify({ error: 'Not found' }));
+});
+
+server.listen(PORT, () => {
+  console.log(`[pompelmi] HTTP scan server listening on port ${PORT}`);
+  console.log(`[pompelmi] POST /scan   — scan a file`);
+  console.log(`[pompelmi] GET  /health — health check`);
+  console.log(`[pompelmi] GET  /stats  — scan statistics`);
+});
+
+process.on('SIGTERM', () => { server.close(); process.exit(0); });
+process.on('SIGINT',  () => { server.close(); process.exit(0); });
+EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",

package/packages/vscode/README.md

@@ -0,0 +1,61 @@
+# pompelmi — VS Code Extension
+
+Scan files for viruses directly from VS Code using pompelmi and ClamAV.
+
+## Requirements
+
+- [ClamAV](https://www.clamav.net/) installed (or clamd running via Docker)
+- Node.js and npm available in your PATH
+
+## Installation
+
+Install from the VS Code Marketplace:
+
+1. Open VS Code
+2. Press `Ctrl+P` (or `Cmd+P` on macOS)
+3. Run: `ext install pompelmi.pompelmi`
+
+## Usage
+
+### Scan a single file
+
+Right-click any file in the Explorer sidebar and select **"Scan with pompelmi"**.
+
+Results appear as VS Code notifications:
+
+- `✅ file.pdf — Clean`
+- `🚨 malware.exe — INFECTED (Win.Malware.Agent)`
+
+### Scan the workspace
+
+Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run:
+
+```
+pompelmi: Scan Workspace
+```
+
+### Configure
+
+Run `pompelmi: Configure` from the Command Palette to open settings.
+
+## Settings
+
+| Setting           | Default     | Description                              |
+|-------------------|-------------|------------------------------------------|
+| `pompelmi.host`   | `localhost` | clamd host                               |
+| `pompelmi.port`   | `3310`      | clamd port                               |
+| `pompelmi.socket` | *(empty)*   | clamd UNIX socket path (takes precedence over host/port) |
+
+## Using with Docker
+
+Start clamd via the official pompelmi Docker image:
+
+```bash
+docker run -p 3310:3310 -p 8080:8080 pompelmi/scanner
+```
+
+Then set `pompelmi.host` to `localhost` and `pompelmi.port` to `3310`.
+
+## License
+
+ISC © pompelmi contributors

package/packages/vscode/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "pompelmi",
+  "displayName": "pompelmi — Antivirus File Scanner",
+  "description": "Scan files for viruses directly from VS Code using pompelmi and ClamAV.",
+  "version": "0.1.0",
+  "publisher": "pompelmi",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git"
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": ["Other", "Linters"],
+  "keywords": ["antivirus", "clamav", "security", "malware", "virus"],
+  "icon": "icon.png",
+  "activationEvents": [
+    "onCommand:pompelmi.scanFile"
+  ],
+  "main": "./src/extension.js",
+  "contributes": {
+    "commands": [
+      {
+        "command": "pompelmi.scanFile",
+        "title": "Scan with pompelmi",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.scanWorkspace",
+        "title": "Scan Workspace",
+        "category": "pompelmi"
+      },
+      {
+        "command": "pompelmi.configure",
+        "title": "Configure pompelmi",
+        "category": "pompelmi"
+      }
+    ],
+    "menus": {
+      "explorer/context": [
+        {
+          "command": "pompelmi.scanFile",
+          "when": "resourceScheme == 'file'",
+          "group": "7_modification"
+        }
+      ]
+    },
+    "configuration": {
+      "title": "pompelmi",
+      "properties": {
+        "pompelmi.host": {
+          "type": "string",
+          "default": "localhost",
+          "description": "clamd host"
+        },
+        "pompelmi.port": {
+          "type": "number",
+          "default": 3310,
+          "description": "clamd port"
+        },
+        "pompelmi.socket": {
+          "type": "string",
+          "default": "",
+          "description": "clamd UNIX socket path (e.g. /run/clamav/clamd.sock)"
+        }
+      }
+    }
+  }
+}

package/packages/vscode/src/extension.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const { execFile } = require('child_process');
+const path         = require('path');
+
+function getScanOptions(vscode) {
+  const cfg    = vscode.workspace.getConfiguration('pompelmi');
+  const host   = cfg.get('host', 'localhost');
+  const port   = cfg.get('port', 3310);
+  const socket = cfg.get('socket', '');
+  const args   = ['scan'];
+  if (socket) { args.push('--socket', socket); }
+  else        { args.push('--host', host, '--port', String(port)); }
+  args.push('--json');
+  return args;
+}
+
+function runScan(filePath, args, callback) {
+  const allArgs = [...args, filePath];
+  execFile('npx', ['pompelmi', ...allArgs], { timeout: 30000 }, (err, stdout) => {
+    if (err && !stdout) return callback(err, null);
+    try {
+      const result = JSON.parse(stdout);
+      callback(null, result);
+    } catch {
+      callback(new Error('Failed to parse pompelmi output'), null);
+    }
+  });
+}
+
+function activate(context) {
+  const vscode = require('vscode');
+
+  const scanFileCmd = vscode.commands.registerCommand('pompelmi.scanFile', async (uri) => {
+    const filePath = uri ? uri.fsPath : vscode.window.activeTextEditor?.document.uri.fsPath;
+    if (!filePath) {
+      vscode.window.showErrorMessage('pompelmi: No file selected.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: `pompelmi: scanning ${path.basename(filePath)}...` },
+      () => new Promise(resolve => {
+        runScan(filePath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const r = result?.results?.[0];
+          if (!r) {
+            vscode.window.showErrorMessage('pompelmi: unexpected response');
+            return;
+          }
+          if (r.verdict === 'clean') {
+            vscode.window.showInformationMessage(`✅ ${path.basename(filePath)} — Clean`);
+          } else if (r.verdict === 'infected') {
+            const virus = r.viruses?.[0] ? ` (${r.viruses[0]})` : '';
+            vscode.window.showErrorMessage(`🚨 ${path.basename(filePath)} — INFECTED${virus}`);
+          } else {
+            vscode.window.showWarningMessage(`⚠️ ${path.basename(filePath)} — Scan error`);
+          }
+        });
+      })
+    );
+  });
+
+  const scanWorkspaceCmd = vscode.commands.registerCommand('pompelmi.scanWorkspace', async () => {
+    const folders = vscode.workspace.workspaceFolders;
+    if (!folders || folders.length === 0) {
+      vscode.window.showErrorMessage('pompelmi: No workspace folder open.');
+      return;
+    }
+
+    const args = getScanOptions(vscode);
+    const dirPath = folders[0].uri.fsPath;
+
+    vscode.window.withProgress(
+      { location: vscode.ProgressLocation.Notification, title: 'pompelmi: scanning workspace...' },
+      () => new Promise(resolve => {
+        runScan(dirPath, args, (err, result) => {
+          resolve();
+          if (err) {
+            vscode.window.showErrorMessage(`pompelmi error: ${err.message}`);
+            return;
+          }
+          const infected = result?.infected ?? 0;
+          const scanned  = result?.scanned  ?? 0;
+          if (infected === 0) {
+            vscode.window.showInformationMessage(`✅ Workspace scan complete — ${scanned} files scanned, all clean.`);
+          } else {
+            vscode.window.showErrorMessage(`🚨 Workspace scan — ${infected} infected file(s) found out of ${scanned} scanned.`);
+          }
+        });
+      })
+    );
+  });
+
+  const configureCmd = vscode.commands.registerCommand('pompelmi.configure', () => {
+    vscode.commands.executeCommand('workbench.action.openSettings', 'pompelmi');
+  });
+
+  context.subscriptions.push(scanFileCmd, scanWorkspaceCmd, configureCmd);
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

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

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,6 @@ const { notify }                                      = require('./WebhookNotifi
 const { createScanner }                               = require('./ScanEmitter.js');
 const { generateDashboard }                           = require('./Dashboard.js');
 const { generateShareCard }                           = require('./ShareCard.js');
+const { generateScorecard }                           = require('./Scorecard.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 };

package/types/index.d.ts

@@ -142,14 +142,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 +274,57 @@ 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>;