ramonvermeulen/whosthereHerramienta de descubrimiento de red de área local con una interfaz de usuario de terminal interactiva (TUI) escrita en Go. Descubre, explora y comprende tu LAN de forma intuitiva. Toc, toc.. ¿quién es? 🚪
# 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)
Herramienta de descubrimiento de Red de Área Local con una Interfaz de Usuario de Terminal (TUI) interactiva escrita en Go.
Descubre, explora y comprende tu LAN de forma intuitiva.
Whosthere realiza **escaneos concurrentes sin privilegios** utilizando escáneres [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS)
y [**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol). Además, barre la
subred local intentando conexiones TCP/UDP para activar la resolución ARP, y luego lee la
[**caché ARP**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) para identificar dispositivos en tu Red de Área Local.
Esta técnica llena la caché ARP sin requerir privilegios elevados. Todos los dispositivos descubiertos se enriquecen con
búsquedas [**OUI**](https://standards-oui.ieee.org/) para mostrar los fabricantes cuando estén disponibles.
Whosthere proporciona una forma amigable e intuitiva de responder a la pregunta que todo administrador de red se hace: "¿Quién está ahí en mi red?"
## Características
- **TUI Interactiva:** Navega y explora los dispositivos descubiertos de forma intuitiva.
- **Rápido y Concurrente:** Aprovecha múltiples métodos de descubrimiento simultáneamente.
- **No Requiere Privilegios Elevados:** Se ejecuta completamente en espacio de usuario.
- **Enriquecimiento de Dispositivos:** Utiliza búsqueda [**OUI**](https://standards-oui.ieee.org/) para mostrar los fabricantes de dispositivos.
- **Escáner de Puertos Integrado:** Descubrimiento de servicios opcional en los hosts encontrados (¡solo escanea dispositivos con permiso!).
- **Modo Daemon con API HTTP:** Ejecútalo en segundo plano e intégralo con otras herramientas.
- **Temas y Configuración:** Personaliza la apariencia y el comportamiento mediante configuración YAML.
## Instalación
Vía [**Homebrew**](https://brew.sh/) con `brew`:
```bash
brew install whosthere
```
En [**NixOS**](https://nixos.org/) con `nix`:
```bash
nix profile install nixpkgs#whosthere
```
En [**Arch Linux**](https://archlinux.org/) con `yay`:
```bash
yay -S whosthere-bin
```
Si tu gestor de paquetes no está listado, siempre puedes instalar con [**Go**](https://go.dev/):
```bash
go install github.com/ramonvermeulen/whosthere@latest
```
O **compilar desde el código fuente**:
```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```
Además, puedes descargar binarios precompilados desde la
[**página de releases**](https://github.com/ramonvermeulen/whosthere/releases).
## Uso
Ejecuta la TUI para descubrimiento interactivo:
```bash
whosthere
```
Ejecuta como cli para hacer un único escaneo y mostrar los resultados:
```bash
whosthere scan -t 5
```
Muestra los resultados en un archivo JSON:
```bash
whosthere scan -t 5 --json --pretty > devices.json
```
Ejecuta como daemon con API HTTP:
```bash
whosthere daemon --port=8080
```
Importa alias en masa desde un archivo, o exporta los actuales:
```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```
Se pueden encontrar opciones adicionales de línea de comandos ejecutando:
```bash
whosthere --help
```
## Atajos de teclado (TUI)
| Tecla | Acción |
| ------------------ | --------------------------- |
| `/` | Iniciar búsqueda regex |
| `k` | Arriba |
| `j` | Abajo |
| `g` | Ir al principio |
| `G` | Ir al final |
| `y` | Copiar IP del dispositivo seleccionado |
| `Y` | Copiar MAC del dispositivo seleccionado |
| `enter` | Mostrar detalles del dispositivo |
| `CTRL+t` | Alternar selector de tema |
| `CTRL+i` | Alternar selector de interfaz |
| `CTRL+c`/`q` | Detener la aplicación |
| `ESC` | Limpiar búsqueda / Volver atrás |
| `p` (vista de detalles) | Iniciar escaneo de puertos en el dispositivo |
| `tab` (vista modal) | Cambiar selección de botón |
## Configuración
Whosthere admite múltiples métodos de configuración con la siguiente precedencia (de mayor a menor):
1. **Flags de línea de comandos** - Máxima prioridad. Consulta `whosthere --help` para ver los flags disponibles.
1. **Variables de entorno** - Prefijo `WHOSTHERE__`. Consulta [**Configuración mediante Variables de Entorno**](#configuración-mediante-variables-de-entorno).
1. **Archivo de configuración** - Archivo de configuración YAML. Consulta [**Archivo de Configuración**](#archivo-de-configuración).
1. **Valores por defecto** - Valores predeterminados de respaldo. Consulta `DefaultConfig()` en [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go).
### Archivo de Configuración
Whosthere busca el archivo de configuración en el siguiente orden, usando el primero que encuentre:
1. Ruta especificada mediante el flag `--config` o la variable de entorno `WHOSTHERE_CONFIG`
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (si `XDG_CONFIG_HOME` está establecido)
1. `~/.config/whosthere/config.yaml` (ubicación por defecto)
**Configuración de ejemplo:**
```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"
```
## Variables de Entorno
### Variables de Entorno Generales
| Variable | Descripción |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | Ruta al archivo de configuración, para poder sobrescribir la ubicación por defecto. |
| `WHOSTHERE_LOG` | Establece el nivel de log (p. ej., `debug`, `info`, `warn`, `error`). Por defecto `info`. |
| `NO_COLOR` | Desactiva los colores ANSI en la TUI. |
### Configuración mediante Variables de Entorno
Cualquier opción de configuración disponible en la configuración YAML puede establecerse mediante variables de entorno usando el
prefijo `WHOSTHERE__` (nótese el doble guion bajo). Las claves de configuración anidadas se separan por dobles guiones bajos, y
las claves no distinguen entre mayúsculas y minúsculas.
Ejemplos:
- `WHOSTHERE__SPLASH__ENABLED=false` - Desactiva la pantalla de bienvenida, equivalente a `splash.enabled: false` en la configuración YAML
- `WHOSTHERE__SPLASH__DELAY=2s` - Establece el retardo de la pantalla de bienvenida a 2 segundos, equivalente a `splash.delay: 2s` en la configuración YAML
- `WHOSTHERE__SCAN_INTERVAL=30s` - Establece el intervalo de escaneo a 30 segundos, equivalente a `scan_interval: 30s` en la configuración YAML
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - Establece las subredes objetivo, equivalente a `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]` en la configuración YAML
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - Desactiva el escáner mDNS, equivalente a `scanners.mdns.enabled: false` en la configuración YAML
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - Establece puertos TCP personalizados a escanear, equivalente a `port_scanner.tcp: [80, 443, 8080]` en la configuración YAML
- `WHOSTHERE__THEME__NAME=cyberpunk` - Establece el tema a cyberpunk, equivalente a `theme.name: cyberpunk` en la configuración YAML
## Alias de dispositivos
Los alias residen en una base de datos local [bbolt](https://github.com/etcd-io/bbolt) en el directorio de estado. Para
establecer muchos a la vez, impórtalos desde un archivo YAML (`aliases.yaml` en el directorio de configuración; sobrescribe con
la clave de configuración `aliases.file` o un argumento de ruta).
El archivo es un **parche, no un espejo**, y solo se lee: la importación inserta o actualiza las MACs que contiene
y deja las demás intactas, y las ediciones de la TUI **nunca se escriben de vuelta al archivo**. Usa `export` para
regenerarlo.
```yaml
version: 1
aliases:
aa:bb:cc:dd:ee:ff: "Living Room TV"
de:ad:be:ef:00:01: "Office Printer"
```
- `version` es la versión del formato del archivo; usa `1` (los archivos sin ella usan 1 por defecto).
- Las MACs se aceptan en cualquier formato común y se normalizan, por lo que `AA:BB:CC:DD:EE:FF`, `aa-bb-cc-dd-ee-ff`
y `aabbccddeeff` son equivalentes. Un alias vacío (`""`) elimina uno.
- Las MACs inválidas se omiten y se reportan; el resto de la importación continúa.
```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
```
Activa la importación al inicio con `aliases.auto_import: true`. El archivo se verifica mediante hash y solo
se reimporta cuando ha cambiado, por lo que un archivo sin modificar nunca sobrescribe tus ediciones de la TUI — pero un **archivo
modificado sí sobrescribe** los alias de cada MAC que contiene. Mantén los alias solo de la TUI fuera del archivo,
o usa `export` después de editar para mantenerlo sincronizado.
## API HTTP del modo daemon
Cuando se ejecuta Whosthere en modo daemon, expone una API HTTP muy simplista con los siguientes endpoints:
| Método | Endpoint | Descripción |
| ------ | -------------- | ---------------------------------- |
| GET | `/devices` | Obtener lista de todos los dispositivos descubiertos |
| GET | `/device/{ip}` | Obtener detalles de un dispositivo específico |
| GET | `/health` | Comprobación de estado |
## Temas
El tema se puede configurar mediante el archivo de configuración, o en tiempo de ejecución mediante el atajo de teclado `CTRL+t`.
Una lista completa de los temas disponibles se puede encontrar [**aquí**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go), ¡no dudes en abrir un PR para añadir tu propio tema!
Ejemplo de configuración de tema:
```yaml
theme:
enabled: true
name: cyberpunk
```
Cuando `name` se establece en `custom`, las otras opciones de color se pueden usar para crear tu propio tema personalizado.
Cuando la opción `enabled` se establece en `false`, la TUI usará los colores ANSI por defecto del terminal.
Cuando la variable de entorno `NO_COLOR` está establecida, todos los colores ANSI se desactivarán.
## Registro de logs
Los logs se escriben en el directorio de estado de la aplicación:
- `$XDG_STATE_HOME/whosthere/app.log` (si `XDG_STATE_HOME` está establecido)
- `~/.local/state/whosthere/app.log` (respaldo Linux/MacOS)
- `%LOCALAPPDATA%/whosthere/app.log` (respaldo Windows)
Cuando no se ejecuta en modo TUI, los logs también se escriben en la consola.
## Plataformas
Whosthere es compatible con las siguientes plataformas:
- [x] Linux
- [x] macOS
- [x] Windows
## Problemas Conocidos
Para que funcione la funcionalidad de portapapeles, se utiliza un [**fork de go-clipboard**](https://github.com/dece2183/go-clipboard).
Asegúrate de tener instalada la herramienta de copiado adecuada para tu sistema operativo:
| SO | Herramientas de copiado compatibles |
| -------------------------------------- | -------------------------------------------- |
| Darwin | `pbcopy` |
| Windows | `clip.exe` |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`, `xclip` <br> Wayland: `wl-copy` |
## Descargo de responsabilidad
Whosthere está destinado a usarse en redes donde tengas permiso para realizar descubrimiento y escaneo de red,
como tu propia red doméstica. El escaneo no autorizado de redes puede ser ilegal y poco ético.
Obtén siempre la autorización adecuada antes de usar esta herramienta en cualquier red.
Esta herramienta fue creada principalmente con fines educativos y para la exploración de redes domésticas. Aunque es funcional
y útil, no debe considerarse una solución de monitoreo de red de grado profesional. Los resultados se
basan en técnicas de escaneo sin privilegios y pueden no ser exhaustivos. Para análisis de red críticos
o evaluaciones de seguridad, considera usar herramientas profesionales establecidas con soporte formal.
## Contribuir
¡Las contribuciones y sugerencias como solicitudes de características, informes de errores o mejoras son bienvenidas!
No dudes en abrir issues o enviar pull requests en el repositorio de GitHub.
Por favor, asegúrate de discutir cualquier cambio importante en un issue de Github antes de implementarlo.