clamscan

Use Node JS to scan files on your server with ClamAV's clamscan binary or clamdscan daemon. This is especially useful for scanning uploaded files provided by un-trusted sources.

Use Node JS to scan files on your server with ClamAV's clamscan binary or clamdscan daemon. This is especially useful for scanning uploaded files provided by un-trusted sources.

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

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:

  • http://www.opensource.org/licenses/mit-license.php

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: {
        path: '/usr/bin/clamdscan', // Path to the clamdscan binary on your server 
        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: true, // 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: {
        path: '/bin/clamdscan', // Special path to the clamdscan binary on your server 
        config_file: __dirname + '/logs/clamscan-log', // logs file in your app directory 
        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    
});

This method allows you to scan a single 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.
clam.is_infected('/a/picture/for_example.jpg', function(errfileis_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:

  • A file_callback callback is provided, and scan_recursively is set to true.
  • The scanner is set to clamdscan and scan_recursively is set to false.
  • dir_path (string) Full path to the directory to scan.
  • 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.
clam.scan_dir('/some/path/to/scan', function(errgood_filesbad_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.
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(errgood_filesbad_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(errfileis_infected) {
    if(is_infected) {
        scan_status.bad++;
    } else {
        scan_status.good++;
    }
    console.log("Scan Status: " + (scan_status.bad + scan_status.good) + "/" + files.length);
});

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(errgood_filesbad_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.

  • Slight change of API to allow for a completely asynchronous module (ie, removal of all fs.xxSync items).