Iotaudit

iotaudit

If you find this useful, you can support me by getting a SkinToScan pack, my other project. It's a one-time purchase that directly funds my open-source work.

pip install iotaudit

sudo iotaudit auto # asks for consent, audits your own network, writes an HTML report iotaudit analyze capture.pcap # no root needed: analyse a pcap or PCAPdroid capture you already have

Quick links: sample report · what common devices send · Home Assistant · MCP server

Is your smart pet feeder, camera or plug safe? iotaudit watches what your own IoT devices do on the network and gives each one an A-F grade, a one-line safety verdict, and a one-page HTML report. Everything runs locally: no account, no telemetry, no cloud.

It answers the questions you actually have about a cheap smart device:

• What is the short version? A one-line verdict next to the grade. Open ports, public DNS, TLS or plaintext, and destination countries are observed facts. Video, audio, and other traffic patterns stay indicators with a confidence.
• Who does it talk to? Domains (DNS + TLS SNI + HTTP Host), IPs, country, organisation. The report lists the destination countries for each device (observed fact).
• What does the traffic look like? A separate per-device indicator for video, audio, telemetry, or unknown, each with a low, medium, or high confidence. It is a pattern match, not proof of what was sent.
• Is it encrypted? Plaintext HTTP, unencrypted TCP, old TLS, or "custom" high-entropy protocols.
• What ports are open? Optional nmap scan with risk notes (telnet, RTSP, UPnP, ADB, …).
• Any known issue for this banner? A short offline hint when a version string matches a curated CVE. It does not change the grade unless the version match is exact and the entry is critical.
• Is it reachable from the internet? Lists the port forwards your router opened via UPnP and which device they point to (read-only, never changes the router).
• Does it phone home while idle? Idle-upload check and a traffic timeline with bursts.
• Where did the video go? LAN peer (phone P2P) vs cloud vs STUN/TURN, and an honest note when a stream was set up but never actually passed through your computer.
• What changed since the last audit? iotaudit diff compares two saved JSON results and exits 1 when a new destination, country, open port, worse grade, unencrypted flow, UPnP forward, or device appeared.

Status: 0.1.18. CSV export via iotaudit export --format csv; Home Assistant summary via --ha-json. iotaudit auto discovers devices, runs the safe checks, captures passively, and writes the report in one command. Hotspot + ARP capture, pcap and PCAPdroid analysis, IPv6/NDP, device-type

identification, UPnP port-forward audit, an opt-in default-password check, grading with a

one-line safety verdict, HTML and PDF reports, a diff between two audits, offline known-issue

hints, a local web UI and the MCP server work. A full vulnerability feed is still on the

roadmap.

Sample report

A report for a Tuya-associated pet feeder (anonymized). The one-line verdict sits beside the grade: telnet open on the LAN, public DNS, TLS cloud traffic to the US, unverified custom encryption, and a P2P video setup whose stream was not observed on this run. The longer summary is still underneath. It also shows an odd special-use "LAN peer" that is not a real device:

Open docs/sample-report.html in a browser for the full version.

Demo

A short walk-through of a capture, the UPnP port-forward check and the opt-in default-password check (animated SVG, no audio, no tracking):

Install

pipx install iotaudit

or with the MCP server extra, and PDF export:

pip install "iotaudit[mcp]" pip install "iotaudit[pdf]"

latest from source:

pipx install "git+https://github.com/emirmrkaljevic/iotaudit"

Capturing needs root (sudo). The optional port scan needs nmap.

Quick start

One command does the audit. It asks you to confirm this is your network, picks the active interface, finds devices, identifies them, scans ports, lists UPnP forwards (read-only), captures passively for 60 seconds, and writes the report.

sudo iotaudit auto

Each device is printed on one line, then the report path. Files land in ~/iotaudit/YYYY-MM-DD/ as HTML and JSON. A PDF is written next to them when iotaudit[pdf] is installed (pip install "iotaudit[pdf]"). If that folder already has a run from today, the new run is compared with the latest one.

Skip the typed confirmation with the existing ownership flag:

sudo iotaudit auto --i-own-this-network

A longer capture, or an explicit folder:

sudo iotaudit auto --i-own-this-network --duration 120 --out-dir ~/iotaudit

nmap and tcpdump are required. If either is missing, the command prints one install line and stops:

# macOS

brew install nmap tcpdump

Debian or Ubuntu

sudo apt install nmap tcpdump

On macOS, Homebrew and a pipx install often sit outside sudo's PATH:

sudo env PATH="$PATH" "$(which iotaudit)" auto --i-own-this-network

Default passwords are not tested. That check stays opt-in, one device at a time (iotaudit credcheck, which is the only command with --yes).

auto does not ARP-spoof and does not start a hotspot. It records traffic that already passes this computer. To pull one device's traffic through this machine, use capture --mode arp below.

macOS

brew install nmap

pipx install iotaudit

Just run it: pick your device from the list, then leave it alone (or use its app).

sudo "$(which iotaudit)" capture --mode arp --i-own-this-network

iotaudit scans your LAN, lists devices (IP, MAC, vendor; Tuya/Espressif flagged as likely IoT), and lets you pick one. It then ARP-spoofs only that device so its traffic flows through your Mac, captures for up to an hour (Ctrl+C stops early and still writes the report), and restores the ARP tables and IP-forwarding on exit. With a device picked, --watch-lan (phone P2P) and the IPv6/NDP filter are on by default.

Linux

sudo apt install nmap

pipx install iotaudit

Same ARP flow as macOS:

sudo "$(which iotaudit)" capture --mode arp --i-own-this-network

Or hotspot mode: your laptop becomes an AP; re-pair the device to it (needs NetworkManager).

sudo iotaudit capture --mode hotspot --iface wlan0 --ssid iotaudit --password 'choose-a-pass' \ --device 10.42.0.50 --scan --out feeder.html

Analyse an existing capture

# from Wireshark, your router, or OpenWrt `tcpdump -w`

iotaudit analyze capture.pcap --device 192.168.1.50 --json results.json --out report.html

The report lands at ./iotaudit-report.html with a matching .json next to it.

Known-issue hints

iotaudit compares banners it already has with a small catalog shipped in the package (src/iotaudit/data/known_issues.yaml). The facts it can use are:

• an open service from the port scan, plus the nmap product and version
• an HTTP Server header from a response the device sent
• a UPnP or SSDP header (including an InternetGatewayDevice advertisement)
• an RTSP response that did not ask for authentication, when that was already in the capture or in the scan record

There is no lookup at runtime and no hints --update-from command. The file changes only when you install a newer iotaudit.

Each hint is a possibility, not proof the firmware is vulnerable. The text always includes: possible, based on version string; verify firmware. The reference is the NVD page for that CVE.

Hints show in the HTML report, in the PDF (the PDF is the same HTML), in the device JSON as known_issue_hints, and in the MCP analyze_pcap result.

Grade rule. A hint does not change the A-F grade unless both are true: the observed version string equals a version the entry lists exactly, and the entry severity is critical. That case subtracts 25 points, the same as one high finding, and the subtraction is applied after the limited-data cap so it still moves a thin capture. A version range, a product name without that exact version, an open port on its own, or any severity other than critical leaves the score unchanged. Telnet being open, an exposed UPnP IGD, or RTSP with no authentication is not by itself a CVE. The catalog cites one only when the banner or the service fact matches that entry.

Limits:

• The file is a short curated list (on the order of 10 to 20 issues), not the NVD and not a firmware database.
• A patched device can still show an old version string. An unpatched device can hide the version. Either way the hint says to verify the firmware.
• Banners are read from IPv4 packets and from the nmap record. IPv6 service banners are not parsed.
• RTSP with no authentication is recorded when a captured RTSP 200 has no WWW-Authenticate header, or when the scan extra info already says so. The shipped list does not treat that fact alone as a CVE. It is mentioned on a hint when a versioned RTSP entry also matches.
• No network access is used to refresh the list.

PDF export

pip install "iotaudit[pdf]"

Writes report.pdf next to report.html:

iotaudit analyze capture.pcap --device 192.168.1.50 --out report.html --pdf sudo "$(which iotaudit)" capture --mode arp --i-own-this-network --pdf

Convert a report you already saved (HTML, or the JSON list of devices):

iotaudit report --pdf report.html iotaudit report --pdf results.json --out results.pdf

--pdf on analyze and capture writes a PDF next to the HTML. Print styles put the grade and verdict at the top of each device (the first device shares page 1 with the title; every later device starts on a new page), keep table rows in one piece, and repeat the table header. The on-screen traffic chart is left out of the PDF.

The renderer is xhtml2pdf, a pure-Python extra (xhtml2pdf, pulled in by iotaudit[pdf]). No Cairo or Pango install is required. If the extra is not installed, analyze and capture still write the HTML and print one install line. iotaudit report --pdf prints that same line and exits, because the PDF is its only output. The MCP tool analyze_pcap takes pdf=true together with report_path and writes the PDF beside the HTML.

Compare two audits

iotaudit diff "$HOME/iotaudit/yesterday.json" "$HOME/iotaudit/to