1.3.1

changelog.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2025-02-07 - 1.3.1 - fix(core)
+Updated descriptions and keywords in package.json and npmextra.json. Improved README content for usage clarity.
+
+- Revised package.json description and keywords to better represent the project's features.
+- Enhanced npmextra.json with updated module attributes.
+- Improved README with clearer instructions and examples for using ClamAVManager and ClamAvService.
+- Fixed incorrect import path in test.clamav.manager.ts.
+
+## 2025-02-05 - 1.3.0 - feat(ClamAvService)
+Add support for enhanced streaming methods in ClamAvService
+
+- Add methods to ClamAvService: scanStream for NodeJS streams, scanWebStream for Web API streams, and scanFileFromWebAsStream for fetching and scanning files from URLs.
+- Update usage examples in readme for new streaming methods.
+
+## 2025-02-05 - 1.2.0 - feat(ClamAvService)
+Add stream scanning methods to ClamAvService
+
+- Added scanStream method to support scanning NodeJS streams directly.
+- Introduced scanWebStream method for scanning web resources as streams.
+- Integrated stream scanning into existing ClamAvService class.
+
+## 2025-02-03 - 1.1.2 - fix(documentation)
+Update readme with additional legal and trademark information
+
+- Added legal information related to licensing and trademarks
+- Provided company details of Task Venture Capital GmbH
+
 ## 2025-02-03 - 1.1.1 - fix(clamav.manager)
 Improve log handling and add timeout for log reception in ClamAV manager tests
 

npmextra.json

@@ -5,21 +5,23 @@
       "githost": "code.foss.global",
       "gitscope": "push.rocks",
       "gitrepo": "smartantivirus",
-      "description": "A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.",
+      "description": "A Node.js package providing integration with ClamAV for anti-virus scanning, facilitating both Docker containerized management and direct connection to a ClamAV daemon.",
       "npmPackagename": "@push.rocks/smartantivirus",
       "license": "MIT",
       "projectDomain": "push.rocks",
       "keywords": [
         "antivirus",
-        "ClamAV",
         "Node.js",
+        "ClamAV",
         "virus scanning",
         "security",
-        "buffer scanning",
+        "Docker",
+        "in-memory scanning",
+        "file scanning",
+        "stream scanning",
         "data protection",
-        "HTTP requests",
-        "file handling",
-        "network communication",
+        "network security",
+        "buffer scanning",
         "software testing"
       ]
     }

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@push.rocks/smartantivirus",
-  "version": "1.1.1",
+  "version": "1.3.1",
   "private": false,
-  "description": "A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.",
+  "description": "A Node.js package providing integration with ClamAV for anti-virus scanning, facilitating both Docker containerized management and direct connection to a ClamAV daemon.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -25,6 +25,7 @@
   "dependencies": {
     "@push.rocks/smartfile": "^11.1.5",
     "@push.rocks/smartpath": "^5.0.18",
+    "@push.rocks/smartstream": "^3.2.5",
     "axios": "^1.7.9",
     "tar": "^7.4.3"
   },
@@ -50,15 +51,17 @@
   ],
   "keywords": [
     "antivirus",
-    "ClamAV",
     "Node.js",
+    "ClamAV",
     "virus scanning",
     "security",
-    "buffer scanning",
+    "Docker",
+    "in-memory scanning",
+    "file scanning",
+    "stream scanning",
     "data protection",
-    "HTTP requests",
-    "file handling",
-    "network communication",
+    "network security",
+    "buffer scanning",
     "software testing"
   ]
 }

pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       '@push.rocks/smartpath':
         specifier: ^5.0.18
         version: 5.0.18
+      '@push.rocks/smartstream':
+        specifier: ^3.2.5
+        version: 3.2.5
       axios:
         specifier: ^1.7.9
         version: 1.7.9

readme.md

@@ -1,18 +1,10 @@
 # @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
+A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.
 
 ## Install
 
-Installing `@push.rocks/smartantivirus` is straightforward. You'll need Node.js and npm installed on your machine:
+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:
 
 ```bash
 npm install @push.rocks/smartantivirus
@@ -26,41 +18,40 @@ npm install @push.rocks/smartantivirus
 
 ## 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.
+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 provides a high-level interface for managing ClamAV in Docker containers:
+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:
 
 ```typescript
 import { ClamAVManager } from '@push.rocks/smartantivirus';
 
 async function main() {
-  // Create a new manager instance
-  const manager = new ClamAVManager();
+  // Instantiate a ClamAVManager
+  const clamAvManager = new ClamAVManager();
 
-  // Start the ClamAV container
-  await manager.startContainer();
+  // Start ClamAV Docker container
+  await clamAvManager.startContainer();
 
   // Listen for log events
-  manager.on('log', (event) => {
-    console.log(`[ClamAV ${event.type}] ${event.message}`);
+  clamAvManager.on('log', event => {
+    console.log(`ClamAV log (${event.type}): ${event.message}`);
   });
 
-  // Get database information
-  const dbInfo = await manager.getDatabaseInfo();
-  console.log('Database Info:', dbInfo);
+  // Fetch and display database information
+  const dbInfo = await clamAvManager.getDatabaseInfo();
+  console.log('Database Information:', dbInfo);
 
-  // Update virus definitions
-  await manager.updateDatabase();
+  // Update the virus database
+  await clamAvManager.updateDatabase();
 
-  // When done, stop the container
-  await manager.stopContainer();
+  // Stop the container when done
+  await clamAvManager.stopContainer();
 }
 
 main().catch(console.error);
@@ -68,156 +59,175 @@ 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.
+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:
 
 ```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
+  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'}`);
 
-  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);
+  // 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);
 ```
 
-**Breaking Down the Example:**
+### Streaming Scanning
 
-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`.
+`ClamAvService` provides methods to scan NodeJS and Web API streams. This is particularly useful for processing large files or data transferred over the network.
 
-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.
+#### Example: NodeJS Streaming
 
-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.
+```typescript
+import { ClamAvService } from '@push.rocks/smartantivirus';
+import { createReadStream } from 'fs';
 
-### Handling Buffers
+async function main() {
+  const clamService = new ClamAvService();
 
-Below is an example demonstrating scanning raw binary data in the form of buffers:
+  // 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)
 
 ```typescript
 import { ClamAvService } from '@push.rocks/smartantivirus';
 
-async function scanBufferExample() {
+async function scanWebStream(url: string) {
+  const response = await fetch(url);
+  const webStream = response.body as ReadableStream<Uint8Array>;
+
   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);
+  if (webStream) {
+    const scanResult = await clamService.scanWebStream(webStream);
+    console.log('Web Stream Scan Result:', scanResult);
   }
 }
 
-scanBufferExample();
+scanWebStream('http://example.com/streamed-file').catch(console.error);
 ```
 
-**Explanation:**
+### Handling Buffers
 
-- 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:
+Scan binary data directly using a buffer:
 
 ```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}`);
-    }
-  });
+import { ClamAvService } from '@push.rocks/smartantivirus';
 
-  // 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}`);
+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);
   }
-} catch (error) {
-  console.error('An error occurred during the scanning process:', error);
 }
+
+main().catch(console.error);
+```
+
+### Error Handling and Event Monitoring
+
+Both `ClamAVManager` and `ClamAvService` are designed with error handling features for robustness.
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+const manager = new ClamAVManager();
+await manager.startContainer(); // Includes readiness checks
+
+const dbInfo = await manager.getDatabaseInfo();
+console.log('Database Version:', dbInfo);
 ```
 
 ### 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:
+Utilize provided test scripts to validate your ClamAV 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.
+These tests use the `@push.rocks/tapbundle` framework to verify functionality, ensuring a reliable setup.
 
-### Advanced Usage and Integration
+### Conclusion
 
-#### 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.
+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

test/test.clamav.manager.ts

@@ -1,4 +1,4 @@
-import { expect, tap } from '../ts/plugins.js';
+import { expect, tap } from '@push.rocks/tapbundle';
 import type { ClamAVLogEvent } from '../ts/classes.clamav.manager.js';
 import { setupClamAV, cleanupClamAV, getManager } from './helpers/clamav.helper.js';
 

test/test.ts

@@ -1,4 +1,4 @@
-import { expect, tap } from '../ts/plugins.js';
+import { tap, expect } from '@push.rocks/tapbundle';
 import * as smartantivirus from '../ts/index.js';
 import { setupClamAV, cleanupClamAV } from './helpers/clamav.helper.js';
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartantivirus',
-  version: '1.1.1',
-  description: 'A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.'
+  version: '1.3.1',
+  description: 'A Node.js package providing integration with ClamAV for anti-virus scanning, facilitating both Docker containerized management and direct connection to a ClamAV daemon.'
 }

ts/classes.clamavservice.ts

@@ -111,4 +111,77 @@ export class ClamAvService {
       });
     });
   }
+
+  /**
+   * Scans data from a NodeJS stream using ClamAV daemon's INSTREAM command.
+   */
+  public async scanStream(stream: NodeJS.ReadableStream): Promise<{ isInfected: boolean; reason?: string }> {
+    await this.ensureContainerStarted();
+    return new Promise((resolve, reject) => {
+      const client = new net.Socket();
+
+      client.connect(this.port, this.host, () => {
+        console.log('Connected to ClamAV daemon for stream scanning');
+        client.write('zINSTREAM\0');
+
+        stream.on('data', (chunk: Buffer) => {
+          const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          const sizeBuf = Buffer.alloc(4);
+          sizeBuf.writeUInt32BE(buf.length, 0);
+          client.write(sizeBuf);
+          client.write(buf);
+        });
+
+        stream.on('end', () => {
+          const endOfStream = Buffer.alloc(4);
+          endOfStream.writeUInt32BE(0, 0);
+          console.log('Stream ended, sending end-of-stream signal');
+          client.write(endOfStream);
+        });
+
+        stream.on('error', (err) => {
+          console.error('Error reading stream:', err);
+          reject(err);
+        });
+      });
+
+      client.on('data', (data) => {
+        const response = data.toString();
+        console.log('Raw Response from ClamAV (stream):', response);
+        const isInfected = response.includes('FOUND');
+        const reason = isInfected ? response.split('FOUND')[0].trim() : undefined;
+        resolve({ isInfected, reason });
+        client.end();
+      });
+
+      client.on('error', (err) => {
+        console.error('Error with ClamAV stream scanning:', err);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Scans a file from a web URL as a stream using ClamAV daemon's INSTREAM command.
+   */
+  public async scanFileFromWebAsStream(url: string): Promise<{ isInfected: boolean; reason?: string }> {
+    return new Promise((resolve, reject) => {
+      const protocol = url.startsWith('https') ? plugins.https : plugins.http;
+      protocol.get(url, (response) => {
+        this.scanStream(response).then(resolve).catch(reject);
+      }).on('error', (err) => {
+        console.error('Error fetching URL:', err);
+        reject(err);
+      });
+    });
+  }
+
+  /**
+   * Scans a web resource by URL using ClamAV daemon's INSTREAM command.
+   */
+  public async scanWebStream(webstreamArg: ReadableStream): Promise<{ isInfected: boolean; reason?: string }> {
+    // Convert the web ReadableStream to a NodeJS ReadableStream
+    const nodeStream = plugins.smartstream.nodewebhelpers.convertWebReadableToNodeReadable(webstreamArg);
+    return this.scanStream(nodeStream);
+  }
 }

ts/index.ts

@@ -1,2 +1,2 @@
-export * from './classes.smartantivirus.js';
+export * from './classes.clamavservice.js';
 export * from './classes.clamav.manager.js';

ts/plugins.ts

@@ -5,6 +5,8 @@ import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import { EventEmitter } from 'events';
 import net from 'net';
+import * as http from 'http';
+import * as https from 'https';
 
 export {
   fs,
@@ -13,19 +15,20 @@ export {
   spawn,
   promisify,
   EventEmitter,
-  net
+  net,
+  http,
+  https
 };
 
 // @push.rocks scope
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartfile from '@push.rocks/smartfile';
-import { expect, tap } from '@push.rocks/tapbundle';
+import * as smartstream from '@push.rocks/smartstream';
 
 export {
   smartpath,
   smartfile,
-  expect,
-  tap
+  smartstream,
 };
 
 // Third party scope