Node-NMAP
NPM package enabling your NodeJs application to interface with the features of NMAP. This package requires that NMAP is installed and available to the running node application.
UPDATE 4.0.0
- Changed the code base from TypeScript to pure ES6
- Removed TypeScript and TS types
- Added additional port service information to output if available (-sV)
- BREAKING - Changed export method to flat object, upgrade instructions below.
Upgrade instructions:
//Previous usage 3.0.4 and belowconst nmap = ;nmapnodenmapnmapLocation = "nmap"; //defaultlet quickscan = '127.0.0.1 google.com'; /*4.0.0+ usage simply removes a layer of object nesting.* simply remove 'nodenmap'*/const nmap = ;nmapnmapLocation = 'nmap'; //defaultlet quickscan = '127.0.0.1 google.com';
UPDATE 3.0.4
- Added extra error handling to detect if NMAP cannot be found a default or passed location.
UPDATE 3.0.3:
- Added NMAP determined Vendor when a MAC address is provided. Credit: tbwiss
UPDATE v3: A lot of changes have come in this update:
- Breaking change: All scan classes are now capitalized.
- Added
scan.scanTimeout
to limit long running scans - Added
scan.scanTime
representing the duration of the scan - Added
scan.cancelScan()
to kill a running scan - Removed
autoDiscover
scan type until method of determining useful interfaces found - Bugfix: Now remove listeners for SIGINT when a scan is complete.
- Added a Queued version of each scan allowing for a highler level of feedback and control over the scanning process.
- Building against the latest version of NMAP (v7)
UPDATE v2: I have rewritten the module in TypeScript. the .d.ts file is located at /node_modules/node-nmap/index.d.ts.
As a part of this update, there is an additional maping for the namespace/module, as well as a requirement to use new
for each scan.
Request: While NmapScan()
will accept valid NMAP arguments, the XML to JSON conversion is only checking for specific things. If there is a common or useful NMAP feature that you would like to see included, please submit an issue and I will work it in.
Installation
npm install node-nmap
Scan Types
NmapScan
- This is the core of the package and runs the NMAP command.QuickScan
- Scans supplied hosts without portscan(-sP). Use for a quick discovery.OsAndPortScan
- Scans for open ports as well as NMAP gathered OS information.QueuedNmapScan
- Queued version for greater controlQueuedQuickScan
- Queued version for greater controlQueuedOsAndPortScan
- Queued version for greater control
Scan instance variables, methods, and events
scanResults
: Array of host objects - contains the results of the scan.scanTime
: number in ms - duration of scan.scanTimeout
: number in ms - scan will cancel if timeout is reached.startScan()
- begins the NMAP scan.cancelScan()
- kills the NMAP process.'complete'
: event - returns array of host objects'error'
: event - returns string with error information
Queued scans instance variables, methods, and events
scanTime
: number in ms - collective duration of all scans.currentScan
- reference to the current scan object if neededrunActiononError
: boolean(default:false) - run the supplied action function when an error is encountered.saveErrorsToResults
: boolean(default:false) - save error data to the results arraysingleScanTimeout
: number in ms - timeout value to be supplied to eachs single scan.saveNotFoundToResults
: boolean(default:false) - save host not found error object to results arraystartRunScan()
- begins processing the entire queue without removing scanned hosts.startShiftScan()
- begins processing entire queue while removing scanned hosts.pause()
- pauses the queue processing (take affect between scans.).resume()
- resumes processing the queue.next(count)
- processes the nextcount
queued items. Default 1.shift(count)
- processes the nextcount
queued items while removing them from the queue. Default 1.results()
- returns Array of current scan result Host objects.shiftResults()
- returns the first item of the results objects and removes it from the results list.index()
- returns the current index of the queue processingpercentComplete()
- returns the percentage completion through the processing queue.'complete'
: event - triggers when entire queue has been processed. Returns results Array.'error'
: event - triggers when an error is encountered. Returns error object.
Usage
NmapScan is the core function of the package. It emits two events: 'complete'
and 'error'
. Both of these events return data. All methods are easy to set up. Simply define a variable as one of the methods, and that variable will become a new instance of NmapScan with appropriately set commands. All input accepts either a space separated string, or an array of strings to make it easier to work with a complex set of hosts. All methods return an array of JSON objects containing information on each host. Any key without information provided from NMAP is filled as null
.
The return structure is:
"hostname":"theHostname" "ip":"127.0.0.1" "mac":null "openPorts": "port":80 "service":"http" ... "osNmap":null //note that osNmap is not guaranteed to be correct. ...
Examples
var nmap = ; nmapnmapLocation = "nmap"; //default // Accepts array or comma separated string of NMAP acceptable hostsvar quickscan = '127.0.0.1 google.com'; quickscan; quickscan; quickscan;// returns// [ // { // "hostname":"localhost",// "ip":"127.0.0.1",// "mac":null,// "openPorts":[ // ],// "osNmap":null// },// { // "hostname":"google.com",// "ip":"74.125.21.113",// "mac":null,// "openPorts":[ // ],// "osNmap":null// }// ] // Accepts array or comma separarted string for custom nmap commands in the second argument.var nmapscan = '127.0.0.1 google.com' '-sn'; nmapscan;nmapscan; nmapscan; // returns// [ // { // "hostname":"localhost",// "ip":"127.0.0.1",// "mac":null,// "openPorts":[ // ],// "osNmap":null// },// { // "hostname":"google.com",// "ip":"74.125.21.113",// "mac":null,// "openPorts":[ // ],// "osNmap":null// }// ]var osandports = 'google.com'; osandports;osandports; osandports; // returns// [// { // "hostname":"google.com",// "ip":"74.125.21.113",// "mac":null,// "openPorts":[ // { // "port":80,// "service":"http"// },// { // "port":443,// "service":"https"// }// ],// "osNmap":"OpenBSD 4.3"// }// ]
Queued Scans
Queued scanning was implemented to give higher level of control over the scanning process. While there are advantages, using the Queued scanning method does produce time overhead as a new instance of NMAP is created for each host. It may be useful to use Queued scans in the event that you are running a lengthy set of long running scans on each host. It would be recommended to perform a quickscan, before supplying the found hosts to a queued scanning process for longer running scans.
Example
//the actionFunction gets run each time a scan on a host is complete{ console; console;}var scan = "google.com 192.168.0.1-10" actionFunction; scan; scan; scan; //processes entire queue
Please open an issue if you have any questions, concerns, bugs, or critiques.