whos-on-my-network

whos-on-my-network copied to clipboard

Keep and eye on who is on your network and when.

📥 Get the latest release

This tool allows you to identify and keep records of who's on your network and when.

After you scan your network, you can then view devices connected to your network, when they were last seen and keep track of who owns devices (thus allowing you to identify who's on the network).

Pre-built Module and Binary

On every official version change, a release is made with two assets:

• whos_on_my_network.zip: The whos_on_my_network module with the webapp pre-built.
• whos_on_my_network_binary.zip: A Windows executable of whos_on_my_network (does not support plugins)

The pre-built Windows executable does not use a plugin and will default to the built-in method. To make a build containing a particular plugin yourself, execute bash package.sh {plugin-name}; this will produce whos_on_my_network.exe which will use the declared plugin.

If you are using Windows, you will also need to install Npcap.

🛠️ Setup

To setup the project, you will need to clone it, install Python dependencies and then build the webapp.

Requirements

• Python 3.6
• Node
• Npcap (Windows Only)

Setup Steps

1. Clone this git repository: git clone https://github.com/brentvollebregt/whos-on-my-network
2. cd into the project: cd whos-on-my-network
3. Create a Python venv: python -m venv .venv
4. Activate the Python venv: .venv/Scripts/activate.bat
5. Install Python dependencies: python -m pip install -r requirements.txt
6. Build the webapp: cd webapp && npm i && npm run build

🖥️ Usage

There are two primary functions to this tool, scanning and viewing scans. To use the tool, use the whos_on_my_network folder as a Python module by executing python -m whos_on_my_network - this command will show you the usage.

To scan, you have two options; the current command and watch. To view scans, you can host the webapp using start.

Scanning Using current

The current command allows you to run a single scan and see who's currently on the network.

Usage can be found by executing: python -m whos_on_my_network current --help

Arguments:

Examples:

Scanning Using watch

The watch command allows you to run multiple scans on a network with a delay indefinitely. This allows you to keep watching the network automatically as a background task.

Usage can be found by executing: python -m whos_on_my_network watch --help

Examples:

Hosting the Webapp and Server Using start

The start command starts the server that serves the webapp.

Examples:

Screenshots

See more in my blog post.

🧪 Development Setup

When running the client (webapp/) in development mode using npm start, the client will use the REACT_APP_API_ROOT environment variable value to decide where to send requests.

The same process for production and development is used for the server; running python -m whos_on_my_network or run.py in a debugger will allow you to set breakpoints and see what is going on.

Examples of using the Python application can be found in .vscode/launch.json.

❓ How Does This Tool Work?

By default, this tool uses scapy to send ARP packets to all addresses in the provided network range (default is 192.168.1.0/24) to identify what devices are on the network. When a host responds, its MAC address, IP address and hostname are obtained and an entry is added to the SQLite database matched to the current scan.

⚙️ Configuration and Database

When running the module/executable, two files will be created if they do not exist already:

• config.json: Contains basic configuration for the application
• database.sqlite: Used for scan and user data storage

The location of these files are in the parent directory of the module when not packaged or in %APPDATA%/WhoIsOnMyNetwork (Windows) / $HOME/WhoIsOnMyNetwork (Linux and MacOS) when using a packaged version of the application (exe).

When running the unpacked application, you can force the files to be in the packaged locations by setting the environment variable FORCE_PACKAGED_MODE to true.

🔌 Plugins

The two commands current and watch both have an argument --use-plugin. This allows you to specify a custom Python script in the directory whos_on_my_network/plugins which contains a function named scan that takes two parameters and returns a list of DiscoveredDevice objects as defined in whos_on_my_network.service.scanning.

An example plugin for the ASUS RT-AC58U router has been provided as asus-rt-ac58u.py in the plugins folder. This script logs into the router, identifies who is connected to the router and returns a summary of the information found in the object expected.

A plugin can also be set as the default scanning method by setting default_plugin in config.json to the name of the file without the extension; for example:

{
  "host": "0.0.0.0",
  "port": 8080,
  "verbose": false,
  "default_network_id": "192.168.1.0/24",
  "default_plugin": "asus-rt-ac58u"
}