pompelmi

Prerequisites

Step 1 — Install ClamAV

pompelmi delegates to the clamscan system binary. Install ClamAV for your operating system before proceeding.

brew install clamav

sudo apt-get update
sudo apt-get install -y clamav clamav-daemon

sudo dnf install -y clamav clamav-update

choco install clamav -y

Download the installer from clamav.net/downloads and follow the setup wizard. Make sure the ClamAV bin directory is added to PATH.

Verify the installation:

clamscan --version

Step 2 — Update virus definitions

ClamAV ships with no virus definitions. You must download them before the first scan. This is done with freshclam.

freshclam

sudo freshclam

sudo systemctl stop clamav-freshclam
sudo freshclam
sudo systemctl start clamav-freshclam

freshclam downloads the main.cvd, daily.cvd, and bytecode.cvd definition files. The download is several hundred megabytes on first run. Subsequent runs are incremental.

Step 3 — Install pompelmi

npm install pompelmi

Or with yarn:

yarn add pompelmi

Verify it installed:

node -e "const p = require('pompelmi'); console.log(typeof p.scan)"
# function

Step 4 — Run your first scan

Create a file called scan.js:

const pompelmi = require('pompelmi');

pompelmi.scan(process.argv[2])
  .then(result => {
    console.log('Result:', result);
    process.exit(result === 'Malicious' ? 1 : 0);
  })
  .catch(err => {
    console.error('Error:', err.message);
    process.exit(2);
  });

Run it against any file:

node scan.js /etc/hosts
# Result: Clean

echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > /tmp/eicar.txt
node scan.js /tmp/eicar.txt
# Result: Malicious

Step 5 — Handle errors properly

scan() rejects the Promise in three situations. Always attach a .catch() or use try/catch in an async function.

const pompelmi = require('pompelmi');
const path = require('path');

async function safeScan(filePath) {
  // Resolve to absolute path to avoid ambiguity
  const abs = path.resolve(filePath);

  let result;
  try {
    result = await pompelmi.scan(abs);
  } catch (err) {
    if (err.message.startsWith('File not found')) {
      console.error('The file does not exist:', abs);
      return null;
    }
    if (err.message.startsWith('Unexpected exit code')) {
      console.error('ClamAV returned an unknown exit code.');
      return null;
    }
    // clamscan binary not found or other OS error
    console.error('ClamAV error:', err.message);
    return null;
  }

  return result;
}

safeScan('./upload.zip').then(console.log);

More examples

Scanning uploaded files in Express

const express = require('express');
const multer  = require('multer');
const pompelmi = require('pompelmi');
const path = require('path');
const fs   = require('fs');

const upload = multer({ dest: '/tmp/uploads/' });
const app    = express();

app.post('/upload', upload.single('file'), async (req, res) => {
  const filePath = req.file.path;

  try {
    const result = await pompelmi.scan(filePath);

    if (result === 'Malicious') {
      fs.unlinkSync(filePath);
      return res.status(400).json({ error: 'Malware detected. Upload rejected.' });
    }

    if (result === 'ScanError') {
      // Scan failed — treat as untrusted, reject upload
      fs.unlinkSync(filePath);
      return res.status(422).json({ error: 'Scan incomplete. Upload rejected as precaution.' });
    }

    // Clean — move to permanent storage
    const dest = path.join('/var/app/uploads', req.file.filename);
    fs.renameSync(filePath, dest);
    res.json({ status: 'ok', file: req.file.filename });

  } catch (err) {
    fs.unlinkSync(filePath);
    res.status(500).json({ error: 'Scan failed: ' + err.message });
  }
});

app.listen(3000);

Scanning multiple files in sequence

const pompelmi = require('pompelmi');
const fs = require('fs');

async function scanDirectory(dirPath) {
  const files = fs.readdirSync(dirPath)
    .map(f => `${dirPath}/${f}`)
    .filter(f => fs.statSync(f).isFile());

  const results = [];

  for (const file of files) {
    const result = await pompelmi.scan(file);
    results.push({ file, result });
    if (result !== 'Clean') {
      console.warn(`[${result}] ${file}`);
    }
  }

  return results;
}

scanDirectory('./downloads').then(results => {
  const malicious = results.filter(r => r.result === 'Malicious');
  console.log(`Scanned ${results.length} files. ${malicious.length} malicious.`);
});

Parallel scanning with Promise.all

const pompelmi = require('pompelmi');

async function scanAll(filePaths) {
  const settled = await Promise.allSettled(
    filePaths.map(f => pompelmi.scan(f).then(r => ({ file: f, result: r })))
  );

  return settled.map(s =>
    s.status === 'fulfilled'
      ? s.value
      : { file: '?', result: 'Error', error: s.reason.message }
  );
}

scanAll(['/tmp/a.zip', '/tmp/b.pdf', '/tmp/c.exe'])
  .then(results => console.table(results));

Common errors