{"id":50154113,"url":"https://github.com/ABGEO/mezz","last_synced_at":"2026-06-10T02:00:34.625Z","repository":{"id":356989347,"uuid":"1233120574","full_name":"ABGEO/mezz","owner":"ABGEO","description":"A self-contained wifi sandbox for inspecting your own IoT devices","archived":false,"fork":false,"pushed_at":"2026-05-10T20:34:49.000Z","size":42,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T15:45:47.456Z","etag":null,"topics":["access-point","dnsmasq","docker","docker-compose","hostapd","iot","iot-security","mitmproxy","network-analysis","networking","penetration-testing","security-tools","wifi"],"latest_commit_sha":null,"homepage":"https://www.abgeo.dev/projects/mezz/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ABGEO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T16:03:01.000Z","updated_at":"2026-05-11T18:24:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ABGEO/mezz","commit_stats":null,"previous_names":["abgeo/mezz"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ABGEO/mezz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABGEO%2Fmezz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABGEO%2Fmezz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABGEO%2Fmezz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABGEO%2Fmezz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ABGEO","download_url":"https://codeload.github.com/ABGEO/mezz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABGEO%2Fmezz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34133404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["access-point","dnsmasq","docker","docker-compose","hostapd","iot","iot-security","mitmproxy","network-analysis","networking","penetration-testing","security-tools","wifi"],"created_at":"2026-05-24T10:00:31.833Z","updated_at":"2026-06-10T02:00:34.617Z","avatar_url":"https://github.com/ABGEO.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# Mezz\n\nMezz is a self-contained wifi sandbox for inspecting your own IoT devices. The name comes\nfrom [mezzanine](https://en.wikipedia.org/wiki/Mezzanine), the half-floor between two main floors of a building. This\nnetwork sits in the same place: between your devices and the rest of your home network.\n\n\u003e [!CAUTION]\n\u003e Mezz is provided for educational purposes and authorized penetration testing only. Use it on networks and devices you\n\u003e own, or on which you have explicit written permission to test. The author accepts no responsibility for any misuse or\n\u003e for damage caused by use of this software.\n\n## What it does\n\nTurns a Linux host with two NICs (one wifi, one wired uplink) into a small isolated network:\n\n- a wifi access point on its own subnet\n- DHCP and DNS for any client that connects (wifi or wired)\n- NAT out through your wired uplink\n- a local domain, so clients resolve as `kitchen-pi.lan` etc.\n- per-query DNS logging, so you can see exactly what your fridge is talking to\n\nIt's defensive only. Made for inspecting devices you own, not for impersonating someone else's network.\n\n## Prerequisites\n\n- a Linux host (kernel with `iptables`, `bridge`, and `nl80211`; any modern distro is fine)\n- Docker Engine 20.10+ with the Compose v2 plugin\n- a wifi NIC that supports **AP mode**. Verify with `iw list | grep -A 10 \"Supported interface modes\"` and look for\n  `* AP`. If your radio doesn't list AP mode, it can't be Mezz's access point. Realtek USB sticks are the most common\n  offenders; see [docs/realtek.md](docs/realtek.md).\n- a wired uplink (`WAN_IFACE`) for NAT\n- (optional) a second wired NIC if you want to plug RJ45 IoT devices into the same LAN as the wifi clients\n- root on the host. `net-init` runs `privileged` because writing `/proc/sys/net/ipv4/ip_forward` needs RW `/proc/sys`\n\nIf `NetworkManager` or `wpa_supplicant` is currently using the wifi NIC for a normal client connection, release it\nfirst or hostapd will fail to start. The exact incantations are in\n[docs/interfaces.md](docs/interfaces.md#wifi_iface-the-ap-radio).\n\n## Quick start\n\nGrab the compose file and a starter `.env` from this repo, then bring it up:\n\n```bash\nmkdir mezz \u0026\u0026 cd mezz\n\ncurl -O https://raw.githubusercontent.com/ABGEO/mezz/main/docker-compose.yaml\ncurl -o .env https://raw.githubusercontent.com/ABGEO/mezz/main/.env.example\n\n# Edit .env. At minimum set WAN_IFACE / WIFI_IFACE to match your host.\n# See docs/interfaces.md for how to find the right values.\n$EDITOR .env\n\ndocker compose up -d\n```\n\nTo revert host network state:\n\n```bash\ndocker compose run --rm net-init teardown\n```\n\nIf something doesn't come up, start with [docs/troubleshooting.md](docs/troubleshooting.md). Most issues are\nenvironmental (a daemon holding the wifi NIC, a misnamed interface, or an adapter that doesn't do AP mode).\n\n## Extending dnsmasq\n\nDrop `*.conf` files into a local directory and mount it over `/etc/dnsmasq.d` in the `lan` service (see the commented\n`volumes:` block in `docker-compose.yaml`). Useful for static DHCP leases, custom upstream rules, etc.\n\n## Optional services\n\nMezz ships extra containers behind Docker Compose profiles. Pick what you want with `COMPOSE_PROFILES` in `.env` (\ncomma-separated, e.g. `mitm` or `mitm,tcpdump`). The base set (`net-init`, `ap`, `lan`) always runs.\n\n| Profile | What it adds                                                  |\n|---------|---------------------------------------------------------------|\n| `mitm`  | mitmproxy in transparent mode for LAN HTTP/HTTPS interception |\n\n### mitm\n\nSet both in `.env`:\n\n```\nCOMPOSE_PROFILES=mitm\nMITM_ENABLED=true\n```\n\n`COMPOSE_PROFILES=mitm` brings up the mitmproxy container; `MITM_ENABLED=true` tells `net-init` to add the iptables\nredirect (LAN tcp/{80,443} -\u003e mitmproxy). Without the env flag the container runs but no traffic reaches it. Web UI is\non `http://\u003chost\u003e:${MITM_WEB_PORT}` (default `8081`); set `MITM_WEB_PASSWORD` to skip the random token mitmweb prints\non startup.\n\nOnly clients that trust the mitmproxy CA produce decryptable traffic. Pinned-cert apps (most modern phones, many IoT\nclouds) won't show up in clear.\n\n## Documentation\n\n- [docs/interfaces.md](docs/interfaces.md): picking values for `WAN_IFACE`, `WIFI_IFACE`, `LAN_IFACE`, `BR_IFACE`,\n  including how to verify your wifi adapter supports AP mode and how to release it from NetworkManager\n- [docs/troubleshooting.md](docs/troubleshooting.md): common failure modes (`net-init` exit codes, hostapd refusing\n  to start, clients with no IP / no internet, mitm caveats) with diagnostic commands and fixes\n- [docs/realtek.md](docs/realtek.md): chipset-specific guidance for Realtek wifi adapters, which often need\n  out-of-tree drivers to support AP mode\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FABGEO%2Fmezz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FABGEO%2Fmezz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FABGEO%2Fmezz/lists"}