# Fabric AIops > **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Cisco, Meraki, Arista, Ubiquiti, or any network-controller vendor.** "Cisco", "Meraki", "Catalyst", "DNA Center", "Arista", "CloudVision", "Ubiquiti", "UniFi" and all product/trademark names belong to their respective owners. MIT licensed. Governed AI-ops for **network fabrics** managed through a controller — the **Cisco Meraki Dashboard API** (the reference platform, full read + write), **Cisco Catalyst Center** (formerly DNA Center; read subset), **Arista CloudVision Portal (CVP)** (read subset), and **UniFi Network** (self-hosted controller or UniFi OS console; read subset + device restart) — with a **built-in governance harness**: unified audit log, token/runaway budget guard, undo-token recording, and descriptive risk tiers. **Multi-platform by construction**: a registry keyed by `platform` maps every *canonical operation* onto each controller's REST API (path templates + response adapters), so adding a controller is a registry entry, never new ops/CLI/MCP surface. An operation a platform doesn't map returns a clear teaching error ("not supported on X yet — open an issue"), never a silent no-op. The test suite is mock-based; no platform has yet been exercised against a live controller — see [`docs/VERIFICATION.md`](docs/VERIFICATION.md). ## What it does Three flagship signature analyses, plus the guarded reads and writes around them: - **Uplink loss & latency RCA** — pull MX WAN uplink loss + latency across an org, rank the worst uplinks by a composite of average loss and latency, and map each degraded uplink to a likely cause + recommended action. Every ranking carries its numbers, not a black-box verdict. - **Network health score** — a composite 0-100 score per network from device online %, uplink health %, and an alert-severity penalty (weighted 0.5/0.3/0.2), with every component returned so the number is explainable. - **Config template drift** — for networks bound to a config template, list the settings that have drifted from the template (expected vs actual). ## What works - **CLI** (`fabric-aiops ...`): `init`, `overview`, `org`, `network`, `device`, `client`, `health`, `remediate`, `secret`, `doctor`, `mcp`. - **MCP server** (`fabric-aiops mcp` or `fabric-aiops-mcp`): **34 tools** (25 read, 9 write), every one wrapped with the bundled `@governed_tool` harness. - **Encrypted credentials**: the controller secret (Meraki API key / Catalyst Center `username:password` / CVP service-account token / UniFi API key) lives in an encrypted store `~/.fabric-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**. Unlock with a master password from `FABRIC_AIOPS_MASTER_PASSWORD` (MCP/CI) or an interactive prompt (CLI). - **Reversibility**: mutating writes fetch the **real before-state first** and record a faithful inverse (`update_device`/`update_network_vlan` restore prior values; `claim`↔`remove`; `bind`↔`unbind`/rebind). Irreversible ops (`reboot_device`, `blink_device_leds`) record the prior state for audit but declare no undo. - **Safety**: every state-changing CLI op supports `--dry-run` and requires double confirmation; every write MCP tool takes a `dry_run` preview. ## Capability matrix (34 MCP tools) | Domain | Tools | Count | R/W | |--------|-------|:-----:|:---:| | **Overview** | `overview` | 1 | read | | **Organizations** | `org_list`, `org_get`, `org_licensing`, `org_admins`, `org_device_statuses`, `org_api_requests` | 6 | read | | **Networks** | `network_list`, `network_get`, `network_vlans`, `network_alerts`, `network_traffic` | 5 | read | | **Devices** | `device_inventory`, `device_status`, `device_uplinks`, `switch_ports`, `wireless_ssids` | 5 | read | | **Clients** | `client_list`, `client_get`, `client_usage`, `client_connectivity` | 4 | read | | **Health (flagship)** | `uplink_loss_and_latency_rca`, `network_health_score`, `config_template_drift` | 3 | read | | **Remediation** | `reboot_device`, `claim_devices_into_network`, `remove_device_from_network`, `bind_network_to_template`, `unbind_network_from_template` | 5 | write (high) | | | `update_device`, `update_network_vlan` | 2 | write (medium) | | | `blink_device_leds` | 1 | write (low) | | **Undo** | `undo_list` | 1 | read | | | `undo_apply` | 1 | write (medium) | `network_health_score` and `config_template_drift` are injected-only (they score data you already hold); `uplink_loss_and_latency_rca` accepts injected `records` for offline analysis or pulls live from a configured target. Device models carry a product-type prefix: **MX** appliance, **MS** switch, **MR** wireless AP, **MV** camera, **MG** cellular gateway. ## Platform support matrix One tool, four controller platforms. The ops/CLI/MCP surface is identical everywhere; each platform maps the canonical operations it supports and raises a teaching error for the rest ("not supported on `` yet — open an issue or PR"). | Canonical operation | meraki | catalyst | cvp | unifi | |---------------------|:------:|:--------:|:---:|:-----:| | `overview` (org/site/container rollup) | ✅ | ✅ | ✅ | ✅ | | `org_list` / `org_get` | ✅ | ✅ sites | ✅ containers | ✅ sites (list; get ❌) | | `org_licensing`, `org_api_requests` | ✅ | ❌ | ❌ | ❌ | | `org_admins` | ✅ | ❌ | ✅ users | ❌ | | `org_device_statuses` | ✅ | ✅ device-health | ✅ inventory + streaming status | ✅ stat/device (state, uptime, firmware) | | `network_list` / `network_get` | ✅ | ✅ site-health / site | ✅ containers | ✅ sites / stat/health (subsystem rollup) | | `network_vlans`, `network_traffic` | ✅ | ❌ | ❌ | ❌ | | `network_alerts` | ✅ | ✅ issues (P1→critical, P2→warning) | ✅ events | ✅ alarms (*_Lost_Contact→critical) | | `device_inventory`, `device_status` | ✅ | ✅ network-device | ✅ inventory (+ complianceCode drift signal) | ✅ stat/device (id = device **MAC**) | | `device_uplinks` | ✅ | ❌ | ❌ | ❌ | | `switch_ports` | ✅ | ✅ interface stats (pass the device **uuid**) | ❌ | ✅ device `port_table` (pass the device **MAC**) | | `wireless_ssids` | ✅ | ❌ | ❌ | ❌ | | `client_list` / `client_get` | ✅ | ✅ client-health (aggregate) / client-detail (by MAC) | ❌ | ✅ stat/sta (connected) / stat/user (by MAC) | | `client_usage`, `client_connectivity` | ✅ | ❌ | ❌ | ❌ | | `uplink_loss_and_latency_rca` (live pull) | ✅ | ❌ (injected `records` still work) | ❌ (injected `records` still work) | ❌ (injected `records` still work) | | `network_health_score`, `config_template_drift` (injected-only) | ✅ | ✅ | ✅ | ✅ | | `reboot_device` | ✅ | ❌ teaching error | ❌ teaching error | ✅ `cmd/devmgr` restart-device | | **The other 7 writes** (blink/update/claim/remove/bind/unbind/VLAN) | ✅ | ❌ teaching error | ❌ teaching error | ❌ teaching error | Concept mapping: canonical *organizations/networks* are Catalyst Center **sites**, CVP **containers**, and UniFi **sites** (the canonical id is the site's short name — the `/api/s/{site}/` path segment); all have one global tree, so the org scope does not filter their lists. On unifi, device-scoped calls (`device get` / `switch_ports` / `reboot`) fill the site from the target's default `org_id` — set it in config.yaml (or the init wizard). Writes are **Meraki-only except UniFi device restart** — Catalyst Center and CVP change models (task/configlet workflows) don't map cleanly onto these canonical writes, so each write fails fast with a teaching error *before* any controller call (never a silent no-op). CVP config-drift surfaces through `device_inventory` (`complianceCode`/`complianceIndication` per device) and `network_alerts` (events); configlet-content retrieval and deep pagination on catalyst/cvp/unifi are known deferrals. ### Per-platform auth | Platform | `platform:` | Secret stored (encrypted) | Auth on the wire | Base URL | |----------|-------------|---------------------------|------------------|----------| | Cisco Meraki Dashboard | `meraki` | API key (Dashboard → Organization → Settings → API access) | `Authorization: Bearer` (or `auth_style: meraki-key` → `X-Cisco-Meraki-API-Key`) | default `https://api.meraki.com/api/v1` | | Cisco Catalyst Center | `catalyst` | `username:password` (one string) | exchanged via `POST /dna/system/api/v1/auth/token` (HTTP Basic) for a ~1 h `X-Auth-Token`, auto-refreshed once on a 401 | required, e.g. `https://` | | Arista CloudVision Portal | `cvp` | service-account token (Settings → Access Control → Service Accounts) | `Authorization: Bearer` | required, e.g. `https://` | | UniFi Network | `unifi` | API key (UniFi OS: Settings → Control Plane → Integrations; self-hosted Network Server 9.0+) | `X-API-KEY` (stateless; legacy cookie login is a known deferral) | required — classic controller `https://:8443`, or UniFi OS console `https:///proxy/network` (keep the prefix) | `fabric-aiops init` walks through the platform choice and stores the right kind of secret; `fabric-aiops doctor` probes each target with the canonical top-of-hierarchy read (organizations / sites / containers / UniFi sites), exercising the full auth flow. ## What this tool does, and does not, decide It delivers network-fabric operations — reads and writes — accurately and efficiently, and records every one of them. It does **not** decide whether a write is allowed to happen. That is the agent's judgement, or the permission of the account you connect it with: give it a Meraki API key whose admin has read-only organization access (or the read-only equivalent on your controller) and the writes fail at the controller — the place that actually owns the permission. So there is no read-only switch, no policy file, no approval gate to configure. The one thing the tool guarantees is that nothing is silent: **every call, over MCP and over the CLI alike, lands an audit row** in `~/.fabric-aiops/audit.db`, and mutating writes still capture their before-state and record an inverse where one exists. > Each tool declares a `risk_level`, kept in agreement with its `[READ]`/`[WRITE]` > documentation tag by a test, and carried into the audit row as a descriptive > tier — so a reviewer can see at a glance that a row was a high-risk delete. It > is a label, not a gate. ## Quick start ### As a Claude Code plugin One install gives an agent both the skill and the MCP server: ``` /plugin marketplace add AIops-tools/marketplace /plugin install fabric-aiops@aiops-tools ``` The MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the package version this plugin declares, so an audit row can be traced back to the code that wrote it. Credentials are still configured with `fabric-aiops init` — see below. ### As an OpenClaw plugin The same bundle is published on [ClawHub](https://clawhub.ai/plugins), where one install delivers the skill and its MCP server together: ```bash openclaw plugins install clawhub:@zw008/fabric-aiops openclaw skills info fabric-aiops # expect: Visible to model: yes ``` Restart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is fetched with [uv](https://docs.astral.sh/uv/), pinned to this exact release, so `uvx` has to be on `PATH` — without it the skill still installs but reports `Visible to model: no`. Credentials are configured exactly as below. ### As a CLI or standalone MCP server ```bash uv tool install fabric-aiops # or: pipx install fabric-aiops fabric-aiops init # wizard: choose platform (meraki/catalyst/cvp/unifi) + store the secret (encrypted) fabric-aiops doctor # verify config, secrets, connectivity (per-platform auth probe) fabric-aiops overview # one-shot fabric fleet health fabric-aiops health uplink-rca # rank worst MX WAN uplinks + cause/action (meraki) fabric-aiops device inventory --model MS # switches in the org ``` Run as an MCP server (stdio): ```bash export FABRIC_AIOPS_MASTER_PASSWORD=... # unlock secrets non-interactively fabric-aiops-mcp ``` > **Where that password then lives**: an exported variable is readable by > every process this shell starts and is recorded by shell history. On a > shared or long-lived host, prefer the interactive prompt, or inject it from > a secret manager for the life of the one command that needs it. ## Governance Every operation — MCP **and** CLI — passes through the bundled `@governed_tool` harness. It records; it does not authorize (see above). - **Audit** — every call (params, result, status, duration, risk tier, and any operator-supplied approver/rationale) is logged to `~/.fabric-aiops/audit.db` (relocatable via `FABRIC_AIOPS_HOME`). The CLI writes the same row the MCP path does — there is no unaudited entry point. - **Runaway guard** — a safety backstop, not an authorization gate: the same call hammered in a tight loop trips a circuit breaker so a stuck agent can't burn unbounded calls/time. Disable with `FABRIC_RUNAWAY_MAX=0`; optional hard ceilings via `FABRIC_MAX_TOOL_CALLS` / `FABRIC_MAX_TOOL_SECONDS`. - **Undo recording** — reversible writes record an inverse descriptor built from the fetched before-state. - **Risk tier** — a descriptive label on the audit row derived from `risk_level`; it gates nothing. ## Scope This is the **network-fabric / controller** member of the AIops-tools family (governed AI-ops with audit + budget + undo + risk tiers). Do **NOT** use it for OT / industrial edge (Modbus, OPC-UA, PROFINET) — see the separate `industrial-aiops` line — nor for device-level CLI/SSH network automation. ## Missing a capability? Coverage is intentionally a curated subset of each controller's API. Missing a call or a device family on **Meraki**? A ❌ in the support matrix you need on **Catalyst Center**, **CloudVision Portal**, or **UniFi Network** (writes included — e.g. the UniFi cookie-login fallback for pre-9.0 controllers)? Want another controller platform entirely? **Open an issue or PR** — contributions welcome (a platform is a single descriptor module: path templates + response adapters). ## Status The test suite is mock-based. No platform has yet been exercised against a live Meraki organization, Catalyst Center appliance, CloudVision Portal instance, or UniFi controller — all four platforms' API paths are modelled from the public API shapes. [`docs/VERIFICATION.md`](docs/VERIFICATION.md) defines the checklist a live run must cover; `fabric-aiops doctor` is the fastest live check.