# 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)
使用 Go 编写的局域网发现工具，带有交互式终端用户界面（TUI）。
以直观的方式发现、探索和理解你的局域网。
Whosthere 使用 [**mDNS**](https://en.wikipedia.org/wiki/Multicast_DNS) 和 [**SSDP**](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol) 扫描器执行**非特权、并发扫描**。此外，它通过尝试 TCP/UDP 连接来触发 ARP 解析，从而扫描本地子网，然后读取 [**ARP 缓存**](https://en.wikipedia.org/wiki/Address_Resolution_Protocol) 来识别局域网中的设备。此技术无需提升权限即可填充 ARP 缓存。所有发现的设备都会通过 [**OUI**](https://standards-oui.ieee.org/) 查询进行增强，以在可用时显示制造商信息。
Whosthere 提供了一种友好、直观的方式来回答每个网络管理员都会问的问题：“我的网络上有谁？”
## 功能特性
- **交互式 TUI：** 直观地导航和探索发现的设备。
- **快速且并发：** 同时利用多种发现方法。
- **无需提升权限：** 完全在用户空间运行。
- **设备信息增强：** 使用 [**OUI**](https://standards-oui.ieee.org/) 查询显示设备制造商。
- **集成端口扫描器：** 对发现的主机进行可选的服务发现（仅在有权限的情况下扫描设备！）。
- **带 HTTP API 的守护进程模式：** 在后台运行并与其他工具集成。
- **主题与配置：** 通过 YAML 配置个性化外观和行为。
## 安装
通过 [**Homebrew**](https://brew.sh/) 使用 `brew`：
```bash
brew install whosthere
```
在 [**NixOS**](https://nixos.org/) 上使用 `nix`：
```bash
nix profile install nixpkgs#whosthere
```
在 [**Arch Linux**](https://archlinux.org/) 上使用 `yay`：
```bash
yay -S whosthere-bin
```
如果你的包管理器未列出，你始终可以使用 [**Go**](https://go.dev/) 安装：
```bash
go install github.com/ramonvermeulen/whosthere@latest
```
或者**从源码构建**：
```bash
git clone https://github.com/ramonvermeulen/whosthere.git
cd whosthere
make build
```
此外，你可以从 [**releases 页面**](https://github.com/ramonvermeulen/whosthere/releases) 下载预构建的二进制文件。
## 使用方法
运行 TUI 进行交互式发现：
```bash
whosthere
```
以 CLI 模式运行，执行单次扫描并输出结果：
```bash
whosthere scan -t 5
```
将结果输出到 JSON 文件：
```bash
whosthere scan -t 5 --json --pretty > devices.json
```
以守护进程模式运行并启用 HTTP API：
```bash
whosthere daemon --port=8080
```
从文件批量导入别名，或导出当前别名：
```text
whosthere aliases import ./aliases.yaml
whosthere aliases export --stdout
```
可以通过运行以下命令查看其他命令行选项：
```bash
whosthere --help
```
## 快捷键（TUI）
| 按键 | 操作 |
| ------------------ | ---------------------------- |
| `/` | 开始正则搜索 |
| `k` | 上移 |
| `j` | 下移 |
| `g` | 跳到顶部 |
| `G` | 跳到底部 |
| `y` | 复制所选设备的 IP |
| `Y` | 复制所选设备的 MAC |
| `enter` | 显示设备详情 |
| `CTRL+t` | 切换主题选择器 |
| `CTRL+i` | 切换接口选择器 |
| `CTRL+c`/`q` | 停止应用程序 |
| `ESC` | 清除搜索 / 返回 |
| `p`（详情视图） | 对设备启动端口扫描 |
| `tab`（模态视图） | 切换按钮选择 |
## 配置
Whosthere 支持多种配置方法，优先级如下（从高到低）：
1. **命令行标志** - 最高优先级。查看 `whosthere --help` 了解可用标志。
1. **环境变量** - 以 `WHOSTHERE__` 为前缀。参见 [**通过环境变量配置**](#configuration-via-environment-variables)。
1. **配置文件** - YAML 配置文件。参见 [**配置文件**](#configuration-file)。
1. **默认值** - 回退默认值。参见 [**config.go**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/core/config/config.go) 中的 `DefaultConfig()`。
### 配置文件
Whosthere 按以下顺序查找配置文件，使用找到的第一个：
1. 通过 `--config` 标志或 `WHOSTHERE_CONFIG` 环境变量指定的路径
1. `$XDG_CONFIG_HOME/whosthere/config.yaml`（如果设置了 `XDG_CONFIG_HOME`）
1. `~/.config/whosthere/config.yaml`（默认位置）
**示例配置：**
```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"
```
## 环境变量
### 通用环境变量
| 变量 | 描述 |
| ------------------ | ------------------------------------------------------------------------------- |
| `WHOSTHERE_CONFIG` | 配置文件路径，用于覆盖默认位置。 |
| `WHOSTHERE_LOG` | 设置日志级别（例如 `debug`、`info`、`warn`、`error`）。默认为 `info`。 |
| `NO_COLOR` | 在 TUI 中禁用 ANSI 颜色。 |
### 通过环境变量配置
YAML 配置中可用的任何配置选项，都可以通过使用 `WHOSTHERE__` 前缀（注意是双下划线）的环境变量来设置。嵌套的配置键由双下划线分隔，键不区分大小写。
示例：
- `WHOSTHERE__SPLASH__ENABLED=false` - 禁用启动画面，等同于 YAML 配置中的 `splash.enabled: false`
- `WHOSTHERE__SPLASH__DELAY=2s` - 将启动画面延迟设置为 2 秒，等同于 YAML 配置中的 `splash.delay: 2s`
- `WHOSTHERE__SCAN_INTERVAL=30s` - 将扫描间隔设置为 30 秒，等同于 YAML 配置中的 `scan_interval: 30s`
- `WHOSTHERE__TARGET_SUBNETS=10.0.0.0/24,10.0.1.0/24` - 设置目标子网，等同于 YAML 配置中的 `target_subnets: ["10.0.0.0/24", "10.0.1.0/24"]`
- `WHOSTHERE__SCANNERS__MDNS__ENABLED=false` - 禁用 mDNS 扫描器，等同于 YAML 配置中的 `scanners.mdns.enabled: false`
- `WHOSTHERE__PORT_SCANNER__TCP=80,443,8080` - 设置要扫描的自定义 TCP 端口，等同于 YAML 配置中的 `port_scanner.tcp: [80, 443, 8080]`
- `WHOSTHERE__THEME__NAME=cyberpunk` - 将主题设置为 cyberpunk，等同于 YAML 配置中的 `theme.name: cyberpunk`
## 设备别名
别名存储在状态目录中的本地 [bbolt](https://github.com/etcd-io/bbolt) 数据库里。要一次性设置多个别名，可以从 YAML 文件导入（配置文件目录中的 `aliases.yaml`；可通过 `aliases.file` 配置键或路径参数覆盖）。
该文件是一个**补丁，而不是镜像**，并且只会被读取：导入会更新其中包含的 MAC 并保持其他不变，TUI 中的编辑**永远不会写回该文件**。使用 `export` 重新生成它。
```yaml
version: 1
aliases:
aa:bb:cc:dd:ee:ff: "Living Room TV"
de:ad:be:ef:00:01: "Office Printer"
```
- `version` 是文件格式版本；使用 `1`（没有该字段的文件默认为 1）。
- MAC 接受任何常见格式并进行规范化，因此 `AA:BB:CC:DD:EE:FF`、`aa-bb-cc-dd-ee-ff` 和 `aabbccddeeff` 是等价的。空别名（`""`）会清除一个别名。
- 无效的 MAC 会被跳过并报告；导入的其余部分仍会继续。
```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
```
通过 `aliases.auto_import: true` 选择在启动时导入。该文件会进行哈希校验，仅在发生变化时重新导入，因此未修改的文件永远不会覆盖你的 TUI 编辑——但**已更改的文件确实会覆盖**其中包含的每个 MAC 的别名。请将仅在 TUI 中创建的别名排除在文件之外，或在编辑后执行 `export` 以保持同步。
## 守护进程模式 HTTP API
以守护进程模式运行 Whosthere 时，它会暴露一个非常简单的 HTTP API，包含以下端点：
| 方法 | 端点 | 描述 |
| ------ | -------------- | ---------------------------------- |
| GET | `/devices` | 获取所有已发现设备的列表 |
| GET | `/device/{ip}` | 获取特定设备的详情 |
| GET | `/health` | 健康检查 |
## 主题
主题可以通过配置文件配置，或在运行时通过 `CTRL+t` 快捷键配置。
可用主题的完整列表可以在[**这里**](https://github.com/ramonvermeulen/whosthere/blob/main/internal/ui/theme/theme.go)找到，欢迎提交 PR 添加你自己的主题！
主题配置示例：
```yaml
theme:
enabled: true
name: cyberpunk
```
当 `name` 设置为 `custom` 时，可以使用其他颜色选项创建你自己的自定义主题。
当 `enabled` 选项设置为 `false` 时，TUI 将使用终端的默认 ANSI 颜色。
当设置了 `NO_COLOR` 环境变量时，所有 ANSI 颜色都将被禁用。
## 日志
日志写入应用程序的状态目录：
- `$XDG_STATE_HOME/whosthere/app.log`（如果设置了 `XDG_STATE_HOME`）
- `~/.local/state/whosthere/app.log`（Linux/MacOS 回退）
- `%LOCALAPPDATA%/whosthere/app.log`（Windows 回退）
当不在 TUI 模式下运行时，日志也会写入控制台。
## 平台
Whosthere 支持以下平台：
- [x] Linux
- [x] macOS
- [x] Windows
## 已知问题
为了使剪贴板功能正常工作，使用了 [**go-clipboard 的一个分支**](https://github.com/dece2183/go-clipboard)。
请确保为你的操作系统安装了适当的复制工具：
| 操作系统 | 支持的复制工具 |
| -------------------------------------- | -------------------------------------------- |
| Darwin | `pbcopy` |
| Windows | `clip.exe` |
| Linux/FreeBSD/NetBSD/OpenBSD/Dragonfly | X11: `xsel`、`xclip` <br> Wayland: `wl-copy` |
## 免责声明
Whosthere 旨在用于你有权限执行网络发现和扫描的网络，例如你自己的家庭网络。未经授权扫描网络可能是非法且不道德的。
在任何网络上使用此工具之前，请务必获得适当的授权。
此工具主要出于教育目的和家庭网络探索而创建。虽然功能可用且实用，但不应将其视为专业级网络监控解决方案。结果基于非特权扫描技术，可能并不全面。对于关键网络分析或安全评估，请考虑使用具有正式支持的成熟专业工具。
## 贡献
欢迎贡献和建议，例如功能请求、错误报告或改进！
请随时在 GitHub 仓库上提交 issue 或 pull request。
在实现任何重大更改之前，请务必在 GitHub issue 上进行讨论。
