Use Node JS to scan files on your server with ClamAV's clamscan/clamdscan binary or via TCP to a remote server or local UNIX Domain socket. This is especially useful for scanning uploaded files provided by un-trusted sources.
The clamscan npm package is a Node.js wrapper for the ClamAV antivirus software. It allows you to scan files, directories, and streams for viruses and malware using ClamAV's powerful scanning capabilities.
Scan a file
This feature allows you to scan a specific file for viruses. The code initializes the clamscan instance and scans the specified file, returning whether the file is infected and the names of any detected viruses.
const NodeClam = require('clamscan');
const clamscan = new NodeClam().init();
clamscan.then(async clamscan => {
const { isInfected, file, viruses } = await clamscan.scanFile('/path/to/file');
if (isInfected) {
console.log(`The file ${file} is infected with ${viruses}`);
} else {
console.log(`The file ${file} is clean.`);
}
}).catch(err => {
console.error(`Error initializing ClamScan: ${err}`);
});Scan a directory
This feature allows you to scan an entire directory for viruses. The code initializes the clamscan instance and scans the specified directory, returning whether any files are infected and listing the infected files and detected viruses.
const NodeClam = require('clamscan');
const clamscan = new NodeClam().init();
clamscan.then(async clamscan => {
const { isInfected, goodFiles, badFiles, viruses } = await clamscan.scanDir('/path/to/directory');
if (isInfected) {
console.log(`The directory contains infected files: ${badFiles}`);
} else {
console.log(`All files in the directory are clean.`);
}
}).catch(err => {
console.error(`Error initializing ClamScan: ${err}`);
});Scan a stream
This feature allows you to scan a stream for viruses. The code initializes the clamscan instance and scans the provided stream, returning whether the stream is infected and the names of any detected viruses.
const NodeClam = require('clamscan');
const fs = require('fs');
const clamscan = new NodeClam().init();
clamscan.then(async clamscan => {
const stream = fs.createReadStream('/path/to/file');
const { isInfected, viruses } = await clamscan.scanStream(stream);
if (isInfected) {
console.log(`The stream is infected with ${viruses}`);
} else {
console.log(`The stream is clean.`);
}
}).catch(err => {
console.error(`Error initializing ClamScan: ${err}`);
});The node-virustotal package is a Node.js client for the VirusTotal API, which allows you to scan files, URLs, and IP addresses for malware using multiple antivirus engines. Compared to clamscan, node-virustotal provides access to a broader range of antivirus engines but requires an API key and internet access.
Use Node JS to scan files on your server with ClamAV's clamscan/clamdscan binary or via TCP to a remote server or local UNIX Domain socket. This is especially useful for scanning uploaded files provided by un-trusted sources.
If you are using a version prior to 0.8.2, please upgrade! There was a security vulnerability in previous versions that allows a malicious user to execute code on your server. Specific details on how the attack could be implemented will not be disclosed here. Please update to 0.8.2 or greater ASAP. No breaking changes are included, only the security patch.
All other versions in NPM have been deprecated.
You will need to install ClamAV's clamscan binary and/or have clamdscan daemon running on your server. On linux, it's quite simple.
Fedora-based distros:
sudo yum install clamav
Debian-based distros:
sudo apt-get install clamav
For OS X, you can install clamav with brew:
sudo brew install clamav
You will need access to either:
clamd
/var/run/clamd.scan/clamd.sockclamd is running on your local serverclamd daemon
clamd is running on your local/remote serverNOTE: This module is not intended to work on a Windows server. This would be a welcome addition if someone wants to add that feature (I may get around to it one day but have no urgent need for this).
npm install clamscan
Licensed under the MIT License:
All of the values listed in the example below represent the default values for their respective configuration item.
You can simply do this:
var clam = require('clamscan')();
And, you'll be good to go.
BUT: If you want more control, you can specify all sorts of options.
var clam = require('clamscan')({
remove_infected: false, // If true, removes infected files
quarantine_infected: false, // False: Don't quarantine, Path: Moves files to this place.
scan_log: null, // Path to a writeable log file to write scan results into
debug_mode: false // Whether or not to log info/debug/error msgs to the console
file_list: null, // path to file containing list of files to scan (for scan_files method)
scan_recursively: true, // If true, deep scan folders recursively
clamscan: {
path: '/usr/bin/clamscan', // Path to clamscan binary on your server
db: null, // Path to a custom virus definition database
scan_archives: true, // If true, scan archives (ex. zip, rar, tar, dmg, iso, etc...)
active: true // If true, this module will consider using the clamscan binary
},
clamdscan: {
socket: false, // Socket file for connecting via TCP
host: false, // IP of host to connect to TCP interface
port: false, // Port of host to use when connecting via TCP interface
path: '/usr/bin/clamdscan', // Path to the clamdscan binary on your server
local_fallback: false, // Do no fail over to binary-method of scanning
config_file: '/etc/clamd.conf', // Specify config file if it's in an unusual place
multiscan: true, // Scan using all available cores! Yay!
reload_db: false, // If true, will re-load the DB on every call (slow)
active: true // If true, this module will consider using the clamdscan binary
},
preference: 'clamdscan' // If clamdscan is found and active, it will be used by default
});
Here is a non-default values example (to help you get an idea of what the proper-looking values should be):
var clam = require('clamscan')({
remove_infected: true, // Removes files if they are infected
quarantine_infected: '~/infected/', // Move file here. remove_infected must be FALSE, though.
scan_recursively: false, // Choosing false here will save some CPU cycles
scan_log: '/var/log/node-clam', // You're a detail-oriented security professional.
debug_mode: true // This will put some debug info in your js console
file_list: '/home/webuser/scan_files.txt', // path to file containing list of files to scan
clamscan: {
path: '/usr/bin/clam', // I dunno, maybe your clamscan is just call "clam"
db: '/usr/bin/better_clam_db', // Path to a custom virus definition database
scan_archives: false, // Choosing false here will save some CPU cycles
active: false // you don't want to use this at all because it's evil
},
clamdscan: {
socket: '/var/run/clamd.scan/clamd.sock', // This is pretty typical
host: '127.0.0.1', // If you want to connect locally but not through socket
port: 12345, // Because, why not
path: '/bin/clamdscan', // Special path to the clamdscan binary on your server
local_fallback: true, // Use local preferred binary to scan if socket/tcp fails
config_file: '/etc/clamd.d/daemon.conf', // A fairly typical config location
multiscan: false, // You hate speed and multi-threaded awesome-sauce
reload_db: true, // You want your scans to run slow like with clamscan
active: false // you don't want to use this at all because it's evil
},
preference: 'clamscan' // If clamscan is found and active, it will be used by default
});
As of version 0.9, this module supports communication with a local or remote ClamAV daemon through Unix Domain sockets or a TCP host/port combo. If you supply both in your configuration object, the UNIX Domain socket option will be used. The module not not fallback to using the alternative Host/Port method. If you wish to connect via Host/Port and not a Socket, please either omit the socket property in the config object or use socket: null.
If you specify a valid clamscan/clamdscan binary in your config and you set clamdscan.local_fallback: true in your config, this module will fallback to the traditional way this module has worked—using a binary directly/locally.
Also, there are some caveats to using the socket/tcp based approach:
remove_infected - remote clamd service config will dictate thisquarantine_infected - remote clamd service config will dictate thisscan_log - remote clamd service config will dictate thisfile_list - this simply won't be availableclamscan.db - only available on fallbackclamscan.scan_archives - only available on fallbackclamscan.path - only available on fallbackclamdscan.config_file - only available on fallbackclamdscan.path - only available on fallbackThis method allows you to determine the version of clamav you are interfacing with
callback (function) (optional) Will be called when the scan is complete. It takes 2 parameters:
err (object or null) A standard javascript Error object (null if no error)version (string) The version of the clamav server you're interfacing withclam.get_version(function(err, version) {
if (err) {
console.log(err);
}
console.log("ClamAV Version: " + version);
});
This method allows you to scan a single file.
.scan_file
file_path (string) Represents a path to the file to be scanned.callback (function) (optional) Will be called when the scan is complete. It takes 3 parameters:
err (object or null) A standard javascript Error object (null if no error)file (string) The original file_path passed into the is_infected method.is_infected (boolean) True: File is infected; False: File is clean. NULL: Unable to scan.clam.is_infected('/a/picture/for_example.jpg', function(err, file, is_infected) {
if (err) {
console.log(err);
return false;
}
if (is_infected) {
res.send({msg: "File is infected!"});
} else {
res.send({msg: "File is clean!"});
}
});
Allows you to scan an entire directory for infected files. This obeys your recursive option even for clamdscan which does not have a native way to turn this feature off. If you have multiple paths, send them in an array to scan_files.
TL;DR: For maximum speed, don't supply a file_callback.
If you choose to supply a file_callback, the scan will run a little bit slower (depending on number of files to be scanned) for clamdscan. If you are using clamscan, while it will work, I'd highly advise you to NOT pass a file_callback... it will run incredibly slow.
The good_files and bad_files parameters of the end_callback callback in this method will only contain the directories that were scanned in all but the following scenarios:
file_callback callback is provided, and scan_recursively is set to true.clamdscan and scan_recursively is set to false.dir_path (string) (required) Full path to the directory to scan.end_callback (function) (required) Will be called when the entire directory has been completely scanned. This callback takes 3 parameters:
err (object) A standard javascript Error object (null if no error)good_files (array) List of the full paths to all files that are clean.bad_files (array) List of the full paths to all files that are infected.file_callback (function) (optional) Will be called after each file in the directory has been scanned. This is useful for keeping track of the progress of the scan. This callback takes 3 parameters:
err (object or null) A standard Javascript Error object (null if no error)file (string) Path to the file that just got scanned.is_infected (boolean) True: File is infected; False: File is clean. NULL: Unable to scan file.clam.scan_dir('/some/path/to/scan', function(err, good_files, bad_files) {
if (!err) {
if (bad_files.length > 0) {
res.send({msg: "Your directory was infected. The offending files have been quarantined."});
} else {
res.send({msg: "Everything looks good! No problems here!."});
}
} else {
// Do some error handling
}
});
This allows you to scan many files that might be in different directories or maybe only certain files of a single directory. This is essentially a wrapper for is_infected that simplifies the process of scanning many files or directories.
files (array) A list of strings representing full paths to files you want scanned.end_callback (function) Will be called when the entire directory has been completely scanned. This callback takes 3 parameters:
err (object) A standard javascript Error object (null if no error)good_files (array) List of the full paths to all files that are clean.bad_files (array) List of the full paths to all files that are infected.file_callback (function) Will be called after each file in the directory has been scanned. This is useful for keeping track of the progress of the scan. This callback takes 3 parameters:
err (object or null)A standard javascript Error object (null if no error)file (string) Path to the file that just got scanned.is_infected (boolean) True: File is infected; False: File is clean. NULL: Unable to scan file.var scan_status = {
good: 0,
bad: 0
};
var files = [
'/path/to/file/1.jpg',
'/path/to/file/2.mov',
'/path/to/file/3.rb'
];
clam.scan_files(files, function(err, good_files, bad_files) {
if (!err) {
if (bad_files.length > 0) {
res.send({
msg: good_files.length + ' files were OK. ' + bad_files.length + ' were infected!',
bad: bad_files,
good: good_files
});
} else {
res.send({msg: "Everything looks good! No problems here!."});
}
} else {
// Do some error handling
}
}, function(err, file, is_infected) {
if (is_infected) {
scan_status.bad++;
} else {
scan_status.good++;
}
console.log("Scan Status: " + (scan_status.bad + scan_status.good) + "/" + files.length);
});
This method allows you to scan a binary stream. NOTE: This method will only work if the scanning method is a TCP or UNIX Domain socket. In other words, this will not work if you are using the local binary method.
stream (stream) A nodejs stream objectcallback (function) Will be called after the stream has been scanned (or attempted to be scanned):
err (object or null) A standard javascript Error object (null if no error)is_infected (boolean) True: Stream is infected; False: Stream is clean. NULL: Unable to scan file.Contrived Example:
var Readable = require('stream').Readable;
var rs = Readable();
rs.push('foooooo');
rs.push('barrrrr');
rs.push(null);
clam.scan_stream(stream, function(err, is_infected) {
if (err) {
console.log(err);
} else {
if (is_infected) {
console.log("Stream is infected! Booo!");
} else {
console.log("Stream is not infected! Yay!");
}
}
});
Slightly More "Realistic" Example:
This example shows how to scan every HTTP request as it comes in to your server using middleware funcionality in express (definitely not advisable!).
var express = require('express');
var app = express();
app.use(function (req, res, next) {
clam.scan_stream(req, function(err, is_infected) {
if (err) {
console.log("Unable to scan request for viruses!", err});
res.status(500).send({error: "There was an error accepting your request!"});
} else {
if (is_infected) {
res.status(500).send({error: "Your request is virus-infected!");
} else {
next();
}
}
});
});
app.get('/', function(req, res) {
// should never get here if request has virus.
});
var server = app.listen(3000);
If this modules is configured with a valid path to a file containing a newline-delimited list of files, it will use the list in that file when scanning if the first paramter passed is falsy.
Files List:
/some/path/to/file.zip
/some/other/path/to/file.exe
/one/more/file/to/scan.rb
Script:
var clam = require('clamscan')({
file_list: '/path/to/file_list.txt'
});
clam.scan_files(null, function(err, good_files, bad_files) {
// doo stuff...
});
You can set settings directly on an instance of this module using the following syntax:
var clam = require('clamscan')({ /** Some configs here... */});
// will quarantine files
clam.settings.quarantine_infected = true;
clam.is_infected('/some/file.txt');
// will not quarantine files
clam.settings.quarantine_infected = false;
clam.is_infected('/some/file.txt');
Just keep in mind that some of the nice validation that happens on instantiation won't happen if it's done this way. Of course, you could also just create a new instance with different a different initial configuration.
Got a missing feature you'd like to use? Found a bug? Go ahead and fork this repo, build the feature and issue a pull request.
fs.xxSync items).FAQs
Use Node JS to scan files on your server with ClamAV's clamscan/clamdscan binary or via TCP to a remote server or local UNIX Domain socket. This is especially useful for scanning uploaded files provided by un-trusted sources.
The npm package clamscan receives a total of 57,585 weekly downloads. As such, clamscan popularity was classified as popular.
We found that clamscan demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.
Security News
vlt introduced its new package manager and a serverless registry this week, innovating in a space where npm has stagnated.