IoT Inspector 3

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

uv cache clean
uv lock
uv sync

User guide

Please review the User Guide 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.

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.

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.

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> -m <TARGET_MAC> -o <OUTPUT_PNG_FILE> --b <BIN_SIZE_IN_SECONDS>

Here is the help output

usage: time_series [-h] -i INPUT_FILE -m TARGET_MAC [-o OUTPUT] [--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_FILE
                        The path to the input PCAP file.
  -m TARGET_MAC, --target-mac TARGET_MAC
                        The MAC address of the device to analyze (e.g., 'aa:bb:cc:dd:ee:ff').
  -o OUTPUT, --output OUTPUT
                        The path to save the output plot PNG file (default: traffic_timeseries.png).
  -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.

The output should look something like this on the console.

INFO: Starting analysis for: TEST.pcap
INFO: Target MAC for analysis: 44:3d:54:e3:4b:6e
INFO: Time bin size: 0.05 seconds
INFO: Read 2392 packets. Starting data processing...
INFO: Generating plot...
INFO: Successfully saved plot to 'traffic_timeseries.png'