ramonvermeulen/whosthereStrumento di scoperta di reti locali (LAN) con un'interfaccia utente terminale interattiva (TUI) scritto in Go. Scopri, esplora e comprendi la tua LAN in modo intuitivo. Toc toc.. chi è? 🚪
# 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)
Strumento di discovery della Local Area Network con un'interfaccia utente a terminale (TUI) interattiva scritta in Go.
Scopri, esplora e comprendi la tua LAN in modo intuitivo.
Whosthere esegue **scansioni concorrenti e senza privilegi** utilizzando gli scanner [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS)
e [**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol). Inoltre, esegue una scansione della
sottorete locale tentando connessioni TCP/UDP per attivare la risoluzione ARP, quindi legge la
[**cache ARP**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) per identificare i dispositivi sulla tua Local Area Network.
Questa tecnica popola la cache ARP senza richiedere privilegi elevati. Tutti i dispositivi rilevati vengono arricchiti con
ricerche [**OUI**](https://standards-oui.ieee.org/) per mostrare i produttori quando disponibili.
Whosthere fornisce un modo semplice e intuitivo per rispondere alla domanda che ogni amministratore di rete si pone: "Chi c'è sulla mia rete?"
## Funzionalità
- **TUI interattiva:** Naviga ed esplora i dispositivi rilevati in modo intuitivo.
- **Veloce e concorrente:** Sfrutta più metodi di discovery simultaneamente.
- **Nessun privilegio elevato richiesto:** Funziona interamente nello spazio utente.
- **Arricchimento dei dispositivi:** Utilizza la ricerca [**OUI**](https://standards-oui.ieee.org/) per mostrare i produttori dei dispositivi.
- **Port Scanner integrato:** Discovery opzionale dei servizi sugli host trovati (scansiona solo i dispositivi per cui hai il permesso!).
- **Modalità Daemon con API HTTP:** Esegui in background e integra con altri strumenti.
- **Temi e configurazione:** Personalizza l'aspetto e il comportamento tramite configurazione YAML.
## Installazione
Tramite [**Homebrew**](https://brew.sh/) con `brew`:
```bash
brew install whosthere
```
Su [**NixOS**](https://nixos.org/) con `nix`:
```bash
nix profile install nixpkgs#whosthere
```
Su [**Arch Linux**](https://archlinux.org/) con `yay`:
```bash
yay -S whosthere-bin
```
Se il tuo gestore di pacchetti non è elencato, puoi sempre installare con [**Go**](https://go.dev/):
```bash
go install github.com/ramonvermeulen/whosthere@latest
```
Oppure **compila dai sorgenti**:
```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```
Inoltre, puoi scaricare binari precompilati dalla
[**pagina delle release**](https://github.com/ramonvermeulen/whosthere/releases).
## Utilizzo
Avvia la TUI per la discovery interattiva:
```bash
whosthere
```
Esegui come CLI per effettuare una singola scansione e mostrare i risultati:
```bash
whosthere scan -t 5
```
Esporta i risultati in un file JSON:
```bash
whosthere scan -t 5 --json --pretty > devices.json
```
Esegui come daemon con API HTTP:
```bash
whosthere daemon --port=8080
```
Importa alias in blocco da un file, oppure esporta quelli correnti:
```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```
Ulteriori opzioni da riga di comando sono disponibili eseguendo:
```bash
whosthere --help
```
## Scorciatoie da tastiera (TUI)
| Tasto | Azione |
| ------------------ | ------------------------------- |
| `/` | Avvia la ricerca regex |
| `k` | Su |
| `j` | Giù |
| `g` | Vai in cima |
| `G` | Vai in fondo |
| `y` | Copia l'IP del dispositivo selezionato |
| `Y` | Copia il MAC del dispositivo selezionato |
| `enter` | Mostra i dettagli del dispositivo |
| `CTRL+t` | Attiva/disattiva il selettore di tema |
| `CTRL+i` | Attiva/disattiva il selettore di interfaccia |
| `CTRL+c`/`q` | Arresta l'applicazione |
| `ESC` | Cancella la ricerca / Torna indietro |
| `p` (vista dettagli) | Avvia la scansione delle porte sul dispositivo |
| `tab` (vista modale) | Cambia la selezione del pulsante |
## Configurazione
Whosthere supporta diversi metodi di configurazione con la seguente precedenza (dalla più alta alla più bassa):
1. **Flag da riga di comando** - Priorità più alta. Vedi `whosthere --help` per i flag disponibili.
1. **Variabili d'ambiente** - Prefisso `WHOSTHERE__`. Vedi [**Configurazione tramite variabili d'ambiente**](#configurazione-tramite-variabili-dambiente).
1. **File di configurazione** - File di configurazione YAML. Vedi [**File di configurazione**](#file-di-configurazione).
1. **Valori predefiniti** - Valori di fallback predefiniti. Vedi `DefaultConfig()` in [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go).
### File di configurazione
Whosthere cerca il file di configurazione nel seguente ordine, utilizzando il primo trovato:
1. Percorso specificato tramite il flag `--config` o la variabile d'ambiente `WHOSTHERE_CONFIG`
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (se `XDG_CONFIG_HOME` è impostata)
1. `~/.config/whosthere/config.yaml` (posizione predefinita)
**Configurazione di esempio:**
```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"
```
## Variabili d'ambiente
### Variabili d'ambiente generali
| Variabile | Descrizione |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | Percorso del file di configurazione, per poter sovrascrivere la posizione predefinita. |
| `WHOSTHERE_LOG` | Imposta il livello di log (es. `debug`, `info`, `warn`, `error`). Predefinito a `info`. |
| `NO_COLOR` | Disabilita i colori ANSI nella TUI. |
### Configurazione tramite variabili d'ambiente
Qualsiasi opzione di configurazione disponibile nel file YAML può essere impostata tramite variabili d'ambiente usando il
prefisso `WHOSTHERE__` (nota il doppio underscore). Le chiavi di configurazione annidate sono separate da doppi underscore, e
le chiavi non sono sensibili alle maiuscole/minuscole.
Esempi:
- `WHOSTHERE__SPLASH__ENABLED=false` - Disabilita la schermata iniziale, equivalente a `splash.enabled: false` nella configurazione YAML
- `WHOSTHERE__SPLASH__DELAY=2s` - Imposta il ritardo della schermata iniziale a 2 secondi, equivalente a `splash.delay: 2s` nella configurazione YAML
- `WHOSTHERE__SCAN_INTERVAL=30s` - Imposta l'intervallo di scansione a 30 secondi, equivalente a `scan_interval: 30s` nella configurazione YAML
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - Imposta le sottoreti di destinazione, equivalente a `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]` nella configurazione YAML
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - Disabilita lo scanner mDNS, equivalente a `scanners.mdns.enabled: false` nella configurazione YAML
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - Imposta porte TCP personalizzate da scansionare, equivalente a `port_scanner.tcp: [80, 443, 8080]` nella configurazione YAML
- `WHOSTHERE__THEME__NAME=cyberpunk` - Imposta il tema a cyberpunk, equivalente a `theme.name: cyberpunk` nella configurazione YAML
## Alias dei dispositivi
Gli alias risiedono in un database locale [bbolt](https://github.com/etcd-io/bbolt) nella directory di stato. Per
impostarne molti contemporaneamente, importali da un file YAML (`aliases.yaml` nella directory di configurazione; sovrascrivibile con
la chiave di configurazione `aliases.file` o un argomento di percorso).
Il file è una **patch, non uno specchio**, ed è sempre e solo letto: l'importazione inserisce o aggiorna i MAC che contiene
e lascia gli altri intatti, e le modifiche dalla TUI **non vengono mai riscritte nel file**. Usa `export` per
rigenerarlo.
```yaml
version: 1
aliases:
aa:bb:cc:dd:ee:ff: "Living Room TV"
de:ad:be:ef:00:01: "Office Printer"
```
- `version` è la versione del formato del file; usa `1` (i file senza di essa predefiniscono a 1).
- I MAC sono accettati in qualsiasi formato comune e normalizzati, quindi `AA:BB:CC:DD:EE:FF`, `aa-bb-cc-dd-ee-ff`
e `aabbccddeeff` sono equivalenti. Un alias vuoto (`""`) ne cancella uno.
- I MAC non validi vengono saltati e segnalati; il resto dell'importazione viene comunque eseguito.
```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
```
Attiva l'importazione all'avvio con `aliases.auto_import: true`. Il file viene verificato tramite hash e reimportato
solo quando è cambiato, quindi un file non modificato non sovrascrive mai le tue modifiche dalla TUI — ma un **file
modificato sovrascrive** gli alias per ogni MAC che contiene. Mantieni gli alias creati solo dalla TUI fuori dal file,
oppure esegui `export` dopo la modifica per mantenerlo sincronizzato.
## API HTTP in modalità daemon
Quando Whosthere viene eseguito in modalità daemon, espone un'API HTTP molto semplice con i seguenti endpoint:
| Metodo | Endpoint | Descrizione |
| ------ | -------------- | ---------------------------------- |
| GET | `/devices` | Ottieni l'elenco di tutti i dispositivi rilevati |
| GET | `/device/{ip}` | Ottieni i dettagli di un dispositivo specifico |
| GET | `/health` | Controllo dello stato |
## Temi
Il tema può essere configurato tramite il file di configurazione, oppure a runtime tramite la scorciatoia `CTRL+t`.
Un elenco completo dei temi disponibili è disponibile [**qui**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go), sentiti libero di aprire una PR per aggiungere il tuo tema!
Esempio di configurazione del tema:
```yaml
theme:
enabled: true
name: cyberpunk
```
Quando `name` è impostato a `custom`, le altre opzioni di colore possono essere utilizzate per creare il tuo tema personalizzato.
Quando l'opzione `enabled` è impostata a `false`, la TUI utilizzerà i colori ANSI predefiniti del terminale.
Quando la variabile d'ambiente `NO_COLOR` è impostata, tutti i colori ANSI verranno disabilitati.
## Logging
I log vengono scritti nella directory di stato dell'applicazione:
- `$XDG_STATE_HOME/whosthere/app.log` (se `XDG_STATE_HOME` è impostata)
- `~/.local/state/whosthere/app.log` (fallback Linux/MacOS)
- `%LOCALAPPDATA%/whosthere/app.log` (fallback Windows)
Quando non si esegue in modalità TUI, i log vengono anche scritti sulla console.
## Piattaforme
Whosthere è supportato sulle seguenti piattaforme:
- [x] Linux
- [x] macOS
- [x] Windows
## Problemi noti
Per il funzionamento della funzionalità degli appunti, viene utilizzato un [**fork di go-clipboard**](https://github.com/dece2183/go-clipboard).
Assicurati di avere installato lo strumento di copia appropriato per il tuo sistema operativo:
| OS | Strumenti di copia supportati |
| -------------------------------------- | -------------------------------------------- |
| Darwin | `pbcopy` |
| Windows | `clip.exe` |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`, `xclip` <br> Wayland: `wl-copy` |
## Disclaimer
Whosthere è destinato all'uso su reti in cui hai il permesso di eseguire discovery e scansione di rete,
come la tua rete domestica. La scansione non autorizzata di reti può essere illegale e non etica.
Ottieni sempre l'autorizzazione appropriata prima di utilizzare questo strumento su qualsiasi rete.
Questo strumento è stato creato principalmente per scopi educativi e per l'esplorazione della rete domestica. Pur essendo funzionale
e utile, non dovrebbe essere considerato una soluzione professionale di monitoraggio della rete. I risultati si
basano su tecniche di scansione senza privilegi e potrebbero non essere completi. Per analisi di rete critiche
o valutazioni di sicurezza, considera l'utilizzo di strumenti professionali consolidati con supporto formale.
## Contribuire
Contributi e suggerimenti come richieste di funzionalità, segnalazioni di bug o miglioramenti sono benvenuti!
Sentiti libero di aprire issue o inviare pull request sul repository GitHub.
Assicurati di discutere qualsiasi modifica importante su una issue di Github prima di implementarla.