Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including arper with all npm packages installed. Try it out:

var arper = require("arper")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

arper v0.0.13


Project for Istanbul Packathon (

NOTE: this tool is still under HEAVY development! The package is there just as a placeholder for the name. Use at your own risk.


I want to see who is connecting to my WiFi network (or any other network for that matter) in real time.

Applications like [1] represent the state of the art in detecting nodes on a network. Their approach is based on periodic scanning of IP addresses using tools like Nmap. There are two problems with this approach:

  1. It's not real time and it requires constant polling (and we all hate polling don't we?).
  2. If there is a central entity in the network (e.g. a router) it might limit things like ICMP requests (ping), port scanning etc. Furthermore individual nodes can simply decide not to reply to any unauthenticated request, regardless of the protocol used (e.g. on OS X a user can set the machine in "stealth mode", i.e. the machine will stop replying to ICMP requests).
  3. They work on top of the IP layer (OSI level 3) which means the packets they send have to be routed by an entity, likely a router.

Why can't I just leave a RaspberryPi scanning IP addresses?

Because IP addresses can change on a regular basis, for example if you use DHCP. It's perfectly normal. MAC addresses, on the other hand, can only be spoofed and the average Joe most probably doesn't know how to do that.


In every network based on the Ethernet protocol (like WiFi 802.11) once a node obtains an IP address (e.g. from a DHCP server) it advertises its pair (IP address, MAC address), that is, its virtual and physical addresses, to every node on the network in a peer-to-peer fashion using the ARP [2] protocol.

ARP packets cannot be routed. A central entity in the network has no control over what ARP packets are sent. Nodes can at most flood the network with packets (for example flooding with ARP responses is often used to carry on man-in-the-middle attacks).

This means that every single node on the network will receive ARP packets broadcasted by other nodes, in a completely passive manner. No polling required!


Arper represents a new class of network detection tools. Arper can detect, in real time, when a new node in the network broadcasts its IP and MAC addresses. By monitoring a network device with Pcap it can passively listen for ARP packets. That passively is of extreme importance. It means there is virtually zero impact on performance and power usage while Arper is running.


This and any other detection methods (including Nmap) do not work if the WiFi access point (which acts at the datalink layer) implements VLANs [3] (a.k.a. "client isolation"). A VLAN is, in fact, a virtual channel established between the node and the AP, at the datalink layer, that prevents the node from communicating with any other node in the network, no matter what higher-level protocol is used. It's basically the equivalent of plugging a cable into a switch.

VLANs are usually implemented in places with a public network such as cafes, universities, companies etc.

I want it

npm install -g arper

Arper accepts three arguments:

  • interface (String): the network interface to use.
  • callback (Function): a callback for whenever a packet is received.
  • pretty (Boolean): if true IP and MAC addresses will be passed as strings (e.g. 00:01:02:AA:BB:CC) otherwise as an array of decimals (e.g. [128, 100, 150, 80, 10, 35]).
var arper = require("arper");
arper.monitor("en0", function(err, newNode) { // en0 is the default WiFi interface on Mac
  if (err)
    console.log("Something went wrong!");
  // Do something with newNode
}, true);


Middleware for Arper can be easily attached. Do you want to receive a notification when a new node is connected? You can. Do you want to receive an SMS/Email/... when it happens? You can.

An example of dead simple logging middleware:

var arper = require("arper");

var loggingMiddleware = function(newNode) {


arper.monitor("en0", function(err, newNode) {
}, true);

Middleware functions are called in the order they are added and are never passed an error. Only the main callback does (see below).


The examples directory includes some use cases of Arper by using specific middleware.

Each example can be run with npm start.


Clone the repository or go to your NODE_PATH directory and cd to arper. Then run:

npm test


  • [1]
  • [2]
  • [3]


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free