gNMIBuddy

🧪 gNMIBuddy

Una herramienta sobrediseñada y dogmática que recupera información esencial de red de los dispositivos utilizando gNMI y modelos OpenConfig. Diseñada principalmente para LLMs con integración de Model Context Protocol (MCP), también proporciona una CLI completa para uso directo.

Dogmática por diseño, sobrediseñada por pasión. gNMI y YANG exponen cantidades abrumadoras de datos con innumerables parámetros. Esta herramienta proporciona lo que considero la información más relevante para LLMs. Y a quién no le gusta construir soluciones complicadas.

🎯 Qué Hace

Recupera datos de red estructurados en formato JSON:

• 🔄 Enrutamiento: Protocolos BGP, ISIS y estados de vecinos
• 🔌 Interfaces: Estado, configuración y estadísticas
• 🏷️ MPLS: Etiquetas, tablas de reenvío y segment routing
• 🔒 VPN/VRF: Configuración L3VPN y route targets
• 📝 Registros: Registros de dispositivos filtrados con búsqueda por palabras clave
• 🏠 Topología: Vecinos de dispositivos y análisis de topología de red

Consulta la definición de la API para todas las APIs y opciones disponibles.

⚡ Requisitos previos

• Python 3.13+
• uv, consulta la documentación para instalarlo.
  • brew es recomendado para usuarios de macOS
• Dispositivos de red con gNMI habilitado.

Usuarios de Windows: El repositorio requiere un entorno similar a Unix. Usa WSL.

Compatibilidad de Dispositivos

Probado en:

• Cisco XRd Control Plane (24.4.1.26I, 25.3.1)

[!NOTE] La función get_logs() solo funciona en IOS-XR.

Los dispositivos deben soportar gNMI y los modelos OpenConfig que se enumeran a continuación:

Dependencias de modelos OpenConfig

• openconfig-system >= 0.17.1
• openconfig-interfaces >= 3.0.0
• openconfig-network-instance >= 1.3.0

[!NOTE] Si el modelo requerido para una función no se encuentra, gNMIBuddy devolverá un error. Si la versión del modelo es anterior a la requerida, continuará la ejecución pero advertirá al usuario sobre posibles errores.

Puedes usar el comando de capacidades para verificar los modelos soportados en un dispositivo específico. Si tienes muchos dispositivos, puedes usar la opción --device.

uvx --from git+https://github.com/jillesca/gNMIBuddy.git \
gnmibuddy device capabilities --all-devices

Archivo de Inventario de Dispositivos

gNMIBuddy identifica los dispositivos por nombre de host y busca sus direcciones IP y credenciales correspondientes en el archivo de inventario.

[!CAUTION] Sin un archivo de inventario de dispositivos, gNMIBuddy no puede operar.

Proporciona el inventario de dispositivos mediante --inventory PATH o establece la variable de entorno NETWORK_INVENTORY.

[!TIP] Almacena las variables de entorno en un archivo .env.

El inventario debe ser una lista JSON de objetos Device con estos campos obligatorios:

• name: Nombre de host del dispositivo
• ip_address: IP para conexiones gNMI
• nos: Identificador del sistema operativo de red
  • iosxr solo por ahora, úsalo incluso si tienes otro NOS. Se agregarán más más adelante.

Autenticación (elige un método):

• Usuario/Contraseña: Requiere los campos username y password
• Basado en certificados: Requiere los campos path_cert y path_key

Esquema: src/schemas/models.py | Ejemplo: xrd_sandbox.json

[
  {
    "name": "xrd-1",
    "ip_address": "10.10.20.101",
    "nos": "iosxr",
    "username": "cisco",
    "password": "C1sco12345"
  },
  {
    "name": "xrd-2",
    "ip_address": "10.10.20.102",
    "nos": "iosxr",
    "path_cert": "/opt/certs/device.pem",
    "path_key": "/opt/certs/device.key"
  }
]

[!TIP] Valida tu inventario: Usa gnmibuddy inventory validate para verificar que tu archivo de inventario tenga el formato adecuado, direcciones IP válidas, campos obligatorios y configuración de autenticación antes de ejecutar comandos de red.

🚀 Inicio Rápido

🎯 Pruebas Instantáneas con MCP Inspector

La forma más rápida de probar gNMIBuddy:

# Replace `xrd_sandbox.json` with your actual inventory file
echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \
&& echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \
&& chmod +x /tmp/gnmibuddy-mcp-wrapper \
&& NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapper

[!TIP] ¡Sin clonar el repositorio, sin configuración de cliente MCP! Si no tienes XRd, consulta Pruebas con DevNet Sandbox.

# Run directly without installation
uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --help

# Example with commands
uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --inventory your_inventory.json device list

# Install the tool globally
uv tool install git+https://github.com/jillesca/gNMIBuddy.git

# Use it directly
gnmibuddy --help
gnmibuddy device info --device R1

# Uninstall when no longer needed
uv tool uninstall gnmibuddy

# To get updates
uv tool upgrade gnmibuddy

🐳 Ejecución como Contenedor

Compila y ejecuta gNMIBuddy como imagen de contenedor usando los objetivos Makefile proporcionados. El Makefile detecta automáticamente Docker o Podman (Docker preferido); anula con CONTAINER_ENGINE=docker o CONTAINER_ENGINE=podman si necesitas forzar uno.

El inventario de dispositivos se proporciona en tiempo de ejecución como un archivo montado.

# Build the image (no inventory needed)
make build

# Run it, mounting your inventory file read-only into the container
# or set the NETWORK_INVENTORY in a .env file
make run NETWORK_INVENTORY=/path/to/inventory.json

# Tail logs / stop the container
make logs
make stop

[!TIP] Ejecuta make help para el resto de los objetivos (restart, shell, clean, fresh).

Puedes probarlo localmente con modelcontextprotocol/inspector.

npx @modelcontextprotocol/inspector --transport http --server-url http://0.0.0.0:8000/mcp

Ejecución en Kubernetes

El contenedor espera un archivo de inventario de dispositivos en la ruta de la variable de entorno NETWORK_INVENTORY (/app/inventory.json por defecto). No hay un manifiesto de Kubernetes incluido — el mecanismo exacto depende de tu clúster — pero el requisito es genérico:

• Compila la imagen con cualquier compilador compatible con OCI (Docker, Buildah, Kaniko, docker buildx, el paso de compilación de tu propio CI, etc.). El Containerfile es estándar y no contiene datos específicos del dispositivo, por lo que la imagen resultante es segura para enviar a tu registro.
• Almacena el inventario como un Secret de Kubernetes.
• Monta ese Secret como volumen en el pod en /app/inventory.json (o móntalo en otro lugar y apunta NETWORK_INVENTORY a esa ruta mediante el entorno del pod).

📖 Referencia de CLI

# Clone and setup (one-time only)
git clone https://github.com/jillesca/gNMIBuddy.git && cd gNMIBuddy
# Install dependencies
uv sync --frozen --no-dev

❯ uv run gnmibuddy.py --help

  ▗▄▄▖▗▖  ▗▖▗▖  ▗▖▗▄▄▄▖▗▄▄▖ ▗▖ ▗▖▗▄▄▄ ▗▄▄▄▗▖  ▗▖
 ▐▌   ▐▛▚▖▐▌▐▛▚▞▜▌  █  ▐▌ ▐▌▐▌ ▐▌▐▌  █▐▌  █▝▚▞▘
 ▐▌▝▜▌▐▌ ▝▜▌▐▌  ▐▌  █  ▐▛▀▚▖▐▌ ▐▌▐▌  █▐▌  █ ▐▌
 ▝▚▄▞▘▐▌  ▐▌▐▌  ▐▌▗▄█▄▖▐▙▄▞▘▝▚▄▞▘▐▙▄▄▀▐▙▄▄▀ ▐▌

An opinionated tool that retrieves essential network information from devices using gNMI and OpenConfig models.
Designed primarily for LLMs with Model Context Protocol (MCP) integration, it also provides a full CLI.
Help: https://github.com/jillesca/gNMIBuddy

Python Version: 3.13.4
gNMIBuddy Version: 0.1.0
Usage:
  gnmibuddy.py [OPTIONS] COMMAND [ARGS]...

📋 Inventory Requirement:
  Provide device inventory via --inventory PATH, set NETWORK_INVENTORY env var, or use .env file (configurable with --env-file PATH)

Options:
  -h, --help            Show this message and exit
  -V, --version         Show version information
  --log-level LEVEL     Set logging level (debug, info, warning, error)
  --module-log-help     Show detailed module logging help
  --all-devices         Run on all devices concurrently
  --inventory PATH      Path to inventory JSON file
  -e, --env-file PATH   Path to .env file for configuration (default: .env in project root)
  --max-workers NUMBER  Maximum number of concurrent workers for batch operations (--all-devices, --devices, --device-file)

Commands:
  device (d)    Device Information
    capabilities Get gNMI capabilities from a network device
    info         Get system information from a network device
    list         List all available devices in the inventory
    profile      Get device profile and role information

  network (n)   Network Protocols
    interface    Get interface status and configuration
    mpls         Get MPLS forwarding and label information
    routing      Get routing protocol information (BGP, ISIS, OSPF)
    vpn          Get VPN/VRF configuration and status

  topology (t)  Network Topology
    neighbors    Get direct neighbor information via LLDP/CDP
    adjacency    Get network-wide IP adjacency analysis for complete topology
    network      Get complete network topology information. Queries all devices in inventory.

  ops (o)       Operations
    logs         Retrieve and filter device logs
    validate     Validate all collector functions (development tool)

  inventory (i) Inventory Management
    validate     Validate inventory file format and schema

Examples:
  gnmibuddy.py device info --device R1
  gnmibuddy.py network routing --device R1
  gnmibuddy.py --all-devices device list
  gnmibuddy.py inventory validate --inventory inventory.json
  gnmibuddy.py --env-file production.env device list
  gnmibuddy.py --env-file dev.env --log-level debug device info --device R1

Run 'gnmibuddy.py COMMAND --help' for more information on a command.

🤖 Desarrollo

Pruebas Rápidas con MCP Inspector

Recomendado: Usa uvx (sin necesidad de clonar el repositorio):

# Replace `xrd_sandbox.json` with your actual inventory file
echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \
&& echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \
&& chmod +x /tmp/gnmibuddy-mcp-wrapper \
&& NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapper
EOF

Para desarrollo local (probar cambios no confirmados):

# Run from your gNMIBuddy project directory (where pyproject.toml is located)
cd /path/to/your/gNMIBuddy && \
NETWORK_INVENTORY=your_inventory.json \
npx @modelcontextprotocol/inspector \
uv run --frozen gnmibuddy-mcp

Configuración del Cliente MCP

Elige el enfoque que se adapte a tus necesidades:

La configuración de Clientes MCP estándar funciona con Cursor, Claude Desktop y cualquier otro cliente que siga la especificación MCP. VSCode requiere un formato específico.

Requisitos de configuración:

• Configuraciones uvx: Solo actualiza la ruta NETWORK_INVENTORY a tu archivo de inventario
• Configuraciones de desarrollo: Actualiza tanto la ruta NETWORK_INVENTORY como cwd a tu directorio de proyecto local

🧪 Pruebas con DevNet Sandbox

¿No tienes dispositivos de red? Usa el DevNet XRd Sandbox, sigue las instrucciones para levantar una red de segment routing con gNMI configurado.

Usa el archivo de inventario xrd_sandbox.json para conectarte a los dispositivos XRd que se ejecutan en DevNet Sandbox.

Si gNMI no está habilitado, puedes habilitarlo con los siguientes comandos:

# If you cloned the repo
# Enable gRPC on the DevNet XRd Sandbox
ANSIBLE_HOST_KEY_CHECKING=False \
uvx --from "ansible-core==2.19.2" --with "paramiko,ansible" \
ansible-playbook ansible-helper/xrd_apply_config.yaml -i ansible-helper/hosts

Pruebas con Agentes de IA

¿Quieres ver cómo esta herramienta MCP se integra con agentes de IA reales? Consulta sp_oncall - un grafo de agentes que usan gNMIBuddy para demostrar escenarios reales de operaciones de red.

📋 Formato de Respuesta

gNMIBuddy proporciona respuestas estructuradas y consistentes para todas las operaciones de red. El formato de respuesta depende de si te diriges a un solo dispositivo o a múltiples dispositivos.

Operaciones de Dispositivo Único

Las operaciones de dispositivo único devuelven un objeto NetworkOperationResult con información detallada sobre la operación, incluidos estado, datos, metadatos y manejo de errores.

@dataclass
class NetworkOperationResult:
    device_name: str
    ip_address: IPAddress
    nos: NetworkOS
    operation_type: str
    status: OperationStatus
    data: Dict[str, Any] = field(default_factory=dict)
    metadata: Dict[str, Any] = field(default_factory=dict)
    error_response: Optional[ErrorResponse] = None
    feature_not_found_response: Optional[FeatureNotFoundResponse] = None

Operaciones por Lotes

Las operaciones por lotes (usando --all-devices, --devices o --device-file) devuelven un objeto BatchOperationResult que contiene:

• results: Una lista de objetos NetworkOperationResult, uno por cada dispositivo
• summary: Estadísticas agregadas sobre la operación por lotes
• metadata: Metadatos adicionales de la operación por lotes

@dataclass
class BatchOperationResult:
    results: List[NetworkOperationResult]  # One result per device
    summary: BatchOperationSummary
    metadata: Dict[str, Any] = field(default_factory=dict)

Para más detalles, consulta la definición del esquema de respuesta.

🏗️ Arquitectura

Organización de Esquemas

gNMIBuddy utiliza un enfoque de esquemas centralizados para los contratos de datos:

• src/schemas/: Contiene todos los modelos de datos compartidos y contratos de respuesta.
• src/collectors/: Recopiladores de datos de telemetría de red que siguen patrones de OpenTelemetry.
• src/processors/: Procesadores de transformación de datos que siguen patrones de OpenTelemetry.

Estos esquemas sirven como contratos entre diferentes partes del sistema, asegurando consistencia en:

• Interfaces CLI y API.
• Respuestas de operaciones de red.
• Manejo de errores y reporte de estado.
• Integración de herramientas MCP.

Pipeline de Procesamiento de Datos

La aplicación sigue una arquitectura inspirada en OpenTelemetry:

Raw gNMI Data → Collector → Processor → Schema → Response

1. Recopiladores obtienen datos de los dispositivos de red mediante gNMI.
2. Procesadores transforman datos sin procesar en formatos estructurados y amigables para LLMs.
3. Esquemas aseguran contratos de datos consistentes en todo el sistema.
4. Respuestas proporcionan salida estandarizada para interfaces CLI, API y MCP.

⚙️ Variables de Entorno

gNMIBuddy admite variables de entorno para configuración, que funcionan tanto para uso CLI como para servidor MCP. Las variables de entorno se pueden cargar desde:

1. Argumentos de línea de comandos (mayor prioridad)
2. Variables de entorno del sistema operativo
3. Archivos .env (por defecto: .env en la raíz del proyecto)
4. Valores predeterminados (menor prioridad)

Soporte de Archivos .env

gNMIBuddy carga automáticamente variables de entorno desde un archivo .env en la raíz del proyecto. Puedes especificar un archivo .env personalizado usando la opción --env-file:

# Use default .env file
gnmibuddy device list

# Use custom environment file
gnmibuddy --env-file production.env device list

Ejemplo:

# .env file

# Network configuration
NETWORK_INVENTORY=/path/to/inventory.json

# Logging configuration
GNMIBUDDY_LOG_LEVEL=debug
GNMIBUDDY_MODULE_LEVELS=src.cmd=warning,src.inventory=debug
GNMIBUDDY_STRUCTURED_LOGGING=true
GNMIBUDDY_LOG_FILE=/custom/log/path.log
GNMIBUDDY_EXTERNAL_SUPPRESSION_MODE=development

# MCP debugging
GNMIBUDDY_MCP_TOOL_DEBUG=true

Configuración Global

Archivos de registro secuenciales: gNMIBuddy crea automáticamente archivos de registro numerados (gnmibuddy_001.log, gnmibuddy_002.log, etc.) para cada ejecución en el directorio logs/. El número más alto siempre corresponde a la ejecución más reciente.

[!NOTE] Las variables de entorno sirven como valores predeterminados y pueden ser anuladas por argumentos de línea de comandos como --log-level y --module-log-levels.

Para opciones detalladas de configuración de entorno y uso avanzado, consulta Guía de configuración de entorno

Para documentación completa de variables de entorno de registro, consulta README de registro

⚙️ Operaciones por lotes y concurrencia

gNMIBuddy admite ejecutar comandos en múltiples dispositivos simultáneamente con controles de concurrencia configurables para optimizar el rendimiento y evitar la limitación de velocidad.

Opciones de operaciones por lotes

Selección de dispositivos:

• --device DEVICE: Operación en un solo dispositivo
• --devices device1,device2,device3: Lista de dispositivos separada por comas
• --device-file path/to/devices.txt: Lista de dispositivos desde archivo (uno por línea)
• --all-devices: Ejecutar en todos los dispositivos del inventario

Controles de concurrencia:

• --max-workers N: Máximo de dispositivos concurrentes a procesar (predeterminado: 5)
• --per-device-workers N: Máximo de operaciones concurrentes por dispositivo (predeterminado: varía según el comando)

Comprendiendo los niveles de concurrencia

gNMIBuddy opera con dos niveles de concurrencia:

1. Concurrencia a nivel de dispositivo (--max-workers): Cuántos dispositivos procesar simultáneamente
2. Concurrencia por dispositivo (específica del comando): Cuántas operaciones ejecutar simultáneamente en cada dispositivo

Total de solicitudes concurrentes = max_workers × operaciones_por_dispositivo

Ejemplos

# Process 3 devices, 2 operations per device = 6 total requests
uv run gnmibuddy.py --max-workers 3 ops validate --devices xrd-1,xrd-2,xrd-3 --per-device-workers 2