UniFi Network

Read-only access to UniFi Network data for device inventory, network config, client info, alerts, health status, and topology export.

Security Scan

The skill's code matches its claimed read-only UniFi purpose, but the registry metadata omits required credentials and runtime dependencies and there are minor persistence/privacy concerns (local cache of API responses), so review before installing.

Purpose & Capability

The skill's name and description (read-only UniFi Network access) align with the included scripts: all network inventory/health/clients/topology scripts use only GETs against the UniFi API. However the registry metadata declares no required env vars or binaries, but the SKILL.md and scripts require UNIFI_URL/UNIFI_API_KEY (or a config file) and runtime binaries (curl, jq). That metadata omission is an incoherence and should be corrected.

Instruction Scope

Runtime instructions and scripts stay within the stated purpose: they only call UniFi API endpoints, read a local config (~/.clawdbot/credentials/unifi/config.json) for URL and API key, and write/read cache under ~/.clawdbot/cache/unifi/. Scripts are explicit about which endpoints are used and include a setup_test to validate endpoints. They do not attempt to read other system config or unrelated credentials.

Install Mechanism

There is no install spec (no external downloads). All code is included in the package and scripts are executed directly. This is lower risk than remote installers; nothing in the files downloads arbitrary code from unknown hosts.

Credentials

The skill legitimately needs an API key and base URL (UNIFI_API_KEY, UNIFI_URL, optional UNIFI_SITE or config file). Those are appropriate and scoped to UniFi read-only access. The concern is that the registry metadata did not declare these required credentials or the primaryEnv, which is misleading. The skill writes raw API responses to local cache files (may contain sensitive information) and expects the user to create a config file containing the API key; the SKILL.md suggests chmod 600, which is good practice.

Persistence & Privilege

The skill persists data in ~/.clawdbot/cache/unifi/ and expects a credentials file at ~/.clawdbot/credentials/unifi/config.json. This is limited to its own directory (no system-wide changes) and always:false. Caching is intentional for efficiency but means API responses (including potentially sensitive device/client data) are stored on disk; the cache and config file locations are mutable via UNIFI_CONFIG_FILE and HOME.

What to consider before installing

What to check before installing: - Metadata mismatch: the package metadata lists no required env vars/binaries, but the scripts need UNIFI_URL and UNIFI_API_KEY (or a config file) and the binaries curl and jq. Don't rely solely on the registry metadata—follow SKILL.md. - Secrets: supply a read-only UniFi API key and keep it limited to Network read scope. The skill stores that key in ~/.clawdbot/credentials/unifi/config.json (SKILL.md recommends chmod 600) and caches API responses in ~/.clawdbot/cache/unifi/; secure those files and consider filesystem backups/rotations. - UNIFI_URL safety: ensure UNIFI_URL points to your trusted UniFi host (typically an internal host). If an attacker can control that URL, they could receive API requests/responses. The skill will send your API key to whatever UNIFI_URL you configure. - Autonomy: the skill is allowed to be invoked by the agent (normal). If you are concerned about autonomous access to network inventory data, consider disabling autonomous invocation for this skill or restricting when it can be used. - Verify binaries: ensure curl and jq are present in the runtime environment; run scripts/setup_test.sh to validate connectivity and endpoint shapes before regular use. - If you need stronger guarantees: ask the publisher to correct registry metadata to declare required env vars and primaryEnv (UNIFI_API_KEY), and to document the cache/content retention policy. If you cannot verify the publisher, review the included scripts yourself (they are readable) or run them in a controlled environment first.

UniFi Network Skill

Read-only access to UniFi Network data for infrastructure documentation and troubleshooting. Covers devices, networks, clients, health, alerts, and topology export.

Base URL: configured via UNIFI_URL (e.g. https://UniFi.Url.Here.local) Auth: API key via X-API-Key header — no session management Site: default unless overridden via UNIFI_SITE

API Response Shape

The UniFi OS (UOS) API has two response formats:

• v2 device endpoint (/proxy/network/v2/api/site/{site}/device): returns {"network_devices": [...], "unmanaged_devices": [...]} — NOT {"data": [...]}. All device scripts account for this.
• Legacy endpoints (/proxy/network/api/s/{site}/...): return {"data": [...]}. Used by health, clients, networks, wlans, alerts, dpi, ports.

WAN subsystem health returns "unknown" status when no UniFi gateway is adopted (e.g. TNSR/other router). LAN status shows "error" when num_disconnected > 0.

Setup

Create ~/.clawdbot/credentials/unifi/config.json:

{
  "url": "https://UniFi.Url.Here.local",
  "api_key": "YOUR_API_KEY",
  "site": "default"
}

chmod 600 ~/.clawdbot/credentials/unifi/config.json

API key: UniFi OS → Settings → System → API → Create API Key (read-only scopes).

Or use env vars: UNIFI_URL, UNIFI_API_KEY, UNIFI_SITE.

Token & API Efficiency Rules

Always follow these — they exist to minimize API calls and token use:

1. Call snapshot.sh first before any other script. Read its output. Only proceed to specific scripts if the answer isn't already there.
2. Rely on cache. Scripts cache responses and serve from disk when fresh. Do not force re-runs to get "fresher" data unless debugging.
3. Use client_locate.sh for any device/client lookup. It joins clients + devices + networks in one call. Never call those three scripts separately for the same query.
4. Use stripped output (default). Only use --json or --raw if you need fields not present in the default output.
5. Don't call scripts you don't need. If snapshot.sh shows 0 open alerts, skip alerts.sh.

Cache TTLs

Data	TTL	Scripts
Inventory	60 min	devices, networks, wlans, port_profiles, port_forwards
Operational	5 min	health, clients, dpi
Alerts	60 sec	alerts

Cache lives at ~/.clawdbot/cache/unifi/. Each script prints cache age in its header.

Scripts

snapshot.sh [--json]

Start here. Compact overview: WAN status, device/client/network/alert counts, device health list, VLAN list, top open alerts.

Trigger when: user asks general "how's the network", "UniFi status", "what's connected", "any issues".

bash scripts/snapshot.sh

---

devices.sh [--json] [--raw]

All adopted devices: name, model, IP, status, client count, firmware.

Trigger when: "list all devices", "show APs", "what switches do I have", "device inventory".

bash scripts/devices.sh

---

networks.sh [--json] [--raw]

All network configs: name, purpose, VLAN ID, subnet, DHCP state.

Trigger when: "what VLANs exist", "show network config", "what subnet is X on", "DHCP ranges".

bash scripts/networks.sh

---

wlans.sh [--json] [--raw]

Wireless networks: SSID, security, VLAN, enabled state, hidden.

Trigger when: "what SSIDs are configured", "wireless networks", "what VLAN is SSID X on".

bash scripts/wlans.sh

---

port_profiles.sh [--json] [--raw]

Switch port profiles: name, native VLAN, PoE mode, speed.

Trigger when: "what port profiles exist", "how is port profile X configured", "PoE profiles".

bash scripts/port_profiles.sh

---

port_forwards.sh [--json] [--raw]

NAT/port forward rules: name, proto, external port, internal dest, state.

Trigger when: "what ports are forwarded", "port forwarding rules", "is port X forwarded", "NAT rules".

bash scripts/port_forwards.sh

---

firmware.sh [--json] [--all]

Devices with pending firmware updates. Default: only shows devices needing update. --all: shows all with current version.

Trigger when: "firmware updates", "what needs upgrading", "firmware versions", change management docs.

bash scripts/firmware.sh
bash scripts/firmware.sh --all  # full version inventory

---

health.sh [--json] [--raw]

Subsystem health: WAN, LAN, WLAN status and counters.

Trigger when: "is WAN up", "network health", "any subsystem issues".

bash scripts/health.sh

---

alerts.sh [N] [--json] [--archived]

Recent open alarms. Default: 20, unarchived.

Trigger when: "any alerts", "recent alarms", "what went wrong", incident investigation.

bash scripts/alerts.sh
bash scripts/alerts.sh 50 --archived

---

clients.sh [--json] [--raw] [--wifi|--wired]

All active connected clients: hostname, IP, VLAN, AP or switch+port.

Trigger when: "who's connected", "active clients", "how many devices on the network". Not for locating a specific client — use client_locate.sh instead.

bash scripts/clients.sh
bash scripts/clients.sh --wired

---

client_history.sh [hours] [--json]

Clients seen in last N hours, including disconnected. Default: 24h.

Trigger when: "did X connect today", "recently disconnected devices", "was Y on the network".

bash scripts/client_history.sh
bash scripts/client_history.sh 48

---

dpi.sh [N] [--json]

Top N apps by bandwidth via DPI. Default: 10.

Trigger when: "what's using bandwidth", "top applications", "bandwidth hogs".

bash scripts/dpi.sh
bash scripts/dpi.sh 20

---

device_detail.sh <name|ip|mac> [--json]

Full detail on one device: all ports with speed/PoE/errors, radio table, firmware update status.

Trigger when: troubleshooting a specific switch or AP — "is port 5 on SW-Core up", "what channel is AP-Living on", "PoE draw on the living room switch".

bash scripts/device_detail.sh AP-Living
bash scripts/device_detail.sh 10.0.5.12
bash scripts/device_detail.sh dc:a6:32:xx:xx:xx

---

client_locate.sh <name|ip|mac> [--json] [--include-history]

Most useful troubleshooting tool. Finds a client and returns: IP, MAC, VLAN, network name, AP or switch+port, signal (if WiFi), last seen. Joins clients+devices+networks from cache — one output, no chaining.

Add --include-history to find recently disconnected clients.

Trigger when: "where is device X", "what port is printer Y on", "what VLAN is Z on", "find hostname X", "I can't reach device X".

bash scripts/client_locate.sh "MacBook"
bash scripts/client_locate.sh 192.0.10.55
bash scripts/client_locate.sh --include-history "old-laptop"

---

topology_export.sh [--out <file>]

Full site topology as markdown: devices table, VLANs table, WLANs table, port forwards. Designed for BookStack, memory writes, or documentation.

Trigger when: "generate network documentation", "export topology", "write to memory", "document the network".

bash scripts/topology_export.sh
bash scripts/topology_export.sh --out ~/clawd/memory/bank/unifi-topology.md

---

Workflow Examples

"Is the network healthy?" → snapshot.sh only. Done.

"Where is the NAS?" → client_locate.sh NAS only. Done.

"What's eating all the bandwidth?" → snapshot.sh (confirms WAN up), then dpi.sh. Two scripts.

"Document the network for BookStack" → topology_export.sh --out <path>. One script.

"AP-Living seems slow" → device_detail.sh AP-Living. One script. Check channel, clients, signal.

"I can't reach 172.0.20.5" → client_locate.sh 172.0.20.5. If not found: client_locate.sh --include-history 172.0.20.5. Then health.sh if VLAN issue suspected.