gNMIBuddy

🧪 gNMIBuddy

Uma ferramenta superengenhada e opinada que recupera informações essenciais de rede de dispositivos usando modelos gNMI e OpenConfig. Projetada principalmente para LLMs com integração Model Context Protocol (MCP), também fornece uma CLI completa para uso direto.

Opinada por design, superengenhada por paixão. O gNMI e o YANG expõem enormes quantidades de dados com inúmeros parâmetros. Esta ferramenta fornece o que considero a informação mais relevante para LLMs. E quem não gosta de construir soluções complicadas.

🎯 O Que Ela Faz

Recupera dados estruturados de rede em formato JSON:

• 🔄 Roteamento: protocolos BGP, ISIS e estados de vizinhos
• 🔌 Interfaces: status, configuração e estatísticas
• 🏷️ MPLS: rótulos, tabelas de encaminhamento e segment routing
• 🔒 VPN/VRF: configuração L3VPN e route targets
• 📝 Logs: logs de dispositivos filtrados com busca por palavra-chave
• 🏠 Topologia: vizinhos de dispositivos e análise de topologia em toda a rede

Consulte a definição da API para todas as APIs e opções disponíveis.

⚡ Pré-requisitos

• Python 3.13+
• uv, consulte a documentação para instalá-lo.
  • brew é recomendado para usuários de macOS
• Dispositivos de rede com gNMI habilitado.

Usuários de Windows: O repositório requer um ambiente semelhante ao Unix. Use o WSL.

Compatibilidade de Dispositivos

Testado em:

• Cisco XRd Control Plane (24.4.1.26I, 25.3.1)

[!NOTE] A função get_logs() só funciona em IOS-XR.

Os dispositivos devem suportar os modelos gNMI e OpenConfig listados abaixo:

Dependências dos modelos OpenConfig

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

[!NOTE] Se o modelo necessário para uma função não for encontrado, o gNMIBuddy retornará um erro. Se a versão do modelo for mais antiga que a necessária, ele continuará a execução, mas avisará o usuário sobre possíveis erros.

Você pode usar o comando capabilities para verificar os modelos suportados em um dispositivo específico. Se você tiver muitos dispositivos, poderá usar a opção --device.

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

Arquivo de Inventário de Dispositivos

O gNMIBuddy identifica dispositivos pelo hostname e consulta seus respectivos endereços IP e credenciais no arquivo de inventário.

[!CAUTION] Sem um arquivo de inventário de dispositivos, o gNMIBuddy não pode operar.

Forneça o inventário de dispositivos via --inventory PATH ou defina a variável de ambiente NETWORK_INVENTORY.

[!TIP] Armazene variáveis de ambiente em um arquivo .env.

O inventário deve ser uma lista JSON de objetos Device com os seguintes campos obrigatórios:

• name: Hostname do dispositivo
• ip_address: IP para conexões gNMI
• nos: Identificador do sistema operacional de rede
  • iosxr apenas por enquanto, use mesmo se você tiver outro NOS. Mais serão adicionados posteriormente.

Autenticação (escolha um método):

• Usuário/Senha: Requer os campos username e password
• Baseado em certificado: Requer os campos path_cert e path_key

Esquema: src/schemas/models.py | Exemplo: 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] Valide seu inventário: Use gnmibuddy inventory validate para verificar se o arquivo de inventário está no formato correto, possui endereços IP válidos, campos obrigatórios e configuração de autenticação antes de executar comandos de rede.

🚀 Início Rápido

🎯 Teste Instantâneo com o MCP Inspector

A maneira mais rápida de experimentar o 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] Sem clonagem de repositório, sem configuração de cliente MCP necessária! Se você não tiver o XRd, consulte Testando com 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

🐳 Execução como Contêiner

Compile e execute o gNMIBuddy como uma imagem de contêiner usando os alvos do Makefile fornecidos. O Makefile detecta automaticamente Docker ou Podman (Docker preferido); sobrescreva com CONTAINER_ENGINE=docker ou CONTAINER_ENGINE=podman se precisar forçar um.

O inventário de dispositivos é fornecido em tempo de execução como um arquivo 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] Execute make help para os demais alvos (restart, shell, clean, fresh).

Você pode testá-lo localmente com o modelcontextprotocol/inspector.

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

Executando no Kubernetes

O contêiner espera um arquivo de inventário de dispositivos no caminho da variável de ambiente NETWORK_INVENTORY (/app/inventory.json por padrão). Não há manifest Kubernetes incluído — o mecanismo exato depende do seu cluster — mas o requisito é genérico:

• Compile a imagem com qualquer compilador compatível com OCI (Docker, Buildah, Kaniko, docker buildx, sua própria etapa de build do CI, etc.). O Containerfile é padrão e não contém dados específicos do dispositivo, então a imagem resultante é segura para enviar ao seu registro.
• Armazene o inventário como um Secret do Kubernetes.
• Monte esse Secret como um volume no pod em /app/inventory.json (ou monte em outro lugar e aponte NETWORK_INVENTORY para esse caminho via env do pod).

📖 Referência da 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.

🤖 Desenvolvimento

Teste Rápido com o MCP Inspector

Recomendado: Use uvx (sem necessidade de clonar o repositório):

# 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 desenvolvimento local (testando alterações não commitadas):

# 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

Configuração do Cliente MCP

Escolha a abordagem que melhor se adapta às suas necessidades:

A configuração Clientes MCP Padrão funciona com Cursor, Claude Desktop e qualquer outro cliente que siga a especificação MCP. O VSCode requer um formato específico.

Requisitos de configuração:

• Configs uvx: Apenas atualize o caminho NETWORK_INVENTORY para o seu arquivo de inventário
• Configs dev: Atualize tanto o caminho NETWORK_INVENTORY quanto cwd para o seu diretório de projeto local

🧪 Testando com o DevNet Sandbox

Não tem dispositivos de rede? Use o DevNet XRd Sandbox, siga as instruções para montar uma rede de segment routing com gNMI configurado.

Use o arquivo de inventário xrd_sandbox.json para conectar-se aos dispositivos XRd em execução no DevNet Sandbox.

Se o gNMI não estiver habilitado, você pode habilitá-lo com os seguintes 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

Testando com Agentes de IA

Quer ver como esta ferramenta MCP se integra com agentes de IA reais? Consulte sp_oncall - um grafo de agentes que usam o gNMIBuddy para demonstrar cenários reais de operações de rede.

📋 Formato de Resposta

O gNMIBuddy fornece respostas estruturadas e consistentes para todas as operações de rede. O formato da resposta depende se você está visando um único dispositivo ou vários dispositivos.

Operações com um único dispositivo

Operações com um único dispositivo retornam um objeto NetworkOperationResult com informações detalhadas sobre a operação, incluindo status, dados, metadados e tratamento de erros.

@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

Operações em lote

Operações em lote (usando --all-devices, --devices ou --device-file) retornam um objeto BatchOperationResult contendo:

• results: Uma lista de objetos NetworkOperationResult, um para cada dispositivo
• summary: Estatísticas agregadas sobre a operação em lote
• metadata: Metadados adicionais da operação em lote

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

Para mais detalhes, consulte a definição do esquema de resposta.

🏗️ Arquitetura

Organização do Esquema

O gNMIBuddy usa uma abordagem de esquema centralizado para contratos de dados:

• src/schemas/: Contém todos os modelos de dados compartilhados e contratos de resposta.
• src/collectors/: Coletores de dados de telemetria de rede seguindo padrões OpenTelemetry.
• src/processors/: Processadores de transformação de dados seguindo padrões OpenTelemetry.

Esses esquemas servem como contratos entre as diferentes partes do sistema, garantindo consistência em:

• Interfaces CLI e API.
• Respostas de operações de rede.
• Tratamento de erros e relatório de status.
• Integração com ferramentas MCP.

Pipeline de Processamento de Dados

A aplicação segue uma arquitetura inspirada no OpenTelemetry:

Raw gNMI Data → Collector → Processor → Schema → Response

1. Coletores coletam dados dos dispositivos de rede via gNMI.
2. Processadores transformam dados brutos em formatos estruturados e amigáveis para LLMs.
3. Esquemas garantem contratos de dados consistentes em todo o sistema.
4. Respostas fornecem saída padronizada para interfaces CLI, API e MCP.

⚙️ Variáveis de Ambiente

O gNMIBuddy suporta variáveis de ambiente para configuração, que funcionam tanto para uso com CLI quanto com servidor MCP. As variáveis de ambiente podem ser carregadas de:

1. Argumentos de linha de comando (maior prioridade)
2. Variáveis de ambiente do sistema operacional
3. Arquivos .env (padrão: .env na raiz do projeto)
4. Valores padrão (menor prioridade)

Suporte a Arquivo .env

O gNMIBuddy carrega automaticamente variáveis de ambiente de um arquivo .env na raiz do projeto. Você pode especificar um arquivo .env personalizado usando a opção --env-file:

# Use default .env file
gnmibuddy device list

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

Exemplo:

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

Configuração Global

Arquivos de Log Sequenciais: O gNMIBuddy cria automaticamente arquivos de log numerados (gnmibuddy_001.log, gnmibuddy_002.log, etc.) para cada execução no diretório logs/. O número mais alto é sempre a execução mais recente.

[!NOTE] As variáveis de ambiente servem como padrões e podem ser substituídas por argumentos de CLI como --log-level e --module-log-levels.

Para opções detalhadas de configuração de ambiente e uso avançado, consulte Guia de Configuração de Ambiente

Para documentação completa das variáveis de ambiente de log, consulte README de Logging

⚙️ Operações em Lote e Concorrência

O gNMIBuddy suporta executar comandos em vários dispositivos simultaneamente com controles de concorrência configuráveis para otimizar o desempenho e evitar limitação de taxa.

Opções de Operação em Lote

Seleção de Dispositivos:

• --device DEVICE: Operação em dispositivo único
• --devices device1,device2,device3: Lista de dispositivos separada por vírgulas
• --device-file path/to/devices.txt: Lista de dispositivos a partir de arquivo (um por linha)
• --all-devices: Executar em todos os dispositivos do inventário

Controles de Concorrência:

• --max-workers N: Número máximo de dispositivos concorrentes para processar (padrão: 5)
• --per-device-workers N: Número máximo de operações concorrentes por dispositivo (padrão: varia por comando)

Entendendo os Níveis de Concorrência

O gNMIBuddy opera com dois níveis de concorrência:

1. Concorrência em nível de dispositivo (--max-workers): Quantos dispositivos processar simultaneamente
2. Concorrência por dispositivo (específica do comando): Quantas operações executar simultaneamente em cada dispositivo

Total de solicitações concorrentes = max_workers × per_device_operations

Exemplos

# 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