pompelmi 1.12.1 → 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.
@@ -86,13 +89,51 @@ Most integrations require parsing ClamAV's stdout with regex, managing a clamd d
 - Symbol-based verdicts (`Verdict.Clean` / `Verdict.Malicious` / `Verdict.ScanError`) — typo-proof comparisons
 - Full clamd support via the INSTREAM protocol — TCP (`host`/`port`) or UNIX socket (`socket`) with configurable timeout
 - Built-in helpers to install ClamAV and update virus definitions programmatically
-- Works with Express, Fastify, and any other Node.js HTTP framework
+- Works with Express, Fastify, NestJS, and any other Node.js HTTP framework
 - Zero runtime dependencies — ships nothing but source code
 - Tested with EICAR standard antivirus test files
 - CommonJS module; TypeScript type declarations available inline
 
 ---
 
+## Framework Integrations
+
+Official integration packages for popular frameworks:
+
+| Package | Framework | Install |
+|---------|-----------|---------|
+| [@pompelmi/nestjs](./packages/nestjs/) | NestJS | `npm i @pompelmi/nestjs` |
+| [@pompelmi/fastify](./packages/fastify/) | Fastify | `npm i @pompelmi/fastify` |
+
+### NestJS
+
+```ts
+import { PompelmiModule, PompelmiService } from '@pompelmi/nestjs';
+
+// app.module.ts
+@Module({ imports: [PompelmiModule.forRoot({ host: 'localhost', port: 3310 })] })
+export class AppModule {}
+
+// upload.service.ts
+constructor(private readonly pompelmi: PompelmiService) {}
+const result = await this.pompelmi.scanBuffer(file.buffer);
+```
+
+### Fastify
+
+```js
+const pompelmi = require('@pompelmi/fastify');
+await fastify.register(pompelmi, { host: 'localhost', port: 3310 });
+
+// Scan manually
+const result = await fastify.pompelmi.scanBuffer(buffer);
+
+// Or use the preHandler hook
+fastify.post('/upload', { preHandler: fastify.pompelmi.preHandler({ field: 'file' }) }, handler);
+```
+
+---
+
 ## Requirements
 
 - **Node.js** — any LTS release (no native addons, no C++ bindings)
@@ -465,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.12.1",
+  "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/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/fastify/README.md

@@ -0,0 +1,115 @@
+# @pompelmi/fastify
+
+Fastify plugin for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+## Installation
+
+```bash
+npm install @pompelmi/fastify pompelmi
+```
+
+## Plugin Setup
+
+```js
+const fastify = require('fastify')();
+const pompelmi = require('@pompelmi/fastify');
+
+await fastify.register(pompelmi, {
+  host: 'localhost',
+  port: 3310,
+  timeout: 5000,
+});
+```
+
+### UNIX socket
+
+```js
+await fastify.register(pompelmi, {
+  socket: '/run/clamav/clamd.sock',
+});
+```
+
+## Decorated Instance
+
+After registration, `fastify.pompelmi` is available everywhere:
+
+```js
+// Scan a file path
+const result = await fastify.pompelmi.scan('/uploads/report.pdf');
+
+// Scan an in-memory Buffer
+const result = await fastify.pompelmi.scanBuffer(file.buffer);
+
+// Scan a Readable stream
+const result = await fastify.pompelmi.scanStream(readableStream);
+
+// Compare against Verdict symbols
+const { Verdict } = require('pompelmi');
+if (result === Verdict.Malicious) { /* ... */ }
+```
+
+## preHandler Hook
+
+Use the built-in `preHandler` helper to scan uploaded files before your route handler runs:
+
+```js
+const multipart = require('@fastify/multipart');
+await fastify.register(multipart);
+
+fastify.post('/upload', {
+  preHandler: fastify.pompelmi.preHandler({ field: 'file' }),
+}, async (request, reply) => {
+  return { message: 'File is clean' };
+});
+```
+
+When a malicious file is detected the preHandler automatically responds with HTTP 400:
+
+```json
+{ "error": "Malicious file detected" }
+```
+
+### Custom malicious handler
+
+```js
+fastify.post('/upload', {
+  preHandler: fastify.pompelmi.preHandler({
+    field: 'file',
+    onMalicious: async (request, reply) => {
+      request.log.warn({ ip: request.ip }, 'malicious upload blocked');
+      reply.code(422).send({ error: 'File rejected by security scan' });
+    },
+  }),
+}, handler);
+```
+
+## Configuration Reference
+
+All options are forwarded to pompelmi's `ScanOptions`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | — | clamd hostname (enables TCP mode) |
+| `port` | `number` | `3310` | clamd port |
+| `socket` | `string` | — | UNIX domain socket path |
+| `timeout` | `number` | `15000` | Socket idle timeout in ms |
+| `retries` | `number` | `0` | Number of retry attempts |
+| `retryDelay` | `number` | `1000` | Delay between retries in ms |
+
+## TypeScript
+
+```ts
+import fastify from 'fastify';
+import pompelmi from '@pompelmi/fastify';
+import { Verdict } from 'pompelmi';
+
+const app = fastify();
+await app.register(pompelmi, { host: 'localhost', port: 3310 });
+
+const result = await app.pompelmi.scanBuffer(buffer);
+if (result === Verdict.Malicious) throw new Error('Infected');
+```
+
+## License
+
+ISC — see root [LICENSE](../../LICENSE).

package/packages/fastify/index.d.ts

@@ -0,0 +1,27 @@
+import { FastifyPluginCallback } from 'fastify';
+import { ScanOptions, VerdictValue } from 'pompelmi';
+import { Readable } from 'stream';
+
+export interface PompelmiPreHandlerOptions {
+  /** Multer/Busboy field name to look for the uploaded file (default: 'file') */
+  field?: string;
+  /** Custom handler called instead of the default 400 response on malicious files */
+  onMalicious?: (request: any, reply: any) => void | Promise<void>;
+}
+
+export interface PompelmiDecorator {
+  Verdict: { readonly Clean: unique symbol; readonly Malicious: unique symbol; readonly ScanError: unique symbol };
+  scan(filePath: string): Promise<VerdictValue>;
+  scanBuffer(buffer: Buffer): Promise<VerdictValue>;
+  scanStream(stream: Readable): Promise<VerdictValue>;
+  preHandler(opts?: PompelmiPreHandlerOptions): (request: any, reply: any) => Promise<void>;
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    pompelmi: PompelmiDecorator;
+  }
+}
+
+declare const pompelmiPlugin: FastifyPluginCallback<ScanOptions>;
+export = pompelmiPlugin;

package/packages/fastify/index.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { scan, scanBuffer, scanStream, Verdict } = require('pompelmi');
+
+function buildScanOptions(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;
+}
+
+function pompelmiPlugin(fastify, options, done) {
+  const scanOptions = buildScanOptions(options || {});
+
+  const pompelmi = {
+    Verdict,
+
+    scan(filePath) {
+      return scan(filePath, scanOptions);
+    },
+
+    scanBuffer(buffer) {
+      return scanBuffer(buffer, scanOptions);
+    },
+
+    scanStream(stream) {
+      return scanStream(stream, scanOptions);
+    },
+
+    preHandler(opts) {
+      const { field = 'file', onMalicious } = opts || {};
+      return async function pompelmiPreHandler(request, reply) {
+        const body = request.body;
+        if (!body) return;
+        const raw = body[field];
+        if (!raw) return;
+        const buffer = Buffer.isBuffer(raw) ? raw : (raw._buf || raw.data || null);
+        if (!buffer) return;
+        const result = await scanBuffer(buffer, scanOptions);
+        if (result === Verdict.Malicious) {
+          if (typeof onMalicious === 'function') return onMalicious(request, reply);
+          return reply.code(400).send({ error: 'Malicious file detected' });
+        }
+      };
+    },
+  };
+
+  fastify.decorate('pompelmi', pompelmi);
+  done();
+}
+
+pompelmiPlugin[Symbol.for('skip-override')] = true;
+
+module.exports = pompelmiPlugin;

package/packages/fastify/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pompelmi/fastify",
+  "version": "1.0.0",
+  "description": "Fastify plugin 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/fastify"
+  },
+  "keywords": [
+    "fastify",
+    "fastify-plugin",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "fastify": ">=4",
+    "pompelmi": ">=1.12.0"
+  },
+  "peerDependenciesMeta": {
+    "fastify": { "optional": false }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/nestjs/README.md

@@ -0,0 +1,150 @@
+# @pompelmi/nestjs
+
+NestJS module for [pompelmi](https://pompelmi.app) — in-process ClamAV virus scanning with zero extra dependencies.
+
+## Installation
+
+```bash
+npm install @pompelmi/nestjs pompelmi
+```
+
+Peer dependencies (install if not already present):
+
+```bash
+npm install @nestjs/common @nestjs/core
+```
+
+## Module Setup
+
+Register the module globally in your root `AppModule`:
+
+```ts
+import { Module } from '@nestjs/common';
+import { PompelmiModule } from '@pompelmi/nestjs';
+
+@Module({
+  imports: [
+    PompelmiModule.forRoot({
+      host: 'localhost',
+      port: 3310,
+      timeout: 5000,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async configuration (`forRootAsync`)
+
+```ts
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { PompelmiModule } from '@pompelmi/nestjs';
+
+PompelmiModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    host: config.get('CLAMAV_HOST'),
+    port: config.get<number>('CLAMAV_PORT'),
+  }),
+  inject: [ConfigService],
+})
+```
+
+## Service Usage
+
+Inject `PompelmiService` into any provider:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { PompelmiService } from '@pompelmi/nestjs';
+import { Verdict } from 'pompelmi';
+
+@Injectable()
+export class UploadService {
+  constructor(private readonly pompelmi: PompelmiService) {}
+
+  async processUpload(buffer: Buffer) {
+    const result = await this.pompelmi.scanBuffer(buffer);
+    if (result === Verdict.Malicious) throw new Error('Malicious file');
+
+    // Or use the convenience helper:
+    const isMalware = await this.pompelmi.isMalware(buffer);
+  }
+}
+```
+
+### Service API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `scan` | `scan(filePath: string): Promise<VerdictValue>` | Scan a file by path |
+| `scanBuffer` | `scanBuffer(buffer: Buffer): Promise<VerdictValue>` | Scan an in-memory Buffer |
+| `scanStream` | `scanStream(stream: Readable): Promise<VerdictValue>` | Scan a Readable stream |
+| `isMalware` | `isMalware(buffer: Buffer): Promise<boolean>` | Returns `true` when infected |
+
+## Guard Usage
+
+`PompelmiGuard` implements `CanActivate`. It reads `req.file` (or `req.files[0]`) set by Multer and blocks the request (`canActivate → false`) when the file is malicious.
+
+```ts
+import { Controller, Post, UploadedFile, UseGuards, UseInterceptors } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { PompelmiGuard } from '@pompelmi/nestjs';
+
+@Controller('upload')
+export class UploadController {
+  @Post()
+  @UseGuards(PompelmiGuard)
+  @UseInterceptors(FileInterceptor('file'))
+  uploadFile(@UploadedFile() file: Express.Multer.File) {
+    return { message: 'File is clean', size: file.size };
+  }
+}
+```
+
+Register `PompelmiGuard` as a provider in your module so NestJS can inject `PompelmiService`:
+
+```ts
+@Module({
+  imports: [PompelmiModule.forRoot({ host: 'localhost', port: 3310 })],
+  providers: [PompelmiGuard],
+  controllers: [UploadController],
+})
+export class UploadModule {}
+```
+
+## Interceptor Usage
+
+`PompelmiInterceptor` is an alternative to the guard. It throws `BadRequestException` when a malicious file is detected, which NestJS maps to an HTTP 400 response.
+
+```ts
+import { Controller, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { PompelmiInterceptor } from '@pompelmi/nestjs';
+
+@Controller('upload')
+export class UploadController {
+  @Post()
+  @UseInterceptors(FileInterceptor('file'), PompelmiInterceptor)
+  uploadFile(@UploadedFile() file: Express.Multer.File) {
+    return { message: 'File is clean' };
+  }
+}
+```
+
+## Configuration Reference
+
+All options are forwarded to pompelmi's `ScanOptions`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | — | clamd hostname (enables TCP mode) |
+| `port` | `number` | `3310` | clamd port |
+| `socket` | `string` | — | UNIX domain socket path |
+| `timeout` | `number` | `15000` | Socket idle timeout in ms |
+| `retries` | `number` | `0` | Number of retry attempts |
+| `retryDelay` | `number` | `1000` | Delay between retries in ms |
+
+## License
+
+ISC — see root [LICENSE](../../LICENSE).

package/packages/nestjs/index.d.ts

@@ -0,0 +1,37 @@
+import { DynamicModule, CanActivate, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { ScanOptions, VerdictValue } from 'pompelmi';
+import { Observable } from 'rxjs';
+
+export declare const POMPELMI_OPTIONS = 'POMPELMI_OPTIONS';
+
+export interface PompelmiModuleOptions extends ScanOptions {}
+
+export interface PompelmiModuleAsyncOptions {
+  imports?: any[];
+  useFactory: (...args: any[]) => PompelmiModuleOptions | Promise<PompelmiModuleOptions>;
+  inject?: any[];
+}
+
+export declare class PompelmiModule {
+  static forRoot(options?: PompelmiModuleOptions): DynamicModule;
+  static forRootAsync(options: PompelmiModuleAsyncOptions): DynamicModule;
+}
+
+export declare class PompelmiService {
+  readonly options: PompelmiModuleOptions;
+  constructor(options?: PompelmiModuleOptions);
+  scan(filePath: string): Promise<VerdictValue>;
+  scanBuffer(buffer: Buffer): Promise<VerdictValue>;
+  scanStream(stream: import('stream').Readable): Promise<VerdictValue>;
+  isMalware(buffer: Buffer): Promise<boolean>;
+}
+
+export declare class PompelmiGuard implements CanActivate {
+  constructor(pompelmiService: PompelmiService);
+  canActivate(context: ExecutionContext): Promise<boolean>;
+}
+
+export declare class PompelmiInterceptor implements NestInterceptor {
+  constructor(pompelmiService: PompelmiService);
+  intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>>;
+}

package/packages/nestjs/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pompelmi/nestjs",
+  "version": "1.0.0",
+  "description": "NestJS module for pompelmi — in-process 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/nestjs"
+  },
+  "keywords": [
+    "nestjs",
+    "nestjs-module",
+    "clamav",
+    "antivirus",
+    "virus-scan",
+    "malware",
+    "file-upload",
+    "security",
+    "pompelmi"
+  ],
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "node --test test/index.test.js"
+  },
+  "peerDependencies": {
+    "@nestjs/common": ">=9",
+    "@nestjs/core": ">=9",
+    "pompelmi": ">=1.12.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/packages/nestjs/src/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { PompelmiModule, POMPELMI_OPTIONS } = require('./pompelmi.module');
+const { PompelmiService }                  = require('./pompelmi.service');
+const { PompelmiGuard }                    = require('./pompelmi.guard');
+const { PompelmiInterceptor }              = require('./pompelmi.interceptor');
+
+module.exports = { PompelmiModule, PompelmiService, PompelmiGuard, PompelmiInterceptor, POMPELMI_OPTIONS };

package/packages/nestjs/src/pompelmi.guard.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { Verdict } = require('pompelmi');
+
+class PompelmiGuard {
+  constructor(pompelmiService) {
+    this.pompelmiService = pompelmiService;
+  }
+
+  async canActivate(context) {
+    const request = context.switchToHttp().getRequest();
+    const file = request.file || (Array.isArray(request.files) && request.files[0]);
+    if (!file) return true;
+    const result = await this.pompelmiService.scanBuffer(file.buffer);
+    return result !== Verdict.Malicious;
+  }
+}
+
+module.exports = { PompelmiGuard };

package/packages/nestjs/src/pompelmi.interceptor.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { BadRequestException } = require('@nestjs/common');
+const { Verdict } = require('pompelmi');
+
+class PompelmiInterceptor {
+  constructor(pompelmiService) {
+    this.pompelmiService = pompelmiService;
+  }
+
+  async intercept(context, next) {
+    const request = context.switchToHttp().getRequest();
+    const file = request.file || (Array.isArray(request.files) && request.files[0]);
+    if (file) {
+      const result = await this.pompelmiService.scanBuffer(file.buffer);
+      if (result === Verdict.Malicious) {
+        throw new BadRequestException('Malicious file detected');
+      }
+    }
+    return next.handle();
+  }
+}
+
+module.exports = { PompelmiInterceptor };