smartantivirus/readme.md

@push.rocks/smartantivirus

A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.

Install

To install @push.rocks/smartantivirus, ensure that you have Node.js and npm installed on your system. You will also need Docker if you intend to use the containerized version of ClamAV. Once the prerequisites are sorted, you can install the package using the following command:

npm install @push.rocks/smartantivirus

Prerequisites

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

Usage

The @push.rocks/smartantivirus package provides intuitive tools for integrating ClamAV's virus scanning capabilities into your Node.js applications. It supports both Docker-based container management and direct communication with a running ClamAV daemon. Let’s dive into how you can effectively use this package.

Docker-based Usage with ClamAVManager

The ClamAVManager class simplifies the process of managing a ClamAV service running inside a Docker container. It ensures that the container is started, the virus database is updated, and logs are captured for monitoring.

Basic Setup

Below demonstrates starting a ClamAV container, updating virus definitions, and reading logs:

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

async function main() {
  // Instantiate a ClamAVManager
  const clamAvManager = new ClamAVManager();

  // Start ClamAV Docker container
  await clamAvManager.startContainer();

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

  // Fetch and display database information
  const dbInfo = await clamAvManager.getDatabaseInfo();
  console.log('Database Information:', dbInfo);

  // Update the virus database
  await clamAvManager.updateDatabase();

  // Stop the container when done
  await clamAvManager.stopContainer();
}

main().catch(console.error);

Direct Daemon Usage with ClamAvService

If you prefer direct communication with an existing ClamAV daemon, use the ClamAvService class. This allows you to scan strings and streams directly in memory.

Connection Verification and String Scanning

Below is an example of verifying connection to the ClamAV daemon and scanning a given string for virus signatures, using the EICAR test string:

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

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

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

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

main().catch(console.error);

Streaming Scanning

ClamAvService provides methods to scan NodeJS and Web API streams. This is particularly useful for processing large files or data transferred over the network.

Example: NodeJS Streaming

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

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

  // Scan a local file stream
  const fileStream = createReadStream('path/to/suspicious/file');
  const fileScanResult = await clamService.scanStream(fileStream);
  console.log('File Stream Scan Result:', fileScanResult);

  // Scan a remote file by stream
  const remoteFileScan = await clamService.scanFileFromWebAsStream('http://example.com/file');
  console.log('Remote File Scan Result:', remoteFileScan);
}

main().catch(console.error);

Example: Web Stream (in Browser)

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

async function scanWebStream(url: string) {
  const response = await fetch(url);
  const webStream = response.body as ReadableStream<Uint8Array>;

  const clamService = new ClamAvService();
  if (webStream) {
    const scanResult = await clamService.scanWebStream(webStream);
    console.log('Web Stream Scan Result:', scanResult);
  }
}

scanWebStream('http://example.com/streamed-file').catch(console.error);

Handling Buffers

Scan binary data directly using a buffer:

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

async function main() {
  const clamService = new ClamAvService();
  const buffer = Buffer.from('Potentially harmful binary data', 'utf8');

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

main().catch(console.error);

Error Handling and Event Monitoring

Both ClamAVManager and ClamAvService are designed with error handling features for robustness.

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

async function errorHandlingExample() {
  const clamAvManager = new ClamAVManager();

  try {
    await clamAvManager.startContainer();

    // Listen for errors in logs
    clamAvManager.on('log', event => {
      if (event.type === 'error') {
        console.error(`ClamAV Error: ${event.message}`);
      }
    });

    console.log('ClamAV container started successfully.');
  } catch (err) {
    console.error('Error starting ClamAV container:', err);
  }
}

errorHandlingExample().catch(console.error);

Advanced Usage and Configuration

Customize Container Settings

Customizing the Docker container setup is possible through class methods and properties:

const manager = new ClamAVManager();
console.log(`Container Name: ${manager.containerName}`); // Access default name
console.log(`Listening Port: ${manager.port}`); // Access default port

Managing Logs

Capture and filter ClamAV logs for insights:

const manager = new ClamAVManager();
await manager.startContainer();

const logs = manager.getLogs();
const errorLogs = logs.filter(log => log.type === 'error');
console.log('Error Logs:', errorLogs);

Health Checks

Monitor and ensure ClamAV service readiness:

const manager = new ClamAVManager();
await manager.startContainer(); // Includes readiness checks

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

Testing your setup

Utilize provided test scripts to validate your ClamAV setup:

npm run test

These tests use the @push.rocks/tapbundle framework to verify functionality, ensuring a reliable setup.

Conclusion

The @push.rocks/smartantivirus package offers a powerful suite of tools for incorporating ClamAV's scanning capabilities into Node.js applications. With Docker integration and direct daemon access, it covers a wide range of use-cases, from file scanning to real-time stream analysis. Designed with a focus on flexibility and ease of use, it allows developers to build secure, antivirus-enabled applications efficiently. undefined