NodeClam class definition.
6 |Clamscan-specific extension of the Javascript Error object
9 |NOTE: If string is passed to first param, it will be msg and data will be {}
A NodeClam - specific Transform extension that coddles 13 | chunks into the correct format for a ClamAV socket.
14 |Promise.<object>Quick check to see if the remote/local socket is working. Callback/Resolve 22 | response is an instance to a ClamAV socket client.
23 |ArrayGets a listing of all files (no directories) within a given path. 31 | By default, it will retrieve files recursively.
32 |Promise.<object>
46 | * [.reset([options], [cb])](#NodeClam+reset) ⇒ Promise.<object>
47 | * [.getVersion([cb])](#NodeClam+getVersion) ⇒ Promise.<string>
48 | * [.isInfected(file, [cb])](#NodeClam+isInfected) ⇒ Promise.<object>
49 | * [.passthrough()](#NodeClam+passthrough) ⇒ Transform
50 | * [.scanFile(file, [cb])](#NodeClam+scanFile) ⇒ Promise.<object>
51 | * [.scanFiles(files, [endCb], [fileCb])](#NodeClam+scanFiles) ⇒ Promise.<object>
52 | * [.scanDir(path, [endCb], [fileCb])](#NodeClam+scanDir) ⇒ Promise.<object>
53 | * [.scanStream(stream, [cb])](#NodeClam+scanStream) ⇒ Promise.<object>
54 |
55 |
56 |
57 | ### new NodeClam()
58 | This sets up all the defaults of the instance but does not
59 | necessarily return an initialized instance. Use `.init` for that.
60 |
61 |
62 |
63 | ### nodeClam.init([options], [cb]) ⇒ Promise.<object>
64 | Initialization method.
65 |
66 | **Kind**: instance method of [NodeClam](#NodeClam)
67 | **Returns**: Promise.<object> - An initated instance of NodeClam
68 | **Access**: public
69 |
70 | | Param | Type | Default | Description |
71 | | --- | --- | --- | --- |
72 | | [options] | object | | User options for the Clamscan module |
73 | | [options.removeInfected] | boolean | false | If true, removes infected files when found |
74 | | [options.quarantineInfected] | boolean \| string | false | If not false, should be a string to a path to quarantine infected files |
75 | | [options.scanLog] | string | null | Path to a writeable log file to write scan results into |
76 | | [options.debugMode] | boolean | false | If true, *a lot* of info will be spewed to the logs |
77 | | [options.fileList] | string | null | Path to file containing list of files to scan (for `scanFiles` method) |
78 | | [options.scanRecursively] | boolean | true | If true, deep scan folders recursively (for `scanDir` method) |
79 | | [options.clamscan] | object | | Options specific to the clamscan binary |
80 | | [options.clamscan.path] | string | "'/usr/bin/clamscan'" | Path to clamscan binary on your server |
81 | | [options.clamscan.db] | string | null | Path to a custom virus definition database |
82 | | [options.clamscan.scanArchives] | boolean | true | If true, scan archives (ex. zip, rar, tar, dmg, iso, etc...) |
83 | | [options.clamscan.active] | boolean | true | If true, this module will consider using the clamscan binary |
84 | | [options.clamdscan] | object | | Options specific to the clamdscan binary |
85 | | [options.clamdscan.socket] | string | false | Path to socket file for connecting via TCP |
86 | | [options.clamdscan.host] | string | false | IP of host to connec to TCP interface |
87 | | [options.clamdscan.port] | string | false | Port of host to use when connecting via TCP interface |
88 | | [options.clamdscan.timeout] | number | 60000 | Timeout for scanning files |
89 | | [options.clamdscan.localFallback] | boolean | false | If false, do not fallback to a local binary-method of scanning |
90 | | [options.clamdscan.path] | string | "'/usr/bin/clamdscan'" | Path to the `clamdscan` binary on your server |
91 | | [options.clamdscan.configFile] | string | null | Specify config file if it's in an usual place |
92 | | [options.clamdscan.multiscan] | boolean | true | If true, scan using all available cores |
93 | | [options.clamdscan.reloadDb] | boolean | false | If true, will re-load the DB on ever call (slow) |
94 | | [options.clamdscan.active] | boolean | true | If true, this module will consider using the `clamdscan` binary |
95 | | [options.clamdscan.bypassTest] | boolean | false | If true, check to see if socket is avaliable |
96 | | [options.clamdscan.tls] | boolean | false | If true, connect to a TLS-Termination proxy in front of ClamAV |
97 | | [options.preference] | object | 'clamdscan' | If preferred binary is found and active, it will be used by default |
98 | | [cb] | function | Promise.<object>
135 | Allows one to create a new instances of clamscan with new options.
136 |
137 | **Kind**: instance method of [NodeClam](#NodeClam)
138 | **Returns**: Promise.<object> - A reset instance of NodeClam
139 | **Access**: public
140 |
141 | | Param | Type | Default | Description |
142 | | --- | --- | --- | --- |
143 | | [options] | object | {} | Same options as the `init` method |
144 | | [cb] | function | Promise.<string>
149 | Establish the clamav version of a local or remote clamav daemon.
150 |
151 | **Kind**: instance method of [NodeClam](#NodeClam)
152 | **Returns**: Promise.<string> - - The version of ClamAV that is being interfaced with
153 | **Access**: public
154 |
155 | | Param | Type | Description |
156 | | --- | --- | --- |
157 | | [cb] | function | What to do when version is established |
158 |
159 | **Example**
160 | ```js
161 | // Callback example
162 | clamscan.getVersion((err, version) => {
163 | if (err) return console.error(err);
164 | console.log(`ClamAV Version: ${version}`);
165 | });
166 |
167 | // Promise example
168 | const clamscan = new NodeClam().init();
169 | const version = await clamscan.getVersion();
170 | console.log(`ClamAV Version: ${version}`);
171 | ```
172 |
173 |
174 | ### nodeClam.isInfected(file, [cb]) ⇒ Promise.<object>
175 | This method allows you to scan a single file. It supports a callback and Promise API.
176 | If no callback is supplied, a Promise will be returned. This method will likely
177 | be the most common use-case for this module.
178 |
179 | **Kind**: instance method of [NodeClam](#NodeClam)
180 | **Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`
181 | **Access**: public
182 |
183 | | Param | Type | Default | Description |
184 | | --- | --- | --- | --- |
185 | | file | string | | Path to the file to check |
186 | | [cb] | function | Transform
213 | Returns a PassthroughStream object which allows you to
214 | pipe a ReadbleStream through it and on to another output. In the case of this
215 | implementation, it's actually forking the data to also
216 | go to ClamAV via TCP or Domain Sockets. Each data chunk is only passed on to
217 | the output if that chunk was successfully sent to and received by ClamAV.
218 | The PassthroughStream object returned from this method has a special event
219 | that is emitted when ClamAV finishes scanning the streamed data (`scan-complete`)
220 | so that you can decide if there's anything you need to do with the final output
221 | destination (ex. delete a file or S3 object).
222 |
223 | **Kind**: instance method of [NodeClam](#NodeClam)
224 | **Returns**: Transform - A Transform stream for piping a Readable stream into
225 | **Access**: public
226 | **Example**
227 | ```js
228 | const NodeClam = require('clamscan');
229 |
230 | // You'll need to specify your socket or TCP connection info
231 | const clamscan = new NodeClam().init({
232 | clamdscan: {
233 | socket: '/var/run/clamd.scan/clamd.sock',
234 | host: '127.0.0.1',
235 | port: 3310,
236 | }
237 | });
238 |
239 | // For example's sake, we're using the Axios module
240 | const axios = require('axios');
241 |
242 | // Get a readable stream for a URL request
243 | const input = axios.get(someUrl);
244 |
245 | // Create a writable stream to a local file
246 | const output = fs.createWriteStream(someLocalFile);
247 |
248 | // Get instance of this module's PassthroughStream object
249 | const av = clamscan.passthrough();
250 |
251 | // Send output of Axios stream to ClamAV.
252 | // Send output of Axios to `someLocalFile` if ClamAV receives data successfully
253 | input.pipe(av).pipe(output);
254 |
255 | // What happens when scan is completed
256 | av.on('scan-complete', result => {
257 | const {isInfected, viruses} = result;
258 | // Do stuff if you want
259 | });
260 |
261 | // What happens when data has been fully written to `output`
262 | output.on('finish', () => {
263 | // Do stuff if you want
264 | });
265 |
266 | // NOTE: no errors (or other events) are being handled in this example but standard errors will be emitted according to NodeJS's Stream specifications
267 | ```
268 |
269 |
270 | ### nodeClam.scanFile(file, [cb]) ⇒ Promise.<object>
271 | Just an alias to `isInfected`. See docs for that for usage examples.
272 |
273 | **Kind**: instance method of [NodeClam](#NodeClam)
274 | **Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array }`
275 | **Access**: public
276 |
277 | | Param | Type | Description |
278 | | --- | --- | --- |
279 | | file | string | Path to the file to check |
280 | | [cb] | function | What to do after the scan |
281 |
282 |
283 |
284 | ### nodeClam.scanFiles(files, [endCb], [fileCb]) ⇒ Promise.<object>
285 | Scans an array of files or paths. You must provide the full paths of the
286 | files and/or paths. Also enables the ability to scan a file list.
287 |
288 | This is essentially a wrapper for isInfected that simplifies the process
289 | of scanning many files or directories.
290 |
291 | **NOTE:** The only way to get per-file notifications is through the callback API.
292 |
293 | **Kind**: instance method of [NodeClam](#NodeClam)
294 | **Returns**: Promise.<object> - Object like: `{ goodFiles: Array, badFiles: Array, errors: Object, viruses: Array }`
295 | **Access**: public
296 |
297 | | Param | Type | Default | Description |
298 | | --- | --- | --- | --- |
299 | | files | Array | | A list of files or paths (full paths) to be scanned |
300 | | [endCb] | function | function | Promise.<object>
339 | Scans an entire directory. Provides 3 params to end callback: Error, path
340 | scanned, and whether its infected or not. To scan multiple directories, pass
341 | them as an array to the `scanFiles` method.
342 |
343 | This obeys your recursive option even for `clamdscan` which does not have a native
344 | way to turn this feature off. If you have multiple paths, send them in an array
345 | to `scanFiles`.
346 |
347 | NOTE: While possible, it is NOT advisable to use the `fileCb` parameter when
348 | using the `clamscan` binary. Doing so with `clamdscan` is okay, however. This
349 | method also allows for non-recursive scanning with the clamdscan binary.
350 |
351 | **Kind**: instance method of [NodeClam](#NodeClam)
352 | **Returns**: Promise.<object> - Object like: `{ path: String, isInfected: Boolean, goodFiles: Array, badFiles: Array, viruses: Array }`
353 | **Access**: public
354 |
355 | | Param | Type | Default | Description |
356 | | --- | --- | --- | --- |
357 | | path | string | | The directory to scan files of |
358 | | [endCb] | function | function | Promise.<object>
381 | Allows you to scan a binary stream.
382 |
383 | **NOTE:** This method will only work if you've configured the module to allow the
384 | use of a TCP or UNIX Domain socket. In other words, this will not work if you only
385 | have access to a local ClamAV binary.
386 |
387 | **Kind**: instance method of [NodeClam](#NodeClam)
388 | **Returns**: Promise.<object> - Object like: `{ file: String, isInfected: Boolean, viruses: Array } `
389 | **Access**: public
390 |
391 | | Param | Type | Description |
392 | | --- | --- | --- |
393 | | stream | Readable | A readable stream to scan |
394 | | [cb] | function | What to do when the socket response with results |
395 |
396 | **Example**
397 | ```js
398 | const NodeClam = require('clamscan');
399 |
400 | // You'll need to specify your socket or TCP connection info
401 | const clamscan = new NodeClam().init({
402 | clamdscan: {
403 | socket: '/var/run/clamd.scan/clamd.sock',
404 | host: '127.0.0.1',
405 | port: 3310,
406 | }
407 | });
408 | const Readable = require('stream').Readable;
409 | const rs = Readable();
410 |
411 | rs.push('foooooo');
412 | rs.push('barrrrr');
413 | rs.push(null);
414 |
415 | // Callback Example
416 | clamscan.scanStream(stream, (err, { isInfected, viruses }) => {
417 | if (err) return console.error(err);
418 | if (isInfected) return console.log('Stream is infected! Booo!', viruses);
419 | console.log('Stream is not infected! Yay!');
420 | });
421 |
422 | // Async/Await Example
423 | const { isInfected, viruses } = await clamscan.scanStream(stream);
424 | ```
425 |
426 |
427 | ## NodeClamError
428 | Clamscan-specific extension of the Javascript Error object
429 |
430 | **NOTE**: If string is passed to first param, it will be `msg` and data will be `{}`
431 |
432 | **Kind**: global class
433 |
434 |
435 | ### new NodeClamError(data, ...params)
436 | Creates a new instance of a NodeClamError.
437 |
438 |
439 | | Param | Type | Description |
440 | | --- | --- | --- |
441 | | data | object | Additional data we might want to have access to on error |
442 | | ...params | any | The usual params you'd pass to create an Error object |
443 |
444 |
445 |
446 | ## NodeClamTransform
447 | A NodeClam - specific Transform extension that coddles
448 | chunks into the correct format for a ClamAV socket.
449 |
450 | **Kind**: global class
451 |
452 | * [NodeClamTransform](#NodeClamTransform)
453 | * [new NodeClamTransform(options, debugMode)](#new_NodeClamTransform_new)
454 | * [._transform(chunk, encoding, cb)](#NodeClamTransform+_transform)
455 | * [._flush(cb)](#NodeClamTransform+_flush)
456 |
457 |
458 |
459 | ### new NodeClamTransform(options, debugMode)
460 | Creates a new instance of NodeClamTransorm.
461 |
462 |
463 | | Param | Type | Default | Description |
464 | | --- | --- | --- | --- |
465 | | options | object | | Optional overrides to defaults (same as Node.js Transform) |
466 | | debugMode | boolean | false | If true, do special debug logging |
467 |
468 |
469 |
470 | ### nodeClamTransform.\_transform(chunk, encoding, cb)
471 | Actually does the transorming of the data for ClamAV.
472 |
473 | **Kind**: instance method of [NodeClamTransform](#NodeClamTransform)
474 |
475 | | Param | Type | Description |
476 | | --- | --- | --- |
477 | | chunk | Buffer | The piece of data to push onto the stream |
478 | | encoding | string | The encoding of the chunk |
479 | | cb | function | What to do when done pushing chunk |
480 |
481 |
482 |
483 | ### nodeClamTransform.\_flush(cb)
484 | This will flush out the stream when all data has been received.
485 |
486 | **Kind**: instance method of [NodeClamTransform](#NodeClamTransform)
487 |
488 | | Param | Type | Description |
489 | | --- | --- | --- |
490 | | cb | function | What to do when done |
491 |
492 |
493 |
494 | ## ping ⇒ Promise.<object>
495 | Quick check to see if the remote/local socket is working. Callback/Resolve
496 | response is an instance to a ClamAV socket client.
497 |
498 | **Kind**: global variable
499 | **Returns**: Promise.<object> - A copy of the Socket/TCP client
500 | **Access**: public
501 |
502 | | Param | Type | Description |
503 | | --- | --- | --- |
504 | | [cb] | function | What to do after the ping |
505 |
506 |
507 |
508 | ## getFiles(dir, [recursive]) ⇒ Array
509 | Gets a listing of all files (no directories) within a given path.
510 | By default, it will retrieve files recursively.
511 |
512 | **Kind**: global function
513 | **Returns**: Array - - List of all requested path files
514 |
515 | | Param | Type | Default | Description |
516 | | --- | --- | --- | --- |
517 | | dir | string | | The directory to get all files of |
518 | | [recursive] | boolean | true | If true (default), get all files recursively; False: only get files directly in path |
519 |
520 |
--------------------------------------------------------------------------------
/HISTORY.md:
--------------------------------------------------------------------------------
1 | # Changes
2 |
3 | This file is a manually maintained list of changes for each release. Feel free to add your changes here when sending pull requests. Also send corrections if you spot any mistakes.
4 |
5 | ## 0.2.1
6 |
7 | - ClamAV returns an exit code 1 when it detects a virus but `exec` was interpreting that response as an error. Checking the response with type-sensitive equivalence resolves this bug.
8 |
9 | ## 0.2.2
10 |
11 | - Fixed documentation
12 |
13 | ## 0.4.0 (2014-11-19)
14 |
15 | - Corrected the installation instructions for `clamav`. Thank you @jshamley!
16 | - Fixed major bug preventing the `scan_dir` method from working properly
17 | - Corrected documentation describing how to instantiate this module.
18 |
19 | ## 0.5.0 (2014-12-19)
20 |
21 | - Deprecated the `quarantine_path` option. Please only use `quarantine_infected` for now on.
22 | - Updated documentation to reflect above change.
23 |
24 | ## 0.6.0 (2015-01-02)
25 |
26 | **NOTE:** There are some breaking changes on this release. Since this is still a pre-version 1 release, I decided to only do a minor bump to 0.4.0
27 |
28 | - The ability to run "forked" instances of `clamscan` has been removed because of irregularities with different systems--namely if you had `max_forks` set to 3, it would sometimes only scan the first or last file in the group... not good.
29 | - Added the ability to use `clamdscan`. This ultimately negates the downside of removing the forking capability mentioned in item one. This is a really big improvement (many orders of magnitude) if your system has access to the `clamdscan` daemon.
30 | - Added a `file_list` option allowing one to specify a text file that lists (one per line) paths to files to be scanned. This is great if you need to scan hundreds or thousands of random files.
31 | - `clam_path` option has been moved to `clam.path`
32 | - `db` option has been moved to `clam.db`
33 | - `scan_archives` option has been moved to `clam.scan_archives`
34 | - `scan_files` now supports directories as well and will obey your `scan_recursively` option.
35 |
36 | ## 0.6.1 (2015-01-05)
37 |
38 | - Updated description in package.json file.
39 |
40 | ## 0.6.2 (2015-01-05)
41 |
42 | - Fixed major bug in the scan_files method that was causing it to only scan half the files passed to it.
43 |
44 | ## 0.6.3 (2015-01-05)
45 |
46 | - Removed the unnecessary "index_old.js" file put there for reference during the 0.5.0 -> 0.6.0 semi-rewrite.
47 |
48 | ## 0.6.4 (2015-01-26)
49 |
50 | - Fixed error messages
51 |
52 | ## 0.7.0 (2015-06-01)
53 |
54 | - Fixed a bug caused by not passing a `file_cb` paramter to the `scan_file` method. Thanks nicolaspeixoto!
55 | - Added tests
56 | - Fixed poor validation of method parameters
57 | - Changed API of `scan_dir` such that the paramaters passed to the `end_cb` are different in certain defined situations. See the "NOTE" section of the `scan_dir` documentation for details.
58 | - Changed `err` paramter in all callbacks from a simple string to a proper javascript `Error` object.
59 | - Added documentation for how to use a file_list file for scanning.
60 |
61 | ## 0.7.1 (2015-06-05)
62 |
63 | - Added node dependency of > 0.12 to `package.json` file
64 |
65 | ## 0.8.0 (2015-06-05)
66 |
67 | - Removed item causing node > 0.12 dependency.
68 | - Removed dependency of node > 0.12 in `package.json` file.
69 |
70 | ## 0.8.1 (2015-06-09)
71 |
72 | - Fixed check for database file. Issue #6
73 |
74 | ## 0.8.2 (2015-08-14)
75 |
76 | - Updated to `execFile` instead of `exec`
77 | - Improved test suite
78 |
79 | ## 0.9.0-beta (2015-07-01) - Never Released
80 |
81 | - Added support for TCP/UNIX Domain socket communication to local or remote clamav services.
82 | - Added a `get_version` method.
83 | - NULL is now returned to the third parameter of the `is_infected` when file is neither infected or clean (i.e. on unexpected response)
84 | - Created alias: `scan_file` for `is_infected`.
85 | - Created a `scan_stream` method.
86 | - Minor code clean-up
87 |
88 | ## 1.0.0 (2019-05-02)
89 |
90 | This is a huge major release in which this module was essentially completely re-written. This version introduces some breaking changes and major new features. Please read the release notes below carefully.
91 |
92 | - Now requires at least Node v10.0.0
93 | - Code re-written in ES2018 code
94 | - Now supports a hybrid Promise/Callback API (supports async/await)
95 | - Now properly supports TCP/UNIX Domain socket communication to local or remote clamav services (with optional fallback to local binary via child process).
96 | - Added new `scan_stream` method which allows you to pass an input stream.
97 | - Added new `get_version` method which allows you to check the version of ClamAV that you'll be communicating with.
98 | - Added new `passthrough` method which allows you to pipe a stream "through" the clamscan module and on to another destination (ex. S3).
99 | - Added new alias `scan_file` that points to `is_infected`.
100 | - In order to provide the name of any viruses found, a new standard `viruses` array is now be provided to the callback for:
101 |
102 | - `is_infected` & `scan_file` methods (callback format: `(err, file, is_infected, viruses) => { ... }`).
103 | - `scan_files` method (callback format: `(err, good_files, bad_files, error_files, viruses) => { ... }`).
104 | - `scan_dir` method (callback format: `(err, good_files, bad_files, viruses) => { ... }`).
105 |
106 | - In all cases, the `viruses` parameter will be an empty array on error or when no viruses are found.
107 |
108 | - `scan_files` now has another additional parameter in its callback:
109 |
110 | - `error_files`: An object keyed by the filenames that presented errors while scanning. The value of those keys will be the error message for that file.
111 |
112 | - Introduces new API to instantiate the module (NOTE: The old way will no longer work! See below for more info).
113 |
114 | ### API Changes with 1.0.0:
115 |
116 | For some full-fledged examples of how the new API works, checkout the `/examples` directory in the module root directory.
117 |
118 | #### Module Initialization
119 |
120 | ##### Pre-1.0.0
121 |
122 | ```javascript
123 | const clamscan = require('clamscan')(options);
124 | ```
125 |
126 | ##### 1.0.0
127 |
128 | **NOTE:** Due to the new asynchronous nature of the checks that are performed upon initialization of the module, the initialization method now returns a Promise instead of the actual instantiated object. Resolving the Promise with `then` will return the object like before.
129 |
130 | ```javascript
131 | const NodeClam = require('clamscan');
132 | const ClamScan = new NodeClam().init(options);
133 | ```
134 |
135 | #### Making Method Calls
136 |
137 | ##### Pre-1.0.0
138 |
139 | ```javascript
140 | clamscan.is_infected('/path/to/file.txt', (err, file, is_infected) => {
141 | // Do stuff
142 | });
143 | ```
144 |
145 | ##### 1.0.0
146 |
147 | ```javascript
148 | ClamScan.then(clamscan => {
149 | clamscan.is_infected('/path/to/file.txt', (err, file, is_infected, viruses) => {
150 | // Do stuff
151 | });
152 | });
153 | ```
154 |
155 | If you prefer the async/await style of coding:
156 |
157 | ```javascript
158 | ;(async () => {
159 | const clamscan = await new NodeClam().init(options);
160 | clamscan.is_infected('/path/to/file.txt', (err, file, is_infected, viruses) => {
161 | // Do stuff
162 | });
163 | })();
164 | ```
165 |
166 | #### New Way to Get Results
167 |
168 | ##### Pre-1.0.0
169 |
170 | The only way to get results/errors in pre-1.0.0 was through callbacks.
171 |
172 | ```javascript
173 | const clamscan = require('clamscan')(options);
174 | clamscan.scan_dir('/path/to/directory', (err, good_files, bad_files) => {
175 | // Do stuff inside callback
176 | });
177 | ```
178 |
179 | ##### 1.0.0
180 |
181 | In version 1.0.0 and beyond, you will now be able to use Promises as well (and, of course, async/await).
182 |
183 | ###### Promises
184 |
185 | ```javascript
186 | const ClamScan = new NodeClam().init(options);
187 | ClamScan.then(clamscan =>
188 | clamscan.scan_dir('/path/to/directory').then(result => {
189 | const {good_files, bad_files} = result;
190 | // Do stuff
191 | }).catch(err => {
192 | // Handle scan error
193 | });
194 | }).catch(err => {
195 | // Handle initialization error
196 | });
197 | ```
198 |
199 | ###### Async/Await
200 |
201 | ```javascript
202 | ;(async () => {
203 | try {
204 | const clamscan = await new NodeClam().init(options);
205 | const {good_files, bad_files} = await clamscan.scan_dir('/path/to/directory');
206 | // Do stuff
207 | } catch (err) {
208 | // Handle any error
209 | }
210 | })();
211 | ```
212 |
213 | #### New Methods
214 |
215 | ##### scan_stream
216 |
217 | The `scan_stream` method allows you supply a readable stream to have it scanned. Theoretically any stream can be scanned this way. Like all methods, it supports callback and Promise response styles (full documentation is in README).
218 |
219 | ###### Basic Promise (async/await) Example:
220 |
221 | ```javascript
222 | ;(async () => {
223 | try {
224 | const clamscan = await new NodeClam().init(options);
225 | const stream = new Readable();
226 | rs.push('foooooo');
227 | rs.push('barrrrr');
228 | rs.push(null);
229 |
230 | const {is_infected, viruses} = await clamscan.scan_stream(stream);
231 |
232 | // Do stuff
233 | } catch (err) {
234 | // Handle any error
235 | }
236 | })();
237 | ```
238 |
239 | ###### Basic Callback Example:
240 |
241 | ```javascript
242 | ;(async () => {
243 | try {
244 | const clamscan = await new NodeClam().init(options);
245 | const stream = new Readable();
246 | rs.push('foooooo');
247 | rs.push('barrrrr');
248 | rs.push(null);
249 |
250 | clamscan.scan_stream(stream, (err, results) => {
251 | if (err) {
252 | // Handle error
253 | } else {
254 | const {is_infected, viruses} = results;
255 | // Do stuff
256 | }
257 | });
258 |
259 | // Do stuff
260 | } catch (err) {
261 | // Handle any error
262 | }
263 | })();
264 | ```
265 |
266 | ##### passthrough
267 |
268 | The `passthrough` method allows you supply a readable stream that will be "passed-through" the clamscan module and onto another destination. In reality, the passthrough method works more like a fork stream whereby the input stream is simultaneously streamed to ClamAV and whatever is the next destination. Events are created when ClamAV is done and/or when viruses are detected so that you can decide what to do with the data on the next destination (delete if virus detected, for instance). Data is only passed through to the next generation if the data has been successfully received by ClamAV. If anything halts the data going to ClamAV (including issues caused by ClamAV), the entire pipeline is halted and events are fired.
269 |
270 | Normally, a file is uploaded and then scanned. This method should theoretically speed up user uploads intended to be scanned by up to 2x because the files are simultaneously scanned and written to disk. Your mileage my vary.
271 |
272 | This method is different than all the others in that it returns a PassthroughStream object and does not support a Promise or Callback API. This makes sense once you see the example below (full documentation is in README).
273 |
274 | ###### Basic Example:
275 |
276 | ```javascript
277 | ;(async () => {
278 | try {
279 | const clamscan = await new NodeClam().init(options);
280 | const request = require('request');
281 | const input = request.get(some_url);
282 | const output = fs.createWriteStream(some_local_file);
283 | const av = clamscan.passthrough();
284 |
285 | // Send output of RequestJS stream to ClamAV.
286 | // Send output of RequestJS to `some_local_file` if ClamAV receives data successfully
287 | input.pipe(av).pipe(output);
288 |
289 | // What happens when scan is completed
290 | av.on('scan-complete', result => {
291 | const {is_infected, viruses} = result;
292 | // Do stuff if you want
293 | });
294 |
295 | // What happens when data has been fully written to `output`
296 | output.on('finish', () => {
297 | // Do stuff if you want
298 | });
299 | } catch (err) {
300 | // Handle any error
301 | }
302 | })();
303 | ```
304 |
305 | ## 1.2.0
306 |
307 | ### SECURITY PATCH
308 |
309 | An important security patch was released in this version which fixes a bug causing false negatives in specific edge cases. Please upgrade immediately and only use this version from this point on.
310 |
311 | All older versions of this package have been deprecated on NPM.
312 |
313 | ## 1.3.0
314 |
315 | This just has some bug fixes and updates to dependencies. Technically, a new `'timeout'` event was added to the `passthrough` stream method, but, its not fully fleshed out and doesn't seem to work so it will remain undocumented for now.
316 |
317 | ## 1.4.0
318 |
319 | - Updated Mocha to v8.1.1. Subsequently, the oldest version of NodeJS allowed for this module is now v10.12.0.
320 | - Fixed issue with the method not throwing errors when testing existence and viability of remote/local socket.
321 |
322 | ## 1.4.1
323 |
324 | All sockets clients should now close when they are done being used, fail, or timeout.
325 |
326 | ## 1.4.2
327 |
328 | - Fixed initialization to pass a config-file option during clamav version check
329 | - Added new contributor
330 | - Fixed tests
331 |
332 | ## Newer Versions
333 |
334 | Please see the [GitHub Release page](https://github.com/kylefarris/clamscan/releases) for this project to see changelog info starting with v2.0.0.
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2013 Kyle Farris
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
6 | this software and associated documentation files (the "Software"), to deal in
7 | the Software without restriction, including without limitation the rights to
8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | .PHONY: all
2 | TESTS = tests/index.js
3 |
4 | all:
5 | @npm install
6 |
7 | test: all
8 | @mkdir -p tests/infected
9 | @mkdir -p tests/bad_scan_dir
10 | @mkdir -p tests/mixed_scan_dir/folder1
11 | @mkdir -p tests/mixed_scan_dir/folder2
12 | @touch tests/clamscan-log
13 | @./node_modules/.bin/mocha --exit --trace-warnings --trace-deprecation --retries 1 --full-trace --timeout 5000 --check-leaks --reporter spec $(TESTS)
14 |
15 | clean:
16 | rm -rf node_modules
17 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # NodeJS Clamscan Virus Scanning Utility
2 |
3 | [![NPM Version][npm-version-image]][npm-url] [![NPM Downloads][npm-downloads-image]][npm-url] [![Node.js Version][node-image]][node-url] [](https://github.com/kylefarris/clamscan/actions/workflows/test.yml)
4 |
5 | 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.
6 |
7 | # !!IMPORTANT
8 |
9 | If you are using a version prior to 1.2.0, please upgrade! There was a security vulnerability in previous versions that can cause false negative in some edge cases. Specific details on how the attack could be implemented will not be disclosed here. Please update to 1.2.0 or greater ASAP. No breaking changes are included, only the security patch.
10 |
11 | All older versions in NPM have been deprecated.
12 |
13 | # Version 1.0.0 Information
14 |
15 | If you are migrating from v0.8.5 or less to v1.0.0 or greater, please read the [release notes](https://github.com/kylefarris/clamscan/releases/tag/v1.0.0) as there are some breaking changes (but also some awesome new features!).
16 |
17 | # Table of Contents
18 |
19 | - [Dependencies](#dependencies)
20 | - [Local Binary Method](#to-use-local-binary-method-of-scanning)
21 | - [TCP/Domain Socket Method](#to-use-clamav-using-tcp-sockets)
22 | - [How to Install](#how-to-install)
23 | - [License Info](#license-info)
24 | - [Getting Started](#getting-started)
25 | - [A note about using this module via sockets or TCP](#a-note-about-using-this-module-via-sockets-or-tcp)
26 | - [Basic Usage Example](#basic-usage-example)
27 | - [API](#api)
28 | - [getVersion](#getVersion)
29 | - [isInfected (alias: scanFile)](#isInfected)
30 | - [scanDir](#scanDir)
31 | - [scanFiles](#scanFiles)
32 | - [scanStream](#scanStream)
33 | - [passthrough](#passthrough)
34 | - [ping](#ping)
35 | - [Contribute](#contribute)
36 | - [Resources used to help develop this module](#resources-used-to-help-develop-this-module)
37 |
38 | # Dependencies
39 |
40 | ## To use local binary method of scanning
41 |
42 | You will need to install ClamAV's clamscan binary and/or have clamdscan daemon running on your server. On linux, it's quite simple.
43 |
44 | Fedora-based distros:
45 |
46 | ```bash
47 | sudo yum install clamav
48 | ```
49 |
50 | Debian-based distros:
51 |
52 | ```bash
53 | sudo apt-get install clamav clamav-daemon
54 | ```
55 |
56 | For OS X, you can install clamav with brew:
57 |
58 | ```bash
59 | sudo brew install clamav
60 | ```
61 |
62 | ## To use ClamAV using TCP sockets
63 |
64 | You will need access to either:
65 |
66 | 1. A local UNIX Domain socket for a local instance of `clamd`
67 |
68 | - Follow instructions in [To use local binary method of scanning](#user-content-to-use-local-binary-method-of-scanning).
69 | - Socket file is usually: `/var/run/clamd.scan/clamd.sock`
70 | - Make sure `clamd` is running on your local server
71 |
72 | 2. A local/remote `clamd` daemon
73 |
74 | - Must know the port the daemon is running on
75 | - If running on remote server, you must have the IP address/domain name
76 | - If running on remote server, it's firewall must have the appropriate TCP port(s) open
77 | - Make sure `clamd` is running on your local/remote server
78 |
79 | **NOTE:** 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).
80 |
81 | # How to Install
82 |
83 | ```bash
84 | npm install clamscan
85 | ```
86 |
87 | # License Info
88 |
89 | Licensed under the MIT License:
90 |
91 | -