pompelmi - ClamAV antivirus scanning for Node.js — scan file

项目说明

<h1 align="center">pompelmi — ClamA Scanning for Node.js</h1>

<p align="center"><strong>ClamA scanning for Node.js — clean, typed, zero dependencies.</strong></p>

<br>

> pompelmi Pro — audit logs, priority support, and enterprise features. Learn more

---

Quick Start

---

Documentation

| Guide | Description |
|-------|-------------|
| Getting Started | Installation, prerequisites, quickstart examples |
| API Reference | Full function signatures, options, , error conditions |
| CLI Reference | Terminal commands, options, examples |
| S3 Integration | Scan S3 objects directly, IAM setup, Lambda pattern |
| Docker / Remote Scanning | TCP sidecar, UNIX socket mount, docker-compose patterns |
| GitHub Action | CI scanning, inputs/outputs, caching, example workflows |

---

O

pompelmi is a minimal Node.js wrapper around ClamAV that exposes a single async function — scan() — and returns one of three typed Symbols: .Clean, .Malicious, or .ScanError. Full documentation at pompelmi.app.

It supports two scanning modes:

Local — spawns clamscan as a child process and maps its exit code to a . No stdout parsing, no regex.

Remote / Docker / UNIX socket — streams the file to a running clamd daemon over TCP or a UNIX domain socket using the ClamAV INSTREAM protocol.

No cloud. No daemon required for local mode. No nati. Zero runtime dependencies.

---

Why pompelmi

If you need to scan file uploads for in Node.js, integrate ClamAV with Express or Fastify, or add antivirus scanning to any upload pipeline, pompelmi is the simplest path.

Most integrations require parsing ClamAV's stdout with regex, managing a clamd daemon, or working around unmaintained packages. pompelmi does none of that: one function call, exit-code-mapped , zero dependencies.

---

Features

Standalone CLI — scan files from any terminal with npx pompelmi scan

Official Docker image — justsouichi/pompelmi-scanner on Docker Hub: ClamAV + HTTP scan API in one pull (docs)

Security scorecard — grade your upload security A–F with npx pompelmi scorecard (docs)

VS Code extension — scan files directly from the IDE (scaffold in packages//) (docs)

Quarantine mode — watch ./uploads --quarantine ./quarantine auto-mo files with sidecar JSON

HTML security dashboard — generate beautiful scan reports with --report (docs)

S card — shareable scan result card with --share-card (docs)

GitHub App — one-click installation for organizations, zero-config PR scanning (docs)

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.

scanDirectory(dirPath, [options]) — recursively scan every file in a directory, returns clean/malicious/errors arrays

scanS3(params, [options]) — scan S3 objects by streaming directly from AWS S3, no disk I/O

createPool([options]) — persistent connection pool for high-throughput clamd scanning

watch(dirPath, [options], callbacks) — watch a directory and auto-scan new/modified files (300 ms debounce)

notify(webhookUrl, scanResult, [options]) — send a POST webhook notification when a virus is detected; optional HMAC-SHA256 signing via X-Pompelmi-Signature; zero extra dependencies

createScanner([options]) — E scanner; call .scan(filePath) or .scanDirectory(dirPath) and listen to 'clean', 'malicious', 'scanError', and 'error' events

SHA256 scan cache — createCache([options]) — skip rescanning known-clean files; LRU e, configurable TTL, optional file-backed persistence; zero extra dependencies (docs)

Scan policies — createPolicy(rules) — unified size, MIME type, extension, and virus rules in one object; Express middleware and NestJS guard included (docs)

Multi-engine scanning — createMultiEngine(options) — combine ClamAV and with any/all/majority consensus; per-engine breakdown; zero extra dependencies (docs)

Directory streaming — scanDirectory.stream(dirPath) — async-iterable progress events (progress / result / complete) for real-time UI feedback

Auto-retry on connection error — retries and retryDelay options on every scan function

Symbol-based (.Clean / .Malicious / .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

Native ESM support — import { scan } from 'pompelmi' works out of the box (dual CJS/ESM build)

Deno support — import { scan } from 'npm:pompelmi' — no install step required

Cloudflare Workers — via /cloudflare — Web APIs only, no Node.js built-ins

Works with Express, Fastify, NestJS, Hono, Remix, S, and any other Node.js HTTP framework

Works with Node.js • Bun • Deno • Cloudflare Workers

Interactive demo at pompelmi.app/demo — try before you install

Zero runtime dependencies — ships nothing but source code

Tested with EICAR standard antivirus test files

CommonJS + ESM module; TypeScript type declarations a inline

See how pompelmi compares to other Node.js ClamA.

---

Framework Integrations

Official integration packages for popular frameworks:

| Package | Framework | Install |
|---------|-----------|---------|
| /nestjs | NestJS | npm i /nestjs |
| /fastify | Fastify | npm i /fastify |
| /hono | Hono | npm i /hono |
| /remix | Remix | npm i /remix |
| /s | S | npm i /s |
| /testing | Jest//Node | npm i -D /testing |
| /cloudflare | Cloudflare Workers | npm i /cloudflare |

NestJS

Fastify

Hono (Node.js, Bun, Cloudflare Workers)

Remix

S

---

Requirements

Node.js — any LTS release (no nati, no C++ bindings)

Bun — fully supported; uses Bun.file() for faster file reading

Deno — import from npm:pompelmi — no install step required

Cloudflare Workers — via /cloudflare — connects to a remote clamd over TCP

ClamAV — must be installed on the host or reachable over TCP

pompelmi does not bundle or automatically download ClamA it once per machine (see Installing ClamAV).

---

Installation

See pompelmi.app for the full getting-started guide.

Docker

Run ClamAV as a sidecar and point pompelmi at it — no local install needed on the application host.

See Docker / remote scanning for details.

---

Usage

Basic scan

Express file upload

Fastify file upload

Full error handling

Scan multiple files concurrently

Scan a Directory

Scan a Buffer

Scan a Stream

---

Docker / Remote Scanning

Pass host and port (or socket) to switch from the local clamscan CLI to the clamd daemon. E else — the returned , error types — is identical.

TCP:

UNIX socket:

See docs/docker.md for Docker Compose examples, UNIX socket mounts, scanBuffer / scanStream in clamd mode, and connection retry patterns.

---

Configuration

pompelmi has no configuration file or en . All options are passed directly to scan().

| Option | Type | Default | Description |
|--------------|----------|---------|----------------------------------------|
| socket | string | — | Path to a clamd UNIX domain socket (e.g. /run/clama.sock). Takes precedence over host/port when set. |
| host | string | — | clamd hostname. Enables TCP mode when set. |
| port | number | 3310 | clamd port. |
| timeout | number | 15000 | Socket idle timeout in milliseconds (clamd mode only). |
| retries | number | 0 | Automatic retry attempts on connection error. |
| retryDelay | number | 1000 | Milliseconds to wait between retries. |

When none of socket, host, or port is provided, pompelmi spawns clamscan --no-summary <filePath> locally.

---

API Reference

See docs/api.md for the full reference: function signatures, options table, Symbols, error conditions, and error handling patterns.

Quick summary:

| Function | Input | Disk I/O |
|----------|-------|----------|
| scan(filePath, [options]) | File path on disk | None in clamd mode (streamed) |
| scanBuffer(buffer, [options]) | Buffer | None (streamed) |
| scanStream(stream, [options]) | Node.js Readable | None (streamed) |
| scanDirectory(dirPath, [options]) | Directory path | None in clamd mode |
| scanS3(params, [options]) | S3 bucket + key | None (streamed from S3) |
| createPool([options]) | — | Returns a ClamdPool |
| watch(dirPath, [options], callbacks) | Directory path | None in clamd mode |

All four functions accept the same options object and resolve to the same three Symbols:

| Symbol | Meaning |
|--------|---------|
| .Clean | No threats found |
| .Malicious | Known signature matched |
| .ScanError | Scan could not complete — treat as untrusted |

---

Installing ClamAV

---

Examples

The examples/ directory contains standalone runnable scripts and framework-specific starters.

Framework starters

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

Standalone scripts

Each can be run with node examples/<name>.js.

| File | Description |
|------|-------------|
| basic-scan.js | Scan a single file and log the |
| scan-on-upload-express.js | Express route: scan before saving |
| scan-on-upload-fastify.js | Fastify route: same pattern |
| scan-with-options.js | Remote clamd with custom host, port, timeout |
| handle-scan-error.js | Handle every including hard rejections |
| delete-on-malicious.js | Auto-delete file if malicious |
| quarantine-on-malicious.js | Mo file to a quarantine folder |
| scan-multiple-files.js | Concurrent scans with Promise.all |
| scan-directory.js | Recursively scan every file in a directory |
| scan-buffer.js | Scan an in-memory Buffer (multer memoryStorage) |
| scan-stream.js | Scan a Readable stream (S3, HTTP, pipes) |
| rest-api-server.js | Minimal HTTP ser POST /scan |
| s3-scan-before-upload.js | Scan locally, then upload to S3 only if clean |
| cli-scan.js | CLI tool: scan file paths, exit non-zero on threats |
| scan-with-timeout.js | Timeout patterns for local and remote scanning |
| scan-pdf.js | PDF upload with extension |
| scan-image.js | Image upload with extension |
| scan-zip.js | ZIP archive scan (ClamA automatically) |
| install-clamav.js | Programmatic ClamA |
| update-.js | Programmatic virus DB update |
| typescript-usage.ts | TypeScript example with full type declarations |

---

GitHub Action

![GitHub Marketplace]()

Scan any repository for on every push or pull request — ClamAV is bundled inside a Docker container, virus definitions are auto-updated at runtime, and no external services are required.

Minimal usage

Full example

Inputs

| Input | Description | Default |
|-------|-------------|---------|
| path | Directory or file to scan | . (full workspace) |
| fail-on-virus | Fail the workflow step when infected files are found | true |
| comment-on-pr | Post a PR comment listing infected files (requires GITHUB_TOKEN) | true |

Outputs

| Output | Description |
|--------|-------------|
| infected-files | Newline-separated list of infected file paths (empty when clean) |
| status | "clean" or "infected" |

A ready-to-copy workflow is a at .github/workflows/action-example.yml. Full reference — inputs, outputs, layer caching, and more examples — in docs/github-action.md.

> For organizations: install the pompelmi GitHub App for zero-config scanning on every PR — no workflow file needed.

---

Contributing

Full documentation and guides are a in the Wiki.

Tests

test/unit.test.js — runs with Node's built-in test runner. Mocks nati and platform dependencies; ClamAV is not required.

test/scan.test.js — integration tests that spawn real clamscan against EICAR test files. Skipped automatically when clamscan is not in PATH.

Submitting changes

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/your-change.
3. Make your changes and confirm npm test passes.
4. Open a pull request against main.

Please read CODE_OF_CONDUCT.md before contributing. To report a security , see SECURITY.md.

---

Coming soon

[x] Cloudflare Workers support — /cloudflare ships in v1.17.0

[x] NestJS official module — PompelmiModule.forRoot() with injectable PompelmiService

---

Sponsor

pompelmi is free and open source. If your company uses pompelmi in production, consider sponsoring de:

![GitHub Sponsors]()

What sponsorship funds:

Faster response to issues and PRs

New framework integrations

Long-term maintenance and security updates

---

License

---

pompelmi.app · npm · GitHub

项目信息

开发语言：JavaScript

Star 数：678

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕ClamAV antivirus scanning for Node.js — scan file uploads with a single function call. Zero dependencies. Typed Symbol verdicts. Local or Docker/clamd.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。

登录后才能参与讨论

下载链接

会员才能下载

登录后开通会员

同分类推荐

暂无同类资源

资源标题	pompelmi - ClamAV antivirus scanning for Node.js — scan file
所属分类	病毒分析
发布作者	admin
发布时间	2026-10-05 23:15:59
下载权限	免费下载
附件数量	2 个下载链接
浏览次数	355
讨论数量	0
主题状态	正常讨论中