Whosthere

Ferramenta de descoberta de rede local com interface de usuário terminal interativa (TUI) escrita em Go. Descubra, explore e compreenda sua LAN de forma intuitiva.

Whosthere realiza varreduras simultâneas sem privilégios usando scanners mDNS e SSDP. Além disso, vasculha a sub-rede local tentando conexões TCP/UDP para disparar resolução ARP e em seguida lê a cache ARP para identificar dispositivos na sua rede local. Essa técnica povoa a cache ARP sem exigir privilégios elevados. Todos os dispositivos descobertos são enriquecidos com consultas OUI para exibir fabricantes quando disponíveis.

Whosthere oferece uma maneira amigável e intuitiva de responder à pergunta que todo administrador de rede faz: "Quem está aí na minha rede?"

Funcionalidades

• TUI Interativa: Navegue e explore dispositivos descobertos de forma intuitiva.
• Rápida e Concorrente: Utiliza múltiplos métodos de descoberta simultaneamente.
• Sem Privilégios Elevados: Executa inteiramente no espaço do usuário.
• Enriquecimento de Dispositivos: Usa consulta OUI para exibir fabricantes dos dispositivos.
• Scanner de Portas Integrado: Descoberta opcional de serviços em hosts encontrados (apenas escaneie dispositivos com permissão!).
• Modo Daemon com API HTTP: Execute em segundo plano e integre com outras ferramentas.
• Temas e Configuração: Personalize a aparência e o comportamento via arquivo YAML.

Instalação

Via Homebrew com brew:

brew install whosthere

No NixOS com nix:

nix profile install nixpkgs#whosthere

No Arch Linux com yay:

yay -S whosthere-bin

Se seu gerenciador de pacotes não estiver listado, você sempre pode instalar com Go:

go install github.com/ramonvermeulen/whosthere@latest

Ou compilar a partir do código fonte:

git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build

Além disso, você pode baixar binários pré-compilados na página de releases.

Uso

Execute a TUI para descoberta interativa:

whosthere

Execute como CLI para fazer uma varredura única e exibir resultados:

whosthere scan -t 5

Saída dos resultados em um arquivo JSON:

whosthere scan -t 5 --json --pretty > devices.json

Execute como daemon com API HTTP:

whosthere daemon --port=8080

Opções adicionais de linha de comando podem ser encontradas executando:

whosthere --help

Atalhos de teclado (TUI)

Configuração

Whosthere suporta múltiplos métodos de configuração com a seguinte precedência (da maior para a menor):

1. Flags de linha de comando - Maior prioridade. Veja whosthere --help para flags disponíveis.
2. Variáveis de ambiente - Prefixo WHOSTHERE__. Veja Configuração via Variáveis de Ambiente.
3. Arquivo de configuração - Arquivo YAML. Veja Arquivo de Configuração.
4. Valores padrão - Fallback padrão. Veja DefaultConfig() em config.go.

Arquivo de Configuração

Whosthere procura o arquivo de configuração na seguinte ordem, usando o primeiro encontrado:

1. Caminho especificado via flag --config ou variável de ambiente WHOSTHERE_CONFIG
2. $XDG_CONFIG_HOME/whosthere/config.yaml (se XDG_CONFIG_HOME estiver definido)
3. ~/.config/whosthere/config.yaml (localização padrão)

Exemplo de configuração:

# Descomente a linha abaixo para configurar uma interface de rede específica - usa o padrão do sistema se não definido
# network_interface: eth0

# Quando habilitado, dispositivos de todas as interfaces de rede são exibidos e persistem ao alternar interfaces
# Nota: se duas interfaces compartilharem a mesma sub-rede (ex.: ambas usam 192.168.1.x), os dispositivos podem ser mesclados
# pois são identificados pelo endereço IP. Use com cuidado em sub-redes sobrepostas.
all_interfaces: false

# Com que frequência executar varreduras de descoberta
scan_interval: 20s

# Tempo máximo de espera para cada varredura, recomendado ser menor que o intervalo de varredura
scan_timeout: 10s

scanners:
  mdns:
    enabled: true
  ssdp:
    enabled: true
  arp:
    enabled: true

sweeper:
  enabled: true
  interval: 5m
  timeout: 20s

port_scanner:
  timeout: 5s
  # Lista de portas TCP a serem varridas nos dispositivos descobertos
  tcp: [21, 22, 23, 25, 80, 110, 135, 139, 143, 389, 443, 445, 993, 995, 1433, 1521, 3306, 3389, 5432, 5900, 8080, 8443, 9000, 9090, 9200, 9300, 10000, 27017]

splash:
  enabled: true
  delay: 1s

theme:
  # Quando desabilitado, a TUI usará as cores ANSI padrão do terminal
  # Veja também a variável de ambiente NO_COLOR para desabilitar completamente as cores ANSI
  enabled: true

  # Veja a lista completa de temas disponíveis em https://github.com/ramonvermeulen/whosthere/tree/main/internal/ui/theme/theme.go
  # Defina name como "custom" para usar as cores personalizadas abaixo
  # Para qualquer cor não configurada, o valor padrão do tema será usado como fallback
  name: default

  # Desabilita cores ANSI completamente, sobrescreve theme.enabled
  # Também pode ser definido via NO_COLOR ou WHOSTHERE__THEME__NO_COLOR
  # no_color: false

  # Cores do tema personalizado (descomente e defina name: custom para usar)
  # primitive_background_color: "#000a1a"
  # contrast_background_color: "#001a33"
  # more_contrast_background_color: "#003366"
  # border_color: "#0088ff"
  # title_color: "#00ffff"
  # graphics_color: "#00ffaa"
  # primary_text_color: "#cceeff"
  # secondary_text_color: "#6699ff"
  # tertiary_text_color: "#ffaa00"
  # inverse_text_color: "#000a1a"
  # contrast_secondary_text_color: "#88ddff"

Variáveis de Ambiente

Variáveis de Ambiente Gerais

Configuração via Variáveis de Ambiente

Qualquer opção de configuração disponível no YAML pode ser definida via variáveis de ambiente usando o prefixo WHOSTHERE__ (note o sublinhado duplo). Chaves de configuração aninhadas são separadas por sublinhado duplo e as chaves não diferenciam maiúsculas de minúsculas.

Exemplos:

• WHOSTHERE__SPLASH__ENABLED=false - Desabilita a tela de abertura, equivalente a splash.enabled: false no YAML
• WHOSTHERE__SPLASH__DELAY=2s - Define o atraso da tela de abertura para 2 segundos, equivalente a splash.delay: 2s no YAML
• WHOSTHERE__SCAN_INTERVAL=30s - Define o intervalo de varredura para 30 segundos, equivalente a scan_interval: 30s no YAML
• WHOSTHERE__SCANNERS__MDNS__ENABLED=false - Desabilita o scanner mDNS, equivalente a scanners.mdns.enabled: false no YAML
• WHOSTHERE__PORT_SCANNER__TCP=80,443,8080 - Define portas TCP personalizadas para varredura, equivalente a port_scanner.tcp: [80, 443, 8080] no YAML
• WHOSTHERE__THEME__NAME=cyberpunk - Define o tema como cyberpunk, equivalente a no YAML

Modo Daemon API HTTP

Quando executando Whosthere em modo daemon, ele expõe uma API HTTP muito simples com os seguintes endpoints:

Temas

O tema pode ser configurado via arquivo de configuração, ou em tempo de execução através do atalho CTRL+t. Uma lista completa de temas disponíveis pode ser encontrada aqui; sinta-se à vontade para abrir um PR para adicionar seu próprio tema!

Exemplo de configuração de tema:

theme:
  enabled: true
  name: cyberpunk

Quando name é definido como custom, as outras opções de cor podem ser usadas para criar seu próprio tema personalizado. Quando a opção enabled é definida como false, a TUI usará as cores ANSI padrão do terminal. Quando a variável de ambiente NO_COLOR está definida, todas as cores ANSI serão desabilitadas.

Logs

Os logs são escritos no diretório de estado da aplicação:

• $XDG_STATE_HOME/whosthere/app.log (se XDG_STATE_HOME estiver definido)
• ~/.local/state/whosthere/app.log (fallback Linux/MacOS)
• %LOCALAPPDATA%/whosthere/app.log (fallback Windows)

Quando não estiver no modo TUI, os logs também são escritos no console.

Plataformas

Whosthere é suportado nas seguintes plataformas:

• Linux
• macOS
• Windows

Problemas Conhecidos

Para que a funcionalidade de área de transferência funcione, é utilizado um fork do go-clipboard. Certifique-se de ter a ferramenta de cópia apropriada instalada para seu sistema operacional:

Aviso Legal

Whosthere destina-se ao uso em redes onde você tem permissão para realizar descoberta e varredura de rede, como sua própria rede doméstica. A varredura não autorizada de redes pode ser ilegal e antiética. Sempre obtenha autorização adequada antes de usar esta ferramenta em qualquer rede.

Esta ferramenta foi criada principalmente para fins educacionais e exploração de redes domésticas. Embora funcional e útil, não deve ser considerada uma solução profissional de monitoramento de rede. Os resultados são baseados em técnicas de varredura sem privilégios e podem não ser abrangentes. Para análise crítica de rede ou avaliações de segurança, considere o uso de ferramentas profissionais estabelecidas com suporte formal.

Contribuindo

Contribuições e sugestões como solicitações de funcionalidades, relatórios de bugs ou melhorias são bem-vindas! Fique à vontade para abrir issues ou enviar pull requests no repositório GitHub. Por favor, discuta quaisquer mudanças importantes em uma issue do GitHub antes de implementá-las.