So you want to discover machines, servers, devices on your network running on a specific port? or even on a range of ports or specific IP's? No problem at all. One of the best tools for the job is NMAP.

If you have never heard of NMAP, you are probably living in a parallel universe. NMAP is one of the standard network scanning utilities that every IT professional should know how to use.

First make sure you have installed NMAP on your box. You can find binaries and source code here:

http://nmap.org/download.html

If you are on a mac you can use brew to install NMAP in a breeze:

brew install nmap

You can verify the installation by running:

nmap -version

It should output the version installed and other information about nmap.

Node.js NMAP API

The best library in Node.js to work with NMAP is called node-libnmap. It is a simple module that interfaces with the NPM command line utility by running the NMAP process with the child_process exec method.

You can download this library using NPM:

npm install --save node-libnmap

The API is very simple and straight-forward, and the two methods that you will use to scan the network are scan and discover.

Discover API

The discover method is used to performs quick auto-discovery of neighbouring hosts in the same subnet. It is not as detailed as the scan operation, but much simpler to use. Here is an example of running the discover method with default settings:

The discover method runs a ping scan of the network (the equivalent of running NMAP in the command line with the -sn option), which basically disables detailed port-scan. The output you get is a list of network neighbours in the host subnet with minimal informationt:

{ 
  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' ] 
}

This is a very fast method, and good for getting a rough map of the subnet.

Scan API

The scan method of the libnmap API is used to perform a more detailed network scan (with port scanning) given an available IP range, ports range etc. It will output very detailed and useful informaton, but it's also significantly slower. Here is an example of scanning specific subnets, ip ranges, and port ranges:

The output is much more detailed than the discover method, and it contains port scanning information:

{ 
  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: '' }] 
}

Advanced usage

In advanced scenarios you might want to have more control over NMAP execution, so your best option is to use the flags option to customize the flags used to execute NMAP. I would recommend using it with the scan method of the API.

The following example demonstrates passing the ports to scan through the flags parameter, as well as explicitly setting the nmap executable path:

For a full reference of the flags you can pass through the option property check out the link below:

http://nmap.org/book/man-briefoptions.html

Conclusion

NMAP is a useful tool, and the libnmap library is a simple wrapper around the NMAP command line utility. It should be very useful for many use-cases of network discovery.