zheng1/beefkvm

# beefkvm [](https://github.com/zheng1/beefkvm/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/zheng1/beefkvm) [](LICENSE) 一个基于浏览器的 KVM 和管理控制台，适用于 Avocent 风格的 BMC，使用纯 Go 编写。 因其通信所用的 APCP/AVPT 协议中的 `0xBEEF` 帧魔术字节而得名。 ## 为什么开发 一些服务器的 BMC 附带了一个 **Java applet** 形式的远程控制台。该 applet 需要支持 `applet` 的 JRE、TLS 1.0、SSLv3 时代的加密套件以及传统的重新协商机制。在任何当前的操作系统和浏览器上，它根本无法启动——这意味着完全正常的硬件变得无法管理，而且厂商也不会提供修复程序。 `beefkvm` 取代了它。它直接与 BMC 的通信协议交互，并在普通的浏览器标签页中渲染控制台： - **无需 Java。** 没有 applet，没有 JNLP，没有捆绑的 JRE，也没有原生库。 - **没有专有的二进制文件。** 此处不重新分发任何专有内容。 - **一个静态的 Go 二进制文件**，外加一个内嵌的 HTML 页面。 ## 功能说明 | 领域 | 状态 | |---|---| | KVM 视频（自定义 DCT 编解码器） | 正常工作 — 全速率，文字清晰 | | 键盘 (USB HID) + 自动重复 | 正常工作 | | 鼠标（绝对定位） | 已实现；移动未经验证（测试目标仅限文本界面） | | 按键宏：Ctrl+Alt+Del、Alt+Tab、Ctrl+Alt+F1–F6、粘滞修饰键 | 正常工作 | | 粘贴剪贴板内容到控制台 | 正常工作 | | 虚拟介质（挂载 ISO / USB / 软盘） | 正常工作 | | 开机 / 关机 / 重置 / 软关机 / 循环 | 正常工作 (IPMI) | | 一次性启动设备 (PXE / CD / HDD / BIOS) | 正常工作 (IPMI) | | 传感器（温度、风扇、电压）+ 实时流传输 | 正常工作 (IPMI SDR) | | 系统事件日志（查看 + 清除） | 正常工作 (IPMI SEL) | | 系统信息：BMC 固件、IPMI 版本、FRU | 正常工作 | | BMC TLS 证书检查 | 正常工作 | | 用户管理（添加 / 编辑 / 权限 / 启用） | 正常工作 (IPMI) | | 网络配置（读取；受控写入） | 正常工作 (IPMI LAN) | | Serial-over-LAN 控制台 | 正常工作 — 请参阅下面的说明 | | 智能卡 (CAC/PIV) 重定向 | 已打通流程；需要 PC/SC 读卡器进行测试 | | 会话断开时自动重连 | 正常工作 | ### 关于最后三项的说明 - **Serial-over-LAN** 已激活并传输流量，但 SoL 仅传输*目标 OS* 放置在串行线路上的内容。如果屏幕保持空白，则目标机器没有串行控制台。在 Linux 上： `systemctl enable --now serial-getty@ttyS0.service` 并将 `console=ttyS0,115200` 添加到 kernel 命令行。 - **智能卡**重定向已端到端打通（macOS 上的 PC/SC、UI 中的状态、通过 VM 通道的 APDU 中继），但目前仅对读卡器识别进行了测试——由于没有实体的 CAC/PIV 读卡器。请将其视为尚未针对真实卡片经过测试。 - **调色板视频块**已实现并经过单元测试，但用于开发的 BMC 仅发送 DCT 块，因此该路径尚未在真实硬件上运行。 ## 截图 传感器 — 通过 IPMI 实时读取 SDR 数据，并流式传输到浏览器：  系统 — BMC 固件、FRU 清单和 TLS 证书详情：  ## 硬件支持 ### 验证可正常工作 确切地说，只有一台机器进行了端到端测试。这是我唯一能亲身保证的配置： | 属性 | 值 | |---|---| | **主板** | **GIGABYTE GA-6PXSV4** | | BIOS | R21_NV (2017-11-21) | | 芯片组 | Intel C600/X79 系列 (LPC `8086:1d41`) | | CPU | Intel Xeon E5-2696 v2 (12核/24线程, LGA2011) | | 内存 | 8× DDR3 插槽，4通道 (`DDR3_P0_A0`…`D1`)；已安装 2× 64 GB | | BMC SoC | ASPEED AST2300-class，经 Avocent 授权的 KVM 栈 | | BMC 固件 | **2.44** | | APCP 服务器版本 | **2.34** | | IPMI 版本 | **2.0** | | IPMI 制造商 ID | 15370 (GIGA-BYTE TECHNOLOGY) | | IPMI 设备 ID / 修订版 | 32 / 1 | | 主板制造日期 | 2011-06-03 (根据 FRU) | | 控制台分辨率 | 1024×768 | | 视频流 | DCT 块，数据包子类型 5 (模式 1，16×16 MCU) | | SoL | 已启用，通道 1，强制加密开启 | 请注意，该 BMC 的 FRU 是未填充的（`Board Product: Undefined`），因此 beefkvm 无法自行报告主板型号——上述型号来自于主机的 SMBIOS。如果你的 BMC 拥有正确填写的 FRU，“系统”标签页将会显示它。 在该机器上验证的功能包括：KVM 视频、键盘（包括自动重复，且在目标屏幕上确认了击键）、按键宏、剪贴板粘贴、虚拟介质、电源控制、一次性启动设备、与 `ipmitool` 交叉检查的 28 个传感器、SEL、用户管理、LAN 配置读取、SoL 激活以及会话自动重连。 鼠标输入已实现，且其数据帧被 BMC 无错误地接受，但由于测试目标始终只显示文本控制台，因此指针的*移动*从未在视觉上得到确认。如果你运行的是图形化控制台，我们特别欢迎你提供关于鼠标反馈的信息。 ### 可能有效（未经测试 — 期待反馈） 参考机器是证明这一点的最清晰证据：其 BMC 报告制造商为 **Gigabyte**，然而它提供的远程控制台却是 **Avocent 的** Java 客户端，使用 APCP 通信。换句话说，Avocent 将这个 KVM 栈授权给了主板供应商，因此该协议出现在许多品牌下，而 BMC 自身的供应商 ID 几乎无法说明它使用的是哪种网络协议格式。 从客户端 JAR 本身来看，该协议是共享的进一步证据： - 无论是通用的 Avocent KVM 客户端还是 Dell 的 iDRAC6 客户端，均由 `Built-By: Avocent Corporation` 构建，并且共享了 245 个名称相同的类，包括整个 `com.avocent.kvm.a.a` 编解码器包。 - 两者的视频解码器都使用**相同的整数 IDCT 常量** (362 / 473 / 277 / 669) 和相同的量化表布局——也就是本项目重新实现的核心编解码器。 因此，这些是可能支持的硬件目标，按可信度粗略排序： | 硬件 | 依据 | 状态 | |---|---|---| | 其他 **Gigabyte GA-6PXSV / GA-7PES** 主板 (LGA2011, C602/X79, AST2300) | 与已验证的 GA-6PXSV4 具有相同的供应商、BMC 代次和 KVM 栈 | 未经测试 | | Dell **iDRAC6** (PowerEdge 11G: R610/R710/T610…) | 源自相同的 Avocent 代码库并附带 `avctKVM.jar`；具有相同的 IDCT 常量 | 未经测试 | | Avocent **MergePoint** 服务处理器 | 与经过测试的设备属于同一产品线 | 未经测试 | | 授权使用 Avocent KVM 的 OEM AST2300/AST2400 主板（各种白牌/超微时代的主板） | 具有相同的 SoC 类型和 APCP 服务器 | 未经测试 | | Dell **iDRAC7/8** | 较新的技术栈；KVM 已迁移到不同的传输方式 | 若无额外开发，不太可能支持 | | **iDRAC9**、现代 AMI MegaRAC、仅支持 Redfish 的 BMC | 完全不同的协议 (HTML5/Redfish) | 超出支持范围 | 类名的重叠是强有力的证据，但并非绝对证明：不同版本之间的解码器类在字节级别上存在差异，因此网络协议级别的细节仍可能存在分歧。在有人报告反馈之前，请将整个表格视为一种假设。 ### 报告你的硬件 无论是否正常工作，你的反馈都有所帮助。请提交一个 issue，并附上： ``` apcp-probe --host --learn-pin # cert pin + handshake info ipmitool -I lanplus -H -U -P -C 3 mc info ``` 以及你的服务器型号、BMC 固件版本，如果视频出现问题，请附上 beefkvm 日志中 `[avo] tile hdr:` 那几行。这些字节标识了数据包的子类型和编解码器模式，这决定了解码器是否需要另一条解析路径。 ## 安装说明 ``` go install github.com/zheng1/beefkvm/cmd/beefkvm@latest ``` 或者直接从检出的代码构建所有内容： ``` git clone https://github.com/zheng1/beefkvm cd beefkvm go build ./... ``` 要求 Go 1.26+。支持 macOS 和 Linux。智能卡后端在 macOS 上使用 cgo + PC/SC； 在其他平台上它会被编译成一个空操作的无实际功能代码，因此使用 `CGO_ENABLED=0` 进行构建也没有问题。 ## 快速开始 BMC 的证书是自签名的（而且在许多设备上早已过期），因此它无法通过 CA 进行验证。`beefkvm` 改为采用证书固定。只需获取一次指纹： ``` apcp-probe --host bmc.example --learn-pin ``` 然后启动控制台： ``` beefkvm \ --host bmc.example \ --user admin \ --pass "$BMC_PASS" \ --pin "$BMC_PIN" \ --ipmi-user admin --ipmi-pass "$BMC_PASS" ``` 它会打印一个包含一次性会话 token 的 URL。打开它： ``` beefkvm: listening on http://127.0.0.1:8080?t= ``` 凭证也可以从 `BMC_HOST`, `BMC_USER`, `BMC_PASS`, `BMC_PIN`, `BMC_IPMI_USER`, 和 `BMC_IPMI_PASS` 环境变量中读取，这样可以避免它们出现在你的 shell 历史记录和进程列表中。 省略 `--ipmi-user`/`--ipmi-pass` 可仅运行 KVM 功能；电源、传感器、事件、用户、网络和串行功能将保持不可用状态。 ## 安全态势 在将其暴露给任何外部环境之前，请阅读此部分。 - **Web UI 使用纯 HTTP 且主要供本地使用。** 它默认绑定到 `127.0.0.1`。访问受限于每次运行生成的随机 256 位 token，该 token 携带在 URL 中，随后存入 cookie，此外 WebSocket 还会进行同源检查。 - **URL 中的 token 并非强密钥。** 它可能会被记录在 shell 历史记录、代理日志和浏览器历史记录中。如果你使用 `--listen` 将其绑定到局域网地址，请将其置于负责 TLS 终结的反向代理之后，并添加你自己的身份验证。目前尚不支持 HTTPS，没有会话超时，也没有审计日志。 - **证书固定是唯一的传输级身份验证。** 固定不匹配会中止连接。请在你信任的网络环境中获取并固定该证书。 - **BMC 拥有对机器的完全控制权** — 包括电源、启动设备、虚拟介质和键盘。任何能够访问此 UI 的人都拥有所有这些权限。如果你的 BMC 仍然使用厂商默认凭证，请务必在做任何事情之前先更改它们。 ## 协议说明 `docs/apcp-protocol.md` 记录了观察到的网络协议格式：AVPT/`BEEF` 帧结构、会话类型（KVM、虚拟介质和配套的视频通道）、登录握手以及视频数据包的布局。 视频编解码器并非标准的 JPEG。它是一个自定义的 DCT 变体，包含 4 位操作码流、4 条目的调色板缓存、专用的量化表以及整数 AAN IDCT。`internal/video` 目录对其进行了实现；那里的注释记录了真正重要的细节——量化表排序、tile 光栅包装以及维持视频流存活所需的逐帧 ACK。 ## 工具 | 命令 | 用途 | |---|---| | `beefkvm` | 控制台：Web UI + KVM +MI 桥接 | | `apcp-probe` | 连接，获取证书固定，检查握手过程 | | `apcp-capture` | 记录原始协议帧以供分析 | | `beefkvm-vm` | 从命令行挂载虚拟介质 | | `beefkvm-power` | 从命令行控制电源 | | `beefkvm-usb` | USB/HID 实验 | ## 测试 ``` go test ./... ``` 单元测试涵盖了编解码器、帧结构和 IPMI 编码，并且在无硬件环境下即可运行。需要真实 BMC 的测试可通过环境变量选择性启用，例如： ``` IKVM_SOL_LIVE=1 SOL_HOST=bmc.example SOL_USER=admin SOL_PASS=secret \ go test ./internal/ipmi -run TestSOLLive -v ``` 请注意，真实的用户管理测试会在一个未使用的插槽中创建然后移除一个临时账户。 ## 法律声明 这是一个独立完成的、净室风格的重新实现，旨在通过观察网络流量和行为，实现与用户已有硬件的**互操作性**。 - 本仓库不包含也不分发任何厂商的源代码、JAR、原生库或固件。 - 文中提及的 Avocent、MergePoint、Vertiv、ASPEED 及其他名称均为其各自所有者的商标，此处仅用于指代本软件所要通信的硬件。本项目的作者与它们不存在任何从属或认可关系。 - 要使用本软件，你需要拥有自己的 BMC 和相应的凭证。 ## 安全性 请通过 [GitHub 安全公告](../../security/advisories/new) 私下报告漏洞，而不是在公开的 issue 中提出 — 详情请参阅 [SECURITY.md](SECURITY.md)，该文件还列出了已知的、刻意为之的局限性，这些局限性*不*被视为漏洞。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。

标签：BMC, EVTX分析, IPMI, KVM, 日志审计, 纯Go开发, 运维管理, 远程管理