IoT Sentinel — Registrando e Organizando Seus Devices

iot homelab docker monitoring

IoT Sentinel — Registrando e Organizando Seus Devices

Este post é o quinto de uma série de oito partes sobre o IoT Sentinel. Aqui mostro como organizar os devices descobertos em um inventário.

De discovered para registered

Se você seguiu os posts anteriores, já tem o Sentinel rodando, com locais e redes configurados, e executou pelo menos um scan. A essa altura, a lista de devices está populada — mas é uma lista crua. Cada device aparece com o nome que o Sentinel conseguiu inferir a partir do scan: um hostname, um vendor, ou simplesmente o endereço IP. O status de todos é discovered.

Esse é o estado inicial e proposital. O Sentinel separa o ciclo de vida de um device em dois momentos: discovered e registered. Um device discovered é algo que a ferramenta encontrou na rede. Um device registered é algo que você, como administrador, confirmou, nomeou e categorizou. A diferença é importante porque dá a você controle sobre o que entra no inventário oficial e o que é ruído — aquele celular de visita que apareceu uma vez, o notebook do técnico que passou pela rede por cinco minutos.

Além do registrationStatus, cada device tem um healthStatus independente: online, offline ou unknown. Isso significa que um device pode estar registrado e offline, ou discovered e online. Os dois eixos de status trabalham juntos para dar uma visão clara do que existe e do que está ativo.

Editando um device

Para registrar um device, basta abrir o detalhe e editar. O Sentinel oferece os seguintes campos editáveis: name, type e description. O campo name é livre — você substitui aquele “192.168.10.1” por algo legível como “Roteador Principal”. O type define a categoria do device (mais sobre isso na próxima seção). E o description é um campo de texto livre para qualquer anotação que faça sentido — “Rack 2, porta 3”, “Garantia até 2027”, o que for.

O detalhe interessante aqui é que o Sentinel promove o device automaticamente para registered assim que você faz a primeira edição. Não existe um botão explícito de “registrar” — a ação de dar um nome ao device já é o registro. Isso foi uma decisão de design para reduzir fricção: se você se deu ao trabalho de abrir o device e preencher um nome, a intenção de registrar é clara.

Depois de editar, o device aparece na lista com o nome que você escolheu, o tipo correto e um badge de status atualizado. A diferença visual entre um device discovered e um registered é imediata.

Tipos de device

Cada device no Sentinel tem um tipo associado. O sistema vem com 19 tipos pré-definidos, cada um com ícone e cor próprios:

TipoSlugÍconeCor
Routerrouterrouter#6366f1
Switchswitchgit-branch#8b5cf6
Access Pointaccess-pointwifi#06b6d4
Firewallfirewallshield#ef4444
Serverserverserver#3b82f6
Workstationworkstationmonitor#64748b
VMvmbox#a855f7
NASnasdatabase#0ea5e9
NVRnvrhard-drive#7c3aed
Cameracameracamera#f59e0b
Printerprinterprinter#78716c
Smart TVsmart-tvtv#ec4899
Sensorsensorthermometer#10b981
PLCplccpu#f97316
HMIhmitablet#d946ef
Gatewaygatewaynetwork#14b8a6
Serviceservicecloud#6366f1
Smart Switchsmart-switchplug-zap#f97316
Otherotherhelp-circle#94a3b8

Esses tipos são marcados como isSystem: true e são criados automaticamente na inicialização da API via seed. Você não pode deletá-los, mas pode editá-los.

O que torna os tipos mais do que cosméticos é o campo capabilities. Cada tipo define três flags:

  • enableChannels — se o device suporta channels (entradas/saídas como relés, sensores, portas). Ativo para PLC e Smart Switch, por exemplo.
  • enablePortScan — se faz sentido rodar port scan nesse device. Ativo para Server, Firewall, VM, NAS, Workstation e Service.
  • enableCredentials — se o device tem credenciais de acesso. Ativo para a maioria, desativado para Printer, Smart TV, Sensor e Other.

Essas capabilities controlam o que aparece na interface quando você abre o detalhe de um device. Se o tipo não tem enableChannels, a aba de channels nem aparece. Se não tem enableCredentials, o formulário de credenciais some. Isso mantém a interface limpa — você só vê o que é relevante para aquele tipo de device.

E se os 19 tipos não cobrem o seu cenário, você pode criar tipos customizados com nome, slug, ícone (usando Lucide icons), cor e capabilities à sua escolha. Tipos customizados funcionam exatamente como os do sistema, mas podem ser deletados.

Grupos: organização transversal

Tipos categorizam o que um device é. Grupos categorizam a que ele pertence — e são completamente independentes da hierarquia de rede.

No modelo de dados, um device pertence a uma networkId (a rede onde foi descoberto) e pode pertencer a múltiplos groupIds. Os grupos são transversais: um grupo “Automação” pode conter um PLC da rede industrial, um Raspberry Pi da rede IoT e um server da rede de servidores. A mesma câmera pode estar no grupo “Segurança” e no grupo “Andar Térreo” ao mesmo tempo.

Criar um grupo é direto: nome, ícone (Lucide), cor e uma descrição opcional. O schema é enxuto de propósito — name, icon, color, description. Sem hierarquia, sem dependência de local ou rede.

Para associar devices a um grupo, o Sentinel oferece atribuição em lote. Na lista de devices, você seleciona múltiplos devices via checkbox e abre o modal de atribuição. Escolhe o grupo (ou cria um novo na hora) e confirma. Os groupIds de cada device selecionado são atualizados em uma chamada. Isso é especialmente útil quando você acabou de rodar um scan grande e precisa organizar 30 devices de uma vez — fazer um por um seria inviável.

O uso real dos grupos aparece quando você precisa de visões que não seguem a topologia da rede. “Quais são todos os devices da automação da fábrica?” — isso pode cruzar três redes diferentes. “Quais devices o fornecedor X instalou?” — outro corte transversal. Grupos existem para esses cenários.

Filtros e busca

Com devices registrados, tipados e agrupados, a próxima necessidade é encontrar o que você precisa rápido. O Sentinel expõe filtros combináveis na listagem de devices:

  • registrationStatus — filtrar só discovered ou só registered
  • healthStatus — filtrar por online, offline ou unknown
  • networkId — filtrar por rede específica
  • groupId — filtrar por grupo

Esses filtros são acumulativos. Você pode, por exemplo, ver todos os devices registered que estão offline na rede “Industrial” — três filtros combinados.

Além dos filtros estruturados, existe a busca textual via parâmetro q. Ela faz regex case-insensitive em vários campos: name, macAddress, ipAddress, hostname, vendor e até channels.name. Então se você lembra que tem um device com “Hikvision” no vendor, ou um com MAC começando em “AA:BB”, a busca encontra.

A combinação de filtros e busca textual cobre a maioria dos cenários do dia a dia. Filtros para navegação estruturada, busca para quando você sabe um pedaço da informação e precisa achar o device.

Próximo passo

Com o inventário organizado — devices nomeados, tipados, agrupados e filtráveis — o próximo passo é configurar credenciais de acesso e channels para os devices que suportam. Credenciais são armazenadas com criptografia simétrica e channels permitem modelar as entradas e saídas de PLCs, smart switches e outros devices com I/O.

Tudo isso na Parte 6 — Credenciais e Channels.