Fabric AIops

Fabric AIops

Audit availability: Real writes require a committed pending audit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.

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", "ACI", "APIC" 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), plus read-only Cisco ACI (APIC) endpoint path reconstruction and faults — 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. No platform has yet been exercised against a live controller by this tool; the ACI reads are the one part built from real controller responses (anonymized APIC payloads a production user supplied) — see 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, aci, remediate, secret, doctor, mcp.
• MCP server (fabric-aiops mcp or fabric-aiops-mcp): 37 tools (28 read, 9 write), every one wrapped with the bundled @governed_tool harness.
• Encrypted credentials: the controller secret (Meraki API key / Catalyst Center or APIC 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 (37 MCP tools)

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, five controller platforms. For the four in the table below 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"). ACI maps none of these — see Cisco ACI below.

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.

Cisco ACI (APIC)

ACI has two axes — tenant → VRF → bridge domain → EPG, and pod → node → interface — and neither is an organization → network → device tree. Rather than make every network_id mean something different per call, an aci target answers the canonical tools with a teaching error and gets three read-only ACI-native tools that take ACI references (MAC/IP, tenant/app/EPG names, DNs):

How to read them:

• A static reconstruction, not a reachability test. staticPathResolved: true means the fabric is configured to carry the endpoint, not that traffic flows. Nothing is written to the APIC and no troubleshooting session is created.
• Links follow the relation APIC resolved (tDn), so cross-tenant links into common are followed; a relation that is not formed is a finding with its state.
• Related faults are candidates matched by DN (the EPG, the attachment interface, the leaf's deployed copy of the EPG's policy) — proximity, not cause.
• Fault rows are records, not incidents: a delegated record mirrors a fault on another object. A cleared fault keeps the description it had when raised.
• Not evaluated (listed in every result as notChecked): vzAny contracts, taboo contracts, imported contract interfaces, preferred-group peers, service graphs / L3Out.

Leaf/spine inventory and interface state (fabricNode, topSystem, l1PhysIf) are not in this release — they will be built once real responses for those classes are available, as the ones above were.

Per-platform auth

| 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/net