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

### Streaming Scanning

The `ClamAvService` now also supports scanning streams directly using two new methods:

- `scanStream(stream: NodeJS.ReadableStream)`: Scans a NodeJS stream (local file streams, network streams, etc.)
- `scanWebStream(url: string)`: Fetches a web resource as a stream and scans it

#### Example Usage

```typescript
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
  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
  const webResult = await clamService.scanWebStream('http://example.com/file');
  console.log('Web Stream Scan Result:', webResult);
}

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.

## 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](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.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.