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

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

Or as an OpenClaw plugin, which installs this skill and its MCP server together:

openclaw plugins install clawhub:@zw008/network-aiops
openclaw skills info network-aiops          # expect: Visible to model: yes

Needs uvx on PATH: the MCP server is fetched with uv, pinned to this release.

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

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

Supported Actions

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

MCP Tools (33 — 28 read, 5 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 '<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 — feature requests, contributions, and comments are all welcome.

License

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