Warpgate 如何改造并内嵌 vnc-rs:RFB 解码循环暴露与对抗不可信 VNC 目标的内存安全加固
Warpgate 如何改造并内嵌 vnc-rs:RFB 解码循环暴露与对抗不可信 VNC 目标的内存安全加固
导读
本文基于仓库 vendor/vnc-rs/PATCHES.md 展开,完整解析 Warpgate 对上游 vnc-rs 0.5.3 的三处定向改造:将私有的 RFB 解码循环 decode_loop 公开以便在代理/录制场景中独立驱动、修复 SetColorMapEntries 消息导致的 panic、以及针对不可信 VNC 目标的全链路内存安全加固。读完本文,你将理解堡垒机在"透明代理 + 会话录制"场景下为什么要 fork 一个纯客户端库,也能掌握每条补丁对应的源码位置、安全上限取值及其在 warpgate-protocol-vnc 中的实际落地方式。
一、为什么 Warpgate 要 vendoring 一个 VNC 客户端库
Warpgate 本身是一个"无需额外客户端软件"的 SSH / HTTPS / Kubernetes / 数据库 / RDP / VNC 堡垒机(见仓库根目录 README.md)。在 VNC 场景下,它的职责不只是把 viewer 的流量转发到目标服务器,还要以无损方式录制整个会话。
上游 vnc-rs(crate 名 vnc)是一个完整的 VNC 客户端:它拥有 socket、负责 RFB 握手,并且只通过 VncClient::poll_event 把解码后的 VncEvent 流暴露给调用者。这意味着如果 Warpgate 想用上游库来录制一个"被代理"的连接,就必须建立第二条后端连接,或者把视频重新编码成 Raw 格式——两条路都会损失保真度或增加带宽。
PATCHES.md 明确给出了诉求:
To record a proxied connection at full fidelity (Tight/JPEG/Zrle/CopyRect/cursor) without a second backend connection or re-encoding to Raw, Warpgate needs to run the RFB decode loop over a tee of the bytes flowing between the real viewer and the target — driving the decoder itself, with a handshake and socket it already owns.
即:Warpgate 需要在自己已经握好手、已经持有 socket 的前提下,对真实 viewer 与目标服务器之间字节流的"分流(tee)"独立驱动 RFB 解码循环,从而在保持 Tight/JPEG/Zrle/CopyRect/光标等编码保真度的同时完成录制。
然而上游的解码循环是一个私有自由函数(asycn_vnc_read_loop,拼写即如此),且其服务器消息解析器在遇到调色板(colour-map)服务器时会 panic。这两处问题"修起来很容易,但必须 fork"。最终 Warpgate 选择把源码 vendoring 进仓库而不是依赖某个个人 Git fork,理由是为了"构建可复现、可审查(hermetic and reviewable)"。
在仓库中可以印证这一工程决策:
- 根目录 Cargo.toml 的
exclude列表把vendor/vnc-rs以及vendor/ironrdp-*、vendor/picky、vendor/sspi全部排除出 workspace,注释说明"这些 vendored 的第三方 fork 被排除,以便 Cranky 的 deny lints 不作用于其上游代码,每个 fork 都带有 PATCHES.md 描述"; warpgate-protocol-vnc通过路径依赖引入:warpgate-protocol-vnc/Cargo.toml 中的vnc = { package = "vnc-rs", path = "../vendor/vnc-rs" }。
二、变更一:公开 RFB 解码循环 decode_loop
2.1 补丁内容
上游的整个解码主循环是私有的,Warpgate 将其改名为 decode_loop 并设为 pub。涉及三个文件:
- vendor/vnc-rs/src/client/connection.rs:定义
pub async fn decode_loop; - vendor/vnc-rs/src/client/mod.rs:
pub use connection::{decode_loop, VncClient}; - vendor/vnc-rs/src/lib.rs:
pub use client::{decode_loop, VncClient, VncConnector};
函数签名与上游完全一致,未做任何改动:
pub async fn decode_loop<S, F, Fut>(
stream: &mut S,
pf: &PixelFormat,
output_func: &F,
mut stop_ch: oneshot::Receiver<()>,
) -> Result<(), VncError>
where
S: AsyncRead + Unpin,
F: Fn(VncEvent) -> Fut,
Fut: Future<Output = Result<(), VncError>>,
2.2 语义与调用约束
从 connection.rs 的文档注释可以提取出关键调用契约:
stream必须恰好位于服务器消息边界(即握手完成之后的位置);pf是已经协商好的PixelFormat;output_func是输出闭包,每个解码出的VncEvent都会经它回调(例如投递到 mpsc channel);stop_ch是 oneshot 停止信号;循环一直运行到收到停止信号、遇到 EOF 或发生解码错误为止。
主循环内部会维护 Raw / Zrle / Tight / TRLE / 光标五个解码器(codec::RawDecoder、codec::ZrleDecoder、codec::TightDecoder、codec::TrleDecoder、codec::CursorDecoder),逐一读取 ServerMsg 并分发到对应解码器。补丁刻意只公开循环本身,内部编码解码器 codec::* 仍然保持 pub(crate)——调用者不能绕过循环直接驱动某个编码的解码器。
2.3 在 Warpgate 客户端连接中的实际使用
虽然 decode_loop 的公开是为"tee 分流录制"场景准备的,但它同时也是 VncClient 内部解码线程的核心:connection.rs 中 VncInner::new 派生出的解码任务正是调用 decode_loop(&mut conn_ch_rx, pf, &output_func, decoding_stop_rx)。
而 Warpgate 的原生 VNC 代理路径正是基于 VncClient 构建的。在 warpgate-protocol-vnc/src/client.rs 可以看到标准的连接流程:
let mut connector =
VncConnector::new(stream).set_auth_method(async move { Ok::<_, vnc::VncError>(password) });
for encoding in encodings {
connector = connector.add_encoding(*encoding);
}
let client = connector
.allow_shared(true)
.set_pixel_format(PixelFormat::bgra())
.build()
.map_err(vnc_error)?
.try_start()
.await
.map_err(vnc_error)?
.finish()
.map_err(vnc_error)?;
随后在事件循环中调用 client.poll_event() 并映射为统一的 DesktopEvent(map_event 负责把 VncEvent::RawImage/JpegImage/Copy/SetCursor/Text/Bell 等转换成 Warpgate 自己的桌面事件模型,见 client.rs)。
值得注意的编码协商细节:文件里定义了两组编码集合——BROWSER_ENCODINGS(浏览器内嵌路径,包含 Tight、Zrle、CopyRect、Raw、CursorPseudo、DesktopSizePseudo)和 PROXY_ENCODINGS(原生代理路径,只保留 Tight、Zrle、Raw、DesktopSizePseudo)。PROXY_ENCODINGS 刻意去掉 CopyRect(避免后端需要维护服务端帧缓冲)和光标伪编码(让后端把光标烘焙进帧缓冲),保留 Tight 是为了利用其 JPEG 子编码在目标链路上节省带宽;这些解码结果最终统一以 RFB Raw 矩形向 viewer 重编码。
三、变更二:SetColorMapEntries 不再 panic
3.1 问题根源
RFB 服务器消息类型 1 是 SetColorMapEntries(调色板更新,用于非 truecolor / 8bpp 调色板服务器)。上游 ServerMsg::read 对这条消息直接命中 unimplemented!(),而 unimplemented!() 在 Rust 中的行为是 panic,panic 会直接中止解码任务,导致整个会话的录制与转发失败。
3.2 修复方式
补丁在 vendor/vnc-rs/src/client/messages.rs 中把这条消息改成"完整解析并丢弃":按 RFB 协议格式读取 padding(1 字节)、first-color(2 字节)、number-of-colors(2 字节),再读走 count * 6 字节的 RGB 调色板数据,然后返回一个新枚举变体 ServerMsg::SetColorMapEntries;解码循环在 connection.rs 中对该变体直接 {} 忽略。
// messages.rs 中的解析(节选)
1 => {
let _padding = reader.read_u8().await?;
let _first_color = reader.read_u16().await?;
let number_of_colors = reader.read_u16().await?;
let mut colors = vec![0_u8; number_of_colors as usize * 6];
reader.read_exact(&mut colors).await?;
Ok(ServerMsg::SetColorMapEntries)
}
3.3 保真度权衡
PATCHES.md 如实说明了这种取舍:Warpgate 记录的是解码后的 truecolor 帧缓冲,因此调色板本身不会被应用——如果遇到 legacy 8bpp 调色板服务器,录制画面的颜色可能不正确,但不会再崩溃;而现代 VNC 服务器都会协商 truecolor,完全不受影响。这是"以崩溃换取潜在错误颜色"的明确工程权衡。
四、变更三:针对不可信 VNC 目标的内存安全加固
VNC 目标服务器在 Warpgate 的威胁模型里属于不可信对端——一个恶意或被攻陷的 VNC 服务器可以通过畸形协议字段让客户端崩溃甚至出现内存安全问题。这一组补丁覆盖了 auth.rs、connector.rs、connection.rs、messages.rs、codec/mod.rs、codec/zrle.rs、codec/trle.rs 共 7 个文件,分两大块。
4.1 移除一处 unsound 的 transmute
上游在 auth.rs 中用 impl From<u32> for AuthResult 实现安全结果字的转换,其内部是:
unsafe { std::mem::transmute(num) }
AuthResult 是一个 #[repr(u32)] 的两变体枚举(Ok = 0、Failed = 1)。transmute 一个来自对端 socket 的任意 u32 值,只要不是 0/1 就立刻构成未定义行为(UB)。
补丁将其替换为带校验的 impl TryFrom<u32> for AuthResult(auth.rs),用普通 match 完成验证、彻底移除 unsafe:
impl TryFrom<u32> for AuthResult {
type Error = VncError;
fn try_from(num: u32) -> Result<Self, Self::Error> {
match num {
0 => Ok(AuthResult::Ok),
1 => Ok(AuthResult::Failed),
other => Err(VncError::General(format!(
"Unknown VNC SecurityResult value: {other}"
))),
}
}
}
相应地,AuthHelper::finish(auth.rs)改为 result.try_into(),未知值会作为协议错误向上传播,而不是把垃圾数据 transmute 成枚举。
4.2 为所有"目标驱动的分配/读取"设置上限
这是本组补丁的主体:凡是长度字段来自对端、且用于决定分配大小或读取字节数的位置,一律加上固定上限,超限即返回 VncError。PATCHES.md 强调"一个合法目标永远不会发出超限值",因此这不会影响正常服务器兼容性。四处加固如下:
| 位置 | 数据 | 上限常量 | 取值 | 源码 |
|---|---|---|---|---|
| 认证失败原因字符串 | RFB 安全握手失败时的 reason string | MAX_REASON_LEN |
4 KiB | auth.rs |
| ServerInit 桌面名 | ServerInit 消息中的 name-string | MAX_NAME_LEN |
4 KiB | connection.rs |
| ServerCutText 文本 | 服务器剪贴板文本 | MAX_CUT_TEXT_LEN |
1 MiB | messages.rs |
| ZRLE/TRLE 矩形 zlib 数据块 | 单矩形压缩数据长度 | MAX_RECT_DATA_LEN |
64 MiB | codec/mod.rs |
失败原因字符串是最典型的漏洞:上游用 read_to_string(读到 EOF),一个恶意目标可以无限流式发送数据。新助手函数 read_reason_string(auth.rs)严格遵循 U32 长度前缀并施加 4 KiB 上限,被 auth.rs 与 connector.rs 的共三处调用点使用:
pub(super) async fn read_reason_string<S>(reader: &mut S) -> Result<String, VncError>
where
S: AsyncRead + Unpin,
{
let len = reader.read_u32().await? as usize;
if len > MAX_REASON_LEN {
return Err(VncError::General(format!(
"VNC failure reason too long ({len} bytes)"
)));
}
let mut buf = vec![0u8; len];
reader.read_exact(&mut buf).await?;
Ok(String::from_utf8_lossy(&buf).into_owned())
}
ZRLE/TRLE 的 zlib 数据块则引入了 uninit_vec_capped 助手(codec/mod.rs),它在分配前校验长度是否超过 64 MiB。值得注意的是,补丁保留了上游的 uninit_vec 不动——理由是:该函数返回的未初始化缓冲只会在紧接着的、同长度的 read_exact 中被填满,因此一旦长度被上限约束,未初始化字节永远不会被观察到。zrle.rs 与 trle.rs 的 decode 都改为先 uninit_vec_capped(data_len)? 再 read_exact(见 zrle.rs、trle.rs)。
这些上限值与 Warpgate 自家 VNC 服务器侧的防护是对齐的:
warpgate-protocol-vnc的服务器模块同样定义了MAX_STRING_LEN = 4096作为字符串长度边界(见 server/mod.rs),PATCHES.md 中多处注释都写明了"Comparable to the Warpgate VNC server's MAX_STRING_LEN"。
4.3 新增单元测试
补丁还在 auth.rs 中补充了 #[cfg(test)] 单元测试,覆盖两个关键行为:
AuthResult转换:0 → Ok、1 → Failed正确映射,2与u32::MAX均返回Err;- 原因字符串长度上限:超限(
u32::MAX前缀)被拒绝,限内("hello")正常读取。
#[test]
fn auth_result_try_from_validates() {
assert!(matches!(AuthResult::try_from(0), Ok(AuthResult::Ok)));
assert!(matches!(AuthResult::try_from(1), Ok(AuthResult::Failed)));
assert!(AuthResult::try_from(2).is_err());
assert!(AuthResult::try_from(u32::MAX).is_err());
}
五、"除此之外没有其他改动"
PATCHES.md 专门用一节强调补丁的最小性:Warpgate 需要从线上构建像素格式、消费解码事件所需的所有类型——PixelFormat(含 TryFrom<[u8; 16]>)、VncEvent、VncEncoding、VncError、Rect——在上游就已是公开 API,无需额外暴露。这也是为什么整份补丁只需要公开一个 decode_loop,而不需要触碰任何其他类型。
这一点在 Warpgate 侧同样成立:client.rs 只从 vnc crate 导入 ClientKeyEvent, PixelFormat, VncConnector, VncEncoding, VncError, VncEvent, X11Event,全部是上游公开 API 加上 fork 的 decode_loop 导出。
六、版本升级与重新同步指南
如果上游发布新版本,PATCHES.md 给出了明确的再同步方法:在源码树中 grep Warpgate fork 注释标记,把上述变更重新应用到新版本上。目前每个改动点都在源码中以内联注释标注,例如 lib.rs 的 // Warpgate fork addition (see PATCHES.md): expose the decode loop for proxy recording.,以及 connection.rs 的 /// Warpgate fork: cap the target-driven ServerInit desktop-name length...。
此外,fork 的 Cargo.toml 是手写的最小化 manifest,等价于上游的 Cargo.toml.orig(依赖完全一致:async_io_stream、flate2、futures、thiserror、tokio-stream、tokio-util、tracing、tokio),并做了两处关键调整:
publish = false——防止这个 vendored 路径依赖被误发布到 crates.io;[lints.rust] warnings = "allow"——静默上游代码的 lint 告警,使它们不会在 Warpgate 的构建中冒出来(配合根 Cargo.toml 的 workspaceexclude,Cranky 的 deny lints 也不会作用到 vendored 代码上)。
七、小结:一条补丁链如何支撑堡垒机的 VNC 录制
把整份 PATCHES.md 串起来,可以看到一条清晰的工程逻辑:
- 业务需求(透明代理 + 无损录制)要求调用者能独立驱动 RFB 解码循环 → 补丁一公开
decode_loop,且只公开循环、不暴露内部编解码器,保持 API 面最小; - 健壮性(不因对端特性而崩溃)要求解析器覆盖全部服务器消息 → 补丁二让调色板消息可解析可忽略,换来"不崩溃"并诚实记录颜色保真度损失;
- 安全性(对端不可信)要求所有对端可控的长度字段都被上限约束、所有 UB 来源被消除 → 补丁三移除 unsound transmute、引入 4 KiB / 4 KiB / 1 MiB / 64 MiB 四级上限与配套测试。
最终,这些改动以"源码内嵌 + PATCHES.md 文档化 + Warpgate fork 注释标记"的方式固化在仓库中,并通过 warpgate-protocol-vnc 的路径依赖进入 Warpgate 的 VNC 代理链路:后端客户端负责解码目标画面,server/bridge.rs 中的 run_proxy_session 则把解码后的 DesktopEvent 逐一录制并重编码回 viewer——录制与否共享同一条代码路径,正如注释所说:"Recording is transparent — recorded and unrecorded sessions share this path."(bridge.rs)。