nlink-jp/mac-lookup
GitHub: nlink-jp/mac-lookup
基于本地 IEEE 注册表缓存的离线 MAC/BSSID 地址解析工具，支持 CLI 与 MCP 双模式，能准确区分地址类型并精确匹配厂商。
Stars: 0 | Forks: 0
# mac-lookup
将 MAC 地址或 BSSID 解析为其制造商——在此之前，还需要解析
**它实际属于哪种类型的地址**。完全离线运行，数据源来自本地缓存的
IEEE Registration Authority 公共注册表副本。既可以作为 CLI 运行，也可以作为本地
MCP 服务器运行。
它是 [`asn-lookup`](https://github.com/nlink-jp/asn-lookup)
(IP → AS/country) 和 [`tor-exit-lookup`](https://github.com/nlink-jp/tor-exit-lookup)
(离线成员查询) 的 L2 层兄弟工具。
## 为什么需要它
仅凭供应商表会给出错误的答案。首先必须明确以下三件事：
- **随机化的 MAC 没有制造商。** 现代手机会针对每个网络轮换本地管理地址，虚拟 NIC 和容器也会做同样的事情。如果将其报告为“供应商未知”，会误导调查员继续寻找一个根本未注册的设备。`mac-lookup` 会将其报告为*本地管理（locally administered）——不适用供应商查询*。
- **仅靠前六位数字是不够的。** IEEE 将 24 位前缀拆分为 28 位 (MA-M) 和 36 位 (MA-S/IAB) 分配，因此多个供应商会共享同一个 OUI。`mac-lookup` 采用最长前缀优先匹配（36 → 28 → 24）。
- **某些地址块属于 IEEE 本身。** 大约有 429 条 MA-L 记录注册给了“IEEE Registration Authority”——这些是预留给后续细分的地址块，并不代表制造商。`mac-lookup` 会将它们报告为 *OUI 已细分（subdivided）*，绝不显示为供应商名称。
所有查询均通过本地缓存完成，因此在查找地址时绝对不会触碰目标可以观察到的网络。
## 安装
```
brew install nlink-jp/tap/mac-lookup
```
或者从源码构建（需要 Go 1.25+，无外部依赖）：
```
make build
```
生成的二进制文件位于 `dist/mac-lookup` 目录下。
## 用法
```
mac-lookup update # download the IEEE registries once
mac-lookup lookup 8C:1F:64:AF:A0:01 # resolve an address
mac-lookup lookup --json < captured.txt # batch from stdin, JSON Lines out
mac-lookup search Apple # vendor name → assigned prefixes
mac-lookup status # cache freshness and size
mac-lookup mcp # run as a local MCP server (stdio)
```
接受的地址格式包括：`00:11:22:33:44:55`、`00-11-22-33-44-55`、
`001122334455`、Cisco 的 `0011.2233.4455` 格式，以及 24、28 或 36 位的纯前缀（`00:11:22`、`8C:1F:64:AF:A`）。
```
$ mac-lookup lookup 8C:1F:64:AF:A0:01 8C:1F:64:00:00:01 DA:A1:19:12:34:56 00:00:5E:00:01:2A FF:FF:FF:FF:FF:FF
8C:1F:64:AF:A0:01 DATA ELECTRONIC DEVICES, INC [MA-S /36]
8C:1F:64:00:00:01 Suzhou Xingxiangyi Precision Manufacturing Co.,Ltd. [MA-S /36]
DA:A1:19:12:34:56 Google, Inc. [CID /24] (locally administered)
00:00:5E:00:01:2A ICANN, IANA Department [MA-L /24] (VRRP (IPv4, RFC 5798))
FF:FF:FF:FF:FF:FF (broadcast — Broadcast)
```
其中有两行输出正是开发此工具的原因。`8C:1F:64` 是一个 IEEE 保留地址块，因此其供应商来源于其内部的 36 位分配，而不是来源于该 OUI。而 `DA:A1:19` 属于本地管理地址：CID 注册表将 Google 列为分配该前缀的组织，但该地址并非稳定的设备标识，绝不能跨网络进行关联——这正是该行输出如此提示的原因。
### 退出码
对于**文本模式下的单一地址查询**，`lookup` 使用类似 grep 的退出码：
| 代码 | 含义 |
|---|---|
| `0` | 成功解析出命名的供应商 |
| `1` | 无供应商名称——未分配、本地管理、多播、已细分的 OUI，或注册为 `Private` |
| `2` | 发生错误 |
```
if mac-lookup lookup "$mac"; then echo "vendor known"; fi
```
如果输入多个地址、使用 stdin 或带有 `--json` 参数，则会切换到批量模式：结果将输出到 stdout，并且退出码仅用于报告错误（`0`/`2`）。
## 配置
可选配置。可以将 [`config.example.toml`](config.example.toml) 复制为
`~/.config/mac-lookup/config.toml`。每个值都可以通过 `MAC_LOOKUP_*`
环境变量进行覆盖。
**无需任何凭据。** IEEE 注册表文件是公开的，因此不需要配置、记录或担心泄露任何 token 或 API 密钥。
当缓存的时间超过 TTL 时会自动重新获取（默认为 24 小时，最小限制为 6 小时——
IEEE 大约每天重新生成一次这些文件）。可以使用 `--no-update` 或
`[ieee] auto_update = false` 来禁用此功能。
## MCP 服务器
`mac-lookup mcp` 通过 stdio 通信使用 JSON-RPC 2.0 协议，并对外暴露 `lookup_mac`、
`search_vendor`、`db_status`、`update_db` 和 `get_usage` 接口。建议首先调用 `get_usage`
——它会返回完整的工具参考说明和错误恢复表。
`search_vendor` 是基于文件传递的：一个知名供应商可能拥有数百个前缀，
因此结果会写入调用者的 `workspace_root` 目录下，并作为
`matches_file` 路径返回。
### JSON 输出
`--json` 会针对每个地址输出一个对象。请务必在读取 `vendor` 之前先查看 `vendor_lookup_applicable`：
当其为 `false` 时，vendor 为空意味着本来就没有可查找的内容，
而不是查询遗漏。每个结果还附带一个 `note`，用于详细说明具体属于哪种情况。注册人地址完全保留 IEEE 原始录入的文本内容——
由于这是自由文本，因此系统不会从中专门解析出国家代码。
## 数据
数据来源于 IEEE Registration Authority 公共注册表——包括 MA-L、MA-M、MA-S、IAB 和 CID
（
标签：EVTX分析, MAC地址, MCP, 数据查询, 文档结构分析, 日志审计, 离线查询, 网络工具