This Services provides actions for testing files for malicious virus threats using ClamAV. It utilizes the file streaming capabilities of the moleculer framework
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
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.
This package is available in the npm-registry. In order to use it simply install it with yarn (or npm):
yarn add moleculer-antivirusTo 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.
| 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 |
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.
| 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 |
Type: PromiseLike.<({signature: (String|undefined), size: (Number|undefined), mime: (String|undefined), ext: (String|undefined)}|AntiVirusScanError)>
Pings the configured clamd backend
| 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 |
Type: PromiseLike.<(undefined|AntiVirusPingError)>
Acquires the version of the configured clamd backend
| 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 |
Type: PromiseLike.<(String|AntiVirusVersionError)>
Creates and returns a new clamd scanner
| 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 |
Type: Object
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!
| Property | Type | Default | Description |
|---|---|---|---|
stream |
ReadableStream |
required |
Type: PromiseLike.<({signature: (String|undefined)}|AntiVirusScanError)>
Obtain the mime type of a stream
| Property | Type | Default | Description |
|---|---|---|---|
stream |
ReadableStream |
required |
Type: PromiseLike.<({ext: String, mime: String}|AntiVirusMimeError)>
Obtain the size of a stream in bytes
| Property | Type | Default | Description |
|---|---|---|---|
stream |
ReadableStream |
required |
Type: PromiseLike.<({size: Number}|AntiVirusSizeError)>
$ docker-compose exec package yarn test
In development with watching
$ docker-compose up
moleculer-antivirus is available under the MIT license.
