Warpgate 如何改造并内嵌 vnc-rs:RFB 解码循环暴露与对抗不可信 VNC 目标的内存安全加固

原创2026-10-14 09:49:521,403 阅读
文章标签:后端网络安全认证鉴权

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。涉及三个文件:

函数签名与上游完全一致,未做任何改动:

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 的 workspace exclude,Cranky 的 deny lints 也不会作用到 vendored 代码上)。

七、小结:一条补丁链如何支撑堡垒机的 VNC 录制

把整份 PATCHES.md 串起来,可以看到一条清晰的工程逻辑:

  1. 业务需求(透明代理 + 无损录制)要求调用者能独立驱动 RFB 解码循环 → 补丁一公开 decode_loop,且只公开循环、不暴露内部编解码器,保持 API 面最小;
  2. 健壮性(不因对端特性而崩溃)要求解析器覆盖全部服务器消息 → 补丁二让调色板消息可解析可忽略,换来"不崩溃"并诚实记录颜色保真度损失;
  3. 安全性(对端不可信)要求所有对端可控的长度字段都被上限约束、所有 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)。

登录后查看全文
warpgate