ramonvermeulen/whosthereFerramenta de descoberta de rede local com uma Interface de Utilizador de Terminal (TUI) interativa escrita em Go. Descubra, explore e compreenda a sua LAN de forma intuitiva. Toc Toc.. quem está aí? 🚪
# Whosthere
[](https://go.dev/doc/devel/release)
[](LICENSE)
[](https://github.com/ramonvermeulen/whosthere/releases)
[](https://github.com/ramonvermeulen/whosthere/releases)
[](https://github.com/ramonvermeulen/whosthere)
Ferramenta de descoberta de Rede Local (LAN) com uma Interface de Usuário de Terminal (TUI) interativa escrita em Go.
Descubra, explore e entenda sua LAN de forma intuitiva.
O Whosthere realiza **varreduras concorrentes e sem privilégios** usando scanners [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS)
e [**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol). Além disso, ele varre a
sub-rede local tentando conexões TCP/UDP para acionar a resolução ARP, e então lê o
[**cache ARP**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) para identificar dispositivos na sua Rede Local.
Essa técnica preenche o cache ARP sem exigir privilégios elevados. Todos os dispositivos descobertos são enriquecidos com
consultas [**OUI**](https://standards-oui.ieee.org/) para exibir fabricantes quando disponíveis.
O Whosthere oferece uma maneira amigável e intuitiva de responder à pergunta que todo administrador de rede faz: "Quem está na minha rede?"
## Recursos
- **TUI Interativa:** Navegue e explore os dispositivos descobertos de forma intuitiva.
- **Rápido e Concorrente:** Aproveita múltiplos métodos de descoberta simultaneamente.
- **Não Requer Privilégios Elevados:** Executa inteiramente no espaço do usuário.
- **Enriquecimento de Dispositivos:** Usa consulta [**OUI**](https://standards-oui.ieee.org/) para mostrar os fabricantes dos dispositivos.
- **Scanner de Portas Integrado:** Descoberta opcional de serviços em hosts encontrados (escaneie apenas 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 configuração YAML.
## Instalação
Via [**Homebrew**](https://brew.sh/) com `brew`:
```bash
brew install whosthere
```
No [**NixOS**](https://nixos.org/) com `nix`:
```bash
nix profile install nixpkgs#whosthere
```
No [**Arch Linux**](https://archlinux.org/) com `yay`:
```bash
yay -S whosthere-bin
```
Se o seu gerenciador de pacotes não estiver listado, você sempre pode instalar com [**Go**](https://go.dev/):
```bash
go install github.com/ramonvermeulen/whosthere@latest
```
Ou **compilar a partir do código-fonte**:
```bash
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**](https://github.com/ramonvermeulen/whosthere/releases).
## Uso
Execute a TUI para descoberta interativa:
```bash
whosthere
```
Execute como CLI para fazer uma única varredura e exibir os resultados:
```bash
whosthere scan -t 5
```
Exporte os resultados para um arquivo JSON:
```bash
whosthere scan -t 5 --json --pretty > devices.json
```
Execute como daemon com API HTTP:
```bash
whosthere daemon --port=8080
```
Importe aliases em massa a partir de um arquivo, ou exporte os atuais:
```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```
Opções adicionais de linha de comando podem ser encontradas executando:
```bash
whosthere --help
```
## Atalhos de teclado (TUI)
| Tecla | Ação |
| ------------------ | --------------------------- |
| `/` | Iniciar busca por regex |
| `k` | Para cima |
| `j` | Para baixo |
| `g` | Ir para o topo |
| `G` | Ir para o final |
| `y` | Copiar IP do dispositivo selecionado |
| `Y` | Copiar MAC do dispositivo selecionado |
| `enter` | Mostrar detalhes do dispositivo |
| `CTRL+t` | Alternar seletor de tema |
| `CTRL+i` | Alternar seletor de interface |
| `CTRL+c`/`q` | Parar aplicação |
| `ESC` | Limpar busca / Voltar |
| `p` (visualização de detalhes) | Iniciar varredura de portas no dispositivo |
| `tab` (visualização modal) | Alternar seleção de botão |
## Configuração
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 as flags disponíveis.
1. **Variáveis de ambiente** - Prefixo `WHOSTHERE__`. Veja [**Configuração via Variáveis de Ambiente**](#configuração-via-variáveis-de-ambiente).
1. **Arquivo de configuração** - Arquivo de configuração YAML. Veja [**Arquivo de Configuração**](#arquivo-de-configuração).
1. **Valores padrão** - Padrões de fallback. Veja `DefaultConfig()` em [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go).
### Arquivo de Configuração
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`
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (se `XDG_CONFIG_HOME` estiver definido)
1. `~/.config/whosthere/config.yaml` (local padrão)
**Exemplo de configuração:**
```yaml
# Uncomment the next line to configure a specific network interface - uses OS default if not set
# network_interface: eth0
# When enabled, devices from all network interfaces are shown and persist when switching interfaces
# Note: if two interfaces share the same subnet (e.g. both use 192.168.1.x), devices may get merged
# since they are identified by IP address. Use with caution on overlapping subnets.
all_interfaces: false
# Optional IPv4 CIDR subnets to sweep. When set, the sweeper skips the auto-detected interface subnet unless it is listed here.
# target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]
# WARNING: scanning subnets larger than /16 sends packets to 65535+ IPs per subnet. Enable only if you understand the traffic implications. Consider using smaller /24 subnets for targeted scanning.
# scan_large_subnets: false
# How often to run discovery scans
scan_interval: 20s
# Maximum timeout for each scan, recommended to be less than the scan interval
scan_timeout: 10s
scanners:
mdns:
enabled: true
ssdp:
enabled: true
arp:
enabled: true
sweeper:
enabled: true
interval: 5m
timeout: 20s
port_scanner:
timeout: 5s
# List of TCP ports to scan on discovered devices
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:
# When disabled, the TUI will use the terminal it's default ANSI colors
# Also see the NO_COLOR environment variable to completely disable ANSI colors
enabled: true
# See the complete list of available themes at https://github.com/ramonvermeulen/whosthere/tree/main/internal/ui/theme/theme.go
# Set name to "custom" to use the custom colors below
# For any color that is not configured it will take the default theme value as fallback
name: default
# Disable ANSI colors completely, overrides theme.enabled
# Can also be set via NO_COLOR or WHOSTHERE__THEME__NO_COLOR environment variables
# no_color: false
# Custom theme colors (uncomment and set name: custom to use)
# 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"
aliases:
# Uncomment to import aliases.yaml into the local database on startup (only when it changed)
# auto_import: false
# Override the aliases file path - defaults to the app config directory
# file: "/path/to/aliases.yaml"
```
## Variáveis de Ambiente
### Variáveis de Ambiente Gerais
| Variável | Descrição |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | Caminho para o arquivo de configuração, para poder sobrescrever o local padrão. |
| `WHOSTHERE_LOG` | Define o nível de log (ex.: `debug`, `info`, `warn`, `error`). Padrão é `info`. |
| `NO_COLOR` | Desabilita cores ANSI na TUI. |
### Configuração via Variáveis de Ambiente
Qualquer opção de configuração disponível na configuração YAML pode ser definida via variáveis de ambiente usando o
prefixo `WHOSTHERE__` (observe o sublinhado duplo). Chaves de configuração aninhadas são separadas por sublinhados duplos, e
as chaves não diferenciam maiúsculas de minúsculas.
Exemplos:
- `WHOSTHERE__SPLASH__ENABLED=false` - Desabilita a tela de splash, equivalente a `splash.enabled: false` na configuração YAML
- `WHOSTHERE__SPLASH__DELAY=2s` - Define o atraso da tela de splash para 2 segundos, equivalente a `splash.delay: 2s` na configuração YAML
- `WHOSTHERE__SCAN_INTERVAL=30s` - Define o intervalo de varredura para 30 segundos, equivalente a `scan_interval: 30s` na configuração YAML
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - Define as sub-redes alvo, equivalente a `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]` na configuração YAML
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - Desabilita o scanner mDNS, equivalente a `scanners.mdns.enabled: false` na configuração YAML
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - Define portas TCP personalizadas para escanear, equivalente a `port_scanner.tcp: [80, 443, 8080]` na configuração YAML
- `WHOSTHERE__THEME__NAME=cyberpunk` - Define o tema como cyberpunk, equivalente a `theme.name: cyberpunk` na configuração YAML
## Aliases de dispositivos
Os aliases ficam em um banco de dados local [bbolt](https://github.com/etcd-io/bbolt) no diretório de estado. Para
definir muitos de uma vez, importe-os de um arquivo YAML (`aliases.yaml` no diretório de configuração; sobrescreva com
a chave de configuração `aliases.file` ou um argumento de caminho).
O arquivo é um **patch, não um espelho**, e é apenas lido: a importação faz upsert dos MACs que ele contém
e deixa os outros intactos, e edições na TUI **nunca são gravadas de volta no arquivo**. Use `export` para
regenerá-lo.
```yaml
version: 1
aliases:
aa:bb:cc:dd:ee:ff: "Living Room TV"
de:ad:be:ef:00:01: "Office Printer"
```
- `version` é a versão do formato do arquivo; use `1` (arquivos sem ela assumem 1).
- MACs são aceitos em qualquer formato comum e normalizados, então `AA:BB:CC:DD:EE:FF`, `aa-bb-cc-dd-ee-ff`
e `aabbccddeeff` são equivalentes. Um alias vazio (`""`) limpa um.
- MACs inválidos são ignorados e reportados; o restante da importação ainda é concluído.
```bash
whosthere aliases import # from the default location
whosthere aliases import ./aliases.yaml
whosthere aliases export # to the default location
whosthere aliases export --stdout # to stdout
```
Opte por importar na inicialização com `aliases.auto_import: true`. O arquivo tem seu hash verificado e só é
reimportado quando mudou, então um arquivo intocado nunca sobrescreve suas edições na TUI — mas um **arquivo
alterado sobrescreve** os aliases de todos os MACs que ele contém. Mantenha aliases apenas da TUI fora do arquivo,
ou faça `export` após editar para mantê-lo sincronizado.
## API HTTP do modo daemon
Ao executar o Whosthere em modo daemon, ele expõe uma API HTTP muito simples com os seguintes endpoints:
| Método | Endpoint | Descrição |
| ------ | -------------- | ---------------------------------- |
| GET | `/devices` | Obter lista de todos os dispositivos descobertos |
| GET | `/device/{ip}` | Obter detalhes de um dispositivo específico |
| GET | `/health` | Verificação de saúde |
## Temas
O tema pode ser configurado via arquivo de configuração, ou em tempo de execução via o atalho de teclado `CTRL+t`.
Uma lista completa dos temas disponíveis pode ser encontrada [**aqui**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go), sinta-se à vontade para abrir um PR para adicionar seu próprio tema!
Exemplo de configuração de tema:
```yaml
theme:
enabled: true
name: cyberpunk
```
Quando o `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.
## Logging
Os logs são gravados 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 executando em modo TUI, os logs também são gravados no console.
## Plataformas
O Whosthere é suportado nas seguintes plataformas:
- [x] Linux
- [x] macOS
- [x] Windows
## Problemas Conhecidos
Para a funcionalidade de área de transferência funcionar, é usado um [**fork do go-clipboard**](https://github.com/dece2183/go-clipboard).
Certifique-se de ter a ferramenta de cópia apropriada instalada para o seu sistema operacional:
| SO | Ferramentas de cópia suportadas |
| -------------------------------------- | -------------------------------------------- |
| Darwin | `pbcopy` |
| Windows | `clip.exe` |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`, `xclip` <br> Wayland: `wl-copy` |
## Aviso Legal
O Whosthere é destinado 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 rede doméstica. Embora seja 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 usar ferramentas profissionais estabelecidas com suporte formal.
## Contribuindo
Contribuições e sugestões como solicitações de recursos, relatórios de bugs ou melhorias são bem-vindas!
Sinta-se à vontade para abrir issues ou enviar pull requests no repositório do GitHub.
Certifique-se de discutir quaisquer mudanças importantes em uma issue do GitHub antes de implementá-las.