network-aiops-x

原始内容

---
name: network-aiops
slug: network-aiops
displayName: "Network AIops"
summary: "Governed network device ops (NAPALM) — 33 MCP tools with audit/undo."
license: MIT
homepage: https://github.com/AIops-tools/Network-AIops
tags: [aiops, mcp, governance, network]
description: >
  Use this skill whenever the user needs to operate a network device — read device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary and detail), ARP/MAC tables, VLANs, routes, hardware environment (fans/temp/power/CPU/mem), optics, NTP, users, SNMP info, VRFs, and an aggregated device-health summary; run read-only RCA diagnostics on interface health and BGP neighbors; back up a switch/router config, diff a candidate config (dry-run), and merge/replace/rollback config — across Cisco IOS/IOS-XE, Nexus NX-OS, IOS-XR, Arista EOS, and Juniper Junos via NAPALM. An optional NetBox block adds source-of-truth lookups.
  Always use this skill for "back up switch config", "show bgp neighbors", "diff network config", "push config to router", "show interfaces on the switch", or tasks mentioning "cisco", "arista", "juniper", "nexus", "ios-xr", or "napalm".
  Do NOT use when the target is not a NAPALM-supported network device (Kubernetes clusters, hypervisor VMs, and cloud consoles are out of scope — route those elsewhere).
  Common multi-vendor device operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers).
installer:
  kind: uv
  package: network-aiops
argument-hint: "[device name or describe your network task]"
allowed-tools:
  - Bash
metadata: {"openclaw":{"requires":{"env":["NETWORK_AIOPS_CONFIG"],"bins":["network-aiops"],"config":["~/.network-aiops/config.yaml"]},"optional":{"env":["NETWORK_AIOPS_HOME","NETWORK_AIOPS_MASTER_PASSWORD","NETWORK_NETBOX_TOKEN"]},"primaryEnv":"NETWORK_AIOPS_CONFIG","homepage":"https://github.com/AIops-tools/Network-AIops","emoji":"🛜","os":["macos","linux"]}}
compatibility: >
  Standalone, self-governed network device operations over NAPALM. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency.
  All write operations are audited to a local SQLite DB under ~/.network-aiops/ (relocatable via NETWORK_AIOPS_HOME).
  Credentials: device login passwords AND the optional NetBox API token live in an ENCRYPTED store at ~/.network-aiops/secrets.enc (Fernet/AES + scrypt-derived key; chmod 600), never in plaintext. Device passwords are keyed by the device name; the NetBox token uses the reserved name "netbox-token". Unlock with the NETWORK_AIOPS_MASTER_PASSWORD env var (for the MCP server / non-interactive use) or an interactive prompt. Run `network-aiops init` (wizard) or `network-aiops secret set <name>` to populate it, and `network-aiops secret migrate` to import a legacy plaintext .env (NETWORK_<TARGET_UPPER>_PASSWORD / NETWORK_NETBOX_TOKEN are still honoured as a deprecated fallback). config.yaml holds only device names, drivers, hosts, usernames, and NAPALM optional_args — never secrets. The state dir ~/.network-aiops should be chmod 700.
  Destructive operations (config merge, config replace, config rollback) require double confirmation at the CLI layer and support --dry-run (which prints the diff without committing). All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). config_merge and config_replace capture the pre-change running config and record an inverse config_replace-to-backup undo descriptor; config_rollback records none, and config_replace is risk_level=high.
  Webhooks: none — no outbound network calls beyond the configured device sessions and the optional NetBox API.
  TLS: NAPALM driver transports (eAPI/NX-API HTTPS, NETCONF/SSH) follow the device's own certificate/SSH host-key settings; the skill does not weaken them.
  Transitive dependencies: napalm (device drivers), pynetbox (optional source-of-truth), typer/rich (CLI), pyyaml/python-dotenv (config), and the MCP SDK. No post-install scripts or background services.
---

# Network AIops

> **Disclaimer**: This is a community-maintained open-source project and is **not affiliated with, endorsed by, or sponsored by Cisco, Arista, Juniper, NetBox Labs, or any network vendor.** Vendor and product names are trademarks of their respective owners. Source code is publicly auditable at [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops) under the MIT license.

Governed multi-vendor network device operations — **33 MCP tools**, every one wrapped with the bundled `@governed_tool` harness: a local unified audit log under `~/.network-aiops/`, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels. Devices are reached over NAPALM; an optional NetBox block adds source-of-truth lookups. Secrets (device passwords + NetBox token) are kept in an **encrypted store** (`secrets.enc`), unlocked by `NETWORK_AIOPS_MASTER_PASSWORD`.

> **Standalone**: the governance harness is bundled in the package (`network_aiops.governance`) — network-aiops has no external skill-family dependency. Coverage focuses on common operations and is not yet exhaustive.

## What This Skill Does

| Category | Tools | Count | Read or Write |
|----------|-------|:-----:|:-------------:|
| **Device facts** | facts, interfaces, interface counters, interface IPs, BGP (+detail), LLDP (+detail), ARP | 9 | 9 read |
| **Inventory** | MAC table, VLANs, route lookup | 3 | 3 read |
| **Platform / env** | environment, optics, NTP servers, NTP stats, users, SNMP info, VRFs, device_health | 8 | 8 read |
| **Diagnostics / RCA** | interface_health_rca, bgp_neighbor_rca | 2 | 2 read |
| **Config** | backup, diff (dry-run), merge, replace, rollback | 5 | 2 read / 3 write |
| **NetBox** | list devices, get device, device interfaces | 3 | 3 read |
| **Undo** | undo_list, undo_apply | 2 | 1 read / 1 write |

## Quick Install

```bash
uv tool install network-aiops
network-aiops init            # interactive wizard: device + driver + host + encrypted password (+ optional NetBox)
network-aiops doctor          # checks config, encrypted secret store, and per-device password presence
```

`init` writes `~/.network-aiops/config.yaml` and stores secrets **encrypted** in `~/.network-aiops/secrets.enc`. Export `NETWORK_AIOPS_MASTER_PASSWORD` in your shell profile so the CLI and MCP server can unlock secrets non-interactively.

## Supported Devices

| Platform | NAPALM driver | Transport |
|----------|---------------|-----------|
| Cisco IOS / IOS-XE | `ios` | SSH |
| Cisco Nexus NX-OS | `nxos` (NX-API) / `nxos_ssh` (SSH) | HTTPS / SSH |
| Cisco IOS-XR | `iosxr` | SSH (XML agent) |
| Arista EOS | `eos` | eAPI (HTTPS) |
| Juniper Junos | `junos` | NETCONF (SSH) |

Other platforms (Nokia SR OS / SR Linux, Huawei VRP, etc.) are reachable via NAPALM **community drivers** but are **not officially tested here** — see [Contributing](#contributing--request-a-device-or-feature).

## When to Use This Skill

- Inspect device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary + detail), ARP/MAC tables, VLANs, and route lookups
- Check hardware health: environment (fans/temp/power/CPU/mem), optics, NTP, users, SNMP info, VRFs, or a one-shot `device_health` summary
- Root-cause a problem with read-only RCA: `interface_health_rca` (down/erroring/discarding/flapping ports) and `bgp_neighbor_rca` (down/shut/recently-reset/route-less peers) — each finding cites the measured number that tripped it, worst-first
- Back up a switch/router running config to a file
- Dry-run a config change as a diff before committing
- Merge a config snippet, replace the full config, or roll back the last commit
- Cross-check intended state in NetBox before pushing a change

**Do NOT use when** the target is not a NAPALM-supported network device (Kubernetes clusters, hypervisor VMs, and cloud-provider consoles are out of scope for this skill).

## Related Skills — Skill Routing

| If the user wants… | Use |
|--------------------|-----|
| Network device config / facts (Cisco/Arista/Juniper) | **network-aiops** (this skill) |
| Kubernetes cluster operations | a cluster ops skill |
| Hypervisor VM lifecycle (power, snapshot, migrate) | a hypervisor ops skill |

## Supported Actions

| Tool | R/W | Risk | Driver support |
|------|:---:|:----:|----------------|
| `device_facts` | R | low | all 5 |
| `get_interfaces` | R | low | all 5 |
| `get_interfaces_counters` | R | low | all 5 |
| `get_interfaces_ip` | R | low | all 5 |
| `get_bgp_neighbors` | R | low | all 5 (varies by feature) |
| `get_bgp_neighbors_detail` | R | low | ios/eos/junos/iosxr; nxos varies |
| `get_lldp_neighbors` | R | low | all 5 |
| `get_lldp_neighbors_detail` | R | low | all 5 |
| `get_arp_table` | R | low | all 5 |
| `get_mac_address_table` | R | low | all 5 (varies by image) |
| `get_vlans` | R | low | eos/junos/nxos; ios varies |
| `get_route_to` | R | low | all 5 (varies by feature) |
| `get_environment` | R | low | all 5 (sensor coverage varies) |
| `get_optics` | R | low | eos/junos/iosxr; ios/nxos varies |
| `get_ntp_servers` | R | low | all 5 |
| `get_ntp_stats` | R | low | all 5 |
| `get_users` | R | low | all 5 (password hashes redacted) |
| `get_snmp_information` | R | low | all 5 (community strings redacted) |
| `get_network_instances` | R | low | eos/junos/iosxr; ios/nxos varies |
| `device_health` | R | low | all 5 (environment section optional) |
| `interface_health_rca` | R | low | all 5 (needs get_interfaces + counters) |
| `bgp_neighbor_rca` | R | low | all 5 (varies by BGP feature) |
| `config_backup` | R | low | all 5 |
| `config_diff` (dry-run) | R | low | all 5 |
| `config_merge` | W | medium | all 5 |
| `config_replace` | W | **high** | ios/eos/junos/iosxr; nxos varies |
| `config_rollback` | W | medium | device-dependent rollback depth |
| `netbox_list_devices` | R | low | NetBox (optional) |
| `netbox_get_device` | R | low | NetBox (optional) |
| `netbox_device_interfaces` | R | low | NetBox (optional) |

**Per-driver caveat**: NAPALM does not implement every getter on every platform. Any unsupported getter returns a teaching error ("not supported by the `<driver>` driver") instead of crashing — try a different getter or fall back to `config_backup`. `device_health` is resilient: if a driver lacks `get_environment` that section is reported as a note, not a failure.

**Credentials**: `get_users` reduces password hashes to a boolean and `get_snmp_information` reduces community strings to a count — those two never return secrets at all. `config_backup` and every returned `diff` *mask* credential values (password/secret hashes, SNMP communities, pre-shared keys, RADIUS/TACACS and keychain keys) and report how many lines they changed in a `redaction` block; `include_secrets=True` returns the verbatim text. The masking is pattern-based across five vendor syntaxes, so it reduces exposure rather than guaranteeing none remains — notably it cannot see multi-line PKI key blocks. To hand a real config to a human, prefer the CLI's `-o <path>`, which writes raw to a file instead of into this transcript.

## Common Workflows

### Safely change a device config with a dry-run first

1. `network-aiops config backup -t core-sw1 -o core-sw1.cfg` → keep a known-good copy
2. `network-aiops config diff change.cfg -t core-sw1` → preview the diff (nothing committed)
3. `network-aiops config merge change.cfg -t core-sw1` (double confirm) → commits **under a 300s device-side revert timer**; the harness also records a `config_replace`-to-backup undo descriptor
4. `network-aiops device interfaces -t core-sw1` → verify the result **and that you can still reach the device**
5. `network-aiops config confirm -t core-sw1` → cancels the revert timer, making the change permanent. If you skip this (or get locked out), the device reverts by itself — that is the point
6. **Failure branch**: if the connection fails (`Could not connect/authenticate`), run `network-aiops doctor` — it shows whether `NETWORK_CORE_SW1_PASSWORD` is set and whether the host/port is reachable; the skill never retries a denied auth.

### Change something that could lock you out (mgmt interface, VTY ACL, AAA)

1. `network-aiops config backup -t core-sw1 -o core-sw1.cfg` → an off-box copy, independent of the tool
2. `network-aiops config diff risky.cfg -t core-sw1` → confirm the diff touches only what you intend
3. `network-aiops config merge risky.cfg -t core-sw1 --revert-in 120` → short timer: if the change severs your session, the device restores itself in 2 minutes with nobody logged in
4. Re-connect and verify. **Do not confirm from a session opened before the commit** — it may survive a change that blocks *new* logins
5. `network-aiops config confirm -t core-sw1` → only once a NEW session proves the path still works
6. **Failure branch**: if the result carries `commit.warning` with `safetyNet: "undo-only"`, this driver could not arm a timer. The change is permanent on landing and the recorded undo needs a working session — arrange out-of-band access (console/OOB mgmt) before you commit anything of this kind.

### Root-cause a flaky uplink / peering problem (RCA-first)

1. `network-aiops diagnose interface-health -t edge-rtr` → worst-first interface findings; a link that is admin-up/oper-down with climbing `rx_errors+tx_errors` and a recent `last_flapped` is a physical-layer fault (cable/optic), each cited with its measured value
2. `network-aiops diagnose bgp -t edge-rtr` → worst-first neighbor findings; if the peer riding that link shows `BGP session down` or `recently reset` (low uptime), the L1 fault — not routing — is resetting the session
3. `network-aiops device counters -t edge-rtr` → confirm the error counters are still climbing before you touch anything
4. `network-aiops config diff fix.cfg -t edge-rtr` → dry-run the remediation first, then `config merge` (double confirm) through the audited path
5. **Failure branch**: if `interface_health_rca` / `bgp_neighbor_rca` returns "not supported by the `<driver>` driver", the platform's NAPALM driver lacks the underlying getter — fall back to `device facts` / `config_backup` and request the getter via a GitHub issue.

## Usage Mode

| Scenario | Recommended | Why |
|----------|:-----------:|-----|
| Local/small models | **CLI** | fewer tokens than MCP |
| Cloud models (Claude, GPT) | Either | MCP gives structured JSON I/O |
| Automated pipelines | **MCP** | type-safe parameters, audited |

## MCP Tools (33 — 28 read, 5 write)

| Category | Tools | R/W |
|----------|-------|:---:|
| Facts | `device_facts`, `get_interfaces`, `get_interfaces_counters`, `get_interfaces_ip`, `get_bgp_neighbors`, `get_bgp_neighbors_detail`, `get_lldp_neighbors`, `get_lldp_neighbors_detail`, `get_arp_table` | Read |
| Inventory | `get_mac_address_table`, `get_vlans`, `get_route_to` | Read |
| Platform / env | `get_environment`, `get_optics`, `get_ntp_servers`, `get_ntp_stats`, `get_users`, `get_snmp_information`, `get_network_instances`, `device_health` | Read |
| Diagnostics / RCA | `interface_health_rca`, `bgp_neighbor_rca` | Read |
| Config | `config_backup`, `config_diff` | Read |
| | `config_merge`, `config_replace`, `confirm_commit`, `config_rollback` | Write |
| NetBox | `netbox_list_devices`, `netbox_get_device`, `netbox_device_interfaces` | Read |
| Undo | `undo_list` | Read |
| | `undo_apply` | Write |

**Commit-confirm is the primary safety net.** `config_merge` and `config_replace` commit with a device-side revert timer (`revert_in`, default 300s): the device rolls the change back on its own unless `confirm_commit` follows. This is the only guard that survives the change severing your own management path — a commit that shuts the management interface, tightens the VTY ACL or breaks AAA also kills the session the recorded undo would need, so the *device* has to be the one enforcing the rollback. Workflow: **commit with timer → verify you can still reach the device → `confirm_commit`** (or do nothing and let it revert). Drivers that cannot arm a timer fall back to a plain commit and say so in `commit.warning` / `commit.safetyNet` — check that field, because for those devices the net is absent.

**Harness features that light up**: `config_merge` and `config_replace` capture the pre-change running config and pass an `undo=` lambda so the harness records an inverse descriptor (with `_undo_id`) that restores the captured config via `config_replace` — the device must support config replace for the undo to apply. The raw config is handed to the harness out-of-band and kept only in `undo.db` (0600); the tool result returns a **digest** (size + SHA-256), never the config body, because a running config carries credential hashes, SNMP communities and PSKs that would otherwise land in the agent transcript. `config_rollback` declares no undo; `config_replace` is tagged `risk_level=high`. `config_diff` is a pure dry-run (stage candidate → compare → discard). The two RCA tools (`interface_health_rca`, `bgp_neighbor_rca`) are pure read-only analyses (`risk_level=low`) that collect getter output and rank findings worst-first. All 33 tools are audit-logged under `~/.network-aiops/` and pass through the budget/runaway guard, with a descriptive risk tier tagged on each audit row. Avoid tight poll loops — the runaway breaker backs this up.

## Encrypted secret store

Secrets never touch disk in plaintext. They live in `~/.network-aiops/secrets.enc` (Fernet/AES-128 + HMAC, key derived from a master password via scrypt; file chmod 600). Both kinds of secret share the one store: per-device login passwords keyed by device name, and the single NetBox API token keyed by the reserved name `netbox-token`.

```bash
network-aiops init                       # wizard: collects devices + passwords (encrypted), optional NetBox
network-aiops secret set core-sw1        # store/replace a device password (hidden prompt)
network-aiops secret set netbox-token    # store the NetBox API token
network-aiops secret list                # names only — values are NEVER printed
network-aiops secret rm core-sw1
network-aiops secret migrate             # import a legacy plaintext .env (renamed to .env.migrated)
network-aiops secret rotate-password     # re-encrypt the whole store under a new master password
```

Unlock non-interactively by exporting `NETWORK_AIOPS_MASTER_PASSWORD` (used by the MCP server / cron / CI). Legacy plaintext env vars (`NETWORK_<TARGET_UPPER>_PASSWORD`, `NETWORK_NETBOX_TOKEN`) are still honoured as a deprecated fallback with a warning. An empty device password is allowed (valid for key-based SSH auth via `optional_args`).

## CLI Quick Reference

```bash
network-aiops init                                               # onboarding wizard (encrypted secrets)
network-aiops device facts [-t <device>]
network-aiops device interfaces [-t <device>]
network-aiops device counters [-t <device>]
network-aiops device bgp [-t <device>]
network-aiops device lldp [-t <device>]
network-aiops device arp [-t <device>]
network-aiops device mac [-t <device>]
network-aiops device vlans [-t <device>]
network-aiops device route <prefix> [-t <device>] [--protocol bgp]
network-aiops device environment [-t <device>]
network-aiops device health [-t <device>]
network-aiops diagnose interface-health [-t <device>]           # interface RCA (worst-first)
network-aiops diagnose bgp [-t <device>]                        # BGP-neighbor RCA (worst-first)
network-aiops config backup [-t <device>] [-o <file>]
network-aiops config diff <file> [-t <device>] [--replace]
network-aiops config merge <file> [-t <device>] [--dry-run]      # double confirm
network-aiops config replace <file> [-t <device>] [--dry-run]    # HIGH RISK
network-aiops config rollback [-t <device>] [--dry-run]          # double confirm
network-aiops netbox list [--name <q>] [--limit N]
network-aiops netbox get <name>
network-aiops netbox interfaces <device> [--limit N]
network-aiops secret set|list|rm|migrate|rotate-password
network-aiops doctor
network-aiops mcp                                                # start MCP server (stdio)
```

See `references/cli-reference.md` for the full command list.

## Troubleshooting

### "Could not connect/authenticate to '<device>'"
The host/port, username, or password is wrong, or the device is unreachable. Run `network-aiops doctor` — it reports whether the encrypted secret store is present, whether a password is stored for the device, and whether the device answers. Store/replace the password with `network-aiops secret set <device>` (or re-run `network-aiops init`). For enable/secret, set it in `optional_args.secret`.

### "Master password not set" / cannot unlock secrets
The encrypted store needs the master password. Export `NETWORK_AIOPS_MASTER_PASSWORD` for non-interactive use (MCP server / cron), or run a CLI command on a TTY to be prompted. If you forgot it, delete `~/.network-aiops/secrets.enc` and re-run `network-aiops init`.

### "Operation not supported by the '<driver>' NAPALM driver"
That getter or config mode is not implemented for this platform. Try a different getter, or fall back to `config_backup` and inspect the relevant stanza. Request the capability via a GitHub issue/PR.

### "Driver '<x>' is not in the officially supported set"
Only `ios`, `nxos`, `nxos_ssh`, `iosxr`, `eos`, `junos` are tested here. Community drivers may work but are untested — request official support via a GitHub issue/PR.

### NetBox commands fail with "NetBox is not configured"
Add a `netbox: {url: ...}` block to `config.yaml` and store the API token encrypted with `network-aiops secret set netbox-token` (or run `network-aiops init`). NetBox tools degrade gracefully when unconfigured.

### `config replace` failed mid-commit
The device may not support full config replace (some Nexus images do not). Use `config merge` for additive changes, or restore from your `config backup` file.

## Audit & Safety

The skill delivers reads and writes and records them; it does **not** decide whether a write is permitted. That is your agent's judgement, or the permission of the account you connect it with (log in with a device account at a read-only privilege level, and give NetBox a read-only API token — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

- **Audit is the guarantee, and it is not bypassable.** Every operation — MCP and CLI alike — is logged to `~/.network-aiops/audit.db` (relocatable via `NETWORK_AIOPS_HOME`): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
- `NETWORK_AUDIT_APPROVED_BY` / `NETWORK_AUDIT_RATIONALE` are optional annotations recorded on the audit row (who/why); they are never required and never block.
- **Runaway guard** — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with `NETWORK_RUNAWAY_MAX=0`.
- Undo store records inverse descriptors for reversible writes (config merge/replace → restore captured running config).
- Writes support `--dry-run` / `dry_run=True` and double confirmation at the CLI.

The harness is bundled in the package — no external dependency, no manual setup. See `references/setup-guide.md` for security details.

Driving these tools with a smaller / local model? See `references/agent-guardrails.md` — which guardrails the harness now enforces for you, a ready-to-paste system prompt, and the network-specific traps (config merge vs replace, per-vendor interface naming, NetBox intent vs live device state).

## Contributing — request a device or feature

Coverage is intentionally focused. **Need a device (Nokia SR OS, Huawei VRP, …) or an action that isn't here yet?** Open an issue or pull request at [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops/issues) — feature requests, contributions, and comments are all welcome.

## License

MIT — [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops)

name: network-aiops slug: network-aiops displayName: "Network AIops" summary: "Governed network device ops (NAPALM) — 33 MCP tools with audit/undo." license: MIT homepage: https://github.com/AIops-tools/Network-AIops tags: [aiops, mcp, governance, network] description: > Use this skill whenever the user needs to operate a network device — read device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary and detail), ARP/MAC tables, VLANs, routes, hardware environment (fans/temp/power/CPU/mem), optics, NTP, users, SNMP info, VRFs, and an aggregated device-health summary; run read-only RCA diagnostics on interface health and BGP neighbors; back up a switch/router config, diff a candidate config (dry-run), and merge/replace/rollback config — across Cisco IOS/IOS-XE, Nexus NX-OS, IOS-XR, Arista EOS, and Juniper Junos via NAPALM. An optional NetBox block adds source-of-truth lookups. Always use this skill for "back up switch config", "show bgp neighbors", "diff network config", "push config to router", "show interfaces on the switch", or tasks mentioning "cisco", "arista", "juniper", "nexus", "ios-xr", or "napalm". Do NOT use when the target is not a NAPALM-supported network device (Kubernetes clusters, hypervisor VMs, and cloud consoles are out of scope — route those elsewhere). Common multi-vendor device operations with a built-in governance harness (audit, policy, token budget, undo, risk-tiers). installer: kind: uv package: network-aiops argument-hint: "[device name or describe your network task]" allowed-tools:

Bash metadata: {"openclaw":{"requires":{"env":["NETWORK_AIOPS_CONFIG"],"bins":["network-aiops"],"config":["~/.network-aiops/config.yaml"]},"optional":{"env":["NETWORK_AIOPS_HOME","NETWORK_AIOPS_MASTER_PASSWORD","NETWORK_NETBOX_TOKEN"]},"primaryEnv":"NETWORK_AIOPS_CONFIG","homepage":"https://github.com/AIops-tools/Network-AIops","emoji":"🛜","os":["macos","linux"]}} compatibility: > Standalone, self-governed network device operations over NAPALM. The governance harness (audit, policy, token/runaway budget, undo, risk-tiers) is bundled in the package — no external skill-family dependency. All write operations are audited to a local SQLite DB under ~/.network-aiops/ (relocatable via NETWORK_AIOPS_HOME). Credentials: device login passwords AND the optional NetBox API token live in an ENCRYPTED store at ~/.network-aiops/secrets.enc (Fernet/AES + scrypt-derived key; chmod 600), never in plaintext. Device passwords are keyed by the device name; the NetBox token uses the reserved name "netbox-token". Unlock with the NETWORK_AIOPS_MASTER_PASSWORD env var (for the MCP server / non-interactive use) or an interactive prompt. Run network-aiops init (wizard) or network-aiops secret set <name> to populate it, and network-aiops secret migrate to import a legacy plaintext .env (NETWORK__PASSWORD / NETWORK_NETBOX_TOKEN are still honoured as a deprecated fallback). config.yaml holds only device names, drivers, hosts, usernames, and NAPALM optional_args — never secrets. The state dir ~/.network-aiops should be chmod 700. Destructive operations (config merge, config replace, config rollback) require double confirmation at the CLI layer and support --dry-run (which prints the diff without committing). All write tools pass through the @governed_tool decorator (budget guard + audit + risk-tier tagging). config_merge and config_replace capture the pre-change running config and record an inverse config_replace-to-backup undo descriptor; config_rollback records none, and config_replace is risk_level=high. Webhooks: none — no outbound network calls beyond the configured device sessions and the optional NetBox API. TLS: NAPALM driver transports (eAPI/NX-API HTTPS, NETCONF/SSH) follow the device's own certificate/SSH host-key settings; the skill does not weaken them. Transitive dependencies: napalm (device drivers), pynetbox (optional source-of-truth), typer/rich (CLI), pyyaml/python-dotenv (config), and the MCP SDK. No post-install scripts or background services.

Network AIops

Disclaimer: This is a community-maintained open-source project and is not affiliated with, endorsed by, or sponsored by Cisco, Arista, Juniper, NetBox Labs, or any network vendor. Vendor and product names are trademarks of their respective owners. Source code is publicly auditable at github.com/AIops-tools/Network-AIops under the MIT license.

Governed multi-vendor network device operations — 33 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.network-aiops/, token/runaway budget guard, undo-token recording, and descriptive risk-tier labels. Devices are reached over NAPALM; an optional NetBox block adds source-of-truth lookups. Secrets (device passwords + NetBox token) are kept in an encrypted store (secrets.enc), unlocked by NETWORK_AIOPS_MASTER_PASSWORD.

Standalone: the governance harness is bundled in the package (network_aiops.governance) — network-aiops has no external skill-family dependency. Coverage focuses on common operations and is not yet exhaustive.

What This Skill Does

Category	Tools	Count	Read or Write
Device facts	facts, interfaces, interface counters, interface IPs, BGP (+detail), LLDP (+detail), ARP	9	9 read
Inventory	MAC table, VLANs, route lookup	3	3 read
Platform / env	environment, optics, NTP servers, NTP stats, users, SNMP info, VRFs, device_health	8	8 read
Diagnostics / RCA	interface_health_rca, bgp_neighbor_rca	2	2 read
Config	backup, diff (dry-run), merge, replace, rollback	5	2 read / 3 write
NetBox	list devices, get device, device interfaces	3	3 read
Undo	undo_list, undo_apply	2	1 read / 1 write

Quick Install

uv tool install network-aiops
network-aiops init            # interactive wizard: device + driver + host + encrypted password (+ optional NetBox)
network-aiops doctor          # checks config, encrypted secret store, and per-device password presence

init writes ~/.network-aiops/config.yaml and stores secrets encrypted in ~/.network-aiops/secrets.enc. Export NETWORK_AIOPS_MASTER_PASSWORD in your shell profile so the CLI and MCP server can unlock secrets non-interactively.

Supported Devices

Platform	NAPALM driver	Transport
Cisco IOS / IOS-XE	`ios`	SSH
Cisco Nexus NX-OS	`nxos` (NX-API) / `nxos_ssh` (SSH)	HTTPS / SSH
Cisco IOS-XR	`iosxr`	SSH (XML agent)
Arista EOS	`eos`	eAPI (HTTPS)
Juniper Junos	`junos`	NETCONF (SSH)

Other platforms (Nokia SR OS / SR Linux, Huawei VRP, etc.) are reachable via NAPALM community drivers but are not officially tested here — see Contributing.

When to Use This Skill

Inspect device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary + detail), ARP/MAC tables, VLANs, and route lookups
Check hardware health: environment (fans/temp/power/CPU/mem), optics, NTP, users, SNMP info, VRFs, or a one-shot device_health summary
Root-cause a problem with read-only RCA: interface_health_rca (down/erroring/discarding/flapping ports) and bgp_neighbor_rca (down/shut/recently-reset/route-less peers) — each finding cites the measured number that tripped it, worst-first
Back up a switch/router running config to a file
Dry-run a config change as a diff before committing
Merge a config snippet, replace the full config, or roll back the last commit
Cross-check intended state in NetBox before pushing a change

Do NOT use when the target is not a NAPALM-supported network device (Kubernetes clusters, hypervisor VMs, and cloud-provider consoles are out of scope for this skill).

Related Skills — Skill Routing

If the user wants…	Use
Network device config / facts (Cisco/Arista/Juniper)	network-aiops (this skill)
Kubernetes cluster operations	a cluster ops skill
Hypervisor VM lifecycle (power, snapshot, migrate)	a hypervisor ops skill

Supported Actions

Tool	R/W	Risk	Driver support
`device_facts`	R	low	all 5
`get_interfaces`	R	low	all 5
`get_interfaces_counters`	R	low	all 5
`get_interfaces_ip`	R	low	all 5
`get_bgp_neighbors`	R	low	all 5 (varies by feature)
`get_bgp_neighbors_detail`	R	low	ios/eos/junos/iosxr; nxos varies
`get_lldp_neighbors`	R	low	all 5
`get_lldp_neighbors_detail`	R	low	all 5
`get_arp_table`	R	low	all 5
`get_mac_address_table`	R	low	all 5 (varies by image)
`get_vlans`	R	low	eos/junos/nxos; ios varies
`get_route_to`	R	low	all 5 (varies by feature)
`get_environment`	R	low	all 5 (sensor coverage varies)
`get_optics`	R	low	eos/junos/iosxr; ios/nxos varies
`get_ntp_servers`	R	low	all 5
`get_ntp_stats`	R	low	all 5
`get_users`	R	low	all 5 (password hashes redacted)
`get_snmp_information`	R	low	all 5 (community strings redacted)
`get_network_instances`	R	low	eos/junos/iosxr; ios/nxos varies
`device_health`	R	low	all 5 (environment section optional)
`interface_health_rca`	R	low	all 5 (needs get_interfaces + counters)
`bgp_neighbor_rca`	R	low	all 5 (varies by BGP feature)
`config_backup`	R	low	all 5
`config_diff` (dry-run)	R	low	all 5
`config_merge`	W	medium	all 5
`config_replace`	W	high	ios/eos/junos/iosxr; nxos varies
`config_rollback`	W	medium	device-dependent rollback depth
`netbox_list_devices`	R	low	NetBox (optional)
`netbox_get_device`	R	low	NetBox (optional)
`netbox_device_interfaces`	R	low	NetBox (optional)

Per-driver caveat: NAPALM does not implement every getter on every platform. Any unsupported getter returns a teaching error ("not supported by the <driver> driver") instead of crashing — try a different getter or fall back to config_backup. device_health is resilient: if a driver lacks get_environment that section is reported as a note, not a failure.

Credentials: get_users reduces password hashes to a boolean and get_snmp_information reduces community strings to a count — those two never return secrets at all. config_backup and every returned diff mask credential values (password/secret hashes, SNMP communities, pre-shared keys, RADIUS/TACACS and keychain keys) and report how many lines they changed in a redaction block; include_secrets=True returns the verbatim text. The masking is pattern-based across five vendor syntaxes, so it reduces exposure rather than guaranteeing none remains — notably it cannot see multi-line PKI key blocks. To hand a real config to a human, prefer the CLI's -o <path>, which writes raw to a file instead of into this transcript.

Common Workflows

Safely change a device config with a dry-run first

network-aiops config backup -t core-sw1 -o core-sw1.cfg → keep a known-good copy
network-aiops config diff change.cfg -t core-sw1 → preview the diff (nothing committed)
network-aiops config merge change.cfg -t core-sw1 (double confirm) → commits under a 300s device-side revert timer; the harness also records a config_replace-to-backup undo descriptor
network-aiops device interfaces -t core-sw1 → verify the result and that you can still reach the device
network-aiops config confirm -t core-sw1 → cancels the revert timer, making the change permanent. If you skip this (or get locked out), the device reverts by itself — that is the point
Failure branch: if the connection fails (Could not connect/authenticate), run network-aiops doctor — it shows whether NETWORK_CORE_SW1_PASSWORD is set and whether the host/port is reachable; the skill never retries a denied auth.

Change something that could lock you out (mgmt interface, VTY ACL, AAA)

network-aiops config backup -t core-sw1 -o core-sw1.cfg → an off-box copy, independent of the tool
network-aiops config diff risky.cfg -t core-sw1 → confirm the diff touches only what you intend
network-aiops config merge risky.cfg -t core-sw1 --revert-in 120 → short timer: if the change severs your session, the device restores itself in 2 minutes with nobody logged in
Re-connect and verify. Do not confirm from a session opened before the commit — it may survive a change that blocks new logins
network-aiops config confirm -t core-sw1 → only once a NEW session proves the path still works
Failure branch: if the result carries commit.warning with safetyNet: "undo-only", this driver could not arm a timer. The change is permanent on landing and the recorded undo needs a working session — arrange out-of-band access (console/OOB mgmt) before you commit anything of this kind.

Root-cause a flaky uplink / peering problem (RCA-first)

network-aiops diagnose interface-health -t edge-rtr → worst-first interface findings; a link that is admin-up/oper-down with climbing rx_errors+tx_errors and a recent last_flapped is a physical-layer fault (cable/optic), each cited with its measured value
network-aiops diagnose bgp -t edge-rtr → worst-first neighbor findings; if the peer riding that link shows BGP session down or recently reset (low uptime), the L1 fault — not routing — is resetting the session
network-aiops device counters -t edge-rtr → confirm the error counters are still climbing before you touch anything
network-aiops config diff fix.cfg -t edge-rtr → dry-run the remediation first, then config merge (double confirm) through the audited path
Failure branch: if interface_health_rca / bgp_neighbor_rca returns "not supported by the <driver> driver", the platform's NAPALM driver lacks the underlying getter — fall back to device facts / config_backup and request the getter via a GitHub issue.

Usage Mode

Scenario	Recommended	Why
Local/small models	CLI	fewer tokens than MCP
Cloud models (Claude, GPT)	Either	MCP gives structured JSON I/O
Automated pipelines	MCP	type-safe parameters, audited

MCP Tools (33 — 28 read, 5 write)

Category	Tools	R/W
Facts	`device_facts`, `get_interfaces`, `get_interfaces_counters`, `get_interfaces_ip`, `get_bgp_neighbors`, `get_bgp_neighbors_detail`, `get_lldp_neighbors`, `get_lldp_neighbors_detail`, `get_arp_table`	Read
Inventory	`get_mac_address_table`, `get_vlans`, `get_route_to`	Read
Platform / env	`get_environment`, `get_optics`, `get_ntp_servers`, `get_ntp_stats`, `get_users`, `get_snmp_information`, `get_network_instances`, `device_health`	Read
Diagnostics / RCA	`interface_health_rca`, `bgp_neighbor_rca`	Read
Config	`config_backup`, `config_diff`	Read
	`config_merge`, `config_replace`, `confirm_commit`, `config_rollback`	Write
NetBox	`netbox_list_devices`, `netbox_get_device`, `netbox_device_interfaces`	Read
Undo	`undo_list`	Read
	`undo_apply`	Write

Commit-confirm is the primary safety net. config_merge and config_replace commit with a device-side revert timer (revert_in, default 300s): the device rolls the change back on its own unless confirm_commit follows. This is the only guard that survives the change severing your own management path — a commit that shuts the management interface, tightens the VTY ACL or breaks AAA also kills the session the recorded undo would need, so the device has to be the one enforcing the rollback. Workflow: commit with timer → verify you can still reach the device → confirm_commit (or do nothing and let it revert). Drivers that cannot arm a timer fall back to a plain commit and say so in commit.warning / commit.safetyNet — check that field, because for those devices the net is absent.

Harness features that light up: config_merge and config_replace capture the pre-change running config and pass an undo= lambda so the harness records an inverse descriptor (with _undo_id) that restores the captured config via config_replace — the device must support config replace for the undo to apply. The raw config is handed to the harness out-of-band and kept only in undo.db (0600); the tool result returns a digest (size + SHA-256), never the config body, because a running config carries credential hashes, SNMP communities and PSKs that would otherwise land in the agent transcript. config_rollback declares no undo; config_replace is tagged risk_level=high. config_diff is a pure dry-run (stage candidate → compare → discard). The two RCA tools (interface_health_rca, bgp_neighbor_rca) are pure read-only analyses (risk_level=low) that collect getter output and rank findings worst-first. All 33 tools are audit-logged under ~/.network-aiops/ and pass through the budget/runaway guard, with a descriptive risk tier tagged on each audit row. Avoid tight poll loops — the runaway breaker backs this up.

Encrypted secret store

Secrets never touch disk in plaintext. They live in ~/.network-aiops/secrets.enc (Fernet/AES-128 + HMAC, key derived from a master password via scrypt; file chmod 600). Both kinds of secret share the one store: per-device login passwords keyed by device name, and the single NetBox API token keyed by the reserved name netbox-token.

network-aiops init                       # wizard: collects devices + passwords (encrypted), optional NetBox
network-aiops secret set core-sw1        # store/replace a device password (hidden prompt)
network-aiops secret set netbox-token    # store the NetBox API token
network-aiops secret list                # names only — values are NEVER printed
network-aiops secret rm core-sw1
network-aiops secret migrate             # import a legacy plaintext .env (renamed to .env.migrated)
network-aiops secret rotate-password     # re-encrypt the whole store under a new master password

Unlock non-interactively by exporting NETWORK_AIOPS_MASTER_PASSWORD (used by the MCP server / cron / CI). Legacy plaintext env vars (NETWORK_<TARGET_UPPER>_PASSWORD, NETWORK_NETBOX_TOKEN) are still honoured as a deprecated fallback with a warning. An empty device password is allowed (valid for key-based SSH auth via optional_args).

CLI Quick Reference

network-aiops init                                               # onboarding wizard (encrypted secrets)
network-aiops device facts [-t <device>]
network-aiops device interfaces [-t <device>]
network-aiops device counters [-t <device>]
network-aiops device bgp [-t <device>]
network-aiops device lldp [-t <device>]
network-aiops device arp [-t <device>]
network-aiops device mac [-t <device>]
network-aiops device vlans [-t <device>]
network-aiops device route <prefix> [-t <device>] [--protocol bgp]
network-aiops device environment [-t <device>]
network-aiops device health [-t <device>]
network-aiops diagnose interface-health [-t <device>]           # interface RCA (worst-first)
network-aiops diagnose bgp [-t <device>]                        # BGP-neighbor RCA (worst-first)
network-aiops config backup [-t <device>] [-o <file>]
network-aiops config diff <file> [-t <device>] [--replace]
network-aiops config merge <file> [-t <device>] [--dry-run]      # double confirm
network-aiops config replace <file> [-t <device>] [--dry-run]    # HIGH RISK
network-aiops config rollback [-t <device>] [--dry-run]          # double confirm
network-aiops netbox list [--name <q>] [--limit N]
network-aiops netbox get <name>
network-aiops netbox interfaces <device> [--limit N]
network-aiops secret set|list|rm|migrate|rotate-password
network-aiops doctor
network-aiops mcp                                                # start MCP server (stdio)

See references/cli-reference.md for the full command list.

Troubleshooting

"Could not connect/authenticate to ''"

The host/port, username, or password is wrong, or the device is unreachable. Run network-aiops doctor — it reports whether the encrypted secret store is present, whether a password is stored for the device, and whether the device answers. Store/replace the password with network-aiops secret set <device> (or re-run network-aiops init). For enable/secret, set it in optional_args.secret.

"Master password not set" / cannot unlock secrets

The encrypted store needs the master password. Export NETWORK_AIOPS_MASTER_PASSWORD for non-interactive use (MCP server / cron), or run a CLI command on a TTY to be prompted. If you forgot it, delete ~/.network-aiops/secrets.enc and re-run network-aiops init.

"Operation not supported by the '' NAPALM driver"

That getter or config mode is not implemented for this platform. Try a different getter, or fall back to config_backup and inspect the relevant stanza. Request the capability via a GitHub issue/PR.

"Driver '' is not in the officially supported set"

Only ios, nxos, nxos_ssh, iosxr, eos, junos are tested here. Community drivers may work but are untested — request official support via a GitHub issue/PR.

NetBox commands fail with "NetBox is not configured"

Add a netbox: {url: ...} block to config.yaml and store the API token encrypted with network-aiops secret set netbox-token (or run network-aiops init). NetBox tools degrade gracefully when unconfigured.

`config replace` failed mid-commit

The device may not support full config replace (some Nexus images do not). Use config merge for additive changes, or restore from your config backup file.

Audit & Safety

The skill delivers reads and writes and records them; it does not decide whether a write is permitted. That is your agent's judgement, or the permission of the account you connect it with (log in with a device account at a read-only privilege level, and give NetBox a read-only API token — writes then fail at the server). There is no read-only switch, policy file, or approval gate.

Audit is the guarantee, and it is not bypassable. Every operation — MCP and CLI alike — is logged to ~/.network-aiops/audit.db (relocatable via NETWORK_AIOPS_HOME): params, result, status, duration, and the risk tier. The CLI writes the same row the MCP path does.
NETWORK_AUDIT_APPROVED_BY / NETWORK_AUDIT_RATIONALE are optional annotations recorded on the audit row (who/why); they are never required and never block.
Runaway guard — a safety backstop, not authorization: the same call looped in a tight window trips a circuit breaker. Disable with NETWORK_RUNAWAY_MAX=0.
Undo store records inverse descriptors for reversible writes (config merge/replace → restore captured running config).
Writes support --dry-run / dry_run=True and double confirmation at the CLI.

The harness is bundled in the package — no external dependency, no manual setup. See references/setup-guide.md for security details.

Driving these tools with a smaller / local model? See references/agent-guardrails.md — which guardrails the harness now enforces for you, a ready-to-paste system prompt, and the network-specific traps (config merge vs replace, per-vendor interface naming, NetBox intent vs live device state).

Contributing — request a device or feature

Coverage is intentionally focused. Need a device (Nokia SR OS, Huawei VRP, …) or an action that isn't here yet? Open an issue or pull request at github.com/AIops-tools/Network-AIops — feature requests, contributions, and comments are all welcome.

License

MIT — github.com/AIops-tools/Network-AIops