{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/network-aiops -->\n# network-aiops\n\n> **Disclaimer**: This is a community-maintained open-source project and is **not\n> affiliated with, endorsed by, or sponsored by Cisco, Arista, Juniper, NetBox\n> Labs, or any network vendor.** Vendor and product names are trademarks of their\n> respective owners. Source code is publicly auditable at\n> [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops)\n> under the MIT license.\n\nGoverned multi-vendor network device operations for AI agents — **33 MCP tools**,\nevery one wrapped with the bundled `@governed_tool` harness: a local unified audit\nlog under `~/.network-aiops/`, token/runaway budget guard, undo-token recording,\nand descriptive risk-tier labels. Credentials (device passwords + the NetBox token)\nare kept in an **encrypted store** (`secrets.enc`), never plaintext on disk.\n\nDevices are reached over [NAPALM](https://napalm.readthedocs.io/); an optional\nNetBox block adds source-of-truth lookups.\n\n> **Standalone**: the governance harness is bundled in the package\n> (`network_aiops.governance`) — network-aiops has no external skill-family\n> dependency. Coverage focuses on common device operations and is not yet exhaustive.\n\n> **Verification status**: the test suite is mock-based; not yet validated against live\n> devices — self-testable with cEOS / vMX / containerlab. See\n> [docs/VERIFICATION.md](docs/VERIFICATION.md).\n\n## What works\n\nRead device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary and\ndetail), ARP/MAC tables, VLANs, route lookups, hardware environment, optics, NTP,\nusers, SNMP info, VRFs, and an aggregated `device_health`; run read-only **RCA\ndiagnostics** that flag down/erroring/flapping interfaces and unhealthy BGP\nneighbors — each finding citing the measured number that tripped it; back up the\nrunning config, dry-run a config diff, and merge/replace/rollback config — across the five\ncore NAPALM platforms below. Optional NetBox lookups (devices + interfaces) confirm\nintended state before a change.\n\nNAPALM does not implement every getter on every platform; an unsupported getter\nreturns a teaching error (\"not supported by the `<driver>` driver\") rather than\ncrashing. Secrets are never returned — `get_users` redacts password hashes and\n`get_snmp_information` redacts community strings.\n\n## Supported devices\n\n| Platform | NAPALM driver | Transport |\n|----------|---------------|-----------|\n| Cisco IOS / IOS-XE | `ios` | SSH |\n| Cisco Nexus NX-OS | `nxos` (NX-API) / `nxos_ssh` (SSH) | HTTPS / SSH |\n| Cisco IOS-XR | `iosxr` | SSH (XML agent) |\n| Arista EOS | `eos` | eAPI (HTTPS) |\n| Juniper Junos | `junos` | NETCONF (SSH) |\n\nAdditional platforms (Nokia SR OS / SR Linux, Huawei VRP, etc.) are reachable via\nNAPALM **community drivers** but are **not officially tested here**. Need one?\nSee [Contributing](#contributing--feature-requests).\n\n## Supported actions\n\n| Action | Tool | R/W | Risk |\n|--------|------|:---:|:----:|\n| Device facts (hostname/vendor/model/OS/serial/uptime) | `device_facts` | R | low |\n| Interfaces (up/down, speed, description) | `get_interfaces` | R | low |\n| Interface traffic + error counters | `get_interfaces_counters` | R | low |\n| Interface IP addresses | `get_interfaces_ip` | R | low |\n| BGP neighbors (summary / detail) | `get_bgp_neighbors` / `get_bgp_neighbors_detail` | R | low |\n| LLDP neighbors (summary / detail) | `get_lldp_neighbors` / `get_lldp_neighbors_detail` | R | low |\n| ARP table | `get_arp_table` | R | low |\n| MAC address table | `get_mac_address_table` | R | low |\n| VLANs | `get_vlans` | R | low |\n| Route lookup | `get_route_to` | R | low |\n| Hardware environment (fans/temp/power/CPU/mem) | `get_environment` | R | low |\n| Optical transceiver levels | `get_optics` | R | low |\n| NTP servers / sync stats | `get_ntp_servers` / `get_ntp_stats` | R | low |\n| Local users (hashes redacted) | `get_users` | R | low |\n| SNMP info (communities redacted) | `get_snmp_information` | R | low |\n| Network instances (VRFs) | `get_network_instances` | R | low |\n| Aggregated device health | `device_health` | R | low |\n| Interface health RCA (down / errors / discards / flaps) | `interface_health_rca` | R | low |\n| BGP neighbor RCA (down / shut / reset / route-less) | `bgp_neighbor_rca` | R | low |\n| Back up running config | `config_backup` | R | low |\n| Diff a candidate (dry-run) | `config_diff` | R | low |\n| Merge config + commit | `config_merge` | W | medium |\n| Replace full config + commit | `config_replace` | W | **high** |\n| Roll back last commit | `config_rollback` | W | medium |\n| NetBox list devices | `netbox_list_devices` | R | low |\n| NetBox get device | `netbox_get_device` | R | low |\n| NetBox device interfaces | `netbox_device_interfaces` | R | low |\n| List recorded reversible writes | `undo_list` | R | low |\n| Apply a recorded inverse (governed, single-use, dry-run capable) | `undo_apply` | W | medium |\n\n## What this tool does, and does not, decide\n\nIt delivers multi-vendor network device (NAPALM) + NetBox operations — reads and writes —\naccurately and efficiently, and records every one of them. It does **not** decide whether a\nwrite is allowed to happen. That is the agent's judgement, or the permission of the account you\nconnect it with: log in with a device account at a read-only privilege level (and give NetBox a\nread-only API token), and the writes fail at the server — the place that actually owns the\npermission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure. The one thing the\ntool guarantees is that nothing is silent: **every call, over MCP and over the CLI alike, lands an\naudit row** in `~/.network-aiops/audit.db`, and destructive writes still capture their before-state\nand record an inverse where one exists.\n\n> Each tool declares a `risk_level`, carried into the audit row as a descriptive tier\n> (none/confirm/review) — so a reviewer can see at a glance that a row was a high-risk delete. It\n> is a label, not a gate.\n\nRunning a smaller / local model? See\n[agent-guardrails.md](skills/network-aiops/references/agent-guardrails.md) — it lists the guardrails\nthis tool enforces for you (so you don't spend prompt budget restating them) and gives a ready-made\nsystem prompt for what's left.\n\n## Quick Start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install network-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `network-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install network-aiops\nnetwork-aiops init                                  # wizard: device + driver + host + encrypted password\nnetwork-aiops doctor\nnetwork-aiops device facts -t core-sw1\nnetwork-aiops device health -t core-sw1\nnetwork-aiops diagnose interface-health -t core-sw1   # worst-first interface RCA\nnetwork-aiops diagnose bgp -t core-sw1                # worst-first BGP-neighbor RCA\nnetwork-aiops config backup -t core-sw1 -o core-sw1.cfg\n```\n\n### Playbook: triage a flaky uplink before touching config\n\n```bash\n# 1. Ask the device what's actually wrong — findings are ranked worst-first and\n#    each cites the measured value (error count, last-flap seconds, uptime).\nnetwork-aiops diagnose interface-health -t core-sw1\nnetwork-aiops diagnose bgp -t core-sw1\n\n# 2. If interface-health flags a link admin-up/oper-down with climbing errors and\n#    BGP shows the peer on that path recently reset, you have your root cause: a\n#    physical-layer fault (cable/optic) resetting the session — not routing.\n\n# 3. Confirm intended state, then remediate with the governed, audited path.\nnetwork-aiops device counters -t core-sw1\nnetwork-aiops config diff -t core-sw1 -f fix.cfg      # dry-run the change first\n```\n\nCreate `~/.network-aiops/config.yaml`:\n\n```yaml\ndevices:\n  - name: core-sw1            # used as -t core-sw1\n    driver: eos               # ios | nxos | nxos_ssh | iosxr | eos | junos\n    host: 10.0.0.1\n    username: admin\n    optional_args:            # passed verbatim to NAPALM (optional)\n      secret: enable-pw       # enable/secret\n      port: 443\n# Optional source-of-truth:\nnetbox:\n  url: https://netbox.example.com\n```\n\nSecrets are stored **encrypted** in `~/.network-aiops/secrets.enc` (Fernet/AES +\nscrypt-derived key; chmod 600) — never in config.yaml or a plaintext `.env`.\nDevice passwords are keyed by device name; the NetBox token uses the reserved\nname `netbox-token`:\n\n```bash\nnetwork-aiops init                     # interactive wizard (recommended)\nnetwork-aiops secret set core-sw1      # store a device password (hidden prompt)\nnetwork-aiops secret set netbox-token  # store the NetBox API token\nnetwork-aiops secret list              # names only — values are never printed\nnetwork-aiops secret migrate           # import a legacy plaintext .env, then delete it\n```\n\nExport `NETWORK_AIOPS_MASTER_PASSWORD` to unlock the store non-interactively (MCP\nserver / cron). Legacy plaintext env vars (`NETWORK_<TARGET_UPPER>_PASSWORD`,\n`NETWORK_NETBOX_TOKEN`) remain a deprecated fallback. An empty device password is\nallowed for key-based SSH auth.\n\n## MCP\n\n```jsonc\n{\n  \"command\": \"network-aiops\",\n  \"args\": [\"mcp\"],\n  \"env\": {\n    \"NETWORK_AIOPS_CONFIG\": \"~/.network-aiops/config.yaml\",\n    \"NETWORK_AIOPS_MASTER_PASSWORD\": \"…\"   // unlocks the encrypted secret store\n  }\n}\n```\n\n## Audit & Safety\n\n- Every tool call is logged to `~/.network-aiops/audit.db` (local SQLite;\n  relocate with `NETWORK_AIOPS_HOME`).\n- `config_merge` / `config_replace` capture the pre-change running config and\n  record an inverse `config_replace`-to-backup undo descriptor.\n- `config_replace` is `risk_level=high`; CLI destructive commands (`config\n  merge/replace/rollback`) require double confirmation and support `--dry-run`\n  (which prints the diff without committing).\n- All device text passes through `sanitize()` (output hygiene: control/format-char\n  stripping + truncation).\n- Device passwords and the NetBox token live only in the encrypted `secrets.enc`\n  (chmod 600); tools never return passwords, SNMP community strings, or hashes.\n\nSee `skills/network-aiops/SKILL.md` and `SECURITY.md` for details.\n\n## Companion Skills\n\n| If you want… | Use |\n|--------------|-----|\n| Network device config / facts (Cisco/Arista/Juniper) | **network-aiops** (this) |\n| Kubernetes cluster operations | a cluster ops skill |\n| Hypervisor VM lifecycle | a hypervisor ops skill |\n\n## Contributing & feature requests\n\nCoverage is intentionally focused. **Need a device or action\nthat isn't here yet?** Open an issue or pull request at\n[github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops/issues)\n— contributions, feature requests, and comments are all welcome.\n\n## License\n\nMIT — [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops)\n",
  "bytes": 11114,
  "sha": "80fafb1aafb26ff63edf5d1ade08449fd5447b5eb3ff47656e291ddfaeb787fb",
  "repo_slug": "aiops-tools/network-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_network_aiops_67e00b04/readme"
}