push.rocks/smartantivirus
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(core): Updated descriptions and keywords in package.json and npmextra.json. Improved README content for usage clarity.

Browse Source
This commit is contained in:
Philipp Kunz
2025-02-07 20:47:30 +01:00
parent 6ddcfc8d90
commit c5049d5155
6 changed files with 161 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
changelog.md
View File

@@ -1,5 +1,13 @@
# 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

14
npmextra.json
View File

@@ -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"
]
}

16
package.json
View File

@@ -2,7 +2,7 @@
"name": "@push.rocks/smartantivirus",
"version": "1.3.0",
"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",
@@ -51,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"
]
}
}

312
readme.md
View File

@@ -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,27 +59,26 @@ 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);
@@ -96,184 +86,148 @@ main().catch(console.error);
### Streaming Scanning
The `ClamAvService` supports scanning both NodeJS streams and Web API streams using three specialized methods:
`ClamAvService` provides methods to scan NodeJS and Web API streams. This is particularly useful for processing large files or data transferred over the network.
- `scanStream(stream: NodeJS.ReadableStream)`: Scans any NodeJS readable stream (files, network, etc.)
- `scanWebStream(webstream: ReadableStream)`: Scans a Web API ReadableStream
- `scanFileFromWebAsStream(url: string)`: Fetches and scans a file from a URL using NodeJS http/https
#### Example Usage
#### Example: NodeJS Streaming
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
import { createReadStream } from 'fs';
async function main() {
const clamService = new ClamAvService('127.0.0.1', 3310);
const clamService = new ClamAvService();
// Example 1: Scanning a local file stream (NodeJS)
const fileStream = createReadStream('path/to/local/file');
const streamResult = await clamService.scanStream(fileStream);
console.log('Stream Scan Result:', streamResult);
// 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);
// Example 2: Scanning a web resource using NodeJS http/https
const webResult = await clamService.scanFileFromWebAsStream('http://example.com/file');
console.log('Web Stream Scan Result:', webResult);
// Scan a remote file by stream
const remoteFileScan = await clamService.scanFileFromWebAsStream('http://example.com/file');
console.log('Remote File Scan Result:', remoteFileScan);
}
// Example 3: Scanning a Web API ReadableStream
const response = await fetch('http://example.com/file');
if (response.body) {
const webStreamResult = await clamService.scanWebStream(response.body);
console.log('Web Stream API Scan Result:', webStreamResult);
main().catch(console.error);
```
#### Example: Web Stream (in Browser)
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
async function scanWebStream(url: string) {
const response = await fetch(url);
const webStream = response.body as ReadableStream<Uint8Array>;
const clamService = new ClamAvService();
if (webStream) {
const scanResult = await clamService.scanWebStream(webStream);
console.log('Web Stream Scan Result:', scanResult);
}
}
scanWebStream('http://example.com/streamed-file').catch(console.error);
```
### Handling Buffers
Scan binary data directly using a buffer:
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
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);
}
}
main().catch(console.error);
```
**Breaking Down the Example:**
### Error Handling and Event Monitoring
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:
Both `ClamAVManager` and `ClamAvService` are designed with error handling features for robustness.
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
import { ClamAVManager } 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');
async function errorHandlingExample() {
const clamAvManager = new ClamAVManager();
try {
const scanResult = await clamService.scanBuffer(buffer);
console.log('Buffer Scan Result:', scanResult);
} catch (error) {
console.error('Error scanning buffer:', error);
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);
}
}
scanBufferExample();
errorHandlingExample().catch(console.error);
```
**Explanation:**
### Advanced Usage and Configuration
- 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.
#### Customize Container Settings
### Error Handling and Debugging
Both `ClamAVManager` and `ClamAvService` provide comprehensive error handling:
Customizing the Docker container setup is possible through class methods and properties:
```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}`);
}
});
const manager = new ClamAVManager();
console.log(`Container Name: ${manager.containerName}`); // Access default name
console.log(`Listening Port: ${manager.port}`); // Access default port
```
// 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);
}
#### 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.
## 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.
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

2
test/test.clamav.manager.ts
View File

@@ -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';

4
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@push.rocks/smartantivirus',
version: '1.3.0',
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.'
}