fabric-aiops 0.1.0__tar.gz

fabric_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

fabric_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

fabric_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to fabric-aiops are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses semantic
+versioning (currently 0.x preview — the API may change).
+
+## [0.1.0] — 2026-07-13
+
+Initial preview release: governed AI-ops for network fabrics managed through the
+**Cisco Meraki Dashboard API** (organizations → networks → devices) with a
+bundled governance harness. **Mock-validated only — not verified against a live
+Meraki organization.** Community-maintained; not affiliated with Cisco/Meraki.
+
+### Added
+
+- **Multi-platform connection layer** — a `platform` registry (`fabric_aiops.platform`)
+  keyed by name so future controllers (Catalyst Center, Arista CVP) can register a
+  descriptor without touching the ops/CLI/MCP layers. Only **meraki** is
+  registered in v0.1. Handles `Authorization: Bearer` / `X-Cisco-Meraki-API-Key`
+  auth, `Link`-header pagination, and injection-safe response normalisation.
+- **32 governed MCP tools**, every one wrapped with `@governed_tool`:
+  - **Overview** — `overview` (org networks + device status/product rollup).
+  - **Organizations** — `org_list`, `org_get`, `org_licensing`, `org_admins`,
+    `org_device_statuses`, `org_api_requests`.
+  - **Networks** — `network_list`, `network_get`, `network_vlans`,
+    `network_alerts`, `network_traffic`.
+  - **Devices** — `device_inventory` (by model MX/MS/MR/MV/MG), `device_status`,
+    `device_uplinks`, `switch_ports`, `wireless_ssids`.
+  - **Clients** — `client_list`, `client_get`, `client_usage`,
+    `client_connectivity`.
+  - **Health (flagship)** — `uplink_loss_and_latency_rca`, `network_health_score`,
+    `config_template_drift`.
+  - **Remediation (writes)** — `reboot_device` (high), `blink_device_leds` (low),
+    `update_device` (medium), `update_network_vlan` (medium),
+    `claim_devices_into_network` (high), `remove_device_from_network` (high),
+    `bind_network_to_template` (high), `unbind_network_from_template` (high).
+- **Guarded writes** — every write supports a `dry_run` preview and (at the CLI)
+  double confirmation. Mutating/reversible writes fetch the **real before-state**
+  and record a faithful inverse undo descriptor.
+- **Bundled governance harness** (`fabric_aiops.governance`) — audit log, policy
+  engine, token/runaway budget guard, undo-token recording, graduated risk tiers,
+  prompt-injection `sanitize`. State under `~/.fabric-aiops/` (relocatable via
+  `FABRIC_AIOPS_HOME`).
+- **Encrypted secret store** — Meraki API keys in `~/.fabric-aiops/secrets.enc`
+  (Fernet + scrypt); legacy `FABRIC_<TARGET>_APIKEY` env fallback + `secret
+  migrate`.
+- **CLI** — `init` wizard, `overview`, `org`, `network`, `device`, `client`,
+  `health`, `remediate`, `secret`, `doctor`, `mcp`.
+
+### Known limitations
+
+- Preview / mock-only: Dashboard API paths need live verification.
+- Coverage is a curated subset of the Dashboard API; open an issue/PR for gaps.
+
+[0.1.0]: https://github.com/AIops-tools/Fabric-AIops/releases/tag/v0.1.0

fabric_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fabric_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: fabric-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Cisco Meraki network fabrics: uplink RCA, health scoring & config-drift with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/fabric-aiops -->
+
+# Fabric AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Cisco, Meraki, or any network-controller vendor.** "Cisco" and "Meraki" and all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **network fabrics** managed through a cloud controller —
+starting with the **Cisco Meraki Dashboard API** (organizations → networks →
+devices) — with a **built-in governance harness**: unified audit log, policy
+engine, token/runaway budget guard, undo-token recording, and graduated-autonomy
+risk tiers. **Multi-platform by construction**: a registry keyed by `platform`
+means Catalyst Center or Arista CVP can be added later as additional platforms
+without touching the ops/CLI/MCP layers — **Meraki is the one platform shipped in
+v0.1**. **Preview — mock-validated only, not verified against a live Meraki org.**
+
+## 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`): **32 tools** (24 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the Meraki 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 (32 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) |
+
+`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.
+
+## Quick start
+
+```bash
+uv tool install fabric-aiops              # or: pipx install fabric-aiops
+fabric-aiops init                         # wizard: add a target + store the Meraki API key (encrypted)
+fabric-aiops doctor                       # verify config, secrets, connectivity
+fabric-aiops overview                     # one-shot fabric fleet health
+fabric-aiops health uplink-rca            # rank worst MX WAN uplinks + cause/action
+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
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.fabric-aiops/audit.db` (relocatable via
+  `FABRIC_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`ENDPOINT_AUDIT_APPROVED_BY` / `ENDPOINT_AUDIT_RATIONALE` — the env-var names
+  the bundled harness reads).
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state.
+
+## 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 the Meraki Dashboard API. Missing a
+call, a device family, or want another controller platform (Catalyst Center,
+Arista CVP)? **Open an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not verified against a live Meraki org.** The
+Dashboard API paths are modelled from the public API shape and need live
+verification. `fabric-aiops doctor` is the fastest live check.

fabric_aiops-0.1.0/README.md

@@ -0,0 +1,107 @@
+<!-- mcp-name: io.github.AIops-tools/fabric-aiops -->
+
+# Fabric AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Cisco, Meraki, or any network-controller vendor.** "Cisco" and "Meraki" and all product/trademark names belong to their respective owners. MIT licensed.
+
+Governed AI-ops for **network fabrics** managed through a cloud controller —
+starting with the **Cisco Meraki Dashboard API** (organizations → networks →
+devices) — with a **built-in governance harness**: unified audit log, policy
+engine, token/runaway budget guard, undo-token recording, and graduated-autonomy
+risk tiers. **Multi-platform by construction**: a registry keyed by `platform`
+means Catalyst Center or Arista CVP can be added later as additional platforms
+without touching the ops/CLI/MCP layers — **Meraki is the one platform shipped in
+v0.1**. **Preview — mock-validated only, not verified against a live Meraki org.**
+
+## 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`): **32 tools** (24 read, 8 write), every one wrapped with the bundled `@governed_tool` harness.
+- **Encrypted credentials**: the Meraki 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 (32 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) |
+
+`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.
+
+## Quick start
+
+```bash
+uv tool install fabric-aiops              # or: pipx install fabric-aiops
+fabric-aiops init                         # wizard: add a target + store the Meraki API key (encrypted)
+fabric-aiops doctor                       # verify config, secrets, connectivity
+fabric-aiops overview                     # one-shot fabric fleet health
+fabric-aiops health uplink-rca            # rank worst MX WAN uplinks + cause/action
+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
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier, approver,
+  rationale) is logged to `~/.fabric-aiops/audit.db` (relocatable via
+  `FABRIC_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops can require a named approver
+  (`ENDPOINT_AUDIT_APPROVED_BY` / `ENDPOINT_AUDIT_RATIONALE` — the env-var names
+  the bundled harness reads).
+- **Undo recording** — reversible writes record an inverse descriptor built from
+  the fetched before-state.
+
+## 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 the Meraki Dashboard API. Missing a
+call, a device family, or want another controller platform (Catalyst Center,
+Arista CVP)? **Open an issue or PR** — contributions welcome.
+
+## Status
+
+**Preview — mock-validated only, not verified against a live Meraki org.** The
+Dashboard API paths are modelled from the public API shape and need live
+verification. `fabric-aiops doctor` is the fastest live check.

fabric_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,51 @@
+# Fabric AIops v0.1.0 — preview
+
+Governed AI-ops for **network fabrics** managed through the **Cisco Meraki
+Dashboard API** (organizations → networks → devices) for AI agents, with a
+built-in governance harness (audit, policy, token/runaway budget, undo-token
+recording, graduated risk tiers) and an encrypted credential store. Standalone —
+no external skill-family dependency. Multi-platform by construction; Meraki is
+the one platform shipped in v0.1.
+
+> **Preview / mock-only.** All behaviour is validated against mocked Dashboard
+> API responses; it has not been run against a live Meraki organization. The
+> fastest live check is `fabric-aiops doctor`.
+>
+> Community-maintained; **not affiliated with or endorsed by Cisco/Meraki.**
+> Trademarks belong to their owners.
+
+## Highlights
+
+- **32 MCP tools** (24 read, 8 write), every one wrapped with `@governed_tool`.
+  - Read: fleet `overview`; organizations (6); networks (5); devices (5);
+    clients (4); and three flagship analyses.
+  - Write: `reboot_device`/`claim_devices_into_network`/`remove_device_from_network`/
+    `bind_network_to_template`/`unbind_network_from_template` (high),
+    `update_device`/`update_network_vlan` (medium, capture before-state),
+    `blink_device_leds` (low).
+- **Three signature analyses** — `uplink_loss_and_latency_rca` (rank worst MX WAN
+  uplinks + cause/action), `network_health_score` (composite per-network health),
+  and `config_template_drift` (settings drifted from a bound template).
+- **Encrypted API key store** (`~/.fabric-aiops/secrets.enc`, Fernet + scrypt) —
+  never plaintext on disk; legacy `FABRIC_<TARGET>_APIKEY` env fallback.
+- **CLI** with an `init` onboarding wizard, `secret` management, and `doctor`.
+- **Multi-platform connection layer** — a `platform` registry (`Authorization:
+  Bearer` or `X-Cisco-Meraki-API-Key` auth, `Link`-header pagination) with
+  teaching error translation (`FabricApiError`); only Meraki registered in v0.1.
+
+## Install
+
+```bash
+uv tool install fabric-aiops
+fabric-aiops init
+fabric-aiops doctor
+```
+
+## Caveats
+
+- The Dashboard API paths are modelled from the public API shape and need live
+  verification against a real organization.
+- Out of scope by design: full org/network provisioning workflows, firmware
+  upgrade orchestration, and any bulk destructive operation.
+- Missing a capability or want another controller platform (Catalyst Center,
+  Arista CVP)? Open an issue or PR.

fabric_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,80 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by Cisco, Meraki, or any network-controller vendor.** "Cisco",
+"Meraki", and all product/trademark names belong to their respective owners.
+Source is publicly auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Fabric-AIops](https://github.com/AIops-tools/Fabric-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target Meraki API keys live **encrypted** in `~/.fabric-aiops/secrets.enc`
+  (Fernet/AES-128 + scrypt-derived key; chmod 600), never in `config.yaml` and
+  never in source. The master password is never stored — only a per-store random
+  salt and the ciphertext are on disk.
+- A legacy plaintext env var `FABRIC_<TARGET_NAME_UPPER>_APIKEY` is still honoured
+  as a fallback with a deprecation warning (migrate with `fabric-aiops secret
+  migrate`).
+- The API key is sent in the platform auth header (`Authorization: Bearer` by
+  default, or `X-Cisco-Meraki-API-Key`) at request time and held only in memory.
+  Keys are never logged or echoed; the config file holds only platform, base URL,
+  default org id, and TLS settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`fabric_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.fabric-aiops/`
+  (relocatable via `FABRIC_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`ENDPOINT_MAX_TOOL_CALLS` /
+  `ENDPOINT_MAX_TOOL_SECONDS` — the env-var names the bundled harness reads) plus
+  an on-by-default guard that trips a tight poll/retry loop, preventing unbounded
+  Dashboard API consumption (and the associated rate-limit exposure).
+- **Graduated risk tiers** — `~/.fabric-aiops/rules.yaml` `risk_tiers` gate writes
+  by environment/tag; the highest tiers require a recorded approver
+  (`ENDPOINT_AUDIT_APPROVED_BY` / `ENDPOINT_AUDIT_RATIONALE`).
+- **Undo-token recording** — mutating/reversible writes fetch the **real
+  before-state first** and record a faithful inverse descriptor (e.g.
+  `update_device` restores the prior attributes; `bind`↔`unbind`; `claim`↔`remove`).
+
+### State-Changing Operations
+Every write supports `--dry-run` (CLI) / `dry_run=True` (MCP) and requires double
+confirmation at the CLI layer. Destructive or fleet-affecting ops (`reboot_device`,
+`claim_devices_into_network`, `remove_device_from_network`,
+`bind_network_to_template`, `unbind_network_from_template`) are `risk_level=high`;
+mutating reversible ops (`update_device`, `update_network_vlan`) are `medium`;
+`blink_device_leds` (a locator aid, no config change) is `low`. Irreversible ops
+capture the before-state for the audit record but record no undo token.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for a self-signed on-prem controller
+proxy.
+
+### Prompt-Injection Protection
+All controller-returned text (network names, device names, client descriptions,
+tags, settings) is passed through a `sanitize()` truncate + control-character
+strip before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured controller REST
+API base URL. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r fabric_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

fabric_aiops-0.1.0/fabric_aiops/__init__.py

@@ -0,0 +1,10 @@
+"""fabric-aiops — governed Cisco Meraki network-fabric operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``fabric_aiops.governance`` — this package has no external
+skill-family dependency. Multi-platform by construction (see
+``fabric_aiops.platform``); v0.1 ships Meraki. Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

fabric_aiops-0.1.0/fabric_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for fabric-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``fabric-aiops = "fabric_aiops.cli:app"`` works unchanged.
+"""
+
+from fabric_aiops.cli._root import app
+
+__all__ = ["app"]

fabric_aiops-0.1.0/fabric_aiops/cli/_common.py

@@ -0,0 +1,81 @@
+"""Shared helpers for fabric-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+OrgOption = Annotated[
+    str | None, typer.Option("--org-id", "-o", help="Meraki organization id (else target default)")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from fabric_aiops.connection import FabricApiError
+
+    return (FabricApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None):
+    """Return a (conn, config) tuple for the given target."""
+    from fabric_aiops.config import load_config
+    from fabric_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

fabric_aiops-0.1.0/fabric_aiops/cli/_root.py

@@ -0,0 +1,64 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from fabric_aiops.cli._common import cli_errors
+from fabric_aiops.cli.client import client_app
+from fabric_aiops.cli.device import device_app
+from fabric_aiops.cli.doctor import doctor_cmd
+from fabric_aiops.cli.health import health_app
+from fabric_aiops.cli.init import init_cmd
+from fabric_aiops.cli.network import network_app
+from fabric_aiops.cli.org import org_app
+from fabric_aiops.cli.overview import overview_cmd
+from fabric_aiops.cli.remediate import remediate_app
+from fabric_aiops.cli.secret import secret_app
+
+app = typer.Typer(
+    name="fabric-aiops",
+    help="Governed AI-ops for Cisco Meraki network fabrics (organizations / networks / devices).",
+    no_args_is_help=True,
+)
+
+app.add_typer(org_app, name="org")
+app.add_typer(network_app, name="network")
+app.add_typer(device_app, name="device")
+app.add_typer(client_app, name="client")
+app.add_typer(health_app, name="health")
+app.add_typer(remediate_app, name="remediate")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        fabric-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: fabric-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force fabric-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()