Installation

npm install lib-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 control
• QueuedQuickScan - Queued version for greater control
• QueuedOsAndPortScan - 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 needed
• runActiononError : boolean(default:false) - run the supplied action function when an error is encountered.
• saveErrorsToResults : boolean(default:false) - save error data to the results array
• singleScanTimeout : number in ms - timeout value to be supplied to each single scan.
• saveNotFoundToResults : boolean(default:false) - save host not found error object to results array
• startRunScan() - 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 next count queued items. Default 1.
• shift(count) - processes the next count 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 processing
• percentComplete() - 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 = require('lib-nmap');

nmap.nmapLocation = "nmap"; //default

//    Accepts array or comma separated string of NMAP acceptable hosts
var quickscan = new nmap.QuickScan('127.0.0.1 google.com');

quickscan.on('complete', function(data){
  console.log(data);
});

quickscan.on('error', function(error){
  console.log(error);
});

quickscan.startScan();
// 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 separated string for custom nmap commands in the second argument.
var nmapscan = new nmap.NmapScan('127.0.0.1 google.com', '-sn');

nmapscan.on('complete',function(data){
  console.log(data);
});
nmapscan.on('error', function(error){
  console.log(error);
});

nmapscan.startScan();

// 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 = new nmap.OsAndPortScan('google.com');

osandports.on('complete',function(data){
  console.log(data);
});
osandports.on('error', function(error){
  console.log(error);
});

osandports.startScan();

// 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
function actionFunction(data){
    console.log(data);
	console.log("Percentage complete" + scan.percentComplete());
}
var scan = new nmap.QueuedOsAndPortScan("google.com 192.168.0.1-10", actionFunction);

scan.on('complete', function(data){
	console.log(data);
    console.log("total scan time" + scan.scanTime);
});

scan.on('error', function(error){
  console.log(error);
});

scan.startRunScan(); //processes entire queue

Please open an issue if you have any questions, concerns, bugs, or critiques.