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](https://www.clamav.net/documents/installing-clamav).

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.

```typescript
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:

```typescript
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.

```typescript
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:

```bash
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.