pompelmi 1.13.0 → 1.14.0

package/README.md

@@ -73,6 +73,9 @@ 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`
+- 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))
 - Single `scan(filePath, [options])` function — works locally or against a remote clamd instance
 - `scanBuffer(buffer, [options])` — scan in-memory Buffers directly, no temp file required in TCP mode
 - `scanStream(stream, [options])` — scan a Readable stream directly. In TCP mode, streamed to clamd with no disk I/O.
@@ -503,6 +506,8 @@ Scan any repository for viruses on every push or pull request — ClamAV is bund
 
 A ready-to-copy workflow is available at [`.github/workflows/action-example.yml`](./.github/workflows/action-example.yml). Full reference — inputs, outputs, layer caching, and more examples — in **[docs/github-action.md](./docs/github-action.md)**.
 
+> **For organizations:** install the [pompelmi GitHub App](./docs/github-app.html) for zero-config scanning on every PR — no workflow file needed.
+
 ---
 
 ## Contributing

package/bin/pompelmi.js

@@ -67,6 +67,10 @@ function parseArgs(argv) {
     quiet: false,
     delete: false,
     recursive: true,
+    report: false,
+    reportOutput: null,
+    shareCard: false,
+    shareCardOutput: null,
   };
 
   let i = 0;
@@ -92,6 +96,14 @@ function parseArgs(argv) {
       opts.timeout = parseInt(args[++i], 10);
     } else if (a === '--retries') {
       opts.retries = parseInt(args[++i], 10);
+    } else if (a === '--report') {
+      opts.report = true;
+    } else if (a === '--share-card') {
+      opts.shareCard = true;
+    } else if (a === '--output') {
+      const next = args[++i];
+      if (next && next.endsWith('.svg')) opts.shareCardOutput = next;
+      else opts.reportOutput = next;
     } else if (!a.startsWith('-') && opts.command && !opts.target) {
       opts.target = a;
     }
@@ -276,6 +288,26 @@ async function cmdScan(opts) {
 
   printResults(results, elapsed, opts);
 
+  if (opts.report) {
+    const { generateDashboard } = require('../src/Dashboard.js');
+    const outPath = opts.reportOutput || 'pompelmi-report.html';
+    generateDashboard(results, {
+      elapsed,
+      host: opts.host,
+      port: opts.port,
+      socket: opts.socket,
+      outputPath: outPath,
+    });
+    if (!opts.quiet) console.log(`\n  Report saved: ${outPath}`);
+  }
+
+  if (opts.shareCard) {
+    const { generateShareCard } = require('../src/ShareCard.js');
+    const outPath = opts.shareCardOutput || 'pompelmi-scan-card.svg';
+    generateShareCard(results, { outputPath: outPath });
+    if (!opts.quiet) console.log(`  Share card saved: ${outPath}`);
+  }
+
   const hasInfected = results.some(r => r.verdict === 'infected');
   const hasError    = results.some(r => r.verdict === 'error');
   const clamdDown   = results.some(r => r._clamdUnreachable);
@@ -361,6 +393,10 @@ SCAN OPTIONS
   --json             Output results as JSON (no logo, no colors)
   --quiet, -q        Only print infected files and summary
   --delete           Delete infected files after confirmation
+  --report           Generate an HTML security dashboard report
+  --share-card       Generate a shareable SVG scan result card
+  --output <file>    Output path for --report (default: pompelmi-report.html)
+                     or --share-card (default: pompelmi-scan-card.svg)
 
 WATCH OPTIONS
   --host, --port, --socket, --timeout   (same as scan)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.13.0",
+  "version": "1.14.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",
@@ -37,7 +37,7 @@
     "pompelmi": "./bin/pompelmi.js"
   },
   "scripts": {
-    "test": "node --test test/unit.test.js && node --test packages/nestjs/test/index.test.js && node --test packages/fastify/test/index.test.js && node test/scan.test.js",
+    "test": "node --test test/unit.test.js && node --test packages/nestjs/test/index.test.js && node --test packages/fastify/test/index.test.js && node --test packages/nextjs/test/index.test.js && node test/scan.test.js",
     "lint": "eslint src/"
   },
   "publishConfig": {

package/packages/nextjs/README.md

@@ -0,0 +1,83 @@
+# @pompelmi/nextjs
+
+Next.js middleware for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+Supports both the **App Router** (Next.js 13+) and the **Pages Router** (Next.js ≤ 12).
+
+## Installation
+
+```bash
+npm install pompelmi @pompelmi/nextjs
+```
+
+ClamAV must be available on the server — either via the system `clamscan` binary or a running `clamd` daemon.
+
+## App Router (Next.js 13+)
+
+```js
+// app/api/upload/route.js
+import { withPompelmi } from '@pompelmi/nextjs'
+
+export const POST = withPompelmi(async (req) => {
+  const formData = await req.formData()
+  const file = formData.get('file')
+  // req.pompelmiVerdict is set — Verdict.Clean is guaranteed here
+  return Response.json({ ok: true })
+}, {
+  host: 'localhost',
+  port: 3310,
+})
+```
+
+With TypeScript:
+
+```ts
+// app/api/upload/route.ts
+import { withPompelmi } from '@pompelmi/nextjs'
+
+export const POST = withPompelmi(async (req: Request) => {
+  return Response.json({ ok: true })
+}, { host: 'localhost', port: 3310 })
+```
+
+## Pages Router (Next.js ≤ 12)
+
+```js
+// pages/api/upload.js
+import { withPompelmiHandler } from '@pompelmi/nextjs'
+
+async function handler(req, res) {
+  // req.pompelmiVerdict is set — Verdict.Clean is guaranteed here
+  res.json({ ok: true })
+}
+
+export default withPompelmiHandler(handler, {
+  host: 'localhost',
+  port: 3310,
+})
+```
+
+## Options
+
+All options are forwarded to `pompelmi.scanBuffer()`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `host` | `string` | — | clamd hostname (TCP mode) |
+| `port` | `number` | `3310` | clamd port |
+| `socket` | `string` | — | UNIX socket path |
+| `timeout` | `number` | `15000` | Connection timeout in ms |
+| `retries` | `number` | `0` | Auto-retry count on failure |
+
+When neither `host` nor `socket` is provided, pompelmi falls back to the local `clamscan` binary.
+
+## Behaviour
+
+- The raw request body is buffered and scanned **before** your handler runs.
+- If the body is malicious, a **400 JSON** response is returned immediately: `{ "error": "Malicious file detected" }`.
+- `req.pompelmiVerdict` is set to the `Verdict` symbol so your handler can inspect it if needed.
+- Scan errors (e.g. clamd unreachable) are **not** blocking — the request proceeds with `Verdict.ScanError`.
+
+## License
+
+ISC

package/packages/nextjs/index.d.ts

@@ -0,0 +1,45 @@
+import type { VerdictValue, ScanOptions } from 'pompelmi';
+
+/** Options accepted by withPompelmi / withPompelmiHandler */
+export interface PompelmiNextOptions extends ScanOptions {}
+
+/**
+ * App Router (Next.js 13+) wrapper.
+ * Scans the raw request body before the handler runs.
+ * Returns HTTP 400 if the body is malicious.
+ *
+ * @example
+ * // app/api/upload/route.ts
+ * import { withPompelmi } from '@pompelmi/nextjs'
+ *
+ * export const POST = withPompelmi(async (req) => {
+ *   return Response.json({ ok: true })
+ * }, { host: 'localhost', port: 3310 })
+ */
+export declare function withPompelmi(
+  handler: (req: Request, ctx?: unknown) => Promise<Response>,
+  options?: PompelmiNextOptions
+): (req: Request, ctx?: unknown) => Promise<Response>;
+
+/**
+ * Pages Router (Next.js ≤ 12) wrapper.
+ * Scans the raw request body before the handler runs.
+ * Sends HTTP 400 if the body is malicious.
+ *
+ * @example
+ * // pages/api/upload.ts
+ * import { withPompelmiHandler } from '@pompelmi/nextjs'
+ * import type { NextApiRequest, NextApiResponse } from 'next'
+ *
+ * async function handler(req: NextApiRequest, res: NextApiResponse) {
+ *   res.json({ ok: true })
+ * }
+ *
+ * export default withPompelmiHandler(handler, { host: 'localhost', port: 3310 })
+ */
+export declare function withPompelmiHandler(
+  handler: (req: import('http').IncomingMessage, res: import('http').ServerResponse) => void | Promise<void>,
+  options?: PompelmiNextOptions
+): (req: import('http').IncomingMessage, res: import('http').ServerResponse) => Promise<void>;
+
+export { Verdict } from 'pompelmi';

package/packages/nextjs/index.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const { scanBuffer, Verdict } = require('pompelmi');
+
+/**
+ * Build a pompelmi scan options object from the plugin options,
+ * excluding non-scan keys.
+ */
+function buildScanOpts(options) {
+  const keys = ['host', 'port', 'socket', 'timeout', 'retries', 'retryDelay'];
+  const out = {};
+  for (const k of keys) {
+    if (options[k] !== undefined) out[k] = options[k];
+  }
+  return out;
+}
+
+/**
+ * Read a Request body as a Buffer.
+ * Supports Web API Request (App Router) and Node.js IncomingMessage (Pages Router).
+ */
+async function bodyBuffer(req) {
+  if (typeof req.arrayBuffer === 'function') {
+    // Web API Request (Next.js App Router)
+    const ab = await req.arrayBuffer();
+    return Buffer.from(ab);
+  }
+  // Node.js IncomingMessage (Pages Router)
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', c => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * App Router wrapper (Next.js 13+).
+ *
+ * Wraps a route handler so that the raw request body is scanned before the
+ * handler runs. req.pompelmiVerdict is set to the scan verdict symbol.
+ * If the body is malicious a 400 JSON response is returned immediately.
+ *
+ * @param {Function} handler  - async (req, ctx) => Response
+ * @param {object}   options  - ScanOptions (host, port, socket, …)
+ * @returns {Function} Next.js App Router handler
+ *
+ * @example
+ * // app/api/upload/route.js
+ * import { withPompelmi } from '@pompelmi/nextjs'
+ *
+ * export const POST = withPompelmi(async (req) => {
+ *   return Response.json({ ok: true })
+ * }, { host: 'localhost', port: 3310 })
+ */
+function withPompelmi(handler, options = {}) {
+  const scanOpts = buildScanOpts(options);
+
+  return async function pompelmiHandler(req, ctx) {
+    let buf;
+    try {
+      buf = await bodyBuffer(req);
+    } catch (_) {
+      return new Response(JSON.stringify({ error: 'Failed to read request body' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    const verdict = await scanBuffer(buf, scanOpts);
+
+    if (verdict === Verdict.Malicious) {
+      return new Response(JSON.stringify({ error: 'Malicious file detected' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    // Attach verdict so the handler can inspect it if needed
+    req.pompelmiVerdict = verdict;
+    return handler(req, ctx);
+  };
+}
+
+/**
+ * Pages Router wrapper (Next.js ≤ 12 / Pages API routes).
+ *
+ * Wraps a Next.js API handler so that the raw request body is scanned before
+ * the handler runs. req.pompelmiVerdict is set to the scan verdict symbol.
+ * If the body is malicious a 400 JSON response is sent immediately.
+ *
+ * @param {Function} handler  - (req, res) => void | Promise<void>
+ * @param {object}   options  - ScanOptions (host, port, socket, …)
+ * @returns {Function} Next.js Pages API handler
+ *
+ * @example
+ * // pages/api/upload.js
+ * import { withPompelmiHandler } from '@pompelmi/nextjs'
+ *
+ * async function handler(req, res) {
+ *   res.json({ ok: true })
+ * }
+ *
+ * export default withPompelmiHandler(handler, { host: 'localhost', port: 3310 })
+ */
+function withPompelmiHandler(handler, options = {}) {
+  const scanOpts = buildScanOpts(options);
+
+  return async function pompelmiPagesHandler(req, res) {
+    let buf;
+    try {
+      buf = await bodyBuffer(req);
+    } catch (_) {
+      res.status(400).json({ error: 'Failed to read request body' });
+      return;
+    }
+
+    const verdict = await scanBuffer(buf, scanOpts);
+
+    if (verdict === Verdict.Malicious) {
+      res.status(400).json({ error: 'Malicious file detected' });
+      return;
+    }
+
+    req.pompelmiVerdict = verdict;
+    return handler(req, res);
+  };
+}
+
+module.exports = { withPompelmi, withPompelmiHandler, Verdict };

package/packages/nextjs/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pompelmi/nextjs",
+  "version": "1.0.0",
+  "description": "Next.js middleware for pompelmi — in-process ClamAV virus scanning with zero extra dependencies",
+  "license": "ISC",
+  "author": "pompelmi contributors",
+  "homepage": "https://pompelmi.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pompelmi/pompelmi.git",
+    "directory": "packages/nextjs"
+  },
+  "keywords": [
+    "nextjs",
+    "next",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi",
+    "app-router",
+    "pages-router"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "next": ">=13",
+    "pompelmi": ">=1.13.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/Dashboard.js

@@ -0,0 +1,370 @@
+'use strict';
+
+const fs  = require('fs');
+const pkg = require('../package.json');
+
+// Inline grapefruit SVG (no external image dependency)
+const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" aria-hidden="true">
+  <circle cx="16" cy="16" r="15" fill="#e8846a"/>
+  <circle cx="16" cy="16" r="12" fill="#f5c4a0"/>
+  <circle cx="16" cy="16" r="9" fill="#f9d8c0"/>
+  <line x1="16" y1="7" x2="16" y2="25" stroke="#e8846a" stroke-width="0.8"/>
+  <line x1="7" y1="16" x2="25" y2="16" stroke="#e8846a" stroke-width="0.8"/>
+  <line x1="9.6" y1="9.6" x2="22.4" y2="22.4" stroke="#e8846a" stroke-width="0.8"/>
+  <line x1="22.4" y1="9.6" x2="9.6" y2="22.4" stroke="#e8846a" stroke-width="0.8"/>
+  <circle cx="16" cy="16" r="2.2" fill="#e8846a" opacity="0.6"/>
+  <rect x="14.5" y="1" width="3" height="4" rx="1" fill="#7a9e5a"/>
+  <ellipse cx="19" cy="2.5" rx="3.5" ry="1.4" fill="#7a9e5a" transform="rotate(-30 19 2.5)"/>
+</svg>`;
+
+/**
+ * Normalise input into a flat array of { file, verdict, viruses[] }.
+ * Accepts:
+ *   - Array<{ file, verdict, viruses? }>  (CLI / scanOne format)
+ *   - DirectoryScanResult { clean[], malicious[], errors[] }
+ */
+function normalise(scanResults) {
+  if (Array.isArray(scanResults)) return scanResults;
+
+  // DirectoryScanResult shape
+  const rows = [];
+  for (const f of (scanResults.clean    || [])) rows.push({ file: f, verdict: 'clean',    viruses: [] });
+  for (const f of (scanResults.malicious|| [])) rows.push({ file: f, verdict: 'infected', viruses: [] });
+  for (const f of (scanResults.errors   || [])) rows.push({ file: f, verdict: 'error',    viruses: [] });
+  return rows;
+}
+
+function escHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function badge(verdict) {
+  if (verdict === 'clean')    return `<span class="badge badge-clean">CLEAN</span>`;
+  if (verdict === 'infected') return `<span class="badge badge-infected">INFECTED</span>`;
+  return `<span class="badge badge-error">ERROR</span>`;
+}
+
+/**
+ * Generate a self-contained HTML security report.
+ *
+ * @param {object|Array} scanResults   - Array<{file,verdict,viruses?}> or DirectoryScanResult
+ * @param {object}       [options]
+ * @param {number}       [options.elapsed]       - Scan time in ms
+ * @param {string}       [options.clamdVersion]  - clamd version string if known
+ * @param {string}       [options.host]          - clamd host used
+ * @param {string}       [options.socket]        - UNIX socket used
+ * @param {string}       [options.outputPath]    - Write HTML to this path (optional)
+ * @returns {string} Self-contained HTML
+ */
+function generateDashboard(scanResults, options = {}) {
+  const rows     = normalise(scanResults);
+  const total    = rows.length;
+  const infected = rows.filter(r => r.verdict === 'infected').length;
+  const clean    = rows.filter(r => r.verdict === 'clean').length;
+  const errors   = rows.filter(r => r.verdict === 'error').length;
+  const elapsed  = options.elapsed != null ? options.elapsed : null;
+  const elapsedStr = elapsed != null ? (elapsed / 1000).toFixed(2) + 's' : '—';
+  const ts       = new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC';
+  const version  = pkg.version;
+  const allClean = infected === 0 && errors === 0;
+
+  const connectionStr = options.socket
+    ? escHtml(options.socket)
+    : options.host
+      ? escHtml(`${options.host}:${options.port || 3310}`)
+      : 'local clamscan';
+
+  const infectedRows = rows.filter(r => r.verdict === 'infected');
+
+  const fileTableRows = rows.map(r => `
+      <tr>
+        <td class="file-cell">${escHtml(r.file)}</td>
+        <td>${badge(r.verdict)}</td>
+        <td class="virus-cell">${r.viruses && r.viruses.length ? `<span class="virus-name">${escHtml(r.viruses[0])}</span>` : ''}</td>
+      </tr>`).join('');
+
+  const infectedSection = infectedRows.length === 0 ? '' : `
+    <section class="infected-section">
+      <h2>&#9888; Infected Files</h2>
+      <ul class="infected-list">
+        ${infectedRows.map(r => `
+        <li>
+          <span class="infected-path">${escHtml(r.file)}</span>
+          ${r.viruses && r.viruses.length ? `<br><span class="virus-label">Virus: <strong>${escHtml(r.viruses[0])}</strong></span>` : ''}
+        </li>`).join('')}
+      </ul>
+    </section>`;
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>pompelmi Security Report — ${ts}</title>
+<style>
+/* ── Reset & base ── */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+:root {
+  --bg:        #ffffff;
+  --bg2:       #f8f9fa;
+  --border:    #e2e8f0;
+  --text:      #0f172a;
+  --muted:     #64748b;
+  --clean:     #16a34a;
+  --clean-bg:  #dcfce7;
+  --infected:  #dc2626;
+  --inf-bg:    #fee2e2;
+  --error:     #d97706;
+  --err-bg:    #fef3c7;
+  --blue:      #2563eb;
+  --banner-clean-bg:   #dcfce7;
+  --banner-clean-txt:  #166534;
+  --banner-clean-bdr:  #86efac;
+  --banner-inf-bg:     #fee2e2;
+  --banner-inf-txt:    #991b1b;
+  --banner-inf-bdr:    #fca5a5;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg:        #0f172a;
+    --bg2:       #1e293b;
+    --border:    #334155;
+    --text:      #f1f5f9;
+    --muted:     #94a3b8;
+    --clean:     #4ade80;
+    --clean-bg:  #14532d;
+    --infected:  #f87171;
+    --inf-bg:    #7f1d1d;
+    --error:     #fbbf24;
+    --err-bg:    #78350f;
+    --banner-clean-bg:   #14532d;
+    --banner-clean-txt:  #bbf7d0;
+    --banner-clean-bdr:  #166534;
+    --banner-inf-bg:     #7f1d1d;
+    --banner-inf-txt:    #fecaca;
+    --banner-inf-bdr:    #991b1b;
+  }
+}
+body {
+  background: var(--bg);
+  color: var(--text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 15px;
+  line-height: 1.6;
+  padding: 32px 20px 64px;
+  max-width: 960px;
+  margin: 0 auto;
+}
+/* ── Header ── */
+.report-header {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 20px;
+  margin-bottom: 28px;
+}
+.report-header svg { flex-shrink: 0; }
+.report-title { font-size: 22px; font-weight: 700; letter-spacing: -0.3px; }
+.report-sub   { font-size: 13px; color: var(--muted); margin-top: 2px; }
+/* ── Banner ── */
+.banner {
+  border-radius: 10px;
+  padding: 18px 24px;
+  margin-bottom: 28px;
+  font-size: 18px;
+  font-weight: 700;
+  border: 1.5px solid;
+}
+.banner.clean    { background: var(--banner-clean-bg); color: var(--banner-clean-txt); border-color: var(--banner-clean-bdr); }
+.banner.infected { background: var(--banner-inf-bg);   color: var(--banner-inf-txt);   border-color: var(--banner-inf-bdr); }
+.banner-icon { font-size: 22px; margin-right: 8px; vertical-align: middle; }
+/* ── Stats grid ── */
+.stats-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 14px;
+  margin-bottom: 32px;
+}
+.stat-card {
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 18px 16px 14px;
+  text-align: center;
+}
+.stat-value { font-size: 36px; font-weight: 800; line-height: 1; }
+.stat-label { font-size: 12px; color: var(--muted); text-transform: uppercase; letter-spacing: 0.5px; margin-top: 6px; }
+.stat-total    .stat-value { color: var(--blue); }
+.stat-clean    .stat-value { color: var(--clean); }
+.stat-infected .stat-value { color: var(--infected); }
+.stat-errors   .stat-value { color: var(--error); }
+.stat-time     .stat-value { font-size: 24px; }
+/* ── Section headings ── */
+section { margin-bottom: 32px; }
+section h2 { font-size: 16px; font-weight: 600; margin-bottom: 12px; color: var(--text); }
+/* ── File table ── */
+.file-table { width: 100%; border-collapse: collapse; font-size: 13.5px; }
+.file-table th {
+  text-align: left;
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.4px;
+  color: var(--muted);
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg2);
+}
+.file-table td {
+  padding: 9px 12px;
+  border-bottom: 1px solid var(--border);
+  vertical-align: middle;
+  word-break: break-all;
+}
+.file-table tr:last-child td { border-bottom: none; }
+.file-table tr:hover td { background: var(--bg2); }
+.file-cell  { font-family: 'Menlo', 'Consolas', monospace; font-size: 12.5px; color: var(--muted); }
+.virus-cell { font-family: 'Menlo', 'Consolas', monospace; font-size: 12px; }
+.virus-name { color: var(--infected); }
+/* ── Badges ── */
+.badge {
+  display: inline-block;
+  padding: 2px 9px;
+  border-radius: 99px;
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.3px;
+  white-space: nowrap;
+}
+.badge-clean    { background: var(--clean-bg);   color: var(--clean); }
+.badge-infected { background: var(--inf-bg);      color: var(--infected); }
+.badge-error    { background: var(--err-bg);      color: var(--error); }
+/* ── Infected section ── */
+.infected-section h2 { color: var(--infected); }
+.infected-list { list-style: none; }
+.infected-list li {
+  background: var(--inf-bg);
+  border: 1px solid var(--banner-inf-bdr);
+  border-radius: 8px;
+  padding: 12px 16px;
+  margin-bottom: 10px;
+}
+.infected-path { font-family: 'Menlo', 'Consolas', monospace; font-size: 13px; color: var(--infected); }
+.virus-label   { font-size: 13px; color: var(--text); margin-top: 4px; display: block; }
+/* ── Metadata ── */
+.meta-table { border-collapse: collapse; font-size: 13.5px; }
+.meta-table td { padding: 6px 14px 6px 0; vertical-align: top; }
+.meta-table td:first-child { color: var(--muted); width: 160px; font-size: 12px; text-transform: uppercase; letter-spacing: 0.4px; padding-top: 8px; }
+/* ── Footer ── */
+.report-footer {
+  margin-top: 48px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--muted);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+/* ── Print ── */
+@media print {
+  body { padding: 0; max-width: 100%; color: #000; background: #fff; }
+  .banner.clean    { background: #dcfce7 !important; color: #166534 !important; }
+  .banner.infected { background: #fee2e2 !important; color: #991b1b !important; }
+  .stat-card { border: 1px solid #ccc; }
+  .badge-clean    { background: #dcfce7 !important; color: #166534 !important; }
+  .badge-infected { background: #fee2e2 !important; color: #991b1b !important; }
+  .badge-error    { background: #fef3c7 !important; color: #d97706 !important; }
+  .file-table tr:hover td { background: none; }
+}
+</style>
+</head>
+<body>
+
+<header class="report-header">
+  ${LOGO_SVG}
+  <div>
+    <div class="report-title">pompelmi Security Report</div>
+    <div class="report-sub">Generated ${ts}</div>
+  </div>
+</header>
+
+<div class="banner ${allClean ? 'clean' : 'infected'}">
+  <span class="banner-icon">${allClean ? '✅' : '🚨'}</span>
+  ${allClean
+    ? `All ${total} file${total === 1 ? '' : 's'} scanned — no threats detected`
+    : `${infected} infected file${infected === 1 ? '' : 's'} detected out of ${total} scanned`}
+</div>
+
+<div class="stats-grid">
+  <div class="stat-card stat-total">
+    <div class="stat-value">${total}</div>
+    <div class="stat-label">Files scanned</div>
+  </div>
+  <div class="stat-card stat-clean">
+    <div class="stat-value">${clean}</div>
+    <div class="stat-label">Clean</div>
+  </div>
+  <div class="stat-card stat-infected">
+    <div class="stat-value">${infected}</div>
+    <div class="stat-label">Infected</div>
+  </div>
+  <div class="stat-card stat-errors">
+    <div class="stat-value">${errors}</div>
+    <div class="stat-label">Errors</div>
+  </div>
+  <div class="stat-card stat-time">
+    <div class="stat-value">${elapsedStr}</div>
+    <div class="stat-label">Scan time</div>
+  </div>
+</div>
+
+${infectedSection}
+
+<section>
+  <h2>All Scanned Files</h2>
+  ${total === 0 ? '<p style="color:var(--muted)">No files scanned.</p>' : `
+  <table class="file-table">
+    <thead>
+      <tr>
+        <th>File</th>
+        <th>Verdict</th>
+        <th>Threat name</th>
+      </tr>
+    </thead>
+    <tbody>${fileTableRows}</tbody>
+  </table>`}
+</section>
+
+<section>
+  <h2>Scan Metadata</h2>
+  <table class="meta-table">
+    <tr><td>Timestamp</td><td>${ts}</td></tr>
+    <tr><td>Connection</td><td>${connectionStr}</td></tr>
+    ${options.clamdVersion ? `<tr><td>ClamAV</td><td>${escHtml(options.clamdVersion)}</td></tr>` : ''}
+    <tr><td>pompelmi</td><td>v${escHtml(version)}</td></tr>
+  </table>
+</section>
+
+<footer class="report-footer">
+  ${LOGO_SVG.replace('width="32" height="32"', 'width="18" height="18"')}
+  Generated by <strong>pompelmi v${escHtml(version)}</strong> &mdash;
+  <a href="https://pompelmi.app" style="color:inherit">pompelmi.app</a>
+</footer>
+
+</body>
+</html>`;
+
+  if (options.outputPath) {
+    fs.writeFileSync(options.outputPath, html, 'utf8');
+  }
+
+  return html;
+}
+
+module.exports = { generateDashboard };

package/src/ShareCard.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs  = require('fs');
+const pkg = require('../package.json');
+
+/**
+ * Normalise scan results (same shapes as Dashboard.js).
+ * Returns { total, infected, clean, errors }.
+ */
+function stats(scanResults) {
+  if (Array.isArray(scanResults)) {
+    const total    = scanResults.length;
+    const infected = scanResults.filter(r => r.verdict === 'infected').length;
+    const errors   = scanResults.filter(r => r.verdict === 'error').length;
+    return { total, infected, clean: total - infected - errors, errors };
+  }
+  // DirectoryScanResult
+  const clean    = (scanResults.clean    || []).length;
+  const infected = (scanResults.malicious|| []).length;
+  const errors   = (scanResults.errors   || []).length;
+  return { total: clean + infected + errors, infected, clean, errors };
+}
+
+function escXml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Generate a shareable SVG card showing the scan result.
+ *
+ * @param {object|Array} scanResults  - Array<{file,verdict}> or DirectoryScanResult
+ * @param {object}       [options]
+ * @param {string}       [options.outputPath]  - Write SVG to this path (optional)
+ * @returns {string} SVG markup
+ */
+function generateShareCard(scanResults, options = {}) {
+  const { total, infected, clean } = stats(scanResults);
+  const version  = pkg.version;
+  const date     = new Date().toISOString().slice(0, 10);
+  const allClean = infected === 0;
+
+  // Card dimensions
+  const W = 560;
+  const H = 200;
+
+  // Theme
+  const bgColor     = allClean ? '#f0fdf4' : '#fff1f2';
+  const borderColor = allClean ? '#86efac' : '#fca5a5';
+  const accentColor = allClean ? '#16a34a' : '#dc2626';
+  const headlineTxt = allClean
+    ? `${total} file${total === 1 ? '' : 's'} scanned — All clean`
+    : `${total} file${total === 1 ? '' : 's'} scanned — ${infected} infected`;
+  const statusIcon  = allClean ? '✅' : '🚨';
+
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" role="img" aria-label="pompelmi scan result: ${escXml(headlineTxt)}">
+  <defs>
+    <style>
+      .card-font { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; }
+    </style>
+  </defs>
+
+  <!-- Background -->
+  <rect width="${W}" height="${H}" rx="14" ry="14" fill="${bgColor}" stroke="${borderColor}" stroke-width="2"/>
+
+  <!-- Grapefruit logo (top-left) -->
+  <g transform="translate(24, 24)">
+    <circle cx="16" cy="16" r="15" fill="#e8846a"/>
+    <circle cx="16" cy="16" r="12" fill="#f5c4a0"/>
+    <circle cx="16" cy="16" r="9"  fill="#f9d8c0"/>
+    <line x1="16" y1="7"   x2="16" y2="25" stroke="#e8846a" stroke-width="0.8"/>
+    <line x1="7"  y1="16"  x2="25" y2="16" stroke="#e8846a" stroke-width="0.8"/>
+    <line x1="9.6" y1="9.6"  x2="22.4" y2="22.4" stroke="#e8846a" stroke-width="0.8"/>
+    <line x1="22.4" y1="9.6" x2="9.6"  y2="22.4" stroke="#e8846a" stroke-width="0.8"/>
+    <circle cx="16" cy="16" r="2.2" fill="#e8846a" opacity="0.6"/>
+    <rect x="14.5" y="1" width="3" height="4" rx="1" fill="#7a9e5a"/>
+    <ellipse cx="19" cy="2.5" rx="3.5" ry="1.4" fill="#7a9e5a" transform="rotate(-30 19 2.5)"/>
+  </g>
+
+  <!-- Brand name -->
+  <text x="64" y="39" class="card-font" font-size="15" font-weight="700" fill="#0f172a">pompelmi</text>
+  <text x="64" y="54" class="card-font" font-size="11" fill="#64748b">Virus scan report</text>
+
+  <!-- Status icon -->
+  <text x="${W - 32}" y="46" class="card-font" font-size="28" text-anchor="end">${statusIcon}</text>
+
+  <!-- Divider -->
+  <line x1="24" y1="76" x2="${W - 24}" y2="76" stroke="${borderColor}" stroke-width="1.5"/>
+
+  <!-- Headline -->
+  <text x="${W / 2}" y="112" class="card-font" font-size="20" font-weight="700"
+        fill="${accentColor}" text-anchor="middle">${escXml(headlineTxt)}</text>
+
+  <!-- Stats row -->
+  <text x="112" y="145" class="card-font" font-size="28" font-weight="800" fill="#2563eb" text-anchor="middle">${total}</text>
+  <text x="112" y="162" class="card-font" font-size="11" fill="#64748b" text-anchor="middle">TOTAL</text>
+
+  <text x="224" y="145" class="card-font" font-size="28" font-weight="800" fill="#16a34a" text-anchor="middle">${clean}</text>
+  <text x="224" y="162" class="card-font" font-size="11" fill="#64748b" text-anchor="middle">CLEAN</text>
+
+  <text x="336" y="145" class="card-font" font-size="28" font-weight="800" fill="#dc2626" text-anchor="middle">${infected}</text>
+  <text x="336" y="162" class="card-font" font-size="11" fill="#64748b" text-anchor="middle">INFECTED</text>
+
+  <!-- Separator lines between stats -->
+  <line x1="170" y1="130" x2="170" y2="168" stroke="${borderColor}" stroke-width="1"/>
+  <line x1="282" y1="130" x2="282" y2="168" stroke="${borderColor}" stroke-width="1"/>
+
+  <!-- Footer: date + version -->
+  <line x1="24" y1="178" x2="${W - 24}" y2="178" stroke="${borderColor}" stroke-width="1"/>
+  <text x="24" y="193" class="card-font" font-size="11" fill="#94a3b8">${escXml(date)}</text>
+  <text x="${W - 24}" y="193" class="card-font" font-size="11" fill="#94a3b8" text-anchor="end">pompelmi v${escXml(version)} • pompelmi.app</text>
+</svg>`;
+
+  if (options.outputPath) {
+    fs.writeFileSync(options.outputPath, svg, 'utf8');
+  }
+
+  return svg;
+}
+
+module.exports = { generateShareCard };

package/src/index.js

@@ -6,5 +6,7 @@ const { createPool }                                  = require('./ClamdPool.js'
 const { watch }                                       = require('./Watcher.js');
 const { notify }                                      = require('./WebhookNotifier.js');
 const { createScanner }                               = require('./ScanEmitter.js');
+const { generateDashboard }                           = require('./Dashboard.js');
+const { generateShareCard }                           = require('./ShareCard.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware, scanS3, createPool, watch, notify, createScanner, generateDashboard, generateShareCard };

package/types/index.d.ts

@@ -215,3 +215,54 @@ export interface ScanEmitter extends EventEmitter {
  * scanner.scanDirectory('/uploads');
  */
 export declare function createScanner(options?: ScanOptions): ScanEmitter;
+
+/** Options for generateDashboard */
+export interface DashboardOptions {
+  /** Scan duration in milliseconds */
+  elapsed?: number;
+  /** ClamAV version string, if available */
+  clamdVersion?: string;
+  /** clamd host used for the scan */
+  host?: string;
+  /** clamd port used for the scan */
+  port?: number;
+  /** UNIX socket used for the scan */
+  socket?: string;
+  /** Write the HTML to this path (optional) */
+  outputPath?: string;
+}
+
+/** A scan result row (output of the CLI or manual scan loop) */
+export interface ScanRow {
+  file: string;
+  verdict: 'clean' | 'infected' | 'error';
+  viruses?: string[];
+}
+
+/**
+ * Generate a self-contained HTML security dashboard report.
+ * Accepts an array of ScanRow objects or a DirectoryScanResult.
+ * When outputPath is set, the file is also written to disk.
+ * Returns the HTML string.
+ */
+export declare function generateDashboard(
+  scanResults: ScanRow[] | DirectoryScanResult,
+  options?: DashboardOptions
+): string;
+
+/** Options for generateShareCard */
+export interface ShareCardOptions {
+  /** Write the SVG to this path (optional) */
+  outputPath?: string;
+}
+
+/**
+ * Generate a shareable SVG card showing the scan summary.
+ * Suitable for embedding in READMEs or sharing on social media.
+ * When outputPath is set, the file is also written to disk.
+ * Returns the SVG string.
+ */
+export declare function generateShareCard(
+  scanResults: ScanRow[] | DirectoryScanResult,
+  options?: ShareCardOptions
+): string;