https://github.com/nyu-mlab/iot-inspector-client
IoT Inspector: capturing and analyzing your smart home network traffic
https://github.com/nyu-mlab/iot-inspector-client
internet-of-things iot network-analysis smart-home
Last synced: 2 months ago
JSON representation
IoT Inspector: capturing and analyzing your smart home network traffic
- Host: GitHub
- URL: https://github.com/nyu-mlab/iot-inspector-client
- Owner: nyu-mlab
- License: apache-2.0
- Created: 2018-11-23T18:23:07.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-04-15T22:44:05.000Z (2 months ago)
- Last Synced: 2026-04-16T00:29:45.556Z (2 months ago)
- Topics: internet-of-things, iot, network-analysis, smart-home
- Language: Python
- Homepage: https://inspector.engineering.nyu.edu/
- Size: 212 MB
- Stars: 467
- Watchers: 27
- Forks: 66
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-rainmana - nyu-mlab/iot-inspector-client - IoT Inspector: capturing and analyzing your smart home network traffic (Python)
README
# IoT Inspector 3
[](https://github.com/astral-sh/ruff)[](https://github.com/nyu-mlab/iot-inspector-client/actions/workflows/inspector_test.yaml)[](https://codecov.io/gh/nyu-mlab/iot-inspector-client)
If the underlying dependencies is updated, please run the following first:
```bash
uv cache clean
uv lock
uv sync
```
# User guide
Please review the [User Guide](https://github.com/nyu-mlab/iot-inspector-client/wiki) for instructions how to run IoT Inspector.
## Running on Windows
You have two options
1. Click `IoT Inspector.lnk`
2. Run `start.bat` on your terminal
It will spawn a new PowerShell admin shell to run IoT Inspector. For first time installation, you need to run `start.bat` twice, as `uv` requires a shell refresh.
For a detailed guide, see how to use IoT Inspector for Windows [here](https://github.com/nyu-mlab/iot-inspector-client/wiki/IoT-Inspector-%E2%80%90-Prolific-Guide).
## Running on Mac
This assumes that you currently have **brew** installed. Once done, run the `./start.bash` script to both install and run IoT Inspector.
## Running on Linux
This assumes that you have either `apt`, `yum` of `dnf` package managers first, which should come by default with your Linux distribution.
Once done, run the `./start.bash` script to both install and run IoT Inspector.
# Developer Guide
If you are developing IoT Inspector, please read this section.
## Database Schema
When presenting network stats, IoT Inspector reads from an internal SQLite database.
To see how the packet collector and database is implemented, look at the [IoT Inspector Core package](https://github.com/nyu-mlab/inspector-core-library).
You should always read from the database using the following approach:
```python
import libinspector.global_state
db_conn, rwlock = libinspector.global_state.db_conn_and_lock
with rwlock:
db_conn.execute("SELECT * FROM devices")
```
The schema is as follows:
```sql
CREATE TABLE devices (
mac_address TEXT PRIMARY KEY,
ip_address TEXT NOT NULL,
is_inspected INTEGER DEFAULT 0,
is_gateway INTEGER DEFAULT 0,
updated_ts INTEGER DEFAULT 0,
metadata_json TEXT DEFAULT '{}'
);
CREATE TABLE hostnames (
ip_address TEXT PRIMARY KEY,
hostname TEXT NOT NULL,
updated_ts INTEGER DEFAULT 0,
data_source TEXT NOT NULL,
metadata_json TEXT DEFAULT '{}'
);
CREATE TABLE network_flows (
timestamp INTEGER,
src_ip_address TEXT,
dest_ip_address TEXT,
src_hostname TEXT,
dest_hostname TEXT,
src_mac_address TEXT,
dest_mac_address TEXT,
src_port TEXT,
dest_port TEXT,
protocol TEXT,
byte_count INTEGER DEFAULT 0,
packet_count INTEGER DEFAULT 0,
metadata_json TEXT DEFAULT '{}',
PRIMARY KEY (
timestamp,
src_mac_address, dest_mac_address,
src_ip_address, dest_ip_address,
src_port, dest_port,
protocol
)
);
```
# IoT Inspector Helper Scripts
We also include two scripts to help with development and debugging.
## Anonymize
After installing IoT Inspector, you can run the following command:
```bash
anonymize -i -o
```
Here is the help output
```text
anonymize -h
usage: anonymize [-h] [-i INPUT_FILE] [-o OUTPUT]
Anonymize MACs and filter specific control packets (DHCP, SSDP, MDNS) from a PCAP file.
options:
-h, --help show this help message and exit
-i INPUT_FILE, --input INPUT_FILE
The path to the input PCAP file.
-o OUTPUT, --output OUTPUT
The path to save the anonymized PCAP file (default: sanitized_output.pcap).
```
The output PCAP file will have all
* MAC addresses anonymized
* all DHCP, SSDP, and MDNS packets removed.
This is useful for sharing PCAP files without revealing sensitive information.
## PCAP Time Series
After installing IoT Inspector, you can run the following command:
```bash
time-series -i -m --b
```
Here is the help output
```text
usage: time_series [-h] -i INPUT_FILE -m TARGET_MAC [--interval INTERVAL]
Analyze PCAP file to plot upload and download traffic over time for a specific MAC address.
options:
-h, --help show this help message and exit
-i INPUT_FILE, --input INPUT_PATH
The path to the input PCAP file or directory with PCAP files.
-m TARGET_MAC, --target-mac TARGET_MAC
The MAC address of the device to analyze (e.g., 'aa:bb:cc:dd:ee:ff').
-b BIN_SIZE, --bin BIN_SIZE
The width of time bins in seconds for aggregating traffic data (default: 0.05 seconds).
```
The output will be a PNG file showing the upload and download traffic over time for the specified MAC address. This is useful for visualizing traffic patterns of a device in a PCAP file. An example is shown [here](https://github.com/nyu-mlab/iot-inspector-client/pull/286).
To visualize the console output, if you pass a directory it would look something like this:
```text
pcap_time_series -i C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano -m
INFO: Starting analysis for: C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-31-52PM_UTC_21.00s.pcap
INFO: Target MAC for analysis:
INFO: Time bin size: 0.05 seconds
Processing: C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-31-52PM_UTC_21.00s.pcap
INFO: Read 209 packets. Starting data processing...
INFO: Generating plot...
Processing: C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-33-30PM_UTC_22.00s.pcap
INFO: Successfully saved plot to 'C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-31-52PM_UTC_21.00s_bin_0.05s.png'
INFO: Starting analysis for: C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-33-30PM_UTC_22.00s.pcap
INFO: Target MAC for analysis:
INFO: Time bin size: 0.05 seconds
INFO: Read 222 packets. Starting data processing...
INFO: Generating plot...
INFO: Successfully saved plot to 'C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano\Amazon Echo Show\Use a voice command to ask for time\Mar-20-2026_05-33-30PM_UTC_22.00s_bin_0.05s.png'
```