IoT Inspector 3

IoT Inspector shows you what the smart devices on your home network are doing: which devices are there, who they talk to, and how much data they send.

The main version is now written in Go and lives in go/. The original Python version is still here and still works.

User guide

Please review the User Guide for instructions how to run IoT Inspector.

Quick start (recommended)

IoT Inspector ships as a single prebuilt program (the Go version), so you don't need Go, Python, or uv installed.

Download or clone this repository, then:

• Windows: run start-go.bat. It asks for admin access and installs the Npcap capture driver the first time.
• Mac / Linux: run ./start-go.bash. It asks for your password.

The script downloads the latest release for your machine, checks its SHA256, and opens the dashboard at http://127.0.0.1:8080. Press Ctrl-C to stop; your network is restored on exit.

The binaries are also on the releases page (tags starting with go-v). See the Go README for command-line options and running a downloaded binary directly.

Python version

The original Python version still works:

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.

Running on Mac

This assumes that you currently have both brew and Apple Developer Tools 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.

Go version

The code is in go/. See the Go README for building, running, and cutting a release.

Python version

If the underlying dependencies is updated, please run the following first:

uv cache clean
uv lock
uv sync

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.

You should always read from the database using the following approach:

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:

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. Both are part of the Python version.

Anonymize

After installing IoT Inspector, you can run the following command:

anonymize -i <input_pcap_file> -o <output_pcap_file>

Here is the help output

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:

time-series -i <PCAP_FILE/PCAP_DIRECTORY> -m <TARGET_MAC> --b <BIN_SIZE_IN_SECONDS>

Here is the help output

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.

To visualize the console output, if you pass a directory it would look something like this:

pcap_time_series -i C:/Users/andre/OneDrive/Desktop/packets/AndrewQuijano -m <MAC-ADDRESS>

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: <MAC-ADDRESS>
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: <MAC-ADDRESS>
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'