smartantivirus/readme.md

# @push.rocks/smartantivirus

A package for performing antivirus testing, especially suitable for use with ClamAV. 

## Install

Installing `@push.rocks/smartantivirus` is straightforward. You'll need Node.js and npm installed on your machine to get started. Once they are ready, you can add the `@push.rocks/smartantivirus` package to your project by running the following command:

```bash
npm install @push.rocks/smartantivirus

This will add the package to your project's dependencies and allow you to integrate antivirus scanning capabilities directly into your application.

Usage

The @push.rocks/smartantivirus package provides tools to easily integrate antivirus scanning capabilities into your Node.js application by interfacing with the ClamAV daemon. Below is a comprehensive guide on how to use the features of this library.

Setting Up the ClamAV Daemon

Before using this package, make sure you have ClamAV installed and running on your system. You can find installation instructions for various operating systems on the ClamAV official website.

After installing ClamAV, start the ClamAV daemon (clamd). Make sure it is configured to listen on a port accessible to your Node.js application. You can configure this in the clamd.conf file, typically located in /etc/clamav/clamd.conf.

Basic Usage

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);

Breaking Down the Example:

1. 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.

2. 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.

3. 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

The methods of ClamAvService throw errors if there are issues with communication or processing data. Wrap your code in try-catch blocks and use appropriate logging to handle errors gracefully.

try {
  const scanResult = await clamService.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

Beyond scanning strings and buffers, you can implement additional advanced use cases based on your specific application needs, such as integrating into web services or automating file scans in cloud environments. Consider building upon provided functionalities and adapting them to meet the requirements of your application architecture.

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

Conclusion

@push.rocks/smartantivirus provides a simple yet effective way to incorporate antivirus checks into your Node.js applications, leveraging the robust ClamAV engine. With features like in-memory scanning and connection verification, you can seamlessly ensure your data security solutions are integrated into your application lifecycle.

undefined