Instalação do agente Sentinel

Registre um agente no portal, instale o pacote assinado, faça o registro no host com o token de uso único e confirme o túnel. Inclui os requisitos de rede, as atualizações pelo portal ou pelo pacote, a saúde do host e do túnel e o comando check para solução de problemas. mTLS até o seu tenant, sem portas de entrada.

O agente Sentinel da WASViking^® é instalado a partir de um pacote assinado. Todo o fluxo é conduzido pelo seu portal: crie o registro do agente para obter um token de uso único, instale o pacote no host, faça o registro com o token para obter os certificados e confirme o túnel. O túnel mTLS sobe e a nuvem da WASViking pode então executar scans nos seus alvos internos.

Plataformas suportadas

Requisitos mínimos: 1 vCPU, 512 MB de RAM, 1 GB de disco para cache e saída efêmera dos scans. Os comandos desta página usam o pacote para Ubuntu / Debian.

Para o passo a passo com capturas de tela do portal, consulte WASViking Sentinel Tunnel em Primeiros passos. Esta página é a referência completa de instalação.

Requisitos de rede

O agente só faz conexões de saída. Libere estes destinos a partir do host do agente:

• Nenhuma porta de entrada. Nada na internet se conecta ao host, e nenhuma abertura de firewall na direção dele é necessária.
• Sem inspeção de TLS em sentinel.wasviking.com. O túnel usa TLS mútuo: o agente comprova a sua identidade com o próprio certificado e só confia na CA privada da WASViking. Um proxy, firewall ou produto de segurança de endpoint que encerra e reassina o TLS não consegue transportar esse handshake. Inclua o domínio na lista de exceções de inspeção do produto. O local onde essa lista costuma ficar nos produtos mais comuns está descrito em Exclusões de proteção de endpoint.
• Instâncias em nuvem. As regras de saída podem ficar em mais de um lugar. Na Amazon EC2, por exemplo, verifique as regras de saída do security group, a network ACL da sub-rede, a rota para um NAT ou internet gateway e qualquer proxy na VPC.
• Relógio. Mantenha o NTP ativado no host. A validação de certificados falha com um relógio fora de sincronia.

O comando check testa cada um desses itens a partir do host.

Passo 1: Registre um novo agente no portal

Entre em portal.wasviking.com. Na barra lateral esquerda, em Infra, abra Sentinel Agents e clique em Add Sentinel Agent.

Defina o Agent display name: um rótulo amigável exibido no portal, por exemplo London - DMZ Scanner 01. Ele não é o hostname da máquina, precisa ser único dentro da sua organização e pode ser renomeado depois.

Clique em Create. O portal emite um token de bootstrap, exibido uma única vez. Copie-o e guarde-o em segurança. Se você o perder, revogue este registro de agente e crie um novo.

Passo 2: Baixe o pacote

Clique em Get Agent no topo da página Sentinel Agents. O portal entrega o pacote certo para a plataforma que você selecionar.

Verifique o download antes de instalar. A ação Verify download (SHA256 & signature) da janela modal fornece o checksum esperado e a assinatura para validar que o artefato não foi adulterado.

Passo 3: Instale e habilite o serviço

No Ubuntu / Debian:

sudo dpkg -i wasviking-sentinel_<version>_amd64.deb
sudo systemctl enable --now wasviking-sentinel

Substitua <version> pela versão da release exibida no portal. O pacote instala o agente em /opt/wasviking-sentinel/, cria a conta de serviço wasviking-sentinel e registra uma unit do systemd chamada wasviking-sentinel.

Iniciar o serviço antes do registro é o esperado. O serviço continua em execução e aguarda o registro. O status e o journal do serviço indicam o comando exato a executar em seguida.

Passo 4: Registre o agente

Registre o agente uma única vez, com o token de bootstrap do Passo 1. Execute o comando a partir de qualquer diretório:

sudo /opt/wasviking-sentinel/wasviking-sentinel register --token <YOUR_TOKEN_FROM_PORTAL>

O comando baixa os certificados de cliente do agente, grava esses certificados e a configuração em /opt/wasviking-sentinel/ e entrega os arquivos à conta de serviço. O serviço em execução detecta o registro e se conecta sozinho em cerca de 15 segundos. Não é preciso reiniciá-lo.

Se você encontrar instruções que executam ./wasviking-sentinel register de dentro do diretório do agente sem sudo, use o comando acima no lugar delas. A forma antiga falha por permissão de arquivo.

Em scripts de provisionamento, leia o token de uma variável de ambiente em vez de colá-lo na linha de comando:

export WASVIKING_BOOTSTRAP_TOKEN="<paste-from-portal>"
sudo /opt/wasviking-sentinel/wasviking-sentinel register --token "$WASVIKING_BOOTSTRAP_TOKEN"

Saída do registro:

Registering with WASViking API...
Certificates downloaded successfully into /opt/wasviking-sentinel/certs
Config written to /opt/wasviking-sentinel/configs/config.yaml
Agent files handed to the service account wasviking-sentinel
Next: sudo systemctl enable --now wasviking-sentinel (a service that is already running connects on its own within 15 seconds)
Then confirm the tunnel with: sudo /opt/wasviking-sentinel/wasviking-sentinel check

A chave privada nunca sai do host. O certificado da CA, o certificado de cliente e a chave de cliente são gravados em /opt/wasviking-sentinel/certs/ e pertencem à conta de serviço:

sudo ls -l /opt/wasviking-sentinel/certs

-rw-r--r--  wasviking-sentinel wasviking-sentinel  ca.crt
-rw-r--r--  wasviking-sentinel wasviking-sentinel  client.crt
-rw-------  wasviking-sentinel wasviking-sentinel  client.key

Passo 5: Confirme que o agente está conectado

sudo systemctl status wasviking-sentinel
sudo /opt/wasviking-sentinel/wasviking-sentinel status

• No status do serviço, as linhas mais recentes incluem Tunnel connected to sentinel.wasviking.com:443.
• O status mostra o estado do agente e, enquanto o túnel estiver fora do ar, o último erro de conexão.
• No portal, o agente aparece como Active na página Sentinel Agents em poucos segundos.

Se algum dos três não corresponder ao esperado, execute o comando check.

O arquivo de configuração

O register grava /opt/wasviking-sentinel/configs/config.yaml:

grpc_server: sentinel.wasviking.com
agent_hostname: dmz-scanner-01
agent_id: ""
use_tls: true
tls_ca_cert: certs/ca.crt
tls_cert: certs/client.crt
tls_key: certs/client.key
use_mtls: true
log_path: logs/sentinel_agent.log

O agent_id fica vazio até a primeira execução. O serviço o preenche automaticamente e o persiste de volta no arquivo. No caso comum, você não precisa editar este arquivo à mão.

# After the first run, agent_id is filled in:
agent_id: 56b3bd08aa4d5201edafd434740d9c140c1e477742d47360d71a76842b09ec21  # auto-generated on first run, do not edit

Status do agente

Em Sentinel Agents, cada agente mostra um destes status:

Os contadores no topo da página resumem o parque: Total · Active · Pending · Offline · Revoked.

Se o agente continuar em Pending

Se um agente permanecer em Pending por mais de alguns minutos, execute a verificação no host:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

O veredito indica a causa e o próximo passo. As causas mais comuns são um agente que nunca foi registrado, um serviço que não consegue ler os seus arquivos, saída TCP 443 para sentinel.wasviking.com bloqueada, inspeção de TLS no caminho e um relógio fora de sincronia. Veja Solução de problemas com o comando check.

Como o portal lista os agentes

Em Infra → Sentinel Agents, a lista Scan Tunnels mostra:

Os agentes conectados vêm primeiro, depois os que pedem atenção, os que ainda aguardam o registro e os revogados. Clique no cabeçalho de uma coluna para ordenar a lista por ela e clique de novo para inverter a ordem; Status volta à ordem padrão.

Dispare o seu primeiro scan interno

Com o agente Active, crie um alvo cuja URL só resolve dentro da sua rede. Na tela New Scan, o agente aparece no seletor de roteamento (Execution Mode). Escolha-o, configure a autenticação, se necessário, e inicie o scan. Todos os analisadores roteiam as suas sondagens HTTP pelo túnel.

Consulte Scans internos para o passo a passo completo.

Rotação e revogação de certificados

As duas são ações do operador no portal, sem nenhuma alteração no host.

• Rotação. Nas ações da linha do agente, clique em Rotate certificate. O portal emite um novo conjunto de certificados; o agente o adota na próxima reconexão. O certificado anterior é revogado imediatamente no lado da WASViking.
• Revogação. Clique em Revoke. O certificado é invalidado imediatamente; o status do agente muda para Revoked e o túnel cai. O registro do host continua na lista para fins de auditoria.

O certificado de cliente também é rotacionado automaticamente antes de expirar, como defesa em profundidade.

Atualização pelo portal

A partir da versão 1.23.0, um agente instalado pelo pacote Debian pode ser atualizado pelo portal. Você escolhe os agentes a atualizar, e cada um baixa, verifica e instala sozinho a nova release assinada. Não é preciso abrir uma sessão no host.

Requisitos

Atualize um agente ou todos

1. Abra Infra → Sentinel Agents e selecione a aba Scan Tunnels.
2. Clique em Update na linha do agente. Para atualizar todos os agentes que podem ser atualizados, clique em Update all (N) no cabeçalho da aba.
3. Revise a confirmação e confirme. O agente baixa o pacote assinado, verifica o pacote e o instala. O túnel dele reinicia e se reconecta em cerca de um minuto, e os scans que passam por ele ficam em pausa até lá.

A página recarrega sozinha enquanto a atualização roda, e a linha acompanha o processo até o fim. Para não pausar um scan interno longo, atualize o agente quando nenhum scan estiver passando por ele.

A atualização instala o pacote Debian padrão, o mesmo que você instala manualmente. O gerenciador de pacotes do host mostra a nova versão, e os certificados e a configuração são preservados:

dpkg -l wasviking-sentinel

Como ler a coluna Version

Na aba Scan Tunnels, a coluna Version mostra a versão que cada agente executa, por exemplo v1.23.0, com um selo:

O card Scan Tunnels no topo da página conta os agentes que ainda não estão na release atual, por exemplo 2 UPDATES AVAILABLE (vX.Y.Z).

Um agente anterior à 1.23.0 não informa a sua versão. A linha dele mostra Not reported e a nota Update once from the package to enable remote updates. Quando há uma atualização disponível, mas o agente não pode recebê-la pelo portal, uma nota abaixo do selo diz o motivo, por exemplo que o agente não está conectado ou que as atualizações remotas estão desligadas naquele host. A página Details do agente mostra a mesma informação na linha Remote updates.

Como as atualizações remotas são protegidas

• Só pacotes assinados pela WASViking são instalados. O agente verifica a assinatura e o checksum do pacote. Um instalador separado, que roda com direitos de administrador no host, verifica os dois de novo antes de instalar qualquer coisa.
• Sem downgrade. Um pacote que não seja mais novo que a versão instalada é recusado.
• O agente continua sem privilégios. O agente segue rodando com a própria conta de serviço wasviking-sentinel. Só o instalador roda com direitos de administrador, e apenas para instalar um pacote verificado.
• Quem decide é o administrador do host. As atualizações remotas podem ser desligadas em qualquer host, como descrito abaixo.

Como desligar as atualizações remotas em um host

Um agente instalado pelo pacote aceita atualizações remotas. Um administrador do host pode desligá-las naquele host:

sudo systemctl mask wasviking-sentinel-update.path

A configuração é mantida nas atualizações do pacote. Enquanto as atualizações remotas estiverem desligadas, o portal mostra que elas estão desligadas naquele host e recusa a atualização informando esse motivo. As atualizações pelo pacote continuam funcionando.

Para ligar as atualizações remotas de novo:

sudo systemctl unmask wasviking-sentinel-update.path
sudo systemctl enable --now wasviking-sentinel-update.path

O comando check tem uma linha Remote updates que informa se o host aceita atualizações remotas e como terminou a última. Em um host em que elas estão desligadas:

  [INFO] Remote updates
         remote updates are turned off on this host (wasviking-sentinel-update.path is masked)
         Next step: To allow them again: sudo systemctl unmask wasviking-sentinel-update.path &&
         sudo systemctl enable --now wasviking-sentinel-update.path

Se uma atualização falhar

A linha mostra UPDATE FAILED com a causa em palavras simples abaixo do selo, por exemplo Download failed ou Package failed verification. View details abre:

• onde a atualização parou: pedida, entregue ao agente, baixada e verificada, instalada e reconectada;
• o que aconteceu e se o host ficou como estava;
• os próximos passos para essa causa, com os comandos para rodar no host e Retry update quando o agente pode receber a atualização agora;
• Technical details: uma referência, as versões, os horários e a mensagem original, que Copy details for support copia para um pedido de suporte.

No host, o log do instalador e a verificação trazem o detalhe completo:

sudo journalctl -u wasviking-sentinel-update -n 50
sudo /opt/wasviking-sentinel/wasviking-sentinel check

Corrija a causa e clique em Update de novo, ou atualize pelo pacote. Quando o download ou uma verificação falha, nada é instalado e o agente mantém a versão atual.

Atualização pelo pacote

Use o pacote para um agente que não pode ser atualizado pelo portal: um agente anterior à 1.23.0, um agente instalado de outra forma ou um host em que as atualizações remotas estão desligadas. Baixe o novo pacote em Get Agent e instale-o sobre o existente:

sudo dpkg -i wasviking-sentinel_<new-version>_amd64.deb
sudo systemctl enable --now wasviking-sentinel

A atualização preserva o certs/ e o configs/config.yaml, então o agente não precisa ser registrado de novo. O segundo comando garante que o serviço esteja habilitado e em execução na nova versão, e não muda nada quando ele já está. Em seguida, confirme o túnel com sudo /opt/wasviking-sentinel/wasviking-sentinel check. Quando o host passa a executar a 1.23.0 ou posterior pelo pacote Debian, as próximas atualizações podem ser feitas pelo portal.

Se você adicionou um override local do systemd para uma versão anterior, por exemplo para executar o agente como root, ele não é mais necessário: a versão atual roda com a conta wasviking-sentinel. A verificação o aponta como [WARN] Local service overrides e imprime o comando exato que o remove.

Saúde do host e do túnel

Quando os scans que passam por um túnel privado ficam lentos ou expiram, comece pelos detalhes desse túnel. Abra Infra → Sentinel Agents, selecione a aba Scan Tunnels e clique em Details na linha do agente. A seção Host and tunnel health mostra como o host está e quanto trabalho de scan o túnel está carregando.

O que o agente envia

A partir da versão 1.24.0, o agente envia um relatório por minuto enquanto o túnel dele está conectado. O relatório trafega pela conexão de saída que o agente já usa, então não há nada novo a liberar no firewall.

• O relatório traz números, além do nome do sistema operacional do host e da versão do kernel. A página Details mostra esses dados nas linhas Operating system e Kernel.
• Ele não traz conteúdo de requisições ou respostas, nem dados dos alvos, nem a lista de processos.
• Os relatórios são mantidos por sete dias.
• Os números do host são medidos no Linux. Um agente em execução no macOS, que é suportado para avaliação local, mostra apenas os números do agente e do túnel.

Em um agente mais antigo, a seção mostra Host and tunnel health needs a newer agent e leva você à página Sentinel Agents para atualizá-lo. Veja Atualização pelo portal, ou Atualização pelo pacote para um host que não aceita atualizações remotas.

Indicadores e gráficos

Uma linha de status informa quando chegou o último relatório. Os indicadores mostram o relatório mais recente:

Um indicador fica âmbar ou vermelho quando o valor passa de um nível de alerta.

Os gráficos abaixo dos indicadores acompanham os mesmos números ao longo do tempo:

Alterne a janela entre 1h, 24h e 7d. Enquanto a página está aberta, os gráficos são atualizados a cada minuto. Um trecho vazio em uma linha significa que o agente não enviou relatórios nesse período. Clique em um item da legenda para ocultar ou mostrar a linha correspondente.

Observações

Acima dos indicadores, a seção descreve em linguagem simples o que vê, na maior parte dos casos nos últimos 15 minutos:

A verificação embutida é executada no host:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

Como interpretar

• Tunnel busy perto de 100%. Os scans estão em fila naquele agente. Instale mais agentes que alcancem os mesmos alvos e distribua os alvos entre eles, ou agende os scans em horários diferentes.
• CPU ou memória do host altas. O host precisa de mais recursos ou de menos cargas de trabalho rodando ao lado do agente.
• Reconexões repetidas. A causa está no caminho de rede entre o host e a WASViking. A verificação indica a causa raiz e o próximo passo. Veja Solução de problemas com o comando check.

Desinstalação

sudo systemctl disable --now wasviking-sentinel
sudo dpkg -r wasviking-sentinel
sudo rm -rf /opt/wasviking-sentinel

No portal, use Revoke no registro do agente para que o CN do certificado deixe de ser aceito no lado da WASViking.

Solução de problemas com o comando check

O check é um diagnóstico somente leitura da instalação do agente e do caminho entre o host e a plataforma da WASViking. Execute-o quando um agente continuar em Pending, ficar Offline ou antes de acionar o suporte:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

Execute-o com sudo. Sem elevação, a verificação não consegue ler os arquivos do agente, e o relatório informa isso.

Como ler o relatório

O relatório começa com um veredito, a causa raiz mais provável e o próximo passo, na forma de um comando exato ou de uma configuração a mudar. Por exemplo, em uma instância em nuvem cujo tráfego de saída é descartado:

VERDICT: FAIL
  Root cause candidate: Tunnel endpoint TCP reachability. TCP connection to
  sentinel.wasviking.com:443 failed: connection timed out; the packets are being silently dropped,
  which is typical of a firewall, security group or egress filter.
  Next step: Allow outbound TCP 443 to sentinel.wasviking.com:443: the instance security group
  outbound rules, the subnet network ACL (including return traffic on ephemeral ports), the route to
  a NAT or internet gateway, and any proxy or network firewall in the VPC.

O veredito é PASS, WARN ou FAIL. Em seguida vêm três seções, e cada achado nelas é marcado como PASS, WARN, FAIL, INFO ou SKIP:

Teste de túnel ao vivo

Quando o túnel do próprio agente está fora do ar, a verificação abre por instantes o túnel com a identidade do agente para confirmar que a plataforma o aceita. Durante esses poucos segundos, o portal mostra o agente como Active. Um scan roteado para o agente durante o teste é respondido como não executado; inicie-o de novo depois. Use --no-tunnel para pular o teste, ou --tunnel para executá-lo mesmo quando o agente informa o túnel conectado.

Pacote de suporte

Cada execução grava dois arquivos no diretório atual: wasviking-sentinel-check_<host>_<timestamp>.json e wasviking-sentinel-check_<host>_<timestamp>.txt. Eles são criados com modo 0600, pertencem à sua conta mesmo quando você executa a verificação com sudo e não contêm tokens nem chaves privadas. Envie os dois arquivos ao suporte da WASViking: eles permitem que a equipe analise o host sem uma sessão nele.

Opções e códigos de saída

O código de saída é 0 quando o agente está saudável, 1 com avisos e 2 com falhas, de modo que um script de provisionamento pode parar em uma verificação com falha.

Problemas comuns

Se o veredito for PASS e o portal ainda mostrar o agente como Pending ou Offline, envie o pacote de suporte ao suporte da WASViking.