ramonvermeulen/whosthereWerkzeug zur Erkennung von lokalen Netzwerken mit einer interaktiven Terminal-Benutzeroberfläche (TUI), geschrieben in Go. Entdecken, erkunden und verstehen Sie Ihr LAN auf intuitive Weise. Klopf Klopf.. wer ist da? 🚪
# 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)
Werkzeug zur Erkennung lokaler Netzwerke (LAN) mit einer interaktiven Terminal-Benutzeroberfläche (TUI), geschrieben in Go.
Entdecke, erkunde und verstehe dein LAN auf intuitive Weise.
Whosthere führt **unprivilegierte, gleichzeitige Scans** mit [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS)
und [**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol)-Scannern durch. Zusätzlich durchsucht es das
lokale Subnetz, indem es TCP/UDP-Verbindungen versucht, um die ARP-Auflösung auszulösen, und liest dann den
[**ARP-Cache**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol), um Geräte in deinem lokalen Netzwerk zu identifizieren.
Diese Technik füllt den ARP-Cache, ohne erhöhte Rechte zu erfordern. Alle entdeckten Geräte werden mit
[**OUI**](https://standards-oui.ieee.org/)-Lookups angereichert, um Hersteller anzuzeigen, sofern verfügbar.
Whosthere bietet eine freundliche, intuitive Möglichkeit, die Frage zu beantworten, die sich jeder Netzwerkadministrator stellt: „Wer ist da in meinem Netzwerk?“
## Funktionen
- **Interaktive TUI:** Navigiere und erkunde entdeckte Geräte intuitiv.
- **Schnell & gleichzeitig:** Nutzt mehrere Erkennungsmethoden gleichzeitig.
- **Keine erhöhten Rechte erforderlich:** Läuft vollständig im User-Space.
- **Geräteanreicherung:** Verwendet [**OUI**](https://standards-oui.ieee.org/)-Lookup, um Gerätehersteller anzuzeigen.
- **Integrierter Portscanner:** Optionale Diensterkennung auf gefundenen Hosts (scanne nur Geräte mit Erlaubnis!).
- **Daemon-Modus mit HTTP-API:** Im Hintergrund ausführen und mit anderen Tools integrieren.
- **Theming & Konfiguration:** Passe Aussehen und Verhalten über eine YAML-Konfiguration an.
## Installation
Über [**Homebrew**](https://brew.sh/) mit `brew`:
```bash
brew install whosthere
```
Auf [**NixOS**](https://nixos.org/) mit `nix`:
```bash
nix profile install nixpkgs#whosthere
```
Auf [**Arch Linux**](https://archlinux.org/) mit `yay`:
```bash
yay -S whosthere-bin
```
Wenn dein Paketmanager nicht aufgeführt ist, kannst du immer mit [**Go**](https://go.dev/) installieren:
```bash
go install github.com/ramonvermeulen/whosthere@latest
```
Oder **aus dem Quellcode bauen**:
```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```
Zusätzlich kannst du vorgefertigte Binärdateien von der
[**Releases-Seite**](https://github.com/ramonvermeulen/whosthere/releases) herunterladen.
## Verwendung
Starte die TUI für die interaktive Erkennung:
```bash
whosthere
```
Als CLI ausführen, um einen einzelnen Scan durchzuführen und Ergebnisse auszugeben:
```bash
whosthere scan -t 5
```
Ergebnisse in eine JSON-Datei ausgeben:
```bash
whosthere scan -t 5 --json --pretty > devices.json
```
Als Daemon mit HTTP-API ausführen:
```bash
whosthere daemon --port=8080
```
Aliase in großen Mengen aus einer Datei importieren oder die aktuellen exportieren:
```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```
Weitere Kommandozeilenoptionen findest du mit:
```bash
whosthere --help
```
## Tastenkürzel (TUI)
| Taste | Aktion |
| ------------------ | ------------------------------- |
| `/` | Regex-Suche starten |
| `k` | Nach oben |
| `j` | Nach unten |
| `g` | Zum Anfang springen |
| `G` | Zum Ende springen |
| `y` | IP des ausgewählten Geräts kopieren |
| `Y` | MAC des ausgewählten Geräts kopieren |
| `enter` | Gerätedetails anzeigen |
| `CTRL+t` | Themenauswahl umschalten |
| `CTRL+i` | Schnittstellenauswahl umschalten |
| `CTRL+c`/`q` | Anwendung beenden |
| `ESC` | Suche löschen / Zurück |
| `p` (Detailansicht) | Portscan auf Gerät starten |
| `tab` (Modalansicht) | Schaltflächenauswahl wechseln |
## Konfiguration
Whosthere unterstützt mehrere Konfigurationsmethoden mit folgender Priorität (von hoch nach niedrig):
1. **Kommandozeilen-Flags** - Höchste Priorität. Siehe `whosthere --help` für verfügbare Flags.
1. **Umgebungsvariablen** - Präfix `WHOSTHERE__`. Siehe [**Konfiguration über Umgebungsvariablen**](#konfiguration-über-umgebungsvariablen).
1. **Konfigurationsdatei** - YAML-Konfigurationsdatei. Siehe [**Konfigurationsdatei**](#konfigurationsdatei).
1. **Standardwerte** - Fallback-Standardwerte. Siehe `DefaultConfig()` in [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go).
### Konfigurationsdatei
Whosthere sucht die Konfigurationsdatei in der folgenden Reihenfolge und verwendet die erste gefundene:
1. Pfad, der über das `--config`-Flag oder die Umgebungsvariable `WHOSTHERE_CONFIG` angegeben wurde
1. `$XDG_CONFIG_HOME/whosthere/config.yaml` (falls `XDG_CONFIG_HOME` gesetzt ist)
1. `~/.config/whosthere/config.yaml` (Standardort)
**Beispielkonfiguration:**
```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"
```
## Umgebungsvariablen
### Allgemeine Umgebungsvariablen
| Variable | Beschreibung |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | Pfad zur Konfigurationsdatei, um den Standardort überschreiben zu können. |
| `WHOSTHERE_LOG` | Legt den Log-Level fest (z. B. `debug`, `info`, `warn`, `error`). Standard ist `info`. |
| `NO_COLOR` | Deaktiviert ANSI-Farben in der TUI. |
### Konfiguration über Umgebungsvariablen
Jede Konfigurationsoption, die in der YAML-Konfiguration verfügbar ist, kann über Umgebungsvariablen mit dem
`WHOSTHERE__`-Präfix (beachte den doppelten Unterstrich) gesetzt werden. Verschachtelte Konfigurationsschlüssel werden durch doppelte Unterstriche getrennt, und
Schlüssel sind nicht case-sensitiv.
Beispiele:
- `WHOSTHERE__SPLASH__ENABLED=false` - Deaktiviert den Splash-Screen, entspricht `splash.enabled: false` in der YAML-Konfiguration
- `WHOSTHERE__SPLASH__DELAY=2s` - Setzt die Splash-Screen-Verzögerung auf 2 Sekunden, entspricht `splash.delay: 2s` in der YAML-Konfiguration
- `WHOSTHERE__SCAN_INTERVAL=30s` - Setzt das Scan-Intervall auf 30 Sekunden, entspricht `scan_interval: 30s` in der YAML-Konfiguration
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - Setzt Ziel-Subnetze, entspricht `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]` in der YAML-Konfiguration
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - Deaktiviert den mDNS-Scanner, entspricht `scanners.mdns.enabled: false` in der YAML-Konfiguration
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - Setzt benutzerdefinierte TCP-Ports zum Scannen, entspricht `port_scanner.tcp: [80, 443, 8080]` in der YAML-Konfiguration
- `WHOSTHERE__THEME__NAME=cyberpunk` - Setzt das Theme auf cyberpunk, entspricht `theme.name: cyberpunk` in der YAML-Konfiguration
## Geräte-Aliase
Aliase befinden sich in einer lokalen [bbolt](https://github.com/etcd-io/bbolt)-Datenbank im State-Verzeichnis. Um
viele auf einmal festzulegen, importiere sie aus einer YAML-Datei (`aliases.yaml` im Konfigurationsverzeichnis; überschreibbar mit
dem Konfigurationsschlüssel `aliases.file` oder einem Pfadargument).
Die Datei ist ein **Patch, kein Spiegel**, und wird nur gelesen: Der Import fügt die enthaltenen MACs ein bzw. aktualisiert sie
und lässt andere unberührt, und TUI-Bearbeitungen werden **niemals in die Datei zurückgeschrieben**. Verwende `export`, um
sie neu zu generieren.
```yaml
version: 1
aliases:
aa:bb:cc:dd:ee:ff: "Living Room TV"
de:ad:be:ef:00:01: "Office Printer"
```
- `version` ist die Dateiformatversion; verwende `1` (Dateien ohne diese Angabe standardmäßig auf 1).
- MACs werden in jedem gängigen Format akzeptiert und normalisiert, sodass `AA:BB:CC:DD:EE:FF`, `aa-bb-cc-dd-ee-ff`
und `aabbccddeeff` äquivalent sind. Ein leerer Alias (`""`) löscht einen.
- Ungültige MACs werden übersprungen und gemeldet; der Rest des Imports wird trotzdem durchgeführt.
```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
```
Optiere für den Import beim Start mit `aliases.auto_import: true`. Die Datei wird per Hash geprüft und nur
neu importiert, wenn sie sich geändert hat, sodass eine unveränderte Datei niemals deine TUI-Bearbeitungen überschreibt — aber eine **geänderte
Datei überschreibt** die Aliase für jede MAC, die sie enthält. Halte TUI-only-Aliase aus der Datei heraus,
oder `export` nach dem Bearbeiten, um sie synchron zu halten.
## Daemon-Modus HTTP-API
Wenn Whosthere im Daemon-Modus läuft, stellt es eine sehr einfache HTTP-API mit den folgenden Endpunkten bereit:
| Methode | Endpunkt | Beschreibung |
| ------ | -------------- | ---------------------------------- |
| GET | `/devices` | Liste aller entdeckten Geräte abrufen |
| GET | `/device/{ip}` | Details eines bestimmten Geräts abrufen |
| GET | `/health` | Health-Check |
## Themes
Das Theme kann über die Konfigurationsdatei oder zur Laufzeit über das Tastenkürzel `CTRL+t` konfiguriert werden.
Eine vollständige Liste der verfügbaren Themes findest du [**hier**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go), fühle dich frei, einen PR einzureichen, um dein eigenes Theme hinzuzufügen!
Beispiel für eine Theme-Konfiguration:
```yaml
theme:
enabled: true
name: cyberpunk
```
Wenn `name` auf `custom` gesetzt ist, können die anderen Farboptionen verwendet werden, um dein eigenes benutzerdefiniertes Theme zu erstellen.
Wenn die Option `enabled` auf `false` gesetzt ist, verwendet die TUI die Standard-ANSI-Farben des Terminals.
Wenn die Umgebungsvariable `NO_COLOR` gesetzt ist, werden alle ANSI-Farben deaktiviert.
## Protokollierung
Logs werden in das State-Verzeichnis der Anwendung geschrieben:
- `$XDG_STATE_HOME/whosthere/app.log` (falls `XDG_STATE_HOME` gesetzt ist)
- `~/.local/state/whosthere/app.log` (Fallback Linux/MacOS)
- `%LOCALAPPDATA%/whosthere/app.log` (Fallback Windows)
Wenn nicht im TUI-Modus ausgeführt, werden Logs auch auf der Konsole ausgegeben.
## Plattformen
Whosthere wird auf den folgenden Plattformen unterstützt:
- [x] Linux
- [x] macOS
- [x] Windows
## Bekannte Probleme
Damit die Zwischenablage-Funktionalität funktioniert, wird ein [**Fork von go-clipboard**](https://github.com/dece2183/go-clipboard) verwendet.
Stelle sicher, dass du das passende Kopierwerkzeug für dein Betriebssystem installiert hast:
| OS | Unterstützte Kopierwerkzeuge |
| -------------------------------------- | -------------------------------------------- |
| Darwin | `pbcopy` |
| Windows | `clip.exe` |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`, `xclip` <br> Wayland: `wl-copy` |
## Haftungsausschluss
Whosthere ist für die Verwendung in Netzwerken gedacht, in denen du die Erlaubnis hast, Netzwerkerkennung und -scans durchzuführen,
wie beispielsweise dein eigenes Heimnetzwerk. Unautorisiertes Scannen von Netzwerken kann illegal und unethisch sein.
Hole immer eine ordnungsgemäße Autorisierung ein, bevor du dieses Tool in einem Netzwerk verwendest.
Dieses Tool wurde in erster Linie zu Bildungszwecken und für die Erkundung von Heimnetzwerken erstellt. Obwohl es funktional
und nützlich ist, sollte es nicht als professionelle Netzwerküberwachungslösung betrachtet werden. Ergebnisse basieren
auf unprivilegierten Scan-Techniken und sind möglicherweise nicht umfassend. Für kritische Netzwerkanalysen
oder Sicherheitsbewertungen solltest du etablierte professionelle Tools mit formellem Support in Betracht ziehen.
## Mitwirken
Beiträge und Vorschläge wie Feature-Anfragen, Fehlerberichte oder Verbesserungen sind willkommen!
Fühle dich frei, Issues zu eröffnen oder Pull Requests im GitHub-Repository einzureichen.
Bitte stelle sicher, dass du größere Änderungen in einem GitHub-Issue diskutierst, bevor du sie implementierst.