smartantivirus/readme.md

# @push.rocks/smartantivirus

A package for performing antivirus testing with ClamAV, featuring both direct daemon communication and Docker container management.

## Features

- **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:

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

1. **Docker-based Usage** (Recommended): Uses `ClamAVManager` to automatically handle container lifecycle
2. **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:

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

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

Both `ClamAVManager` and `ClamAvService` provide comprehensive error handling:

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

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

#### Container Configuration

The `ClamAVManager` supports customizing the Docker container:

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

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

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