ClamAV for humans

A minimal Node.js wrapper around ClamAV that scans any file and returns a typed Verdict Symbol: Verdict.Clean, Verdict.Malicious, or Verdict.ScanError. No daemons. No cloud. No native bindings. Zero runtime dependencies.

• Quickstart
• How it works
• API
  • pompelmi.scan()
• Docker / remote scanning
• Internal utilities
  • ClamAVInstaller()
  • updateClamAVDatabase()
• Supported platforms
• Installing ClamAV manually
• Testing
• Contributing
• Security
• License

npm install pompelmi

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

const result = await scan('/path/to/file.zip');

if (result === Verdict.Malicious) {
  throw new Error('File rejected: malware detected');
}

1. Validate — pompelmi checks that the argument is a string and that the file exists before spawning anything.
2. Scan — pompelmi spawns clamscan --no-summary <filePath> as a child process and reads the exit code.
3. Map — the exit code is mapped to a result string. Unknown codes and spawn errors reject the Promise.

No stdout parsing. No regex. No surprises.

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;
  }
}

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.

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

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.

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.

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

# macOS
brew install clamav && freshclam

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

# Windows (Chocolatey)
choco install clamav -y

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.

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.

To report a vulnerability, see SECURITY.md.

ISC — © pompelmi contributors