Repository files navigation

Fast browser-based network discovery module

This project is no longer maintained.

netmap.js provides browser-based host discovery and port scanning capabilities to allow you to map website visitors' networks.

It's quite fast, making use ofes6-promise-pool to efficiently run the maximum number of concurrent connections browsers will allow.

I needed a browser-based port scanner for an idea I was working on. I thought it would be a simple matter of importing an existing module or copy-pasting from another project likeBeEF.

Turns out there wasn't a decent ready-to-usenpm module and theport_scanner module in BeEF is (at the time of writing) inaccurate, slow and doesn't work on Chromium.

netmap.js is therefor a somewhat optimized "ping" sweeper and TCP scanner that works on all modern browsers.

npm install --save netmap.js

Let's figure out the IP address of a website visitor's gateway, starting from a list of likely candidates in a home environment:

importNetMapfrom'netmap.js'constnetmap=newNetMap()consthosts=['192.168.0.1','192.168.0.254','192.168.1.1','192.168.1.254']netmap.pingSweep(hosts).then(results=>{console.log(results)})

{"hosts": [    {"host":"192.168.0.1","delta":1003,"live":false },    {"host":"192.168.0.254","delta":1001,"live":false },    {"host":"192.168.1.1","delta":18,"live":true },    {"host":"192.168.1.254","delta":1002,"live":false }  ],"meta": {}}

Host192.168.1.1 appears to be live.

Let's try to find some open TCP ports on a few hosts:

importNetMapfrom'netmap.js'constnetmap=newNetMap()consthosts=['192.168.1.1','192.168.99.100','google.co.uk']constports=[80,443,8000,8080,27017]netmap.tcpScan(hosts,ports).then(results=>{console.log(results)})

{"hosts": [    {"host":"192.168.1.1","control":"22","ports": [        {"port":443,"delta":15,"open":false },        {"port":8000,"delta":19,"open":false },        {"port":8080,"delta":21,"open":false },        {"port":27017,"delta":26,"open":false },        {"port":80,"delta":95,"open":true }      ]    },    {"host":"192.168.99.100","control":"1001","ports": [        {"port":8080,"delta":40,"open":true },        {"port":80,"delta":1001,"open":false },        {"port":443,"delta":1000,"open":false },        {"port":8000,"delta":1004,"open":false },        {"port":27017,"delta":1000,"open":false }      ]    },    {"host":"google.co.uk","control":"1001","ports": [        {"port":443,"delta":67,"open":true },        {"port":80,"delta":159,"open":true },        {"port":8000,"delta":1001,"open":false },        {"port":8080,"delta":1002,"open":false },        {"port":27017,"delta":1000,"open":false }      ]    }  ],"meta": {}}

At first the results may seem contradictory.

192.168.1.1 is an embedded Linux machine (a router) on the local network segment, and the only port open is80. We can see that it took the browser about 5 times longer to error out on80 compared to the other, closed, ports.

192.168.99.100 is a host-only VM with port8080 open andgoogle.co.uk is an external host with both443 and80 open. In these cases the browser threw an error relatively rapidly on the open ports while the closed ports simply timed out. TheTheory section further down explains when this happens.

In order to determine if ports should be tagged as open or closed,netmap.js will scan a "control" port (by default45000) that is assumed to be closed. Thecontrol time is then used to determine the status of other ports. If the ratiodelta/control is greater than a set value (default0.8), the port is assumed to be closed (tl;dr: a difference of more that 20% from the control time means the port is open).

Browsers maintain a blacklist of ports against which they'll refuse to connect (such as FTP, SSH or SMTP). If you try to scan those ports withnetmap.js using the default protocol (http) you'll get a very short timeout. A short timeout is usually a sign that the port is closed but in the case of blacklisted ports it doesn't mean anything.

You can check the blacklists from these sources:

• Chromium source
• Mozilla docs
• Edge/IE (send me a link if you find a source)

BeforeFirefox 61 (and maybe other browsers), it's possible to get around this limitation by using theftp protocol instead ofhttp to establish connections. You can specify theprotocol in the options object when instantiatingNetMap. When usingftp you should expect open ports to time out and closed ports to error out relatively rapidly.ftp scanning is also subject to the limitations around TCPRST packets discussed in this document.

Sub-resource requests from "legacy" protocols likeftp have been blocked for a while in Chromium.

The "ping" sweep functionality provided bynetmap.js does a pretty good job at quickly finding live *nix-based hosts on a local network segment (other computers, phones, routers, printers etc.)

However, due to the implementation this won't work when TCPRST packets are not returned. Typically:

• Windows machines
• Some external hosts
• Some network setups like bridged/host-only VMs

The reason behind this is explained in theTheory section below.

This limitation doesn't affect the TCP scanning capabilities and it's still possible to determine if the above hosts are live by trying to find an open port on them.

Overall, I've found this module to be more accurate and faster than the other bits of code I found laying around the web. That being said, the whole idea of mapping networks from a browser is going to be fidgety by nature. Your mileage may vary.

TheNetMap constructor takes an options object that allows you to configure:

• Theprotocol used for scanning (defaulthttp, seePort Blacklists for why you may want to set it toftp)
• The port connectiontimeout (default1000 milliseconds)

importNetMapfrom'netmap.js'constnetmap=newNetMap({protocol:'http',timeout:3000})

ThepingSweep() method determines if a given array of hosts are live. It does this by checking if connection to a port times out, in which case a host is considered offline (see"Ping" Sweep for limitations andStandard Case for the theory).

The method takes the following parameters:

• hosts array of hosts to scan (IP addresses or host names)
• options object with:
  • maxConnections - the maximum number of concurrent connections (by default10 on Chrome and17 on other browsers - the maximum concurrent connections supported by the browsers)
  • theport to scan (default45000)

It returns a promise.

netmap.pingSweep(['192.168.1.1'],{maxConnections:5,port:80}).then(results=>{console.log(results)})

ThetcpScan() method will perform a port scan against a range of targets. Read theStandard Case to understand how it does this.

The method takes the following parameters:

• hosts array of hosts to scan (IP addresses or host names)
• ports list of ports to scan (integers between 1-65535, avoid ports in theblacklists)
• options object with:
  • maxConnections - the maximum number of concurrent connections (by default6 - the maximum connections per domain browsers will allow)
  • portCallback - a callback to execute when an individualhost:port combination has finished scanning
  • controlPort - the port to scan to determine a baseline closed-port delta (default45000)
  • controlRatio - the similarity, in percentage, from the control delta for a port to be considered closed (default0.8, seeexample)

It returns a promise.

netmap.tcpScan(['192.168.1.1'],[80,27017],{maxConnections:5,portCallback:result=>{console.log(result)},controlPort:45000,controlRatio:0.8}).then(results=>{console.log(results)})

Check theexample to interpret the output.

This section briefly covers the theory behind the module's discovery techniques.

This module usesImage objects to try to request cross-origin resources (the series ofhttp://{host}:{port} URLs under test). The time it takes for the browser to raise an error (thedelta), or the lack of error after a certain timeout value, provides insights into the state of the host and port under review.

A live host willusually respond relatively rapidly with a TCPRST packet when attempting to connect to a closed port.

If the port is open, and even if it's not running an HTTP server, the browser will take a bit longer to raise an error due to the overhead of establishing a full TCP connection and then realising it can't get an image from the provided URL.

An offline host will naturally neither respond with aRST nor allow a full TCP connection to be established. Browsers will still try to establish the connection for a bit before timing out (~90 seconds).netmap.js will time out after waiting 1000 milliseconds by default.

In summary:

• Closed ports on live hosts will have a very shortdelta
• Open ports on live hosts will have a slightly longerdelta
• Offline hosts or unused IP addresses will time out

The standard case is illustrated by the host192.168.1.1 in theTCP Port Scan example.

Some hosts (likegoogle.co.uk or Windows hosts) and some network setups (like VirtualBox host-only networks) will not return TCPRST packets when hitting a closed port.

In these cases, closed ports will usually time out while open ports will quickly raise an error.

The implementation of thepingSweep() method is therefor unreliable whenRST packets are not returned.

In summary, when TCPRST packets are not returned for whatever reason:

• Closed ports on live hosts will time out
• Open ports on live hosts will have a shortdelta
• pingSweep() can't distinguish between a closed port time out and a "dead" host time out

The special case is illustrated by the hosts192.168.99.100 andgoogle.co.uk in theTCP Port Scan example.

It's well-documented that you should also be able to map networks with WebSockets and AJAX.

I gave it a try (and also tweaked BeEF to try itsport_scanner module with WebSockets and AJAX only); I found both methods to produce completely unreliable results.

Please let me know if I'm missing something in this regard.