Antivirus Service for the Moleculer framework

This Services provides actions for testing files for malicious virus threats using ClamAV. It utilizes the file streaming capabilities of the moleculer framework

Features

The following List details which features are implemented

• Scan a stream for malicious virus content
• Scan a local file for malicious virus content
• Scan a file at a remote location for malicious virus content
• Detect the mime type of a file
• Detect the size of a file

Requirements

This service relies on clamav.js which itself relies on a clam daemon available to connect to in the network. Files to be scanned are streamed to the clam daemon being installed. If the scan action is invoked with a string as an argument, it is assumed that the string is path to a valid location and a ReadStream from that location is created. If you plan to scan large files (> 100M), make sure to properly configure the clam daemon for accepting bigger files on the stream interface. This repository includes a Dockerfile which installes clamav. The examples folder includes a docker-compose file which includes an example, which itself includes a docker-compose file connecting to the antivirus service to a daemon configured for larger stream payloads. A configuration example for the clam daemon is included in the examples folder.

Install

This package is available in the npm-registry. In order to use it simply install it with yarn (or npm):

yarn add moleculer-antivirus

Usage

To make use of this Service, simply require it and create a new service:

const fs = require("fs");
let { ServiceBroker } = require("moleculer");
let AVService = require("moleculer-antivirus");

let broker = new ServiceBroker({ logger: console });

// Create a service
broker.createService({
    mixins: AVService
});

// Start server
broker.start().then(() => {
    const stream = fs.createReadStream('./suspicious.exe');
    broker.call('antivirus.scan', stream);
    broker.call('antivirus.scan', './this/suspicious.exe');
    broker.call('antivirus.scan', {url: "http://www.eicar.org/download/eicar.com"});
});

For a more indepth example checkout out the examples folder. It includes a docker-compose file, running docker-compose up will boot a broker with an antivirus service, a connected clamav deamon and an API Gateway to upload files to. This project includes a published postman collection enabling you to quickly explore the service in your local environment. EICAR signatures for testing are available here.

Settings

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | clamdPort | Number | null | The port that clamd is listening on | | clamdHost | String | null | The ip that clamd is listening on | | clamdTimeout | Number | null | The timeout when communicating with clamd for pinging and acquireing the clamd version | | clamdHealthCheckInterval | Number | null | This service will perform a periodic healthcheck of clamd. Use this setting to configure the inverval in which the healthcheck is performed. Set to 0 to turn healthcheks of |

Actions

scan

Scans a given file or stream. Not that this action does not reject, if a virus signature was detected! It will only reject if an error was encoutered during the scan. If a signature was found (and the file therefore is malicious) the resolved object of this action will contain the signature.

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | the | String, ReadableStream, Object | required | file to scan, can be a path, a stream or an object. If a path is given, this action will try to acquire a readable stream for the path. If an object is given, a http(s) stream will be acquired and the response body will be scanned. For the location of the request, the url property will be used, while all other properties will be used as node-fetch-options |

Results

Type: PromiseLike.<({signature: (String|undefined), size: (Number|undefined), mime: (String|undefined), ext: (String|undefined)}|AntiVirusScanError)>

Methods

ping

Pings the configured clamd backend

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | port | Number | required | The port clamd is listening on. Defaults to settings.clamdPort | | host | string | required | The host clamd is listening on. Defaults to settings.clamdHost | | timeout | Number | required | The timeout for this operation. Defaults to settings.clamdTimeout |

Results

Type: PromiseLike.<(undefined|AntiVirusPingError)>

clamdVersion

Acquires the version of the configured clamd backend

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | port | Number | required | The port clamd is listening on. Defaults to settings.clamdPort | | host | string | required | The host clamd is listening on. Defaults to settings.clamdHost | | timeout | Number | required | The timeout for this operation. Defaults to settings.clamdTimeout |

Results

Type: PromiseLike.<(String|AntiVirusVersionError)>

createScanner

Creates and returns a new clamd scanner

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | port | Number | required | The port clamd is listening on. Defaults to settings.clamdPort | | host | string | required | The host clamd is listening on. Defaults to settings.clamdHost |

Results

Type: Object

scan

Scan a stream for malicious content. Resolves with an object. If a virus signature was found in the stream, the signature property of the resolve object contains the name of the signature found. If the property is not undefined, you should consider the scanned stream malicious. This method rejects when an error was encountered during the scan, not when the scan found a signature!

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | stream | ReadableStream | required | |

Results

Type: PromiseLike.<({signature: (String|undefined)}|AntiVirusScanError)>

mime

Obtain the mime type of a stream

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | stream | ReadableStream | required | |

Results

Type: PromiseLike.<({ext: String, mime: String}|AntiVirusMimeError)>

size

Obtain the size of a stream in bytes

Parameters

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | | stream | ReadableStream | required | |

Results

Type: PromiseLike.<({size: Number}|AntiVirusSizeError)>

Test

$ docker-compose exec package yarn test

In development with watching

$ docker-compose up

License

moleculer-antivirus is available under the MIT license.