Docker Integration: Automatically manages ClamAV containers for easy setup and testing
Real-time Logging: Captures and processes ClamAV logs with type-safe event handling
Database Management: Supports automatic database updates and version tracking
Flexible Scanning: Scan strings, buffers, and files for malware
Health Monitoring: Built-in service readiness checks and connection verification

Install

Installing @push.rocks/smartantivirus is straightforward. You'll need Node.js and npm installed on your machine:

npm install @push.rocks/smartantivirus

Prerequisites

Node.js and npm
Docker (for container-based usage)
ClamAV daemon (for direct daemon usage)

Usage

The package provides two main ways to use ClamAV:

Docker-based Usage (Recommended): Uses ClamAVManager to automatically handle container lifecycle
Direct Daemon Usage: Uses ClamAvService to communicate with an existing ClamAV daemon

Below is a comprehensive guide on how to use both approaches.

Docker-based Usage with ClamAVManager

The ClamAVManager class provides a high-level interface for managing ClamAV in Docker containers:

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

async function main() {
  // Create a new manager instance
  const manager = new ClamAVManager();

  // Start the ClamAV container
  await manager.startContainer();

  // Listen for log events
  manager.on('log', (event) => {
    console.log(`[ClamAV ${event.type}] ${event.message}`);
  });

  // Get database information
  const dbInfo = await manager.getDatabaseInfo();
  console.log('Database Info:', dbInfo);

  // Update virus definitions
  await manager.updateDatabase();

  // When done, stop the container
  await manager.stopContainer();
}

main().catch(console.error);

Direct Daemon Usage with ClamAvService

The primary interface provided by the package is the ClamAvService class. It allows you to scan data in memory or verify the connection to the ClamAV daemon.

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

async function main() {
  const clamService = new ClamAvService('127.0.0.1', 3310); // Replace with your ClamAV host and port

  // Verify connection to ClamAV
  const isConnected = await clamService.verifyConnection();
  console.log(`Connection to ClamAV: ${isConnected ? 'successful' : 'failed'}`);

  if (!isConnected) {
    console.error('Could not connect to ClamAV daemon. Please check your configuration.');
    return;
  }

  // Scan a text string
  const testString = 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*';
  const scanResult = await clamService.scanString(testString);
  console.log('Scan Result:', scanResult);
}

main().catch(console.error);

Streaming Scanning

The ClamAvService supports scanning both NodeJS streams and Web API streams using three specialized methods:

scanStream(stream: NodeJS.ReadableStream): Scans any NodeJS readable stream (files, network, etc.)
scanWebStream(webstream: ReadableStream): Scans a Web API ReadableStream
scanFileFromWebAsStream(url: string): Fetches and scans a file from a URL using NodeJS http/https

Example Usage

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

async function main() {
  const clamService = new ClamAvService('127.0.0.1', 3310);

  // Example 1: Scanning a local file stream (NodeJS)
  const fileStream = createReadStream('path/to/local/file');
  const streamResult = await clamService.scanStream(fileStream);
  console.log('Stream Scan Result:', streamResult);

  // Example 2: Scanning a web resource using NodeJS http/https
  const webResult = await clamService.scanFileFromWebAsStream('http://example.com/file');
  console.log('Web Stream Scan Result:', webResult);

  // Example 3: Scanning a Web API ReadableStream
  const response = await fetch('http://example.com/file');
  if (response.body) {
    const webStreamResult = await clamService.scanWebStream(response.body);
    console.log('Web Stream API Scan Result:', webStreamResult);
  }
}

main().catch(console.error);

Breaking Down the Example:

Initialization: We start by creating an instance of the ClamAvService class. It takes two optional parameters: the host and port where your ClamAV daemon is running. By default, it assumes 127.0.0.1 and 3310.
Verify Connection: The verifyConnection method is called to ensure that our application can communicate with the ClamAV daemon. It returns a promise that resolves to true if the connection is successful, and false otherwise.
Scan Strings: We utilize the scanString method to scan a text string (in this example, the EICAR test virus string is used). This method converts the string to a buffer and sends it to the ClamAV daemon for scanning.

Handling Buffers

Below is an example demonstrating scanning raw binary data in the form of buffers:

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

async function scanBufferExample() {
  const clamService = new ClamAvService();

  // This buffer should represent the binary data you want to scan.
  const buffer = Buffer.from('Sample buffer contents', 'utf8');

  try {
    const scanResult = await clamService.scanBuffer(buffer);
    console.log('Buffer Scan Result:', scanResult);
  } catch (error) {
    console.error('Error scanning buffer:', error);
  }
}

scanBufferExample();

Explanation:

We create an instance of ClamAvService.
A buffer is created and passed to the scanBuffer method, which scans the in-memory data for potential viruses.

Error Handling and Debugging

Both ClamAVManager and ClamAvService provide comprehensive error handling:

try {
  // Using ClamAVManager
  const manager = new ClamAVManager();
  await manager.startContainer();
  
  // Listen for errors in logs
  manager.on('log', (event) => {
    if (event.type === 'error') {
      console.error(`ClamAV Error: ${event.message}`);
    }
  });

  // Using ClamAvService
  const service = new ClamAvService();
  const scanResult = await service.scanString('Some suspicious string...');
  console.log(`Infection Status: ${scanResult.isInfected ? 'Infected' : 'Clean'}`);
  if (scanResult.isInfected) {
    console.log(`Reason: ${scanResult.reason}`);
  }
} catch (error) {
  console.error('An error occurred during the scanning process:', error);
}

Testing your setup

A preconfigured test script is provided, which demonstrates how to use the package with the Tap bundle testing framework. You can find the test script in test/test.ts. This is configured to run with the default @push.rocks/tapbundle setup:

npm run test

The tests include creating and utilizing a ClamAvService instance and attempts to scan the well-known EICAR test string. They ensure that the basic functionality of the package is working as intended.

Advanced Usage and Integration

Container Configuration

The ClamAVManager supports customizing the Docker container:

const manager = new ClamAVManager();

// Container properties are configurable
console.log(manager.containerName); // 'clamav-daemon'
console.log(manager.port); // 3310

Log Management

Access and process ClamAV logs:

const manager = new ClamAVManager();

// Get all logs
const logs = manager.getLogs();

// Filter logs by type
const errorLogs = logs.filter(log => log.type === 'error');
const updateLogs = logs.filter(log => log.type === 'update');

Health Checks

Monitor ClamAV service health:

const manager = new ClamAVManager();

// Service automatically checks readiness during initialization
await manager.startContainer(); // Includes readiness checks

// Get database status
const dbInfo = await manager.getDatabaseInfo();
console.log('Database Version:', dbInfo);

You can build upon these functionalities to implement advanced use cases such as:

Automated virus scanning in CI/CD pipelines
Real-time file monitoring in web applications
Cloud-based malware detection services
Integration with security information and event management (SIEM) systems

With the help of Node.js worker threads or external task queues like RabbitMQ, you can distribute scanning tasks efficiently within high-traffic environments.

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

Features