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

fix(build): Bump dependencies, improve test/build scripts, expand documentation and add project metadata

Browse Source
This commit is contained in:
Jürgen Kunz
2025-08-16 20:37:58 +00:00
parent a810338cc4
commit a8c36a64b7
12 changed files with 3447 additions and 2223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
readme.md
View File

@@ -1,233 +1,322 @@
# @push.rocks/smartantivirus
# @push.rocks/smartantivirus 🛡️
A Node.js package for integrating antivirus scanning capabilities using ClamAV, allowing in-memory file and data scanning.
**Enterprise-grade antivirus scanning for Node.js applications** - Seamlessly integrate ClamAV's powerful virus detection into your TypeScript/JavaScript projects with zero hassle.
## Why SmartAntivirus? 🚀
In today's digital landscape, security is paramount. Whether you're building a file-sharing platform, processing user uploads, or handling sensitive data streams, you need reliable virus protection that just works. SmartAntivirus gives you:
- **🐳 Docker-based or Direct Connection** - Choose your deployment style
- **⚡ In-memory Scanning** - Lightning-fast scanning without disk I/O
- **🌊 Stream Processing** - Scan data on-the-fly as it flows through your app
- **🎯 TypeScript First** - Full type safety and IntelliSense support
- **📦 Zero Config** - Works out of the box with sensible defaults
- **🔄 Auto-updating** - Virus definitions stay current automatically
## Install
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
```
### Prerequisites
Or if you're using pnpm (recommended):
- Node.js and npm
- Docker (for container-based usage)
- ClamAV daemon (for direct daemon usage)
## Usage
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 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() {
// Instantiate a ClamAVManager
const clamAvManager = new ClamAVManager();
// Start ClamAV Docker container
await clamAvManager.startContainer();
// Listen for log events
clamAvManager.on('log', event => {
console.log(`ClamAV log (${event.type}): ${event.message}`);
});
// Fetch and display database information
const dbInfo = await clamAvManager.getDatabaseInfo();
console.log('Database Information:', dbInfo);
// Update the virus database
await clamAvManager.updateDatabase();
// Stop the container when done
await clamAvManager.stopContainer();
}
main().catch(console.error);
```bash
pnpm add @push.rocks/smartantivirus
```
### Direct Daemon Usage with ClamAvService
## Quick Start 🏃‍♂️
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:
### The 5-Minute Setup
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
async function main() {
const clamService = new ClamAvService('127.0.0.1', 3310);
// That's it! The service automatically manages a Docker container
const scanner = new ClamAvService();
// Verify connection to ClamAV
const isConnected = await clamService.verifyConnection();
console.log(`Connection to ClamAV: ${isConnected ? 'successful' : 'failed'}`);
// Scan a suspicious string
const result = await scanner.scanString('Is this text safe?');
console.log(result.isInfected ? '⚠️ Threat detected!' : '✅ All clear!');
// 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);
// Scan a buffer
const fileBuffer = await fs.readFile('./upload.pdf');
const scanResult = await scanner.scanBuffer(fileBuffer);
```
### Streaming Scanning
## Core Concepts 💡
`ClamAvService` provides methods to scan NodeJS and Web API streams. This is particularly useful for processing large files or data transferred over the network.
SmartAntivirus provides two main classes:
#### Example: NodeJS Streaming
### 🎯 ClamAvService
The high-level interface for virus scanning. It handles all the complexity behind a simple, intuitive API.
### 🐳 ClamAVManager
Low-level Docker container management for advanced use cases. Most users won't need to interact with this directly.
## Real-World Examples 🌍
### Protecting File Uploads
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
import express from 'express';
import multer from 'multer';
const app = express();
const scanner = new ClamAvService();
const upload = multer({ storage: multer.memoryStorage() });
app.post('/upload', upload.single('file'), async (req, res) => {
try {
// Scan the uploaded file buffer
const result = await scanner.scanBuffer(req.file.buffer);
if (result.isInfected) {
return res.status(400).json({
error: 'File rejected',
threat: result.reason
});
}
// File is safe, proceed with storage
await saveFile(req.file);
res.json({ message: 'File uploaded successfully' });
} catch (error) {
res.status(500).json({ error: 'Scan failed' });
}
});
```
### Streaming Large Files
Never load huge files into memory! Stream them instead:
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
import { createReadStream } from 'fs';
async function main() {
const clamService = new ClamAvService();
const scanner = new ClamAvService();
// 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);
async function scanLargeFile(filePath: string) {
const stream = createReadStream(filePath);
const result = await scanner.scanStream(stream);
if (result.isInfected) {
console.log(`🚨 Threat found: ${result.reason}`);
// Quarantine or delete the file
} else {
console.log('✅ File is clean');
}
}
main().catch(console.error);
```
#### Example: Web Stream (in Browser)
### Scanning Remote Content
Perfect for proxies, CDNs, or content moderation:
```typescript
import { ClamAvService } from '@push.rocks/smartantivirus';
const scanner = new ClamAvService();
async function scanWebStream(url: string) {
// Scan a file from a URL
const result = await scanner.scanFileFromWebAsStream('https://example.com/document.pdf');
// For browser environments using Web Streams API
async function scanInBrowser(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);
const result = await scanner.scanWebStream(webStream);
return result;
}
}
scanWebStream('http://example.com/streamed-file').catch(console.error);
```
### Handling Buffers
### Advanced Container Management
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);
```
### Error Handling and Event Monitoring
Both `ClamAVManager` and `ClamAvService` are designed with error handling features for robustness.
For production environments requiring fine-grained control:
```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 => {
class AntivirusService {
private manager: ClamAVManager;
async initialize() {
this.manager = new ClamAVManager();
// Start the container
await this.manager.startContainer();
// Set up log monitoring
this.manager.on('log', (event) => {
if (event.type === 'error') {
console.error(`ClamAV Error: ${event.message}`);
// Send to your logging service
}
});
console.log('ClamAV container started successfully.');
} catch (err) {
console.error('Error starting ClamAV container:', err);
// Update virus definitions
await this.manager.updateDatabase();
// Get database info
const dbInfo = await this.manager.getDatabaseInfo();
console.log(`Virus DB Version: ${dbInfo}`);
}
async shutdown() {
await this.manager.stopContainer();
}
}
errorHandlingExample().catch(console.error);
```
### Advanced Usage and Configuration
## Testing 🧪
#### Customize Container Settings
Customizing the Docker container setup is possible through class methods and properties:
We use the industry-standard EICAR test string for verification:
```typescript
const manager = new ClamAVManager();
console.log(`Container Name: ${manager.containerName}`); // Access default name
console.log(`Listening Port: ${manager.port}`); // Access default port
import { ClamAvService } from '@push.rocks/smartantivirus';
const scanner = new ClamAvService();
// This is the EICAR test string - it's harmless but triggers antivirus
const EICAR = 'X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*';
const result = await scanner.scanString(EICAR);
console.log(result.isInfected); // true
console.log(result.reason); // 'Eicar-Test-Signature'
```
#### 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
Utilize provided test scripts to validate your ClamAV setup:
Run the test suite:
```bash
npm run test
npm test
```
These tests use the `@push.rocks/tapbundle` framework to verify functionality, ensuring a reliable setup.
## API Reference 📚
### Conclusion
### ClamAvService
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
#### Constructor
```typescript
new ClamAvService(host?: string, port?: number)
```
- `host` - ClamAV daemon host (default: '127.0.0.1')
- `port` - ClamAV daemon port (default: 3310)
#### Methods
##### `scanString(text: string): Promise<ScanResult>`
Scan a text string for threats.
##### `scanBuffer(buffer: Buffer): Promise<ScanResult>`
Scan binary data in a Buffer.
##### `scanStream(stream: NodeJS.ReadableStream): Promise<ScanResult>`
Scan a Node.js readable stream.
##### `scanWebStream(stream: ReadableStream<Uint8Array>): Promise<ScanResult>`
Scan a Web Streams API stream (browser-compatible).
##### `scanFileFromWebAsStream(url: string): Promise<ScanResult>`
Download and scan a file from a URL.
##### `verifyConnection(): Promise<boolean>`
Test the connection to ClamAV daemon.
#### ScanResult Type
```typescript
interface ScanResult {
isInfected: boolean;
reason?: string; // Threat name if infected
}
```
### ClamAVManager
Advanced container management for production deployments:
- `startContainer()` - Launch ClamAV in Docker
- `stopContainer()` - Gracefully shutdown
- `updateDatabase()` - Update virus definitions
- `getDatabaseInfo()` - Get current DB version
- `getLogs()` - Retrieve container logs
- Event: `'log'` - Real-time log streaming
## Production Considerations 🏭
### Performance Tips
1. **Reuse connections** - Create one `ClamAvService` instance and reuse it
2. **Stream large files** - Don't load them into memory
3. **Implement timeouts** - Protect against hanging scans
4. **Monitor logs** - Watch for database update failures
### Security Best Practices
- Run ClamAV container with limited resources
- Implement rate limiting on scan endpoints
- Log all detected threats for audit trails
- Regularly update virus definitions
- Use separate containers for different environments
### Deployment Options
#### Docker Compose
```yaml
services:
clamav:
image: clamav/clamav:latest
ports:
- "3310:3310"
volumes:
- clamav-db:/var/lib/clamav
```
#### Kubernetes
The service automatically manages containers, but you can also deploy ClamAV separately and connect directly to the daemon.
## Troubleshooting 🔧
### Common Issues
**Container won't start**
- Ensure Docker is running
- Check port 3310 isn't already in use
- Verify sufficient disk space for virus definitions
**Scans timing out**
- Large files may take time - implement appropriate timeouts
- Check container resources (CPU/Memory)
- Ensure virus database is not updating
**False positives**
- Some packers/obfuscators trigger detection
- Whitelist known-safe patterns if needed
- Keep virus definitions updated
## Contributing & Support 🤝
- 🐛 [Report Issues](https://code.foss.global/push.rocks/smartantivirus/issues)
- 📖 [Documentation](https://code.foss.global/push.rocks/smartantivirus)
- 💬 [Discussions](https://code.foss.global/push.rocks/smartantivirus/issues)
## 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.