No stdout parsing. No regex. No surprises.

API

pompelmi.scan(filePath, [options])

scan(filePath: string, options?: { host?: string; port?: number; timeout?: number }): Promise<symbol>
// resolves to one of: Verdict.Clean | Verdict.Malicious | Verdict.ScanError

Resolves to one of:

Reading the verdict as a string — each Verdict Symbol carries a .description property (Verdict.Clean.description === 'Clean') for logging or serialisation without comparing against raw strings in application logic.

Rejects with an Error in these cases:

Example — full error handling:

const { scan, Verdict } = require('pompelmi');
const path = require('path');

async function safeScan(filePath) {
  try {
    const result = await scan(path.resolve(filePath));

    if (result === Verdict.ScanError) {
      // The scan could not complete — treat the file as untrusted.
      console.warn('Scan incomplete, rejecting file as precaution.');
      return null;
    }

    return result; // Verdict.Clean or Verdict.Malicious
  } catch (err) {
    console.error('Scan failed:', err.message);
    return null;
  }
}

Docker / remote scanning

If ClamAV runs in a Docker container (or anywhere on the network), pass host and port — everything else stays the same.

const result = await pompelmi.scan('/path/to/upload.zip', {
  host: '127.0.0.1',
  port: 3310,
});

See docs/docker.md for the docker-compose.yml snippet and first-boot notes.

Examples

The examples/ directory contains standalone, runnable scripts for common use cases. Each file can be run directly with node examples/<name>.js.

• basic-scan.js — Scan a single file and log the Verdict
• scan-on-upload-express.js — Express route: receive upload, scan before saving
• scan-on-upload-fastify.js — Fastify route: same pattern
• scan-with-options.js — Scan via a remote clamd instance with custom host, port, and timeout
• handle-scan-error.js — Gracefully handle every Verdict including ScanError and hard rejections
• delete-on-malicious.js — Auto-delete file if Verdict.Malicious
• quarantine-on-malicious.js — Move infected file to a quarantine/ folder
• scan-multiple-files.js — Scan an array of files concurrently with Promise.all
• scan-directory.js — Walk a directory recursively and scan every file
• scan-buffer.js — Scan an in-memory Buffer via a temp-file shim
• install-clamav.js — Programmatically trigger ClamAV installation
• update-virus-database.js — Programmatically run freshclam / DB update
• scan-with-timeout.js — Timeout patterns for both local clamscan and remote clamd
• scan-pdf.js — Scan a PDF upload with extension validation
• scan-image.js — Scan an image upload with extension validation
• scan-zip.js — Scan a ZIP archive upload (ClamAV recurses automatically)
• rest-api-server.js — Minimal HTTP server exposing POST /scan
• s3-scan-before-upload.js — Scan locally, then upload to AWS S3 only if clean
• cli-scan.js — Accept file paths as CLI arguments, print verdicts, exit non-zero on threats
• typescript-usage.ts — TypeScript example with inline type declarations

Internal utilities

These modules are not part of the public npm API but are used internally to set up the ClamAV environment on a fresh machine.

ClamAVInstaller()

Installs ClamAV using the platform's native package manager. Skips silently if ClamAV is already installed.

ClamAVInstaller(): Promise<string>

• Resolves with a status message string on success or skip.
• Rejects if the install process exits with a non-zero code or if spawning the package manager fails.

updateClamAVDatabase()

Downloads or updates the ClamAV virus definition database by running freshclam. Skips if main.cvd is already present on disk.

updateClamAVDatabase(): Promise<string>

• Resolves with a status message string on success or skip.
• Rejects if freshclam exits with a non-zero code or if spawning fails.

Supported platforms

ClamAV must be installed on the host system. pompelmi does not bundle or download it.

Installing ClamAV manually

# macOS
brew install clamav && freshclam

# Linux (Debian / Ubuntu)
sudo apt-get install -y clamav clamav-daemon && sudo freshclam

# Windows (Chocolatey)
choco install clamav -y

Testing

npm test

The test suite has two parts:

• Unit tests (test/unit.test.js) — run with Node's built-in test runner. Mock nativeSpawn from src/spawn.js and platform dependencies via require-cache injection; no ClamAV installation required.
• Integration tests (test/scan.test.js) — spawn real clamscan processes against EICAR test files. Skipped automatically if clamscan is not found in PATH.

Contributing

1. Fork the repository at https://github.com/pompelmi/pompelmi.
2. Create a feature branch: git checkout -b feat/your-change.
3. Make your changes and run npm test to verify.
4. Open a pull request against main.

Please read CODE_OF_CONDUCT.md before contributing.

Security

To report a vulnerability, see SECURITY.md.

License

ISC — © pompelmi contributors