Metadata-Version: 2.4
Name: iot-inspector
Version: 3.0.21
Summary: IoT Inspector Client for analyzing IoT device firmware
Author-email: Danny Huang <dhuang@nyu.edu>, Andrew Quijano <andrew.quijano@nyu.edu>
License-Expression: Apache-2.0
Project-URL: Homepage, https://inspector.engineering.nyu.edu/
Project-URL: Source, https://github.com/nyu-mlab/iot-inspector-client/
Project-URL: Tracker, https://github.com/nyu-mlab/iot-inspector-client/issues
Project-URL: Documentation, https://github.com/nyu-mlab/iot-inspector-client/wiki
Project-URL: Download, https://github.com/nyu-mlab/iot-inspector-client/releases/latest
Keywords: iot-inspector,network-traffic-analysis,network-monitoring,iot-security
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi==2026.1.4
Requires-Dist: requests==2.32.5
Requires-Dist: pandas==2.3.3
Requires-Dist: flask==3.1.3
Requires-Dist: pymongo==4.16.0
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: libinspector>=1.0.26
Requires-Dist: streamlit>=1.52.1
Requires-Dist: gdown>=5.2.1
Requires-Dist: matplotlib==3.10.8
Requires-Dist: scipy==1.15.3
Requires-Dist: statsmodels==0.14.4
Requires-Dist: scikit-learn==1.7.0
Dynamic: license-file

# IoT Inspector 3
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)[![libinspector_test](https://github.com/nyu-mlab/iot-inspector-client/actions/workflows/inspector_test.yaml/badge.svg)](https://github.com/nyu-mlab/iot-inspector-client/actions/workflows/inspector_test.yaml)[![codecov](https://codecov.io/gh/nyu-mlab/iot-inspector-client/graph/badge.svg?token=SFZ2QUJWQW)](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 <input_pcap_file> -o <output_pcap_file>
```

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 <PCAP_FILE/PCAP_DIRECTORY> -m <TARGET_MAC> --b <BIN_SIZE_IN_SECONDS>
```

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 <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'
```
