network-aiops 0.1.0__tar.gz

network_aiops-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual envs / build
+.venv/
+dist/
+build/
+
+# uv
+uv.lock
+
+# Local config / secrets (never commit)
+*.env
+.env
+config.yaml
+
+# OS
+.DS_Store

network_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.

network_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: network-aiops
+Version: 0.1.0
+Summary: Governed multi-vendor network device operations for AI agents (NAPALM) 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: mcp[cli]<2.0,>=1.10
+Requires-Dist: napalm<6,>=4.1
+Requires-Dist: pynetbox<8,>=7
+Requires-Dist: python-dotenv<2.0,>=1.0
+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/network-aiops -->
+# 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](https://github.com/AIops-tools/Network-AIops)
+> under the MIT license.
+
+Governed multi-vendor network device operations for AI agents — **13 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.
+
+Devices are reached over [NAPALM](https://napalm.readthedocs.io/); 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/IP/BGP/LLDP/ARP, 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 confirm intended state before a change.
+
+## 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](#contributing--feature-requests).
+
+## 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 IP addresses | `get_interfaces_ip` | R | low |
+| BGP neighbors | `get_bgp_neighbors` | R | low |
+| LLDP neighbors | `get_lldp_neighbors` | R | low |
+| ARP table | `get_arp_table` | 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 |
+
+## Quick Start
+
+```bash
+uv tool install network-aiops
+network-aiops doctor
+network-aiops device facts -t core-sw1
+network-aiops config backup -t core-sw1 -o core-sw1.cfg
+```
+
+Create `~/.network-aiops/config.yaml`:
+
+```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
+```
+
+Put secrets in `~/.network-aiops/.env` (chmod 600) — never in config.yaml:
+
+```bash
+NETWORK_CORE_SW1_PASSWORD=...     # NETWORK_<TARGET_UPPER>_PASSWORD
+NETWORK_NETBOX_TOKEN=...
+```
+
+## MCP
+
+```jsonc
+{
+  "command": "network-aiops",
+  "args": ["mcp"],
+  "env": { "NETWORK_AIOPS_CONFIG": "~/.network-aiops/config.yaml" }
+}
+```
+
+## 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).
+
+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](https://github.com/AIops-tools/Network-AIops/issues)
+— contributions, feature requests, and comments are all welcome.
+
+## License
+
+MIT — [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops)

network_aiops-0.1.0/README.md

@@ -0,0 +1,133 @@
+<!-- mcp-name: io.github.AIops-tools/network-aiops -->
+# 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](https://github.com/AIops-tools/Network-AIops)
+> under the MIT license.
+
+Governed multi-vendor network device operations for AI agents — **13 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.
+
+Devices are reached over [NAPALM](https://napalm.readthedocs.io/); 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/IP/BGP/LLDP/ARP, 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 confirm intended state before a change.
+
+## 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](#contributing--feature-requests).
+
+## 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 IP addresses | `get_interfaces_ip` | R | low |
+| BGP neighbors | `get_bgp_neighbors` | R | low |
+| LLDP neighbors | `get_lldp_neighbors` | R | low |
+| ARP table | `get_arp_table` | 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 |
+
+## Quick Start
+
+```bash
+uv tool install network-aiops
+network-aiops doctor
+network-aiops device facts -t core-sw1
+network-aiops config backup -t core-sw1 -o core-sw1.cfg
+```
+
+Create `~/.network-aiops/config.yaml`:
+
+```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
+```
+
+Put secrets in `~/.network-aiops/.env` (chmod 600) — never in config.yaml:
+
+```bash
+NETWORK_CORE_SW1_PASSWORD=...     # NETWORK_<TARGET_UPPER>_PASSWORD
+NETWORK_NETBOX_TOKEN=...
+```
+
+## MCP
+
+```jsonc
+{
+  "command": "network-aiops",
+  "args": ["mcp"],
+  "env": { "NETWORK_AIOPS_CONFIG": "~/.network-aiops/config.yaml" }
+}
+```
+
+## 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).
+
+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](https://github.com/AIops-tools/Network-AIops/issues)
+— contributions, feature requests, and comments are all welcome.
+
+## License
+
+MIT — [github.com/AIops-tools/Network-AIops](https://github.com/AIops-tools/Network-AIops)

network_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,24 @@
+# Release Notes
+
+## 0.1.0 (preview)
+
+Initial preview release of **network-aiops** — governed multi-vendor network
+device operations for AI agents.
+
+- **13 MCP tools** (10 read / 3 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo-token
+  recording, graduated risk tiers).
+- Devices reached over **NAPALM**. Officially supported drivers: `ios`,
+  `nxos`, `nxos_ssh`, `iosxr`, `eos`, `junos`.
+- Read getters: device facts, interfaces, interface IPs, BGP neighbors, LLDP
+  neighbors, ARP table, config backup, config diff (dry-run).
+- Config writes: merge (medium), replace (high), rollback (medium). Merge and
+  replace capture the pre-change running config and record a `config_replace`
+  undo descriptor that restores it.
+- Optional **NetBox** source-of-truth lookups (`netbox_list_devices`,
+  `netbox_get_device`); degrade gracefully when not configured.
+- CLI: `device facts/interfaces/bgp/lldp/arp`, `config backup/diff/merge/replace/rollback`,
+  `netbox list/get`, `doctor`, `mcp`. Destructive config ops require double
+  confirmation and `--dry-run`.
+- Standalone: governance harness bundled under `network_aiops.governance`; no
+  external skill-family dependency.

network_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,82 @@
+# Security Policy
+
+## 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.
+
+## Reporting Vulnerabilities
+
+Report security issues privately to **zhouwei008@gmail.com** or via a GitHub
+private security advisory on the repository. Please do not open public issues for
+undisclosed vulnerabilities.
+
+## Security Design
+
+### Credential Management
+
+Device passwords are read from `~/.network-aiops/.env` as
+`NETWORK_<TARGET_UPPER>_PASSWORD` (one per device); enable/secret and transport
+options go in the device's `optional_args` and are passed verbatim to NAPALM. The
+optional NetBox token is read from `NETWORK_NETBOX_TOKEN`. `config.yaml` holds
+only device names, drivers, hosts, usernames, and `optional_args` — never
+secrets. The state directory `~/.network-aiops` should be owner-only
+(`chmod 700`) and `.env` `chmod 600`; the skill warns if the directory is more
+permissive. Credentials are never read into results, logged, or echoed.
+
+### Destructive Operation Safety
+
+Config write operations (merge, replace, rollback) all pass through the bundled
+`@governed_tool` decorator: policy pre-check, token / runaway budget guard,
+graduated-autonomy risk-tier gate, and audit logging. The CLI layer additionally
+requires double confirmation and supports `--dry-run` (which prints the diff
+without committing) for `config merge`, `config replace`, and `config rollback`.
+`config_merge` and `config_replace` capture the pre-change running config and
+record an inverse `config_replace`-to-backup undo descriptor; `config_rollback`
+declares no undo; `config_replace` is tagged `risk_level=high`. `config_diff` is a
+pure dry-run (stage candidate → compare → discard).
+
+### Least Privilege
+
+Use a device account with only the privilege you need — a read-only login for
+facts/backup, and a config-capable login only for the merge/replace/rollback
+tools. The optional NetBox token should be read-only.
+
+### Webhooks / Outbound Network
+
+None. The skill makes no outbound network calls beyond the configured device
+sessions (NAPALM) and the optional NetBox API. There are no background services
+or post-install scripts.
+
+### TLS Verification
+
+NAPALM driver transports (eAPI / NX-API over HTTPS, NETCONF / SSH) follow each
+device's own certificate and SSH host-key configuration. The skill does not
+weaken transport security.
+
+### Prompt Injection Protection
+
+All text returned from a device (facts, configs, diffs, interface descriptions,
+neighbor data) and from NetBox is run through `sanitize()` — truncation plus
+C0/C1 control-character stripping — before reaching the agent.
+
+### Transitive Dependencies
+
+`napalm` (device drivers), `pynetbox` (optional source-of-truth), `typer`/`rich`
+(CLI), `pyyaml`/`python-dotenv` (config), and the MCP SDK. No external
+skill-family dependency — the governance harness is vendored under
+`network_aiops.governance`.
+
+## Static Analysis
+
+```bash
+uvx bandit -r network_aiops/ mcp_server/
+```
+
+## Supported Versions
+
+The latest released version (currently 0.1.0, preview) receives security fixes.

network_aiops-0.1.0/mcp_server/_shared.py

@@ -0,0 +1,113 @@
+"""Shared MCP server primitives: the FastMCP instance, manager helper,
+error sanitisation, and the ``@tool_errors`` decorator.
+
+Tool modules under ``mcp_server/tools/`` import ``mcp`` from here and register
+their ``@mcp.tool()`` functions onto it. ``mcp_server/server.py`` then imports
+those modules and runs the server.
+
+Keep ``Optional[X]`` (never PEP 604 ``X | None``) in any FastMCP-reflected
+tool signature — on older mcp/pydantic the union eval'd to ``types.UnionType``
+crashes FastMCP's ``issubclass`` check.
+"""
+
+import functools
+import logging
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from network_aiops.config import load_config
+from network_aiops.connection import ConnectionManager, NetworkApiError
+from network_aiops.governance import sanitize
+
+logger = logging.getLogger(__name__)
+
+_DOCTOR_HINT = "Run 'network-aiops doctor' to verify device config and reachability."
+
+_SUPPORTED = "ios, nxos, nxos_ssh, iosxr, eos, junos"
+
+
+def _safe_error(exc: Exception, tool: str) -> str:
+    """Return an agent-safe error string; log full detail server-side only."""
+    logger.error("Tool %s failed", tool, exc_info=True)
+    _passthrough = (
+        ValueError,
+        FileNotFoundError,
+        KeyError,
+        PermissionError,
+        TimeoutError,
+        ConnectionError,
+        NetworkApiError,
+    )
+    if isinstance(exc, _passthrough):
+        return sanitize(str(exc), 300)
+    return f"{type(exc).__name__}: operation failed."
+
+
+def tool_errors(shape: str = "dict") -> Callable:
+    """Wrap a tool body in the canonical try/except → ``_safe_error`` pattern.
+
+    Place this *between* ``@governed_tool`` and the function so the audit
+    decorator and FastMCP still see the original signature.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        name = func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:  # noqa: BLE001 — sanitised below
+                msg = _safe_error(e, name)
+                if shape == "list":
+                    return [{"error": msg, "hint": _DOCTOR_HINT}]
+                if shape == "str":
+                    return f"Error: {msg} {_DOCTOR_HINT}"
+                return {"error": msg, "hint": _DOCTOR_HINT}
+
+        return wrapper
+
+    return decorator
+
+
+mcp = FastMCP(
+    "network-aiops",
+    instructions=(
+        "Governed multi-vendor network device operations (preview) over NAPALM. "
+        f"Officially supported drivers: {_SUPPORTED} (Cisco IOS/IOS-XE, Nexus "
+        "NX-OS, IOS-XR, Arista EOS, Juniper Junos). Read tools: device facts, "
+        "interfaces, IP addresses, BGP/LLDP neighbors, ARP table, config backup, "
+        "and config diff (dry-run). Write tools: config merge, config replace, "
+        "config rollback. An optional NetBox block adds source-of-truth device "
+        "lookups. A 'target' selects a device from config. Every tool runs "
+        "through the network-aiops governance harness (audit / budget / risk-tier "
+        "/ undo). Need another platform (Nokia SR OS, Huawei VRP) or action? "
+        "Request it via a GitHub issue or PR."
+    ),
+)
+
+_conn_mgr: Optional[ConnectionManager] = None
+
+
+def _manager() -> ConnectionManager:
+    """Return the connection manager, lazily initialising it from config."""
+    global _conn_mgr  # noqa: PLW0603
+    if _conn_mgr is None:
+        config_path_str = os.environ.get("NETWORK_AIOPS_CONFIG")
+        config_path = Path(config_path_str) if config_path_str else None
+        _conn_mgr = ConnectionManager(load_config(config_path))
+    return _conn_mgr
+
+
+def _target(name: Optional[str] = None) -> Any:
+    """Resolve a device target by name (or the default device)."""
+    return _manager().target(name)
+
+
+def _netbox() -> Any:
+    """Return a NetBox client (raises a teaching NetworkApiError if unconfigured)."""
+    return _manager().netbox()

network_aiops-0.1.0/mcp_server/server.py

@@ -0,0 +1,33 @@
+"""MCP server wrapping network-aiops operations (stdio transport).
+
+Thin adapter layer: each ``@mcp.tool()`` function (in ``mcp_server/tools/``)
+delegates to the ``network_aiops`` ops package and is wrapped with the
+network-aiops ``@governed_tool`` harness (audit / budget / undo / risk-tier).
+
+Standalone, self-governed network device operations (preview) over NAPALM —
+Cisco IOS/IOS-XE, Nexus NX-OS, IOS-XR, Arista EOS, Juniper Junos, plus optional
+NetBox source-of-truth.
+
+Source: https://github.com/AIops-tools/Network-AIops
+License: MIT
+"""
+
+import logging
+
+from mcp_server._shared import _safe_error, mcp, tool_errors
+
+# Importing the tool modules registers every @mcp.tool() onto the shared
+# `mcp` instance. Order does not matter; each module is self-contained.
+from mcp_server.tools import (  # noqa: F401 — side effects
+    config_ops,
+    facts,
+    netbox,
+)
+
+__all__ = ["mcp", "main", "_safe_error", "tool_errors"]
+
+
+def main() -> None:
+    """Run the MCP server over stdio."""
+    logging.basicConfig(level=logging.INFO)
+    mcp.run(transport="stdio")