From 1049265672a2b6ecabbd637196aa940818a4070b Mon Sep 17 00:00:00 2001 From: Jas- Date: Sun, 6 Sep 2015 02:45:34 +0000 Subject: [PATCH] Updated README, CHANGELOG & version minor bump --- CHANGELOG | 51 +++++ README.md | 475 ++------------------------------------------ examples/scan.js | 6 +- lib/node-libnmap.js | 2 +- package.json | 2 +- 5 files changed, 78 insertions(+), 458 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 74c4474..dfe3ed9 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,54 @@ +commit 7a4f54ad372081cc7de68d82ba9bf9aadc601120 +Author: Jas- +Date: Sun Sep 6 02:03:07 2015 +0000 + + defaults.blocksize default value: + Lowered the default option of defaults.blocksize to 16 to create larger ranges when scanning large network blocks + +commit 41e538fbbfd1434011a388c9455d2a12ed44f311 +Author: Jas- +Date: Sun Sep 6 01:15:45 2015 +0000 + + Updated the scan example, and other minor changes + +commit fe9b9644650fcd8308e95aa7e34562c5638a0c6e +Author: jas- +Date: Sat Sep 5 08:44:24 2015 -0600 + + Error handling for empty reporting + +commit 2805c9c403e545ab9d3b5a457debd8ee5f8f3a60 +Author: jas- +Date: Sat Sep 5 08:38:04 2015 -0600 + + Removed iojs version specific & added debugging for travis-ci tests + +commit 46b9f8a26b39d6dca9c70224b514651d009c0362 +Author: jas- +Date: Sat Sep 5 08:35:58 2015 -0600 + + Removed iojs version specific & added debugging for travis-ci tests + +commit 71fe92bd56d8a079600a41703e3b7d6045a79cd2 +Author: jas- +Date: Sat Sep 5 08:30:09 2015 -0600 + + Updated .travis.yml to install nmap + +commit 1849b46093371da5406a3ace5ef205d9f635f5fc +Author: jas- +Date: Sat Sep 5 08:26:41 2015 -0600 + + Updated .travis.yml to install nmap + +commit 92cad8f6d34fdc6d7cf0e8af4f26e128a39900d1 +Author: jas- +Date: Sat Sep 5 08:23:50 2015 -0600 + + Validation object: + init(): Resolved async issues regarding returning errors + tests: Worked through failing test cases for v0.2.1 + commit b56e54fc25cfe4328f7f6b82a233ccb666bd7f5a Author: Jas- Date: Sat Sep 5 13:35:13 2015 +0000 diff --git a/README.md b/README.md index c34421a..be5cdb3 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,23 @@ # node-libnmap [![Build Status](https://travis-ci.org/jas-/node-libnmap.png?branch=master)](https://travis-ci.org/jas-/node-libnmap) Access nmap using node.js -v0.2.0 is a breaking change version iteration. Please update implementations to -accomodate API changes. ## install ## -To install `npm install node-libnmap` +To install `npm install -g node-libnmap` ## methods ## -* `discover` - Performs auto-discovery of online hosts -* `scan` - Performs scan given available range & optional port +* `scan` Performs scan given available range & optional port ## options ## -* `nmap` - Path to nmap binary -* `range` - Subnet range(s) -* `ports` - Port range(s) -* `callback` - A user defined callback function to retrieve report -* `threshold` - Limits for concurrent processing +* `nmap` {String} Path to NMAP binary +* `verbose` {Boolean} Turn on verbosity during scan(s) +* `ports` {String} Range of ports to scan +* `range` {Array} An array of hostnames/ipv4/ipv6, CIDR or ranges +* `timeout` {Number} Number of minutes to wait for host/port response +* `blocksize` {Number} Number of hosts per network scanning block +* `threshold` {Number} Max number of spawned process +* `flags` {Array} Array of flags for .spawn() +* `json` {Boolean} JSON object as output, false produces XML ## tests ## To test `npm test` @@ -24,49 +25,6 @@ To test `npm test` ## examples ## Here are a few usage examples & their output -### discover ### -The discover method is the quickest method but is limited to finding local -peers within the same CIDR per interface. - -If the device is using 802.1Q all attached subnets are probed. See example -output. - -```javascript -var nmap = require('node-libnmap'); - -nmap.discover(function(err, report){ - if (err) throw err; - console.log(report); -}) -``` - -### output ### - -```javascript -{ adapter: 'eth0', - properties: - { address: '10.0.2.15', - netmask: '255.255.255.0', - family: 'IPv4', - mac: '52:54:00:12:34:56', - internal: false, - cidr: '10.0.2.0/24', - hosts: 256, - range: { start: '10.0.2.1', end: '10.0.2.254' } }, - neighbors: [ '10.0.2.2', '10.0.2.3', '10.0.2.15' ] }, -{ adapter: 'eth1', - properties: - { address: '172.0.2.135', - netmask: '255.255.255.0', - family: 'IPv4', - mac: '23:56:10:e2:3f:a1', - internal: false, - cidr: '172.0.2.128/25', - hosts: 128, - range: { start: '172.0.2.129', end: '172.0.2.254' } }, - neighbors: [ '172.0.2.145', '172.0.2.146', '172.0.2.147', '172.0.2.201' ] } -``` - ### scan ### A manually specified scan example using a single host (both IPv4 & IPv6 notation), a CIDR range a host range as well as a port range specification. @@ -74,409 +32,16 @@ a CIDR range a host range as well as a port range specification. ```javascript var nmap = require('node-libnmap') , opts = { - // RFC-1123 hostname, IPv4 range notation, IPv4 CIDR notation & IPv6 - range: ['scanme.nmap.org', '10.0.2.128-255', '10.0.2.0/25', '::ffff:192.168.2.15'], - ports: '21,22,80,443,3306,60000-65535' + timeout: 100, + range: ['scanme.nmap.org', '10.0.2.0/25', '192.168.10.80-120'], + ports: '21,22,80,443' }; -nmap.scan(opts, function(err, report){ - if (err) throw err; - report.forEach(function(item){ - console.log(item[0]); - }); -}); -``` -### output ### - -```javascript -{ ip: '10.0.2.15', - ports: - [ { port: '22', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ssh', - rpc: '', - version: '' } ] } -{ ip: '192.168.2.15', - ports: - [ { port: '22', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ssh', - rpc: '', - version: '' } ] } -{ ip: '192.168.2.2', - ports: - [ { port: '513', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'login', - rpc: '', - version: '' }, - { port: '514', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'shell', - rpc: '', - version: '' }, - { port: '631', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ipp', - rpc: '', - version: '' } ] } -``` - -## error handling ## -The following errors are thrown when invalid configuration options are passed -to the module and/or when the necessary node.js version is below version v0.11.* - -### version requirement ### -The discover method requires a node.js version > `v0.11` due to the -`os.networkInterfaces().netmask` property being used to traverse each -physical/virtual adapter and examing the address space for online hosts. - -```javascript -Requires node.js v0.11.* and above -``` - -### nmap binary ### -If your system does not have the nmap binary installed the following error is -thrown - -```javascript -nmap binary not found, install nmap -``` - -### scanning ranges ### -When specifying an invalid range to the `scan` method the following error is -thrown. Valid range types are a single hostname/ipv4 (ipv6 is not yet -implemented), a CIDR range notation or a range. - -```javascript -Range must be an array of host(s), examples: ['192.168.2.10', '10.0.2.0/24', '10.0.10.5-20'] -``` - -### port range ### -A range of ports may also be specified with the `scan` method, for an invalid -port specification the following error is thrown. - -```javascript -Port(s) must match one of the following examples: 512 (single) | 0-65535 (range) | 22-25,80,443,3306 (multiple) -``` - -### threshold ### -The current value of the `threshold` limits the number of spawned processes to -protect the performance of the system in use. The default value is to only -spawn double the amount of CPU cores on the system. - -If you recieve the `spawn EAGAIN` or `spawn EMFILE` error(s) you have reached -the max number of `max user processes`. This error is generally thrown if your -attempting to scan a very large network block. - -To alleviate this you may need to increase the max number of processes and/or -which can file handles can be done like so (though not recommended): - -```sh -$ ulimit -u 65000 -$ ulimit -n 65000 -``` - -*Important* These limits are in place to help protect the operating system -against attacks such as a [fork bombing](http://en.wikipedia.org/wiki/Fork_bomb) -& [chroot jail breaking](http://www.bpfh.net/simes/computing/chroot-break.html). +nmap.scan(opts, function(err, report) { + if (err) throw new Error(err); -## performance ## -A note on performance of nmap scans; the nmap tool already makes efforts to -utilize parallel processing when multiple processor cores are available. - -Even with that in mind this library performs the following calculation prior -to running scans on an IP range. `ip-range / cpu`. It tries to split the -IP range into chunks then creates separate threads performing each scan -sequentially. - -For example instead of executing nmap like this `nmap -sn -oG - 10.0.2.0/24` -it instead breaks the subnet range into chunks based on the amount of cpu -cores like this (i.e. 8 cores, where each command is run in its own thread) - -``` -nmap -sn -oG - 10.0.2.1-31 -nmap -sn -oG - 10.0.2.33-63 -nmap -sn -oG - 10.0.2.65-95 -nmap -sn -oG - 10.0.2.97-127 -nmap -sn -oG - 10.0.2.129-159 -nmap -sn -oG - 10.0.2.161-191 -nmap -sn -oG - 10.0.2.193-223 -nmap -sn -oG - 10.0.2.225-255 -``` - -The technical details of [Fyodor's](http://insecure.org/fyodor/) optimizations -can be found @ [insecure.org](http://nmap.org/book/man-performance.html). - -## benchmarks ## -The results here are all coming from a virtual environment with limited system -resources but should give an overall picture of performance of the scans. My VM -environment is using 8 cores with 4 threads per core given a total returned from -`require('os').cpus.length` = 32. - -### Nmap host discovery ### -```sh -$ time nmap -sn -oG - 10.0.2.0/24 -# Nmap 5.51 scan initiated Wed Jan 8 18:54:07 2014 as: nmap -sn -oG - 10.0.2.0/24 -Host: 10.0.2.2 () Status: Up -Host: 10.0.2.3 () Status: Up -Host: 10.0.2.15 () Status: Up -# Nmap done at Wed Jan 8 18:54:26 2014 -- 256 IP addresses (3 hosts up) scanned in 19.33 seconds - -real 0m19.339s -user 0m0.052s -sys 0m0.080s -``` - -### Nmap host `discover` method using node-libnmap ### -```javascript -$ time node test/run.js -{ adapter: 'eth0', - properties: - { address: '10.0.2.15', - netmask: '255.255.255.0', - family: 'IPv4', - mac: '52:54:00:12:34:56', - internal: false, - cidr: '10.0.2.0/24', - hosts: 256, - range: { start: '10.0.2.1', end: '10.0.2.254' } }, - neighbors: [ '10.0.2.2', '10.0.2.3', '10.0.2.15' ] } - -real 0m3.323s -user 0m0.326s -sys 0m0.412s -``` - -And an example with multiple adapters on multiple 802.11Q segments -```javascript -$ time node test/run.js -[ { adapter: 'eth0', - properties: - { address: '10.0.2.15', - netmask: '255.255.255.0', - family: 'IPv4', - mac: '52:54:00:12:34:56', - internal: false, - cidr: '10.0.2.0/24', - hosts: 256, - range: {start: '10.0.2.0', end: '10.0.2.255'} }, - neighbors: [ '10.0.2.2', '10.0.2.3', '10.0.2.15' ] }, - { adapter: 'eth1', - properties: - { address: '192.168.2.15', - netmask: '255.255.255.128', - family: 'IPv4', - mac: '52:54:00:12:34:57', - internal: false, - cidr: '192.168.2.0/25', - hosts: 128, - range: {start: '192.168.2.1', end: '192.168.2.128'} }, - neighbors: [ '192.168.2.2', '192.168.2.3', '192.168.2.15' ] } ] - -real 0m3.447s -user 0m0.493s -sys 0m0.796s -``` - -### Nmap full port scan ### -```sh -$ time nmap -T4 -oG - localhost 10.0.2.0/24 192.168.2.0/25 -# Nmap 5.51 scan initiated Sun Jan 26 08:03:18 2014 as: nmap -T4 -oG - localhost 10.0.2.0/24 192.168.2.0/25 -Host: 127.0.0.1 (localhost) Status: Up -Host: 127.0.0.1 (localhost) Ports: 22/open/tcp//ssh/// Ignored State: closed (999) -Host: 10.0.2.2 () Status: Up -Host: 10.0.2.2 () Ports: 513/open/tcp//login///, 514/open/tcp//shell///, 631/open/tcp//ipp///, 1192/filtered/tcp//caids-sensor///, 1524/filtered/tcp//ingreslock///, 1533/filtered/tcp//virtual-places///, 1862/filtered/tcp//mysql-cm-agent///, 1864/filtered/tcp//paradym-31///, 2179/filtered/tcp//vmrdp///, 2222/open/tcp//EtherNet|IP-1///, 2381/filtered/tcp//compaq-https///, 3000/open/tcp//ppp///, 3003/filtered/tcp//cgms///, 3369/filtered/tcp//satvid-datalnk///, 4343/open/tcp//unicall///, 5901/open/tcp//vnc-1///, 7019/filtered/tcp//unknown///, 8000/open/tcp//http-alt///, 8080/open/tcp//http-proxy///, 8300/filtered/tcp//tmi///, 9009/filtered/tcp//pichat///, 9594/filtered/tcp//msgsys///, 10009/filtered/tcp//swdtp-sv///, 16000/filtered/tcp//fmsas/// Ignored State: closed (976) -Host: 10.0.2.15 () Status: Up -Host: 10.0.2.15 () Ports: 22/open/tcp//ssh/// Ignored State: closed (999) -Host: 192.168.2.2 () Status: Up -Host: 192.168.2.2 () Ports: 513/open/tcp//login///, 514/open/tcp//shell///, 631/open/tcp//ipp///, 1174/filtered/tcp//fnet-remote-ui///, 2222/open/tcp//EtherNet|IP-1///, 3000/open/tcp//ppp///, 4343/open/tcp//unicall///, 5901/open/tcp//vnc-1///, 7402/filtered/tcp//rtps-dd-mt///, 8000/open/tcp//http-alt///, 8002/filtered/tcp//teradataordbms///, 8080/open/tcp//http-proxy///, 9100/filtered/tcp//jetdirect///, 9666/filtered/tcp//unknown///, 9968/filtered/tcp//unknown///, 11110/filtered/tcp//unknown///, 54045/filtered/tcp//unknown/// Ignored State: closed (983) -Host: 192.168.2.3 () Status: Up -Host: 192.168.2.3 () Ports: 80/open/tcp//http///, 513/open/tcp//login///, 514/open/tcp//shell///, 1051/filtered/tcp//optima-vnet/// Ignored State: closed (996) -Host: 192.168.2.15 () Status: Up -Host: 192.168.2.15 () Ports: 22/open/tcp//ssh/// Ignored State: closed (999) -# Nmap done at Sun Jan 26 08:06:52 2014 -- 385 IP addresses (6 hosts up) scanned in 214.20 seconds - -real 3m34.218s -user 0m0.911s -sys 0m3.315s -``` - -### Nmap host `scan` method using node-libnmap ### -The test case used: -```javascript -var libnmap = require('node-libnmap') - -var opts = { - range: ['localhost', '10.0.2.0/24', '192.168.2.0/25'] -} - -libnmap.nmap('scan', opts, function(err, report){ - if (err) throw err - report.forEach(function(item){ - console.log(item[0]) - }) -}) -``` - -The results -```javascript -{ ip: '127.0.0.1', - hostname: 'localhost', - ports: - [ { port: '22', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ssh', - rpc: '', - version: '' } ] } -{ ip: '10.0.2.15', - ports: - [ { port: '22', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ssh', - rpc: '', - version: '' } ] } -{ ip: '192.168.2.15', - ports: - [ { port: '22', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ssh', - rpc: '', - version: '' } ] } -{ ip: '192.168.2.2', - ports: - [ { port: '255', - state: 'filtered', - protocol: 'tcp', - owner: '', - service: 'unknown', - rpc: '', - version: '' }, - { port: '513', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'login', - rpc: '', - version: '' }, - { port: '514', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'shell', - rpc: '', - version: '' }, - { port: '631', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ipp', - rpc: '', - version: '' }, - { port: '1186', - state: 'filtered', - protocol: 'tcp', - owner: '', - service: 'mysql-cluster', - rpc: '', - version: '' }, - { port: '2222', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'EtherNet|IP-1', - rpc: '', - version: '' }, - { port: '3000', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'ppp', - rpc: '', - version: '' }, - { port: '4343', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'unicall', - rpc: '', - version: '' }, - { port: '5901', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'vnc-1', - rpc: '', - version: '' }, - { port: '8000', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'http-alt', - rpc: '', - version: '' }, - { port: '8080', - state: 'open', - protocol: 'tcp', - owner: '', - service: 'http-proxy', - rpc: '', - version: '' }, - { port: '9111', - state: 'filtered', - protocol: 'tcp', - owner: '', - service: 'DragonIDSConsole', - rpc: '', - version: '' }, - { port: '19801', - state: 'filtered', - protocol: 'tcp', - owner: '', - service: 'unknown', - rpc: '', - version: '' } ] } - -real 2m32.158s -user 0m13.066s -sys 0m8.890s -``` - -### Class B network scans ### -To really test the performance of the module I did several scans of a class B -network containing a maximum host count of `32766`. Below are the times for -both scans. - -```sh -$ time nmap -T4 -n -oG - 155.97.0.0/17 - -real 10m32.856s -user 0m11.709s -sys 0m33.364s -``` - -```sh -$ time node nmap-test.js - -real 0m32.034s -user 1m3.209s -sys 0m33.950s + for (var item in report) { + console.log(JSON.stringify(report[item])); + } +}); ``` - -Mileage may vary diff --git a/examples/scan.js b/examples/scan.js index 4e14a3e..2bee321 100644 --- a/examples/scan.js +++ b/examples/scan.js @@ -9,7 +9,8 @@ var nmap = require('../') , path = './scans/' , opts = { timeout: 100, - range: ['scanme.nmap.org', 'localhost', '172.17.190.0/17'], + //range: ['scanme.nmap.org', 'localhost', '172.17.190.0/17'], + range: ['scanme.nmap.org', 'localhost', '172.17.190.0/27'], ports: '21,22,80,443' }; @@ -17,6 +18,8 @@ nmap.scan(opts, function(err, report) { if (err) throw new Error(err); for (var item in report) { + console.log(JSON.stringify(report[item])); +/* for (var host in report[item].host) { var data = JSON.stringify(report[item].host[host]) @@ -27,5 +30,6 @@ nmap.scan(opts, function(err, report) { console.log('Wrote report for '+filename); }); } +*/ } }); diff --git a/lib/node-libnmap.js b/lib/node-libnmap.js index 59c92ac..e357707 100644 --- a/lib/node-libnmap.js +++ b/lib/node-libnmap.js @@ -4,7 +4,7 @@ * License: MIT */ -var version = 'v0.2.1' +var version = 'v0.2.2' , fs = require('fs') , os = require('os') , async = require('async') diff --git a/package.json b/package.json index d23c278..1352a73 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "node-libnmap", - "version": "0.2.1", + "version": "0.2.2", "description": "libnmap for node.js", "author": "Jason Gerfen ", "keywords": [