pompelmi 1.6.0 → 1.8.0

package/BADGE.md

@@ -0,0 +1,29 @@
+# Scanned by pompelmi — Badge
+
+Add this badge to your repository's `README.md` to show that your file uploads are scanned with pompelmi.
+
+## Markdown
+
+```markdown
+[![Scanned by pompelmi](https://img.shields.io/badge/scanned%20by-pompelmi-orange?logo=github)](https://github.com/pompelmi/pompelmi)
+```
+
+## HTML
+
+```html
+<a href="https://github.com/pompelmi/pompelmi">
+  <img src="https://img.shields.io/badge/scanned%20by-pompelmi-orange?logo=github" alt="Scanned by pompelmi">
+</a>
+```
+
+## RST (reStructuredText)
+
+```rst
+.. image:: https://img.shields.io/badge/scanned%20by-pompelmi-orange?logo=github
+   :target: https://github.com/pompelmi/pompelmi
+   :alt: Scanned by pompelmi
+```
+
+## Preview
+
+[![Scanned by pompelmi](https://img.shields.io/badge/scanned%20by-pompelmi-orange?logo=github)](https://github.com/pompelmi/pompelmi)

package/README.md

@@ -15,10 +15,22 @@
   <img src="https://img.shields.io/badge/license-ISC-blue" alt="license">
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml"><img src="https://github.com/pompelmi/pompelmi/actions/workflows/release.yml/badge.svg" alt="npm publish"></a>
+  <a href="https://github.com/pompelmi/pompelmi"><img src="https://img.shields.io/badge/scanned%20by-pompelmi-orange?logo=github" alt="Scanned by pompelmi"></a>
 </p>
 
 ---
 
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./docs/getting-started.md) | Installation, prerequisites, quickstart examples |
+| [API Reference](./docs/api.md) | Full function signatures, options, verdicts, error conditions |
+| [Docker / Remote Scanning](./docs/docker.md) | TCP sidecar, UNIX socket mount, docker-compose patterns |
+| [GitHub Action](./docs/github-action.md) | CI scanning, inputs/outputs, caching, example workflows |
+
+---
+
 ## Overview
 
 pompelmi is a minimal Node.js wrapper around [ClamAV](https://www.clamav.net/) that exposes a single async function — `scan()` — and returns one of three typed verdict Symbols: `Verdict.Clean`, `Verdict.Malicious`, or `Verdict.ScanError`. Full documentation at [pompelmi.app](https://pompelmi.app).
@@ -265,23 +277,17 @@ if (result === Verdict.ScanError) console.warn('Scan incomplete.');
 
 Pass `host` and `port` (or `socket`) to switch from the local `clamscan` CLI to the clamd daemon. Everything else — the returned verdicts, error types — is identical.
 
-**TCP (Docker / remote clamd):**
+**TCP:**
 ```js
-const result = await scan('/path/to/file.zip', {
-  host:    '127.0.0.1',
-  port:    3310,
-  timeout: 30_000, // socket idle timeout, ms — default 15 000
-});
+const result = await scan('/path/to/file.zip', { host: '127.0.0.1', port: 3310 });
 ```
 
-**UNIX socket (local clamd daemon):**
+**UNIX socket:**
 ```js
-const result = await scan('/path/to/file.zip', {
-  socket: '/run/clamav/clamd.sock', // path to clamd's UNIX domain socket
-});
+const result = await scan('/path/to/file.zip', { socket: '/run/clamav/clamd.sock' });
 ```
 
-pompelmi uses the ClamAV `INSTREAM` protocol: the file is streamed in 64 KB chunks, each prefixed with a 4-byte big-endian length header, terminated by four zero bytes. The response line (`stream: OK`, `stream: <name> FOUND`, or an error) is mapped to the same verdict Symbols.
+See **[docs/docker.md](./docs/docker.md)** for Docker Compose examples, UNIX socket volume mounts, `scanBuffer` / `scanStream` in clamd mode, and connection retry patterns.
 
 ---
 
@@ -302,155 +308,24 @@ When none of `socket`, `host`, or `port` is provided, pompelmi spawns `clamscan
 
 ## API Reference
 
-### `scan(filePath, [options])`
-
-```ts
-scan(
-  filePath: string,
-  options?: { socket?: string; host?: string; port?: number; timeout?: number }
-): Promise<symbol>
-```
-
-**Returns** a Promise that resolves to one of:
-
-| Verdict             | ClamAV exit code / response | Meaning                                                                 |
-|---------------------|-----------------------------|-------------------------------------------------------------------------|
-| `Verdict.Clean`     | `0` / `stream: OK`          | No threats found.                                                       |
-| `Verdict.Malicious` | `1` / `<name> FOUND`        | A known virus or malware signature was matched.                         |
-| `Verdict.ScanError` | `2` / other response        | Scan failed — I/O error, encrypted archive, permission denied. Treat file as untrusted. |
-
-**Rejects** with an `Error` in these cases:
-
-| Condition                             | Error message                     |
-|---------------------------------------|-----------------------------------|
-| `filePath` is not a string            | `filePath must be a string`       |
-| File does not exist                   | `File not found: <path>`          |
-| `clamscan` not in PATH                | `ENOENT` (from the OS)            |
-| ClamAV returns an unknown exit code   | `Unexpected exit code: N`         |
-| Process killed by signal              | `Process killed by signal: <SIG>` |
-| clamd connection timed out            | `clamd connection timed out after Nms` |
-
-Each `Verdict` Symbol exposes a `.description` property for safe serialisation:
-
-```js
-Verdict.Clean.description     // 'Clean'
-Verdict.Malicious.description // 'Malicious'
-Verdict.ScanError.description // 'ScanError'
-```
-
----
-
-### `scanBuffer(buffer, [options])`
+See **[docs/api.md](./docs/api.md)** for the full reference: function signatures, options table, verdict Symbols, error conditions, and error handling patterns.
 
-```ts
-scanBuffer(
-  buffer: Buffer,
-  options?: { socket?: string; host?: string; port?: number; timeout?: number }
-): Promise<symbol>
-```
-
-| Parameter | Type | Description |
-|---|---|---|
-| `buffer` | `Buffer` | The in-memory buffer to scan |
-| `options` | `object` | Same options as `scan()` — socket, host, port, timeout |
-
-**Returns** the same three Symbol verdicts as `scan()`: `Verdict.Clean`, `Verdict.Malicious`, `Verdict.ScanError`.
+**Quick summary:**
 
-**Rejects** with the same error types as `scan()` where applicable, plus:
+| Function | Input | clamd mode disk I/O |
+|----------|-------|---------------------|
+| `scan(filePath, [options])` | File path on disk | None (streamed) |
+| `scanBuffer(buffer, [options])` | `Buffer` | None (streamed) |
+| `scanStream(stream, [options])` | Node.js `Readable` | None (streamed) |
+| `scanDirectory(dirPath, [options])` | Directory path | None (streamed) |
 
-| Condition | Error message |
-|---|---|
-| `buffer` is not a Buffer | `buffer must be a Buffer` |
-| `buffer` is empty | `buffer is empty` |
+All four functions accept the same `options` object and resolve to the same three verdict Symbols:
 
-In clamd mode (`socket`, `host`, or `port` provided), the buffer is streamed directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, a temp file is written to `os.tmpdir()` and deleted automatically in a `finally` block regardless of outcome.
-
----
-
-### `scanStream(stream, [options])`
-
-```ts
-scanStream(
-  stream: Readable,
-  options?: { socket?: string; host?: string; port?: number; timeout?: number }
-): Promise<symbol>
-```
-
-| Parameter | Type | Description |
-|---|---|---|
-| `stream` | `Readable` | Node.js Readable stream to scan |
-| `options` | `object` | Same options as `scan()` — socket, host, port, timeout |
-
-**Returns** the same three Symbol verdicts as `scan()`: `Verdict.Clean`, `Verdict.Malicious`, `Verdict.ScanError`.
-
-**Rejects** with the same error types as `scan()` where applicable, plus:
-
-| Condition | Error message |
-|---|---|
-| `stream` is not a Readable | `stream must be a Readable` |
-| Stream emits error | propagated as-is |
-
-In clamd mode (`socket`, `host`, or `port` provided), the stream is piped directly to clamd via the INSTREAM protocol — no data is written to disk. In local mode, the stream is piped to a temp file in `os.tmpdir()` that is deleted automatically in a `finally` block.
-
----
-
-### `scanDirectory(dirPath, [options])`
-
-```ts
-scanDirectory(
-  dirPath: string,
-  options?: { socket?: string; host?: string; port?: number; timeout?: number }
-): Promise<{ clean: string[], malicious: string[], errors: string[] }>
-```
-
-Recursively scans every file in `dirPath` and returns three arrays of absolute paths.
-
-| Field | Type | Description |
-|---|---|---|
-| `clean` | `string[]` | Paths of files with no threats found |
-| `malicious` | `string[]` | Paths of files with a matched signature |
-| `errors` | `string[]` | Paths of files that could not be scanned |
-
-Per-file scan failures are caught and collected into `errors` — the function never throws because of an individual file.
-
-**Rejects** with an `Error` in these cases:
-
-| Condition | Error message |
-|---|---|
-| `dirPath` is not a string | `dirPath must be a string` |
-| Directory does not exist | `Directory not found: <path>` |
-
----
-
-### `ClamAVInstaller()` _(internal)_
-
-Installs ClamAV using the platform's native package manager. Resolves immediately if ClamAV is already installed.
-
-```ts
-ClamAVInstaller(): Promise<string>
-```
-
-| Platform | Package manager | Command                                   |
-|----------|-----------------|-------------------------------------------|
-| macOS    | Homebrew        | `brew install clamav`                     |
-| Linux    | apt-get         | `sudo apt-get install -y clamav clamav-daemon` |
-| Windows  | Chocolatey      | `choco install clamav -y`                 |
-
----
-
-### `updateClamAVDatabase()` _(internal)_
-
-Runs `freshclam` to download or refresh the virus definition database. Skips if the database file is already present.
-
-```ts
-updateClamAVDatabase(): Promise<string>
-```
-
-| Platform | Database path                         |
-|----------|---------------------------------------|
-| macOS    | `/usr/local/share/clamav/main.cvd`    |
-| Linux    | `/var/lib/clamav/main.cvd`            |
-| Windows  | `C:\ProgramData\ClamAV\main.cvd`      |
+| Symbol | Meaning |
+|--------|---------|
+| `Verdict.Clean` | No threats found |
+| `Verdict.Malicious` | Known signature matched |
+| `Verdict.ScanError` | Scan could not complete — treat as untrusted |
 
 ---
 
@@ -499,6 +374,56 @@ The [`examples/`](./examples/) directory contains standalone runnable scripts. E
 
 ---
 
+## GitHub Action
+
+[![GitHub Marketplace](https://img.shields.io/badge/Marketplace-Pompelmi%20ClamAV%20Scanner-blue?logo=github)](https://github.com/marketplace/actions/pompelmi-clamav-scanner)
+
+Scan any repository for viruses 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
+
+```yaml
+- uses: actions/checkout@v4
+
+- name: Virus scan
+  uses: pompelmi/pompelmi@v1.7.0
+```
+
+### Full example
+
+```yaml
+- uses: actions/checkout@v4
+
+- name: Virus scan
+  id: scan
+  uses: pompelmi/pompelmi@v1.7.0
+  with:
+    path: 'uploads/'        # scan a subdirectory instead of the whole workspace
+    fail-on-virus: 'true'   # fail the workflow step on detection (default)
+
+- name: Print infected files
+  if: always()
+  run: echo "${{ steps.scan.outputs.infected-files }}"
+```
+
+### 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` |
+
+### 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 available at [`.github/workflows/action-example.yml`](./.github/workflows/action-example.yml). Full reference — inputs, outputs, layer caching, and more examples — in **[docs/github-action.md](./docs/github-action.md)**.
+
+---
+
 ## Contributing
 
 Full documentation and guides are available in the [Wiki](https://github.com/pompelmi/pompelmi/wiki).

package/action/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends clamav clamav-freshclam && \
+    rm -rf /var/lib/apt/lists/* && \
+    sed -i 's/^Example/#Example/' /etc/clamav/freshclam.conf && \
+    mkdir -p /var/lib/clamav /run/clamav
+
+WORKDIR /action
+
+RUN npm install pompelmi
+
+COPY entrypoint.sh ./entrypoint.sh
+COPY scanner.js ./scanner.js
+
+RUN chmod +x ./entrypoint.sh
+
+ENTRYPOINT ["/action/entrypoint.sh"]

package/action/entrypoint.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+set -e
+
+SCAN_PATH="${1:-.}"
+FAIL_ON_VIRUS="${2:-true}"
+
+# Resolve relative paths against the GitHub workspace mount point
+WORKSPACE="${GITHUB_WORKSPACE:-/github/workspace}"
+case "$SCAN_PATH" in
+    /*) FULL_PATH="$SCAN_PATH" ;;
+    *)  FULL_PATH="${WORKSPACE}/${SCAN_PATH}" ;;
+esac
+
+echo "::group::Updating ClamAV virus definitions (freshclam)"
+# Remove any stale lock left from previous container runs
+rm -f /run/clamav/freshclam.pid /run/lock/freshclam 2>/dev/null || true
+freshclam --quiet 2>&1 \
+    && echo "Definitions updated successfully." \
+    || echo "Warning: freshclam update failed — scanning with cached definitions."
+echo "::endgroup::"
+
+echo "Scanning: ${FULL_PATH}"
+exec node /action/scanner.js "${FULL_PATH}" "${FAIL_ON_VIRUS}"

package/action/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "pompelmi-action",
+  "version": "1.8.0",
+  "private": true,
+  "description": "GitHub Action entrypoint for pompelmi ClamAV scanner",
+  "main": "scanner.js",
+  "scripts": {},
+  "dependencies": {
+    "@actions/artifact": "^2.1.11"
+  }
+}

package/action/scanner.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { scan, scanDirectory, Verdict } = require('pompelmi');
+
+const scanPath    = process.argv[2] || '.';
+const failOnVirus = process.argv[3] !== 'false';
+
+async function writeReport(clean, malicious, errors, outputDir) {
+    const total  = clean.length + malicious.length + errors.length;
+    const status = malicious.length > 0 ? 'infected' : 'clean';
+
+    const rows = [
+        ...clean.map(f => ({ file: f, status: 'clean', verdict: 'Clean' })),
+        ...malicious.map(f => ({ file: f, status: 'infected', verdict: 'Malicious' })),
+        ...errors.map(f => ({ file: f, status: 'error', verdict: 'ScanError' })),
+    ];
+
+    const json = JSON.stringify({ status, total, clean: clean.length, malicious: malicious.length, errors: errors.length, files: rows }, null, 2);
+    fs.writeFileSync(path.join(outputDir, 'report.json'), json);
+
+    const tableRows = rows.map(r => {
+        const color = r.status === 'clean' ? '#22c55e' : r.status === 'infected' ? '#ef4444' : '#f59e0b';
+        return `<tr><td>${escHtml(r.file)}</td><td style="color:${color};font-weight:bold">${r.verdict}</td></tr>`;
+    }).join('\n');
+
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Pompelmi Scan Report</title>
+<style>
+  body { font-family: sans-serif; max-width: 900px; margin: 40px auto; padding: 0 20px; }
+  h1 { font-size: 1.5rem; }
+  .summary { display: flex; gap: 24px; margin: 16px 0; }
+  .stat { background: #f1f5f9; border-radius: 8px; padding: 12px 20px; text-align: center; }
+  .stat span { display: block; font-size: 1.8rem; font-weight: bold; }
+  table { width: 100%; border-collapse: collapse; margin-top: 24px; }
+  th { background: #0f172a; color: #fff; text-align: left; padding: 8px 12px; }
+  td { padding: 8px 12px; border-bottom: 1px solid #e2e8f0; word-break: break-all; }
+  tr:hover td { background: #f8fafc; }
+</style>
+</head>
+<body>
+<h1>${status === 'clean' ? '✅' : '❌'} Pompelmi Scan Report</h1>
+<div class="summary">
+  <div class="stat"><span>${total}</span>Total</div>
+  <div class="stat"><span style="color:#22c55e">${clean.length}</span>Clean</div>
+  <div class="stat"><span style="color:#ef4444">${malicious.length}</span>Infected</div>
+  <div class="stat"><span style="color:#f59e0b">${errors.length}</span>Errors</div>
+</div>
+<table>
+<thead><tr><th>File</th><th>Verdict</th></tr></thead>
+<tbody>
+${tableRows}
+</tbody>
+</table>
+</body>
+</html>`;
+    fs.writeFileSync(path.join(outputDir, 'report.html'), html);
+
+    return { jsonPath: path.join(outputDir, 'report.json'), htmlPath: path.join(outputDir, 'report.html') };
+}
+
+function escHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+async function uploadArtifact(jsonPath, htmlPath) {
+    try {
+        const { DefaultArtifactClient } = require('@actions/artifact');
+        const client = new DefaultArtifactClient();
+        await client.uploadArtifact('pompelmi-scan-report', [jsonPath, htmlPath], path.dirname(jsonPath));
+        console.log('Scan report artifact uploaded: pompelmi-scan-report');
+    } catch (err) {
+        console.warn(`Could not upload artifact (not running in Actions?): ${err.message}`);
+    }
+}
+
+async function main() {
+    const resolved = path.resolve(scanPath);
+
+    if (!fs.existsSync(resolved)) {
+        console.error(`::error::Path not found: ${resolved}`);
+        process.exit(2);
+    }
+
+    let clean = [], malicious = [], errors = [];
+    const stat = fs.statSync(resolved);
+
+    if (stat.isDirectory()) {
+        const result = await scanDirectory(resolved);
+        clean     = result.clean;
+        malicious = result.malicious;
+        errors    = result.errors;
+    } else {
+        const verdict = await scan(resolved);
+        if (verdict === Verdict.Clean)          clean.push(resolved);
+        else if (verdict === Verdict.Malicious) malicious.push(resolved);
+        else                                    errors.push(resolved);
+    }
+
+    const total  = clean.length + malicious.length + errors.length;
+    const status = malicious.length > 0 ? 'infected' : 'clean';
+
+    // --- GitHub outputs ---
+    const outputFile = process.env.GITHUB_OUTPUT;
+    if (outputFile) {
+        const lines = [
+            `status=${status}`,
+            `infected-files<<POMPELMI_EOF`,
+            malicious.join('\n'),
+            `POMPELMI_EOF`,
+        ].join('\n') + '\n';
+        fs.appendFileSync(outputFile, lines);
+    }
+
+    // --- Job summary ---
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+        const icon = status === 'clean' ? '✅' : '❌';
+        const rows = [
+            `## ${icon} ClamAV Scan Results`,
+            '',
+            `| Metric | Count |`,
+            `|--------|-------|`,
+            `| Files scanned | ${total} |`,
+            `| Clean | ${clean.length} |`,
+            `| Infected | **${malicious.length}** |`,
+            `| Errors | ${errors.length} |`,
+        ];
+        if (malicious.length > 0) {
+            rows.push('', '### Infected Files', '');
+            malicious.forEach(f => rows.push(`- \`${f}\``));
+        }
+        fs.appendFileSync(summaryFile, rows.join('\n') + '\n');
+    }
+
+    // --- Report artifact ---
+    const reportDir = process.env.RUNNER_TEMP || '/tmp';
+    const { jsonPath, htmlPath } = await writeReport(clean, malicious, errors, reportDir);
+    await uploadArtifact(jsonPath, htmlPath);
+
+    // --- Console ---
+    console.log(`\nScan complete — ${total} file(s) scanned`);
+    console.log(`  Clean:    ${clean.length}`);
+    console.log(`  Infected: ${malicious.length}`);
+    console.log(`  Errors:   ${errors.length}`);
+    console.log(`  Status:   ${status.toUpperCase()}`);
+
+    if (malicious.length > 0) {
+        console.error('\nInfected files:');
+        malicious.forEach(f => console.error(`  ${f}`));
+        if (failOnVirus) {
+            console.error('\n::error::Virus(es) detected — failing workflow.');
+            process.exit(1);
+        }
+    }
+}
+
+main().catch(err => {
+    console.error(`::error::Scanner crashed: ${err.message}`);
+    process.exit(2);
+});

package/action.yml

@@ -0,0 +1,29 @@
+name: 'Pompelmi ClamAV Scanner'
+description: 'Scan for viruses with ClamAV (bundled) — no daemon, no cloud, zero external dependencies'
+author: 'pompelmi'
+branding:
+  icon: 'shield'
+  color: 'orange'
+
+inputs:
+  path:
+    description: 'Directory or file to scan (default: full workspace)'
+    required: false
+    default: '.'
+  fail-on-virus:
+    description: 'Fail the workflow step when infected files are found'
+    required: false
+    default: 'true'
+
+outputs:
+  infected-files:
+    description: 'Newline-separated list of infected file paths (empty when clean)'
+  status:
+    description: '"clean" or "infected"'
+
+runs:
+  using: 'docker'
+  image: './action/Dockerfile'
+  args:
+    - ${{ inputs.path }}
+    - ${{ inputs.fail-on-virus }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pompelmi",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "ClamAV for humans — scan any file and get back Clean, Malicious, or ScanError. No daemons. No cloud. No native bindings.",
   "license": "ISC",
   "author": "pompelmi contributors",

package/src/index.js

@@ -1,4 +1,5 @@
 const { scan, scanBuffer, scanStream, scanDirectory } = require('./ClamAVScanner.js');
 const { Verdict }                                     = require('./verdicts.js');
+const { middleware }                                  = require('./middleware.js');
 
-module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict };
+module.exports = { scan, scanBuffer, scanStream, scanDirectory, Verdict, middleware };

package/src/middleware.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { scanBuffer, Verdict } = require('./ClamAVScanner.js');
+
+function middleware(opts = {}) {
+    const field = opts.uploadField || 'file';
+
+    return async function pompelmiMiddleware(req, res, next) {
+        let buffers = [];
+
+        if (req.file) {
+            buffers = [req.file.buffer];
+        } else if (req.files) {
+            const files = Array.isArray(req.files)
+                ? req.files
+                : (req.files[field] || Object.values(req.files).flat());
+            buffers = files.map(f => f.buffer).filter(Boolean);
+        }
+
+        if (buffers.length === 0) return next();
+
+        try {
+            for (const buf of buffers) {
+                const verdict = await scanBuffer(buf, opts);
+                if (verdict === Verdict.Malicious) {
+                    return res.status(403).json({ error: 'Malicious file detected' });
+                }
+            }
+            next();
+        } catch (err) {
+            next(err);
+        }
+    };
+}
+
+module.exports = { middleware };