ABGEO/mezz

Source: https://github.com/ABGEO/mezz

Mezz

Mezz is a self-contained wifi sandbox for inspecting your own IoT devices. The name comes from mezzanine, the half-floor between two main floors of a building. This network sits in the same place: between your devices and the rest of your home network.

Mezz is provided for educational purposes and authorized penetration testing only. Use it on networks and devices you own, or on which you have explicit written permission to test. The author accepts no responsibility for any misuse or for damage caused by use of this software.

What it does

Turns a Linux host with two NICs (one wifi, one wired uplink) into a small isolated network:

• a wifi access point on its own subnet
• DHCP and DNS for any client that connects (wifi or wired)
• NAT out through your wired uplink
• a local domain, so clients resolve as kitchen-pi.lan etc.
• per-query DNS logging, so you can see exactly what your fridge is talking to

It’s defensive only. Made for inspecting devices you own, not for impersonating someone else’s network.

Prerequisites

• a Linux host (kernel with iptables, bridge, and nl80211; any modern distro is fine)
• Docker Engine 20.10+ with the Compose v2 plugin
• a wifi NIC that supports AP mode. Verify with iw list | grep -A 10 "Supported interface modes" and look for * AP. If your radio doesn’t list AP mode, it can’t be Mezz’s access point. Realtek USB sticks are the most common offenders; see docs/realtek.md.
• a wired uplink (WAN_IFACE) for NAT
• (optional) a second wired NIC if you want to plug RJ45 IoT devices into the same LAN as the wifi clients
• root on the host. net-init runs privileged because writing /proc/sys/net/ipv4/ip_forward needs RW /proc/sys

If NetworkManager or wpa_supplicant is currently using the wifi NIC for a normal client connection, release it first or hostapd will fail to start. The exact incantations are in docs/interfaces.md.

Quick start

Grab the compose file and a starter .env from this repo, then bring it up:

mkdir mezz && cd mezz

curl -O https://raw.githubusercontent.com/ABGEO/mezz/main/docker-compose.yaml
curl -o .env https://raw.githubusercontent.com/ABGEO/mezz/main/.env.example

# Edit .env. At minimum set WAN_IFACE / WIFI_IFACE to match your host.
# See docs/interfaces.md for how to find the right values.
$EDITOR .env

docker compose up -d

To revert host network state:

docker compose run --rm net-init teardown

If something doesn’t come up, start with docs/troubleshooting.md. Most issues are environmental (a daemon holding the wifi NIC, a misnamed interface, or an adapter that doesn’t do AP mode).

Extending dnsmasq

Drop *.conf files into a local directory and mount it over /etc/dnsmasq.d in the lan service (see the commented volumes: block in docker-compose.yaml). Useful for static DHCP leases, custom upstream rules, etc.

Optional services

Mezz ships extra containers behind Docker Compose profiles. Pick what you want with COMPOSE_PROFILES in .env ( comma-separated, e.g. mitm or mitm,tcpdump). The base set (net-init, ap, lan) always runs.

mitm

Set both in .env:

COMPOSE_PROFILES=mitm
MITM_ENABLED=true

COMPOSE_PROFILES=mitm brings up the mitmproxy container; MITM_ENABLED=true tells net-init to add the iptables redirect (LAN tcp/{80,443} -> mitmproxy). Without the env flag the container runs but no traffic reaches it. Web UI is on http://<host>:${MITM_WEB_PORT} (default 8081); set MITM_WEB_PASSWORD to skip the random token mitmweb prints on startup.

Only clients that trust the mitmproxy CA produce decryptable traffic. Pinned-cert apps (most modern phones, many IoT clouds) won’t show up in clear.

Documentation

• docs/interfaces.md: picking values for WAN_IFACE, WIFI_IFACE, LAN_IFACE, BR_IFACE, including how to verify your wifi adapter supports AP mode and how to release it from NetworkManager
• docs/troubleshooting.md: common failure modes (net-init exit codes, hostapd refusing to start, clients with no IP / no internet, mitm caveats) with diagnostic commands and fixes
• docs/realtek.md: chipset-specific guidance for Realtek wifi adapters, which often need out-of-tree drivers to support AP mode