pompelmi 1.5.0 → 1.6.0

package/src/StreamScanner.js

@@ -13,52 +13,55 @@ function parseClamdResponse(raw) {
 }
 
 /**
- * Scan a Readable stream by piping it to a running clamd instance over TCP.
+ * Scan a Readable stream by piping it to a running clamd instance over TCP or a UNIX socket.
  * No data is written to disk.
  *
  * @param {import('stream').Readable} stream
  * @param {object} [options]
+ * @param {string} [options.socket]          - Path to a clamd UNIX domain socket.
+ *                                             When set, takes precedence over host/port.
  * @param {string} [options.host='127.0.0.1']
  * @param {number} [options.port=3310]
  * @param {number} [options.timeout=15000]
  * @returns {Promise<symbol>}
  */
-function scanStreamViaClamd(stream, { host = '127.0.0.1', port = 3310, timeout = 15_000 } = {}) {
+function scanStreamViaClamd(stream, { host = '127.0.0.1', port = 3310, socket: socketPath, timeout = 15_000 } = {}) {
     return new Promise((resolve, reject) => {
-        const socket  = net.createConnection({ host, port });
-        const chunks  = [];
-        let   settled = false;
+        const connOpts = socketPath ? { path: socketPath } : { host, port };
+        const conn     = net.createConnection(connOpts);
+        const chunks   = [];
+        let   settled  = false;
 
         function settle(fn, value) {
             if (settled) return;
             settled = true;
-            socket.destroy();
+            conn.destroy();
             fn(value);
         }
 
-        socket.setTimeout(timeout);
-        socket.on('timeout', () =>
+        conn.setTimeout(timeout);
+        conn.on('timeout', () =>
             settle(reject, new Error(`clamd connection timed out after ${timeout}ms`))
         );
-        socket.on('error', (err) => settle(reject, err));
-        socket.on('data',  (chunk) => chunks.push(chunk));
-        socket.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
+        conn.on('error', (err) => settle(reject, err));
+        conn.on('data',  (chunk) => chunks.push(chunk));
+        conn.on('end',   () => settle(resolve, parseClamdResponse(Buffer.concat(chunks))));
 
-        socket.on('connect', () => {
-            socket.write(CLAMD_INSTREAM);
+        conn.on('connect', () => {
+            conn.write(CLAMD_INSTREAM);
 
             stream.on('error', (err) => settle(reject, err));
 
             stream.on('data', (chunk) => {
                 const header = Buffer.allocUnsafe(4);
                 header.writeUInt32BE(chunk.length, 0);
-                socket.write(header);
-                socket.write(chunk);
+                conn.write(header);
+                conn.write(chunk);
             });
 
             stream.on('end', () => {
-                socket.write(Buffer.alloc(4)); // terminating zero-length chunk
-                socket.end();
+                conn.write(Buffer.alloc(4)); // terminating zero-length chunk
+                conn.end();
             });
         });
     });

package/wiki/api-reference.md

@@ -0,0 +1,268 @@
+# API Reference
+
+Complete reference for all public functions exported by pompelmi.
+
+---
+
+## Installation
+
+```bash
+npm install pompelmi
+```
+
+```js
+const { scan, scanBuffer, scanStream, scanDirectory, Verdict } = require('pompelmi');
+```
+
+---
+
+## `scan(filePath, [options])`
+
+Scan a file by absolute or relative path. In local mode spawns `clamscan`; in TCP mode streams the file to clamd via INSTREAM.
+
+```ts
+scan(
+  filePath: string,
+  options?: {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+): Promise<symbol>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `filePath` | `string` | Yes | Path to the file to scan. Use `path.resolve()` for safety. |
+| `options.host` | `string` | No | clamd hostname. Setting this enables TCP mode. |
+| `options.port` | `number` | No | clamd port. Default: `3310`. |
+| `options.timeout` | `number` | No | Socket idle timeout in ms (TCP mode only). Default: `15000`. |
+
+### Returns
+
+`Promise<symbol>` — resolves to one of the three `Verdict` Symbols:
+
+| Verdict | Local exit code | TCP response | Meaning |
+|---------|-----------------|--------------|---------|
+| `Verdict.Clean` | `0` | `stream: OK` | No threats found. |
+| `Verdict.Malicious` | `1` | `stream: <name> FOUND` | Known malware signature matched. |
+| `Verdict.ScanError` | `2` | other response | Scan could not complete. Treat as untrusted. |
+
+### Rejects with
+
+| Message | Cause |
+|---------|-------|
+| `filePath must be a string` | First argument is not a string. |
+| `File not found: <path>` | File does not exist at the given path. |
+| `ENOENT` | `clamscan` binary not found in PATH (local mode). |
+| `Unexpected exit code: N` | ClamAV exited with an undocumented code. |
+| `Process killed by signal: <SIG>` | Process was killed (timeout, OOM, SIGTERM). |
+| `clamd connection timed out after Nms` | TCP socket idle timeout exceeded. |
+
+### Examples
+
+```js
+// Local mode
+const result = await scan('/uploads/report.pdf');
+
+// TCP mode
+const result = await scan('/uploads/report.pdf', {
+  host: '127.0.0.1',
+  port: 3310,
+  timeout: 30_000,
+});
+
+if (result === Verdict.Clean)     console.log('Safe.');
+if (result === Verdict.Malicious) throw new Error('Malware detected.');
+if (result === Verdict.ScanError) console.warn('Scan incomplete — treat as untrusted.');
+```
+
+---
+
+## `scanBuffer(buffer, [options])`
+
+Scan an in-memory `Buffer` without writing to disk (TCP mode) or via a temp file that is deleted automatically (local mode).
+
+```ts
+scanBuffer(
+  buffer: Buffer,
+  options?: {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+): Promise<symbol>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `buffer` | `Buffer` | Yes | The in-memory buffer to scan. |
+| `options` | `object` | No | Same options as `scan()`. |
+
+### Returns
+
+Same three `Verdict` Symbols as `scan()`.
+
+### Rejects with
+
+Everything `scan()` can reject with, plus:
+
+| Message | Cause |
+|---------|-------|
+| `buffer must be a Buffer` | First argument is not a `Buffer` instance. |
+| `buffer is empty` | Zero-length Buffer passed. |
+
+### Notes
+
+- **TCP mode:** buffer is streamed to clamd via INSTREAM — no disk I/O.
+- **Local mode:** buffer is written to a temp file in `os.tmpdir()`, scanned, then deleted in a `finally` block.
+
+### Example
+
+```js
+// multer memoryStorage
+const result = await scanBuffer(req.file.buffer, {
+  host: process.env.CLAMAV_HOST,
+  port: 3310,
+});
+```
+
+---
+
+## `scanStream(stream, [options])`
+
+Scan any Node.js `Readable` stream. In TCP mode the stream is piped directly to clamd — no disk I/O. In local mode it is written to a temp file that is deleted automatically.
+
+```ts
+scanStream(
+  stream: Readable,
+  options?: {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+): Promise<symbol>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `stream` | `stream.Readable` | Yes | The readable stream to scan. |
+| `options` | `object` | No | Same options as `scan()`. |
+
+### Returns
+
+Same three `Verdict` Symbols as `scan()`.
+
+### Rejects with
+
+Everything `scan()` can reject with, plus:
+
+| Message | Cause |
+|---------|-------|
+| `stream must be a Readable` | First argument is not a `stream.Readable`. |
+| stream error | Any error emitted by the stream is propagated as-is. |
+
+### Example
+
+```js
+// S3 getObject stream
+const { GetObjectCommand } = require('@aws-sdk/client-s3');
+const response = await s3.send(new GetObjectCommand({ Bucket, Key }));
+const result = await scanStream(response.Body, { host: 'clamav', port: 3310 });
+```
+
+---
+
+## `scanDirectory(dirPath, [options])`
+
+Recursively scan every file in a directory. Returns three arrays of absolute paths; per-file failures are collected rather than thrown.
+
+```ts
+scanDirectory(
+  dirPath: string,
+  options?: {
+    host?: string;
+    port?: number;
+    timeout?: number;
+  }
+): Promise<{
+  clean: string[];
+  malicious: string[];
+  errors: string[];
+}>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dirPath` | `string` | Yes | Path to the directory to scan recursively. |
+| `options` | `object` | No | Same options as `scan()`. |
+
+### Returns
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `clean` | `string[]` | Absolute paths of files with no threats. |
+| `malicious` | `string[]` | Absolute paths of files with matched signatures. |
+| `errors` | `string[]` | Absolute paths of files that could not be scanned. |
+
+### Rejects with
+
+| Message | Cause |
+|---------|-------|
+| `dirPath must be a string` | First argument is not a string. |
+| `Directory not found: <path>` | Directory does not exist. |
+
+Individual file scan failures do **not** cause the function to reject — they appear in `errors`.
+
+### Example
+
+```js
+const results = await scanDirectory('/uploads', { host: 'clamav', port: 3310 });
+
+console.log(`${results.clean.length} clean, ${results.malicious.length} malicious`);
+results.malicious.forEach(f => fs.unlinkSync(f));
+```
+
+---
+
+## `Verdict`
+
+The `Verdict` object exported by pompelmi contains three Symbols:
+
+```js
+const { Verdict } = require('pompelmi');
+
+Verdict.Clean     // Symbol(Clean)
+Verdict.Malicious // Symbol(Malicious)
+Verdict.ScanError // Symbol(ScanError)
+```
+
+Each Symbol has a `.description` property for safe serialisation:
+
+```js
+Verdict.Clean.description     // 'Clean'
+Verdict.Malicious.description // 'Malicious'
+Verdict.ScanError.description // 'ScanError'
+```
+
+---
+
+## Options reference
+
+All four functions accept the same options object:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | — | clamd hostname. Setting this enables TCP mode. |
+| `port` | `number` | `3310` | clamd port. |
+| `timeout` | `number` | `15000` | Socket idle timeout in ms. TCP mode only. |
+
+When neither `host` nor `port` is set, pompelmi uses local mode (spawns `clamscan`).

package/wiki/cli-usage.md

@@ -0,0 +1,263 @@
+# CLI Usage
+
+pompelmi can be used as a command-line tool for scripting, CI pipelines, and interactive scanning. This page shows how to build a CLI scanner with pompelmi and how to use it in shell scripts.
+
+---
+
+## Minimal CLI scanner
+
+```js
+#!/usr/bin/env node
+// cli-scan.js
+
+const { scan, scanDirectory, Verdict } = require('pompelmi');
+const path = require('path');
+const fs   = require('fs');
+
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.error('Usage: node cli-scan.js <file-or-dir> [file2] ...');
+  process.exit(2);
+}
+
+const SCAN_OPTS = {
+  host:    process.env.CLAMAV_HOST,
+  port:    Number(process.env.CLAMAV_PORT) || 3310,
+  timeout: Number(process.env.CLAMAV_TIMEOUT) || 30_000,
+};
+
+async function main() {
+  let anyMalicious = false;
+
+  for (const target of args) {
+    const resolved = path.resolve(target);
+
+    let stat;
+    try {
+      stat = fs.statSync(resolved);
+    } catch {
+      console.error(`Not found: ${resolved}`);
+      process.exit(2);
+    }
+
+    if (stat.isDirectory()) {
+      const results = await scanDirectory(resolved, SCAN_OPTS);
+
+      for (const f of results.clean)     console.log(`CLEAN     ${f}`);
+      for (const f of results.malicious) console.log(`MALICIOUS ${f}`);
+      for (const f of results.errors)    console.log(`ERROR     ${f}`);
+
+      if (results.malicious.length > 0) anyMalicious = true;
+    } else {
+      const result = await scan(resolved, SCAN_OPTS);
+      const label  = result.description.toUpperCase().padEnd(9);
+      console.log(`${label} ${resolved}`);
+      if (result === Verdict.Malicious) anyMalicious = true;
+    }
+  }
+
+  // Exit code 1 if any malicious file found — useful for CI
+  process.exit(anyMalicious ? 1 : 0);
+}
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(2);
+});
+```
+
+Make it executable:
+
+```bash
+chmod +x cli-scan.js
+```
+
+---
+
+## Usage examples
+
+```bash
+# Scan a single file
+node cli-scan.js /path/to/file.pdf
+
+# Scan multiple files
+node cli-scan.js /uploads/a.pdf /uploads/b.zip
+
+# Scan a directory recursively
+node cli-scan.js /uploads/
+
+# TCP mode (set env vars)
+CLAMAV_HOST=127.0.0.1 node cli-scan.js /uploads/file.pdf
+```
+
+---
+
+## Exit codes
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | All scanned files are clean |
+| `1` | One or more malicious files found |
+| `2` | Scan failed or argument error |
+
+Exit code `1` for malicious is standard in shell scripting — makes it easy to use in `if` statements and CI pipelines.
+
+---
+
+## Shell scripting
+
+```bash
+#!/bin/bash
+set -e
+
+FILE="$1"
+
+if [ -z "$FILE" ]; then
+  echo "Usage: $0 <file>"
+  exit 2
+fi
+
+node /usr/local/bin/cli-scan.js "$FILE"
+STATUS=$?
+
+if [ $STATUS -eq 1 ]; then
+  echo "Upload rejected: malware detected."
+  exit 1
+elif [ $STATUS -eq 2 ]; then
+  echo "Scan failed."
+  exit 2
+else
+  echo "File is clean."
+fi
+```
+
+---
+
+## CI pipeline integration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/scan-artifacts.yml
+name: Scan artifacts
+
+on:
+  workflow_run:
+    workflows: ["Build"]
+    types: [completed]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ClamAV
+        run: |
+          sudo apt-get install -y clamav
+          sudo freshclam
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Scan artifacts
+        run: |
+          npm ci
+          node cli-scan.js dist/
+          # Exits 1 if malicious files found — fails the job
+```
+
+### Pre-commit hook
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+
+# Scan staged files before commit
+STAGED=$(git diff --cached --name-only --diff-filter=ACM)
+
+if [ -z "$STAGED" ]; then
+  exit 0
+fi
+
+echo "$STAGED" | xargs node cli-scan.js
+
+if [ $? -ne 0 ]; then
+  echo "Commit blocked: malware detected in staged files."
+  exit 1
+fi
+```
+
+---
+
+## Adding a global `pompelmi` command
+
+Add to `package.json` to expose as a package binary:
+
+```json
+{
+  "bin": {
+    "pompelmi-scan": "./cli-scan.js"
+  }
+}
+```
+
+Install globally:
+
+```bash
+npm install -g pompelmi
+pompelmi-scan /path/to/file.pdf
+```
+
+---
+
+## Scanning directories and deleting malicious files
+
+```js
+#!/usr/bin/env node
+// cli-purge.js — scan a directory and delete malicious files
+
+const { scanDirectory, Verdict } = require('pompelmi');
+const fs   = require('fs');
+const path = require('path');
+
+const dir = path.resolve(process.argv[2] || '.');
+
+const results = await scanDirectory(dir, {
+  host: process.env.CLAMAV_HOST,
+  port: 3310,
+});
+
+console.log(`Scanned: ${results.clean.length + results.malicious.length + results.errors.length} files`);
+console.log(`Clean:     ${results.clean.length}`);
+console.log(`Malicious: ${results.malicious.length}`);
+console.log(`Errors:    ${results.errors.length}`);
+
+for (const f of results.malicious) {
+  fs.unlinkSync(f);
+  console.log(`Deleted: ${f}`);
+}
+
+process.exit(results.malicious.length > 0 ? 1 : 0);
+```
+
+---
+
+## JSON output for piping to other tools
+
+```js
+// cli-scan-json.js — outputs JSON for use with jq
+const results = [];
+// ... scan logic ...
+
+process.stdout.write(JSON.stringify({ files: results }, null, 2));
+process.exit(anyMalicious ? 1 : 0);
+```
+
+```bash
+node cli-scan-json.js /uploads/ | jq '.files[] | select(.verdict == "Malicious") | .path'
+```