mlab-unifi

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

It talks to a UniFi console on the LAN or to a UniFi Site Manager account in the cloud, both with the same X-API-KEY header, and a profile in $HOME/.mlab/unify.conf says which one to reach and how.

It reads. Nothing changes a configuration except the device actions you ask for explicitly, and no data leaves your machine unless a command says it does and you pass the flag that allows it.

Requires UniFi Network 9.x or later on the console.

Install

Homebrew (macOS and Linux)

brew tap mlab-sh/mlab-unifi https://github.com/mlab-sh/mlab-unifi.git
brew install mlab-unifi

Debian and Ubuntu: download the .deb for your architecture from the releases page, then:

sudo apt install ./mlab-unifi_1.0.0_amd64.deb

Fedora, RHEL and rebuilds: the same with the .rpm:

sudo dnf install ./mlab-unifi-1.0.0-1.x86_64.rpm

Prebuilt binary (macOS and Linux, x86_64 and arm64): a tarball from the same page. The Linux builds are linked against glibc 2.35, so Debian 12 and Ubuntu 22.04 and newer.

Every release carries a SHA256SUMS file covering all of its assets:

sha256sum -c --ignore-missing SHA256SUMS

From source (a recent Rust toolchain):

git clone https://github.com/mlab-sh/mlab-unifi.git
cd mlab-unifi && cargo build --release

See Install for the details, and Releasing for how these packages are built.

First run

Get an API key from the console UI (Settings, Control Plane, Integrations), or from unifi.ui.com for cloud mode, then:

mlab-unifi login --name lab --host 192.168.1.1
mlab-unifi ping
mlab-unifi audit

login prompts for the key without echoing it, checks the connection, picks the site, and writes the config file with mode 0600 in a 0700 directory.

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.
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.

Every command renders to the terminal by default and to raw JSON with -o json. See Output.

Documentation

Everything lives in the wiki, one page per command plus the concepts they rest on:

• Install, building and first run.
• Configuration, profiles and the precedence between flags, environment and file.
• Surfaces, the three HTTP APIs a console answers on and what each one is worth.
• Identity, how a MAC becomes a named device.
• Passive security, the catalogue of defensive work this data supports without emitting a packet at a target.
• Secrets, why a read-only API key is not read-only in the way you would hope.
• Roadmap, what is built and what is next.

The pages are written in wiki/ in this repository and mirrored to the GitHub wiki by .github/workflows/wiki-sync.yml on every push to main that touches them. The repository is the source of truth, so edit the files here rather than the pages in the wiki UI, which are overwritten on the next sync.

Layout

src/
  main.rs          entry point
  cli/             the clap surface, and the context a command runs in
  commands/        one file per command
  unifi/           the HTTP client, the surfaces, profiles, the registry
  enrich/          fingerprints, OUI, firmware posture, advisories
  audit.rs         the graded checks, as pure functions over fetched data
  ui/              the terminal render and the progress rules
wiki/              the documentation, mirrored to the GitHub wiki
Formula/           the Homebrew formula, regenerated at every release
.github/workflows/ the wiki sync and the release pipeline

Prior art for the API surface: colindickson/unifi (Go).