Pompelmi releases

What's New

Official Docker Image

pompelmi/scanner is now available on Docker Hub.
A self-contained image with ClamAV, clamd, and an HTTP scan API
built in — no configuration required.

docker pull pompelmi/scanner
docker run -p 8080:8080 pompelmi/scanner

# Scan a file via HTTP
curl -F "file=@./document.pdf" http://localhost:8080/scan
# {"verdict":"clean","file":"document.pdf","viruses":[]}

# Health check
curl http://localhost:8080/health
# {"status":"ok","clamd":"running"}

Security Scorecard

Grade your upload security configuration from A to F:

const { generateScorecard } = require('pompelmi')

const scorecard = await generateScorecard({
  scanEnabled: true,
  mimeTypeAllowlist: ['image/jpeg', 'image/png', 'application/pdf'],
  fileSizeLimit: 10 * 1024 * 1024,
  diskWriteBeforeScan: false,
  scanErrorBehavior: 'reject',
  clamdUnavailableBehavior: 'reject'
})

console.log(scorecard.grade)    // 'A'
console.log(scorecard.score)    // 95
console.log(scorecard.findings) // array of passed/failed checks

From the CLI:

npx pompelmi scorecard --config ./pompelmi.config.js

VS Code Extension

A VS Code extension scaffold is now available at packages/vscode/.
Right-click any file in the IDE and select "Scan with pompelmi".
Marketplace publishing coming in a future release.

Quarantine Mode

Automatically move infected files to a quarantine directory:

watch('/uploads', {
  host: 'localhost',
  port: 3310,
  quarantine: '/quarantine'
}, {
  onMalicious: 'quarantine'
})

npx pompelmi watch ./uploads --quarantine ./quarantine

Each quarantined file gets a sidecar JSON with original path,
virus name, timestamp, and SHA256 hash.

Changes

• docker/ — Dockerfile, entrypoint.sh, HTTP scan API server
• .github/workflows/docker.yml — automated Docker Hub publishing
• src/Scorecard.js — A-F grading for upload security config
• src/Watcher.js — quarantine mode support
• packages/vscode/ — VS Code extension scaffold
• bin/pompelmi.js — scorecard command and --quarantine flag
• docs/docker-image.html — Docker Hub image guide
• docs/scorecard.html — scorecard API and CLI reference
• docs/vscode.html — VS Code extension guide
• docs/*.html — navbar updated across all pages
• README.md — Docker Hub badge, new features

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.17.0...v1.18.0

What's New

Native ESM Support

pompelmi now supports both CommonJS and ES Modules natively.
No more createRequire workarounds.

// ESM (new)
import { scan, scanBuffer, Verdict } from 'pompelmi'

// CommonJS (unchanged)
const { scan, scanBuffer, Verdict } = require('pompelmi')

Deno Support

pompelmi now works natively in Deno:

import { scan, Verdict } from 'npm:pompelmi'

const result = await scan('./file.pdf', {
  host: 'localhost',
  port: 3310
})

Cloudflare Workers Package

@pompelmi/cloudflare is now available on npm.
Scan file uploads at the edge via a remote clamd instance.

npm install @pompelmi/cloudflare

import { scanBuffer } from '@pompelmi/cloudflare'

export default {
  async fetch(request, env) {
    const formData = await request.formData()
    const file = formData.get('file')
    const buffer = await file.arrayBuffer()

    const result = await scanBuffer(buffer, {
      host: env.CLAMAV_HOST,
      port: parseInt(env.CLAMAV_PORT)
    })

    if (result !== 'clean') {
      return new Response('File rejected', { status: 422 })
    }

    return new Response('OK')
  }
}

Landing Page Improvements

pompelmi.app now shows:

• Runtime compatibility logos: Node.js • Bun • Deno • Cloudflare Workers
• Framework logos grid: Express • Fastify • NestJS • Next.js • Hono • Remix • SvelteKit
• Live GitHub stars and npm downloads badges

GitHub Sponsors

A Sponsor button is now visible on the GitHub repo via .github/FUNDING.yml.

Runtime Support

| Runtime | Status |
|---------|--------|
| Node.js | ✅ |
| Bun | ✅ |
| Deno | ✅ |
| Cloudflare Workers | ✅ via @pompelmi/cloudflare |

Framework Integrations

| Package | Framework |
|---------|-----------|
| @pompelmi/nestjs | NestJS |
| @pompelmi/fastify | Fastify |
| @pompelmi/nextjs | Next.js |
| @pompelmi/hono | Hono |
| @pompelmi/remix | Remix |
| @pompelmi/sveltekit | SvelteKit |
| @pompelmi/cloudflare | Cloudflare Workers |
| @pompelmi/testing | Jest / Vitest / Node |

Changes

• src/index.mjs — native ESM entry point
• package.json — dual CJS/ESM exports field
• deno.json — Deno configuration
• packages/cloudflare/ — Cloudflare Workers package
• .github/FUNDING.yml — GitHub Sponsors button
• docs/deno.html — Deno usage guide
• docs/cloudflare.html — Cloudflare Workers guide
• docs/*.html — navbar updated
• index.html — landing page runtime and framework logos

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.16.0...v1.17.0

What's New

Remix Plugin

@pompelmi/remix is now available on npm.

npm install @pompelmi/remix pompelmi

import { withPompelmi } from '@pompelmi/remix'

export const action = withPompelmi(async ({ request }) => {
  const formData = await request.formData()
  return json({ ok: true })
}, { host: 'localhost', port: 3310 })

SvelteKit Plugin

@pompelmi/sveltekit is now available on npm.

npm install @pompelmi/sveltekit pompelmi

import { withPompelmi } from '@pompelmi/sveltekit'

export const POST = withPompelmi(async ({ request }) => {
  return new Response(JSON.stringify({ ok: true }))
}, { host: 'localhost', port: 3310 })

Scan Statistics

Track scan activity in-memory with createStats():

const { createStats } = require('pompelmi')

const stats = createStats()
const result = await stats.track(() => scan(filePath, options))

stats.get()
// {
//   totalScanned: 1247,
//   totalClean: 1245,
//   totalInfected: 2,
//   totalErrors: 0,
//   avgScanTimeMs: 45,
//   lastScanAt: '2026-05-07T...',
//   uptime: 3600000
// }

app.get('/pompelmi/stats', (req, res) => res.json(stats.get()))

Navbar Fix

All docs/ HTML pages now have a consistent navbar linking to every
page in the documentation site. Previously several pages were missing
links to newer sections.

Framework Integrations

| Package | Framework |
|---------|-----------|
| @pompelmi/nestjs | NestJS |
| @pompelmi/fastify | Fastify |
| @pompelmi/nextjs | Next.js |
| @pompelmi/hono | Hono |
| @pompelmi/remix | Remix |
| @pompelmi/sveltekit | SvelteKit |
| @pompelmi/testing | Jest / Vitest / Node |

Changes

• packages/remix/ — Remix action wrapper
• packages/sveltekit/ — SvelteKit server handler and hook
• src/Stats.js — in-memory scan statistics tracker
• docs/remix.html, docs/sveltekit.html, docs/stats.html — new docs pages
• docs/*.html — canonical navbar across all pages
• README.md — updated framework integrations table
• .github/workflows/ci.yml — updated to Node.js 24 actions

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.15.0...v1.16.0

What's New

Hono Plugin

@pompelmi/hono is now available on npm. Works on Node.js, Bun,
and Cloudflare Workers.

npm install @pompelmi/hono pompelmi

import { pompelmiMiddleware } from '@pompelmi/hono'
import { Hono } from 'hono'

const app = new Hono()

app.use('/upload/*', pompelmiMiddleware({
  host: 'localhost',
  port: 3310,
  field: 'file',
  onInfected: (c) => c.json({ error: 'Malware detected' }, 422)
}))

Bun Support

pompelmi now officially supports the Bun runtime. The core library
detects Bun at runtime and uses native Bun APIs where available for
faster file reads. Bun is now included in the CI test matrix.

bun install pompelmi
bun run your-app.js

Interactive Demo

A browser-based demo is now available at
pompelmi.app/demo — try the pompelmi
terminal UI and see all three verdicts without installing anything.

Testing Utilities

@pompelmi/testing provides mock utilities for unit testing
applications that use pompelmi.

npm install --save-dev @pompelmi/testing

const { mockClean, mockInfected, mockScanError } = require('@pompelmi/testing')

// In your tests
it('rejects infected files', async () => {
  const scanner = mockInfected('Win.Malware.Test')
  const result = await scanner.scanBuffer(buffer)
  expect(result).toBe(Verdict.Malicious)
})

Works with Jest, Vitest, and the Node.js built-in test runner.

Comparison Page

Side-by-side comparison of pompelmi against other Node.js ClamAV
integrations at docs/comparison.html.

Framework Integrations

| Package | Framework |
|---------|-----------|
| @pompelmi/nestjs | NestJS |
| @pompelmi/fastify | Fastify |
| @pompelmi/nextjs | Next.js |
| @pompelmi/hono | Hono |
| @pompelmi/testing | Jest / Vitest / Node |

Changes

• packages/hono/ — Hono middleware plugin
• packages/testing/ — mock utilities for unit testing
• src/ClamdScanner.js, BufferScanner.js, StreamScanner.js — Bun runtime detection
• .github/workflows/ci.yml — Bun added to test matrix
• docs/demo.html — interactive browser demo
• docs/comparison.html — comparison with alternatives
• docs/*.html — navbar updated across all pages
• README.md — Bun support, demo link, updated integrations table

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.14.0...v1.15.0

Added

• HTML security dashboard — generateDashboard(scanResults, options) generates a self-contained HTML report with summary stats, colour-coded status banner, file table with verdict badges, infected files section, scan metadata, dark mode via prefers-color-scheme, and print-friendly CSS. No external dependencies.
• SVG share card — generateShareCard(scanResults, options) generates a 560 × 200 px SVG card showing the scan summary. Suitable for embedding in READMEs or sharing on social media. Green theme for clean scans, red for infected.
• CLI --report flag — pompelmi scan ./uploads --report saves pompelmi-report.html after scanning. Use --output <path> to customise the filename.
• CLI --share-card flag — pompelmi scan ./uploads --share-card saves pompelmi-scan-card.svg after scanning. Use --output <path> to customise the filename.
• @pompelmi/nextjs — new package providing withPompelmi(handler, options) (App Router / Next.js 13+) and withPompelmiHandler(handler, options) (Pages Router). Scans the raw request body before the handler runs; returns HTTP 400 on malicious files. Full TypeScript declarations included.
• GitHub App configuration — .github/app.yml describes the pompelmi GitHub App that organizations can install for zero-config virus scanning on every pull request. Posts native check runs with pass/fail status and inline diff annotations for infected files.
• docs/dashboard.html — new documentation page covering generateDashboard, generateShareCard, CLI flags, options reference, and usage examples.
• docs/github-app.html — new documentation page explaining the GitHub App, the Action vs App comparison table, installation steps, permissions, check run flow, and self-hosting instructions.
• Navbar updated across all docs/ HTML pages to include Dashboard and GitHub App links.
• docs/cli.html updated — added --report, --share-card, and --output to the options table and added dedicated #report and #share-card sections.
• README.md updated — added HTML dashboard, SVG share card, and GitHub App to the Features list; added GitHub App callout under the GitHub Action section.

Changed

• src/index.js — exports generateDashboard and generateShareCard alongside existing API.
• types/index.d.ts — full TypeScript declarations for generateDashboard, DashboardOptions, generateShareCard, ShareCardOptions, and ScanRow.

Added

• @pompelmi/nestjs — NestJS module with PompelmiModule.forRoot() / .forRootAsync(), injectable PompelmiService (scan / scanBuffer / isMalware), PompelmiGuard (blocks malicious uploads via CanActivate), and PompelmiInterceptor (throws BadRequestException on infection). Full TypeScript declarations included.
• @pompelmi/fastify — Fastify plugin that decorates the instance with fastify.pompelmi (scan / scanBuffer / scanStream / preHandler). The preHandler() helper returns a route-level hook that scans uploaded files before the route handler runs. Supports custom onMalicious callbacks and full TypeScript declarations.
• Framework Integrations section in README.md — table of official packages with usage snippets for NestJS and Fastify.

What's New

Standalone CLI

Scan files directly from the terminal — no code required:

# Scan a file
npx pompelmi scan ./uploads/file.pdf

# Scan a directory recursively
npx pompelmi scan ./uploads --recursive

# Output as JSON for scripting
npx pompelmi scan ./uploads --json

# Watch a folder in real time
npx pompelmi watch ./uploads

Features:

• Renders the pompelmi grapefruit logo in the terminal via terminal-image
• Live progress bar for directory scans
• Box-drawing UI with color-coded results (green/red/yellow)
• --json mode for shell script integration
• --delete flag to auto-remove infected files
• --quiet mode for CI pipelines
• Works with TCP, UNIX socket, and local clamscan

Exit codes: 0 clean · 1 infected · 2 scan error · 3 clamd unreachable

Install globally:

npm install -g pompelmi
pompelmi scan ./uploads

Or use without installing:

npx pompelmi scan ./uploads

CLI Documentation

New dedicated page: docs/cli.html

• Full commands and options reference
• JSON output format
• Exit codes table
• 8 real-world examples
• Shell script integration

Navbar updated across all docs

All docs/ pages now have a consistent navbar including the new CLI link.

Changes

• bin/pompelmi.js — full CLI implementation
• package.json — bin field added, terminal-image dependency
• docs/cli.html — new CLI documentation page
• docs/*.html — navbar updated across all pages
• README.md — Quick Start section, CLI in Features and docs table
• CHANGELOG.md — v1.12.0 entry

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.11.0...v1.12.0

Added

• Webhook notifications — notify(webhookUrl, scanResult, options) sends a POST request when a virus is detected. Payload includes file, verdict, viruses, timestamp, and hostname. Supports HMAC-SHA256 request signing via X-Pompelmi-Signature header when a secret is provided. Ships with onlyOnMalicious: true default so noise-free by default. Uses Node.js built-in https/http — zero extra dependencies.
• EventEmitter scanner — createScanner(options) returns an EventEmitter-based scanner with scan(filePath) and scanDirectory(dirPath) methods. Emits 'clean', 'malicious', 'scanError', and 'error' events per file — ideal for streaming pipelines and upload processing loops.
• Automated GitHub Release notes — release workflow now extracts the matching changelog section from CHANGELOG.md and uses it as the release body, with a one-line summary in the release title (vX.Y.Z — <summary>). No more static template.
• .mailmap — maps any historical claude/Claude authorship entries to the project author so they are excluded from GitHub's contributor list.

Changed

• src/index.js — exports notify and createScanner alongside existing API.
• types/index.d.ts — full TypeScript declarations for notify, NotifyOptions, WebhookPayload, ScanResultInput, createScanner, and ScanEmitter (including typed event overloads).

What's New

AWS S3 Integration

Scan S3 objects directly without downloading to disk:

const { scanS3 } = require('pompelmi')

const result = await scanS3({
  bucket: 'my-bucket',
  key: 'uploads/file.pdf',
  region: 'us-east-1'
})

Streams the object directly from S3 to clamd via the INSTREAM protocol — zero disk I/O.

Connection Pooling

Maintain persistent connections to clamd for high-throughput applications:

const { createPool } = require('pompelmi')

const pool = createPool({ host: 'localhost', port: 3310, size: 5 })
const result = await pool.scan('file.pdf')
await pool.destroy()

👀 Watch Mode

Monitor a directory and auto-scan every new or modified file:

const { watch } = require('pompelmi')

watch('/uploads', { socket: '/var/run/clamav/clamd.sock' }, {
  onClean:     (file) => console.log('Clean:', file),
  onMalicious: (file) => fs.unlinkSync(file),
  onError:     (err)  => console.error(err)
})

Automatic Retry

Reconnect automatically if clamd is temporarily unreachable:

const result = await scan('file.pdf', {
  host: 'localhost',
  port: 3310,
  retries: 3,
  retryDelay: 1000
})

Changes

• src/S3Scanner.js — S3 streaming integration via @aws-sdk/client-s3
• src/ClamdPool.js — queue-based persistent connection pool
• src/Watcher.js — fs.watch wrapper with debounce and auto-scan
• src/ClamdScanner.js, BufferScanner.js, StreamScanner.js — retry logic
• src/index.js — exports scanS3, createPool, watch
• types/index.d.ts — updated type declarations
• docs/s3.md — new S3 integration guide
• docs/api.md — updated with all new functions
• README.md — updated Features list and API table

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.9.0...v1.10.0

What's New

TypeScript Types Built-in

Full type declarations included in the package — no @types/pompelmi needed.

import { scan, scanBuffer, scanStream, scanDirectory, middleware, Verdict, ScanOptions, ScanResult } from 'pompelmi';

const result: ScanResult = await scan('/path/to/file.pdf');

Automatic PR Comment on Virus Detection

The GitHub Action now posts a comment directly on the PR when infected files are found — no need to dig through logs.

- uses: pompelmi/[email protected]
  with:
    path: .
    fail-on-virus: true
    comment-on-pr: true  # default

Examples Folder

Three ready-to-run framework starters added:

| Directory | Description |
|-----------|-------------|
| examples/express/ | Full Express app with multer + pompelmi middleware |
| examples/nextjs/ | Next.js API route scanning raw upload bytes |
| examples/nestjs/ | NestJS guard wrapping pompelmi for route-level protection |

Changes

• types/index.d.ts — full TypeScript declarations
• package.json — "types" field added
• action/scanner.js — PR comment on virus detection
• action.yml — new comment-on-pr input
• examples/ — Express, Next.js, NestJS starters
• README.md — TypeScript badge, examples section, coming soon

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.8.0...v1.9.0

What's New

Express/Fastify Middleware

Protect file uploads in one line:

const { middleware } = require('pompelmi')
app.use(middleware({ uploadField: 'file' }))

• Automatically scans files uploaded via multer
• Returns 403 if a virus is detected, calls next() if clean
• Works with Express and Fastify

Scan Report Artifact

The GitHub Action now generates a downloadable scan report after every run:

• report.json — machine-readable results
• report.html — human-readable table with file, status, verdict
• Uploaded automatically as a GitHub Actions artifact named pompelmi-scan-report

pompelmi Badge

Add the badge to your repo to show it's protected:

[![Scanned by pompelmi](https://img.shields.io/badge/scanned%20by-pompelmi-orange)]

See BADGE.md for copy-paste instructions.

Changes

• src/middleware.js — new Express/Fastify middleware
• src/index.js — exports middleware
• action/scanner.js — report.json + report.html artifact upload
• README.md — badge + middleware section
• BADGE.md — copy-paste badge instructions
• docs/github-action.md — badge and report sections updated

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.7.0...v1.8.0

What's new

See CHANGELOG.md
for the full list of changes in this release.

What's New

UNIX Socket Support (#184)

You can now connect to clamd via a UNIX socket path, in addition to the existing TCP host:port mode. This is especially useful for local setups and Docker environments where clamd listens on a socket instead of a TCP port.

// UNIX socket (new in v1.6.0)
const result = await scan('file.txt', { socket: '/var/run/clamav/clamd.sock' });

// TCP (unchanged)
const result = await scan('file.txt', { host: 'localhost', port: 3310 });

Previously, calling scan without a reachable TCP socket would hang indefinitely. Passing socket now routes the connection correctly across all three scan methods: scan, scanBuffer, and scanStream.

Changes

• src/ClamdScanner.js — UNIX socket connection via net.createConnection({ path })
• src/BufferScanner.js — UNIX socket support for scanBufferViaClamd
• src/StreamScanner.js — UNIX socket support for scanStreamViaClamd
• src/ClamAVScanner.js — routing logic updated to recognize the socket option
• README.md — new socket entry in the Configuration table, updated API signatures and Docker section

Tests

7 new tests added — all 76 tests pass.

Full Changelog

https://github.com/pompelmi/pompelmi/compare/v1.5.0...v1.6.0

What's new

See CHANGELOG.md
for the full list of changes in this release.

What's new

scanStream(stream, [options]) — scan any Node.js Readable stream directly without writing to disk.

Useful for S3 getObject streams, HTTP downloads, or any piped source.

In TCP mode, the stream is piped to clamd via INSTREAM protocol — zero disk I/O.
In local mode, a temp file is created, scanned, and deleted automatically.

const { scanStream, Verdict } = require('pompelmi');
const stream = s3.getObject({ Bucket, Key }).createReadStream();
const result = await scanStream(stream);
if (result === Verdict.Malicious) throw new Error('Malware detected.');

Full changelog: https://github.com/pompelmi/pompelmi/blob/main/CHANGELOG.md

What's new

scanBuffer(buffer, [options]) — scan an in-memory Buffer directly without writing to disk.

Useful when using multer memoryStorage or any pipeline where the file never touches the filesystem.

In TCP mode, the buffer is streamed to clamd via INSTREAM protocol — zero disk I/O.
In local mode, a temp file is created, scanned, and deleted automatically.

const { scanBuffer, Verdict } = require('pompelmi');
const result = await scanBuffer(req.file.buffer);
if (result === Verdict.Malicious) throw new Error('Malware detected.');

Full changelog: https://github.com/pompelmi/pompelmi/blob/main/CHANGELOG.md

What's Changed

• Dependency Refactoring: Replaced the unmaintained cross-spawn dependency with a native child_process wrapper, keeping the dependency chain clean and secure.
• Architectural Refactoring: Replaced fragile string-based scan results with a robust Symbol-based Verdict object to ensure type safety and prevent typos.

⚠️ Migration Note (Important)

The scan() function now returns a Symbol instead of a raw string. Users must import Verdict from the package and update their equality checks:
Change result === 'Clean' ➡️ result === Verdict.Clean

Closes #183

Overview

This marks the first official stable release of Pompelmi. The core architecture has been finalized for production environments.

⚠️ Deprecation Notice

All prior 0.x versions are now strictly deprecated. Legacy 0.x releases are no longer maintained, should be considered unstable, and must not be used in production. All users are strongly advised to migrate to 1.0.0 immediately.

Key Additions

• Finalized production-ready API and feature set.
• Enhanced core stability and performance optimizations.
• Formalized versioning strictly adhering to Semantic Versioning (SemVer).

For a granular breakdown of all changes, please review the commit history.