network-aiops (preview)

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 for AI agents — 28 MCP tools, every one wrapped with the bundled @governed_tool harness: a local unified audit log under ~/.network-aiops/, policy engine, token/runaway budget guard, undo-token recording, and graduated-autonomy risk tiers. Credentials (device passwords + the NetBox token) are kept in an encrypted store (secrets.enc), never plaintext on disk.

Devices are reached over NAPALM; an optional NetBox block adds source-of-truth lookups.

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

What works

Read device facts, interfaces (+ counters/IP), BGP/LLDP neighbors (summary and detail), ARP/MAC tables, VLANs, route lookups, hardware environment, optics, NTP, users, SNMP info, VRFs, and an aggregated device_health; back up the running config, dry-run a config diff, and merge/replace/rollback config — across the five core NAPALM platforms below. Optional NetBox lookups (devices + interfaces) confirm intended state before a change.

NAPALM does not implement every getter on every platform; an unsupported getter returns a teaching error ("not supported by the <driver> driver") rather than crashing. Secrets are never returned — get_users redacts password hashes and get_snmp_information redacts community strings.

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)

Additional platforms (Nokia SR OS / SR Linux, Huawei VRP, etc.) are reachable via NAPALM community drivers but are not officially tested here. Need one? See Contributing.

Supported actions

Action	Tool	R/W	Risk
Device facts (hostname/vendor/model/OS/serial/uptime)	device_facts	R	low
Interfaces (up/down, speed, description)	get_interfaces	R	low
Interface traffic + error counters	get_interfaces_counters	R	low
Interface IP addresses	get_interfaces_ip	R	low
BGP neighbors (summary / detail)	get_bgp_neighbors / get_bgp_neighbors_detail	R	low
LLDP neighbors (summary / detail)	get_lldp_neighbors / get_lldp_neighbors_detail	R	low
ARP table	get_arp_table	R	low
MAC address table	get_mac_address_table	R	low
VLANs	get_vlans	R	low
Route lookup	get_route_to	R	low
Hardware environment (fans/temp/power/CPU/mem)	get_environment	R	low
Optical transceiver levels	get_optics	R	low
NTP servers / sync stats	get_ntp_servers / get_ntp_stats	R	low
Local users (hashes redacted)	get_users	R	low
SNMP info (communities redacted)	get_snmp_information	R	low
Network instances (VRFs)	get_network_instances	R	low
Aggregated device health	device_health	R	low
Back up running config	config_backup	R	low
Diff a candidate (dry-run)	config_diff	R	low
Merge config + commit	config_merge	W	medium
Replace full config + commit	config_replace	W	high
Roll back last commit	config_rollback	W	medium
NetBox list devices	netbox_list_devices	R	low
NetBox get device	netbox_get_device	R	low
NetBox device interfaces	netbox_device_interfaces	R	low

Quick Start

uv tool install network-aiops
network-aiops init                                  # wizard: device + driver + host + encrypted password
network-aiops doctor
network-aiops device facts -t core-sw1
network-aiops device health -t core-sw1
network-aiops config backup -t core-sw1 -o core-sw1.cfg

Create ~/.network-aiops/config.yaml:

devices:
  - name: core-sw1            # used as -t core-sw1
    driver: eos               # ios | nxos | nxos_ssh | iosxr | eos | junos
    host: 10.0.0.1
    username: admin
    optional_args:            # passed verbatim to NAPALM (optional)
      secret: enable-pw       # enable/secret
      port: 443
# Optional source-of-truth:
netbox:
  url: https://netbox.example.com

Secrets are stored encrypted in ~/.network-aiops/secrets.enc (Fernet/AES + scrypt-derived key; chmod 600) — never in config.yaml or a plaintext .env. Device passwords are keyed by device name; the NetBox token uses the reserved name netbox-token:

network-aiops init                     # interactive wizard (recommended)
network-aiops secret set core-sw1      # store 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 migrate           # import a legacy plaintext .env, then delete it

Export NETWORK_AIOPS_MASTER_PASSWORD to unlock the store non-interactively (MCP server / cron). Legacy plaintext env vars (NETWORK_<TARGET_UPPER>_PASSWORD, NETWORK_NETBOX_TOKEN) remain a deprecated fallback. An empty device password is allowed for key-based SSH auth.

MCP

{
  "command": "network-aiops",
  "args": ["mcp"],
  "env": {
    "NETWORK_AIOPS_CONFIG": "~/.network-aiops/config.yaml",
    "NETWORK_AIOPS_MASTER_PASSWORD": "…"   // unlocks the encrypted secret store
  }
}

Audit & Safety

• Every tool call is logged to ~/.network-aiops/audit.db (local SQLite; relocate with NETWORK_AIOPS_HOME).
• config_merge / config_replace capture the pre-change running config and record an inverse config_replace-to-backup undo descriptor.
• config_replace is risk_level=high; CLI destructive commands (config merge/replace/rollback) require double confirmation and support --dry-run (which prints the diff without committing).
• All device text passes through sanitize() (prompt-injection defense).
• Device passwords and the NetBox token live only in the encrypted secrets.enc (chmod 600); tools never return passwords, SNMP community strings, or hashes.

See skills/network-aiops/SKILL.md and SECURITY.md for details.

Companion Skills

If you want…	Use
Network device config / facts (Cisco/Arista/Juniper)	network-aiops (this)
Kubernetes cluster operations	a cluster ops skill
Hypervisor VM lifecycle	a hypervisor ops skill

Contributing & feature requests

This is a preview — coverage is intentionally focused. Need a device or action that isn't here yet? Open an issue or pull request at github.com/AIops-tools/Network-AIops — contributions, feature requests, and comments are all welcome.

License

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