Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
clamscan - npm Package Compare versions
Comparing version 0.1.1 to 0.2.0
28
index.js
@@ -95,4 +95,5 @@ /*! | ||
| // @param Function callback What to do when all files have been scanned | ||
| // @param Function file_cb What to do after each file has been scanned | ||
| // ***************************************************************************** | ||
| this.do_multiscan = function(all_files,callback) { | ||
| this.do_multiscan = function(all_files,end_cb,file_cb) { | ||
| var chunks = []; | ||
@@ -118,2 +119,5 @@ var chunk = 0; | ||
| if(!infected) self.good_files.push(file); | ||
| if(__.isFunction(file_cb)) file_cb(err,file,infected); | ||
| if(self.completed_files % self.settings.max_forks == 0 || self.completed_files == all_files.length) { | ||
@@ -129,3 +133,3 @@ // Fires when all files have been scanned | ||
| } | ||
| if(__.isFunction(callback)) callback(null,self.good_files,self.bad_files); | ||
| if(__.isFunction(end_cb)) end_cb(null,self.good_files,self.bad_files); | ||
| self.reset(); | ||
@@ -188,7 +192,8 @@ } | ||
| // ----- | ||
| // @param Array files A list of files (full paths) to be scanned. | ||
| // @param Function callback What to do after the scan | ||
| // @param Array files A list of files (full paths) to be scanned. | ||
| // @param Function end_cb What to do after the scan | ||
| // @param Function file_cb What to do after each file has been scanned | ||
| // **************************************************************************** | ||
| NodeClam.prototype.scan_files = function(files,callback) { | ||
| this.do_multiscan(files,callback); | ||
| NodeClam.prototype.scan_files = function(files,end_cb,file_cb) { | ||
| this.do_multiscan(files,end_cb,file_cb); | ||
| } | ||
@@ -201,11 +206,12 @@ | ||
| // @param String path The directory to scan files of | ||
| // @param Function callback What to do when all files have been scanned | ||
| // @param Function en_cb What to do when all files have been scanned | ||
| // @param Function file_cb What to do after each file has been scanned | ||
| // **************************************************************************** | ||
| NodeClam.prototype.scan_dir = function(path,callback) { | ||
| NodeClam.prototype.scan_dir = function(path,end_cb,file_cb) { | ||
| var self = this; | ||
| fs.readdir(path, function(err,all_files) { | ||
| if(!err) { | ||
| self.do_multiscan(all_files,callback); | ||
| self.do_multiscan(all_files,end_cb,file_cb); | ||
| } else { | ||
| callback(err); | ||
| end_cb(err); | ||
| } | ||
@@ -268,2 +274,2 @@ }); | ||
| } | ||
| } |
| { | ||
| "name": "clamscan", | ||
| "version": "0.1.1", | ||
| "version": "0.2.0", | ||
| "author": "Kyle Farris <kfarris@chomponllc.com> (http://chomponllc.com)", | ||
@@ -5,0 +5,0 @@ "description": "Use Node JS to scan files on your server with ClamAV's clamscan binary. This is especially useful for scanning uploaded files provided by un-trusted sources.", |
241
README.md
@@ -1,92 +0,177 @@ | ||
| # NodeJS Clamscan Virus Scanning Utility | ||
| ## NodeJS Clamscan Virus Scanning Utility | ||
| Use Node JS to scan files on your server with ClamAV's clamscan binary. 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. This is especially useful for scanning uploaded files provided by un-trusted sources. | ||
| This module has the ability to scan many files at once if you set the max_forks greater than 1. By default it is set to scan 2 at a time. Using this technique may not prove to be more efficient depending on your setup. Scans are called via `child_process.exec` and, so, each execution (scan) is a new child process. The more CPU cores you have, the higher you can make this number. If you have 8 cores, I wouldn't go higher than 7. If you have 4, set this number to 3. If you have a 2-core machine, you can safely set this to 2, per my testing. | ||
| ## Examples | ||
| ## How to Install | ||
| ### Including node-clam in Your Project | ||
| npm install clamscan | ||
| ## Licence info | ||
| Licensed under the MIT License: | ||
| * http://www.opensource.org/licenses/mit-license.php | ||
| ## Getting Started | ||
| All of the values listed in the example below represent the default values for their respective configuration item. | ||
| var clam = require('clamscan')({ | ||
| max_forks: 2, // Num of files to scan at once (should be no more than # of CPU cores) | ||
| clam_path: '/usr/bin/clamscan', // Path to clamscan binary on your server | ||
| remove_infected: false, // If true, removes infected files | ||
| quarantine_infected: false, // False: Don't quarantine, Path: Moves files to this place. | ||
| scan_archives: true, // If true, scan archives (ex. zip, rar, tar, dmg, iso, etc...) | ||
| scan_recursively: true, // If true, deep scan folders recursively | ||
| scan_log: null, // Path to a writeable log file to write scan results into | ||
| db: null, // Path to a custom virus definition database | ||
| debug_mode: false // Whether or not to log info/debug/error msgs to the console | ||
| }); | ||
| Here is a non-default values example (to help you get an idea of what the proper-looking values should be): | ||
| You can simply do this: | ||
| var clam = require('clamscan')({ | ||
| max_forks: 1, // Do this if you only have one CPU core (12 for a monster machine) | ||
| clam_path: '/usr/bin/clam', // I dunno, maybe your clamscan is just call "clam" | ||
| remove_infected: true, // Removes files if they are infected | ||
| quarantine_path: '~/infected/', // Move file here. `remove_infected` must be FALSE, though. | ||
| scan_archives: false, // Choosing false here will save some CPU cycles | ||
| scan_recursively: true, // Choosing false here will save some CPU cycles | ||
| scan_log: '/var/log/node-clam', // You're a detail-oriented security professional. | ||
| db: '/usr/bin/better_clam_db', // Path to a custom virus definition database | ||
| debug_mode: true // This will put some debug info in your js console | ||
| }); | ||
| ```javascript | ||
| var clam = require('clamscan'); | ||
| ``` | ||
| ### Scanning an Entire Directory | ||
| And, you'll be good to go. | ||
| 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 | ||
| } | ||
| }); | ||
| ### Scanning a Single File | ||
| 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!"}); | ||
| } | ||
| }); | ||
| ### Scanning an Array of Files | ||
| 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 | ||
| } | ||
| }); | ||
| __BUT__: If you want more control, you can specify all sorts of options. | ||
| ```javascript | ||
| var clam = require('clamscan')({ | ||
| max_forks: 2, // Num of files to scan at once (should be no more than # of CPU cores) | ||
| clam_path: '/usr/bin/clamscan', // Path to clamscan binary on your server | ||
| remove_infected: false, // If true, removes infected files | ||
| quarantine_infected: false, // False: Don't quarantine, Path: Moves files to this place. | ||
| scan_archives: true, // If true, scan archives (ex. zip, rar, tar, dmg, iso, etc...) | ||
| scan_recursively: true, // If true, deep scan folders recursively | ||
| scan_log: null, // Path to a writeable log file to write scan results into | ||
| db: null, // Path to a custom virus definition database | ||
| debug_mode: false // Whether or not to log info/debug/error msgs to the console | ||
| }); | ||
| ``` | ||
| Here is a _non-default values example_ (to help you get an idea of what the proper-looking values should be): | ||
| ```javascript | ||
| var clam = require('clamscan')({ | ||
| max_forks: 1, // Do this if you only have one CPU core (12 for a monster machine) | ||
| clam_path: '/usr/bin/clam', // I dunno, maybe your clamscan is just call "clam" | ||
| remove_infected: true, // Removes files if they are infected | ||
| quarantine_path: '~/infected/', // Move file here. remove_infected must be FALSE, though. | ||
| scan_archives: false, // Choosing false here will save some CPU cycles | ||
| scan_recursively: true, // Choosing false here will save some CPU cycles | ||
| scan_log: '/var/log/node-clam', // You're a detail-oriented security professional. | ||
| db: '/usr/bin/better_clam_db', // Path to a custom virus definition database | ||
| debug_mode: true // This will put some debug info in your js console | ||
| }); | ||
| ``` | ||
| ## API | ||
| ### .is_infected(file_path, callback) | ||
| This method allows you to scan a single file. | ||
| #### Parameters: | ||
| * `file_path` (string) Represents a path to the file to be scanned. | ||
| * `callback` (function) Will be called when the scan is complete. It takes 3 parameters: | ||
| * `err` (string or null) A standard error message string (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. | ||
| #### Example: | ||
| ```javascript | ||
| 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!"}); | ||
| } | ||
| }); | ||
| ``` | ||
| ### .scan_dir(dir_path, end_callback, file_callback) | ||
| Allows you to scan an entire directory for infected files. | ||
| #### Parameters | ||
| * `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`(string or null) A standard error message string (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` (string or null) A standard error message string (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. | ||
| #### Example | ||
| ```javascript | ||
| 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 | ||
| } | ||
| }); | ||
| ``` | ||
| ### .scan_files(files, end_callback, file_callback) | ||
| 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 but not a whole directory. | ||
| #### Parameters | ||
| * `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` A standard error message string (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` (string or null) A standard error message string (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. | ||
| #### Example | ||
| ```javascript | ||
| 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); | ||
| }); | ||
| ``` | ||
| ## Contribute | ||
| 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. |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by23.48%
18739
- Lines of code
- increased by2.17%
235
- Number of lines in readme file
- increased by90.32%
177
No dependency changes