Home

mlab-unifi

A CLI over the UniFi APIs, built as a base for passive network security work.

mlab-unifi talks to a UniFi console on the LAN (the Network Integration API) or to a UniFi Site Manager account in the cloud. Both authenticate with the same X-API-KEY header, so one client covers them, and a profile in $HOME/.mlab/unify.conf says which one to reach and how.

It reads. Nothing in the tool changes a configuration except the device actions you ask for explicitly, and no data leaves your machine.

---

The commands

Command	What it does
audit	Every graded check in one report. Start here.
snapshot	One dated, secret-free record of everything the console holds.
diff	What changed between two snapshots.
login	Create or update a profile, prove the credentials work, save them.
ping	Check that the current profile reaches its API, and report what is on the other end.
info	The console's own version information.
sites	List sites, on either mode.
devices	List, inspect and act on the managed hardware of a site.
clients	What is connected now, or with --all every client ever seen.
network	Segmentation, firewall zones, and what can reach the site from outside.
wifi	Wireless hardening, the neighbourhood, impostors, and airtime.
shadow	What turned up on the network that nobody announced.
posture	What the site's settings say it is defending, and with what.
footprint	What this site looks like from the outside.
blast	What a compromised client would reach.
live	Attach to a console event stream and print what arrives.
hosts	Consoles visible on a Site Manager account (cloud only).
api	Raw request against any surface, for everything not wrapped yet.
profile	List, show, select and delete saved profiles.
config	Where the config file is, and what is in it.

Key concepts

• Surfaces - a console answers on three separate HTTP APIs of very different richness, plus WebSocket streams. Knowing which one a command uses explains most of its behaviour.
• Configuration - profiles, the precedence between flags, environment and file, and where secrets live.
• Identity - how a MAC becomes a named device: the console's fingerprint engine, what --min-score actually gates, and the opt-in vendor lookup for the gaps.
• Output - a terminal render by default, raw JSON with -o json, and the rules that keep the two from mixing.
• Passive security - the catalogue of defensive work this data supports without emitting a single packet at a target.
• Secrets - a read-only API key returns credentials in clear text. What that means for how you store the key and what the tool writes to disk.
• Roadmap - what is built, what is next, in order.
• Releasing - how a version becomes a Homebrew formula, a .deb and an .rpm.

Getting started

brew tap mlab-sh/mlab-unifi https://github.com/mlab-sh/mlab-unifi.git
brew install mlab-unifi
mlab-unifi login --name lab --host 192.168.1.1
mlab-unifi ping

There are .deb and .rpm packages and tarballs for every target on the releases page too. See Install.

Scope and stability

The documented Integration API is stable and versioned. The legacy and v2 surfaces are what the web app calls for itself: far richer, undocumented, and free to change on any firmware update. Commands that depend on them say so on their page, and are expected to degrade rather than fail when a route disappears.