Enterprise-grade antivirus scanning for Node.js applications - Seamlessly integrate ClamAV's powerful virus detection into your TypeScript/JavaScript projects with zero hassle.

Why SmartAntivirus? 🚀

In today's digital landscape, security is paramount. Whether you're building a file-sharing platform, processing user uploads, or handling sensitive data streams, you need reliable virus protection that just works. SmartAntivirus gives you:

🐳 Docker-based or Direct Connection - Choose your deployment style
⚡ In-memory Scanning - Lightning-fast scanning without disk I/O
🌊 Stream Processing - Scan data on-the-fly as it flows through your app
🎯 TypeScript First - Full type safety and IntelliSense support
📦 Zero Config - Works out of the box with sensible defaults
🔄 Auto-updating - Virus definitions stay current automatically

Install

npm install @push.rocks/smartantivirus

Or if you're using pnpm (recommended):

pnpm add @push.rocks/smartantivirus

Quick Start 🏃‍♂️

The 5-Minute Setup

import { ClamAvService } from '@push.rocks/smartantivirus';

// That's it! The service automatically manages a Docker container
const scanner = new ClamAvService();

// Scan a suspicious string
const result = await scanner.scanString('Is this text safe?');
console.log(result.isInfected ? '⚠️ Threat detected!' : '✅ All clear!');

// Scan a buffer
const fileBuffer = await fs.readFile('./upload.pdf');
const scanResult = await scanner.scanBuffer(fileBuffer);

Core Concepts 💡

SmartAntivirus provides two main classes:

🎯 ClamAvService

The high-level interface for virus scanning. It handles all the complexity behind a simple, intuitive API.

🐳 ClamAVManager

Low-level Docker container management for advanced use cases. Most users won't need to interact with this directly.

Real-World Examples 🌍

Protecting File Uploads

import { ClamAvService } from '@push.rocks/smartantivirus';
import express from 'express';
import multer from 'multer';

const app = express();
const scanner = new ClamAvService();
const upload = multer({ storage: multer.memoryStorage() });

app.post('/upload', upload.single('file'), async (req, res) => {
  try {
    // Scan the uploaded file buffer
    const result = await scanner.scanBuffer(req.file.buffer);
    
    if (result.isInfected) {
      return res.status(400).json({ 
        error: 'File rejected',
        threat: result.reason 
      });
    }
    
    // File is safe, proceed with storage
    await saveFile(req.file);
    res.json({ message: 'File uploaded successfully' });
  } catch (error) {
    res.status(500).json({ error: 'Scan failed' });
  }
});

Streaming Large Files

Never load huge files into memory! Stream them instead:

import { ClamAvService } from '@push.rocks/smartantivirus';
import { createReadStream } from 'fs';

const scanner = new ClamAvService();

async function scanLargeFile(filePath: string) {
  const stream = createReadStream(filePath);
  const result = await scanner.scanStream(stream);
  
  if (result.isInfected) {
    console.log(`🚨 Threat found: ${result.reason}`);
    // Quarantine or delete the file
  } else {
    console.log('✅ File is clean');
  }
}

Scanning Remote Content

Perfect for proxies, CDNs, or content moderation:

const scanner = new ClamAvService();

// Scan a file from a URL
const result = await scanner.scanFileFromWebAsStream('https://example.com/document.pdf');

// For browser environments using Web Streams API
async function scanInBrowser(url: string) {
  const response = await fetch(url);
  const webStream = response.body as ReadableStream<Uint8Array>;
  
  if (webStream) {
    const result = await scanner.scanWebStream(webStream);
    return result;
  }
}

Advanced Container Management

For production environments requiring fine-grained control:

import { ClamAVManager } from '@push.rocks/smartantivirus';

class AntivirusService {
  private manager: ClamAVManager;
  
  async initialize() {
    this.manager = new ClamAVManager();
    
    // Start the container
    await this.manager.startContainer();
    
    // Set up log monitoring
    this.manager.on('log', (event) => {
      if (event.type === 'error') {
        console.error(`ClamAV Error: ${event.message}`);
        // Send to your logging service
      }
    });
    
    // Update virus definitions
    await this.manager.updateDatabase();
    
    // Get database info
    const dbInfo = await this.manager.getDatabaseInfo();
    console.log(`Virus DB Version: ${dbInfo}`);
  }
  
  async shutdown() {
    await this.manager.stopContainer();
  }
}

Testing 🧪

We use the industry-standard EICAR test string for verification:

import { ClamAvService } from '@push.rocks/smartantivirus';

const scanner = new ClamAvService();

// This is the EICAR test string - it's harmless but triggers antivirus
const EICAR = 'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*';

const result = await scanner.scanString(EICAR);
console.log(result.isInfected); // true
console.log(result.reason);     // 'Eicar-Test-Signature'

Run the test suite:

npm test

API Reference 📚

ClamAvService

Constructor

new ClamAvService(host?: string, port?: number)

host - ClamAV daemon host (default: '127.0.0.1')
port - ClamAV daemon port (default: 3310)

Methods

`scanString(text: string): Promise<ScanResult>`

Scan a text string for threats.

`scanBuffer(buffer: Buffer): Promise<ScanResult>`

Scan binary data in a Buffer.

`scanStream(stream: NodeJS.ReadableStream): Promise<ScanResult>`

Scan a Node.js readable stream.

`scanWebStream(stream: ReadableStream<Uint8Array>): Promise<ScanResult>`

Scan a Web Streams API stream (browser-compatible).

`scanFileFromWebAsStream(url: string): Promise<ScanResult>`

Download and scan a file from a URL.

`verifyConnection(): Promise<boolean>`

Test the connection to ClamAV daemon.

ScanResult Type

interface ScanResult {
  isInfected: boolean;
  reason?: string;  // Threat name if infected
}

ClamAVManager

Advanced container management for production deployments:

startContainer() - Launch ClamAV in Docker
stopContainer() - Gracefully shutdown
updateDatabase() - Update virus definitions
getDatabaseInfo() - Get current DB version
getLogs() - Retrieve container logs
Event: 'log' - Real-time log streaming

Production Considerations 🏭

Performance Tips

Reuse connections - Create one ClamAvService instance and reuse it
Stream large files - Don't load them into memory
Implement timeouts - Protect against hanging scans
Monitor logs - Watch for database update failures

Security Best Practices

Run ClamAV container with limited resources
Implement rate limiting on scan endpoints
Log all detected threats for audit trails
Regularly update virus definitions
Use separate containers for different environments

Deployment Options

Docker Compose

services:
  clamav:
    image: clamav/clamav:latest
    ports:
      - "3310:3310"
    volumes:
      - clamav-db:/var/lib/clamav

Kubernetes

The service automatically manages containers, but you can also deploy ClamAV separately and connect directly to the daemon.

Troubleshooting 🔧

Common Issues

Container won't start

Ensure Docker is running
Check port 3310 isn't already in use
Verify sufficient disk space for virus definitions

Scans timing out

Large files may take time - implement appropriate timeouts
Check container resources (CPU/Memory)
Ensure virus database is not updating

False positives

Some packers/obfuscators trigger detection
Whitelist known-safe patterns if needed
Keep virus definitions updated

Contributing & Support 🤝

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

@push.rocks/smartantivirus 🛡️