fix(security): 协议闸门 fix round 2 —— 堵日志放大器 + 补公开 API 覆盖

I1 变量 key 集合满了改为抑制(不淘汰):淘汰会让每个新版本串补一条 WARN,
   退化成按对端节奏的无界日志放大器,且被淘汰的 key 会再次告警
I2 补公开 check_protocol 的直接断言(.0/.1 反转此前 14 个用例全绿)
M1 warn_once_variable / sanitize_for_log 降为 pub(crate),收回公开面
M2 warn_once 的 key 改 &'static str:对端派生的动态 key 编译不过
M3 全局集合的精确条数断言改为包含性断言
M4 补用例钉住「固定集合无上限」
M5 is_log_unsafe 补 U+2028/U+2029(行/段分隔符)
M6 incompatible_warn_key 收已净化值,同一字符串只净化一次

Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
adminandClaude Code committed 2026-10-24 15:31:16 +08:00
1 parent 88dd271012
commit ec18a3f2ee
1 file changed
+150 -54
+150 -54
View File
@@ -8,11 +8,13 @@
//! ⚠️ 细节:**只比 major,但 minor 段解析失败会连累整体**
//! (`"1.x"` ⇒ 不可解析 ⇒ 不兼容;`"1.2.3"` ⇒ 段数超限 ⇒ 不兼容)。
//!
//! 一次性 WARN 的两条安全约束:
//! - **固定 key 与变量 key 分开计数**:固定 key(`protocol:missing`)永不受变量 key
//! 集合上限影响 —— 对端没法用一堆伪造版本号把「老客户端还在线上」的信号永久静音。
//! - **对端可控的值进日志前先净化**:去控制字符(含 ANSI ESC 序列)并截断,
//! 防日志伪造 / 终端转义注入。净化**只用于日志**,安全判定一律用原值。
//! 一次性 WARN 的三条安全约束:
//! - **固定 key 与变量 key 分属两个集合**:固定 key(`protocol:missing`)永不受上限约束
//! ⇒ 对端没法用一堆伪造版本号把「老客户端还在线上」的信号永久静音。
//! - **变量 key 集合满了就抑制(不淘汰)** ⇒ 洪水量按每进程 256 条封顶;
//! 若改成淘汰,每来一个新版本串就会补一条 WARN,等于给对端一个「按对端节奏打日志」的放大器。
//! - **对端可控的值进日志前先净化**:去控制字符(含 ANSI ESC 序列、U+2028/U+2029)并按
//! 整字符截断,防日志伪造 / 终端转义注入。净化**只用于日志**,安全判定一律用原值。
use std::collections::HashSet;
use std::sync::{Mutex, MutexGuard, OnceLock};
@@ -25,7 +27,7 @@ pub const PROTOCOL_VERSION_HEADER: &str = "X-Protocol-Version";
pub const INTERNAL_TOKEN_HEADER: &str = "X-Internal-Token";
/// **变量** key(key 里含对端可控内容)的集合上限(对齐上游 `warnOnce` 的有界集合)。
/// 固定 key 不受此上限约束 —— 见 [`warn_once`]。
/// 固定 key 不受此上限约束 —— 见 `warn_once`。
const WARN_ONCE_MAX_KEYS: usize = 256;
/// 写入日志前对声明值的净化上限(字节)。
@@ -37,7 +39,7 @@ fn fixed_warned_keys() -> &'static Mutex<HashSet<String>> {
KEYS.get_or_init(|| Mutex::new(HashSet::new()))
}
/// 变量 key 的已告警集合:key 含对端可控内容,**有界**(见 [`WARN_ONCE_MAX_KEYS`])。
/// 变量 key 的已告警集合:key 含对端可控内容,**有界**(见 `WARN_ONCE_MAX_KEYS`)。
fn variable_warned_keys() -> &'static Mutex<HashSet<String>> {
static KEYS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
KEYS.get_or_init(|| Mutex::new(HashSet::new()))
@@ -56,24 +58,16 @@ fn claim_fixed_key(set: &Mutex<HashSet<String>>, key: &str) -> bool {
lock_set(set).insert(key.to_string())
}
/// 登记变量 key:首次登记返回 true。集合有界 —— 满了就淘汰一个旧 key 再插入,
/// 于是对端灌爆集合也只能「挤掉旧告警」,不能让新告警永久失效。
/// 登记变量 key:首次登记返回 true。
///
/// 集合有界:**满了就抑制**(返回 false),**不淘汰**。淘汰会让「每来一个新版本串就补一条 WARN」
/// 变成按对端节奏的无界日志放大器,而且被淘汰的 key 之后会再次告警,破坏「同 key 只告警一次」。
fn claim_variable_key(set: &Mutex<HashSet<String>>, key: &str) -> bool {
let mut set = lock_set(set);
if set.contains(key) {
if set.len() >= WARN_ONCE_MAX_KEYS {
return false;
}
while set.len() >= WARN_ONCE_MAX_KEYS {
let victim = { set.iter().next().cloned() };
match victim {
Some(v) => {
set.remove(&v);
}
None => break,
}
}
set.insert(key.to_string());
true
set.insert(key.to_string())
}
/// 实际打印告警。**调用方必须已释放集合锁**(打印与登记分离,避免持锁做 IO)。
@@ -123,9 +117,10 @@ pub fn is_protocol_acceptable(declared: Option<&str>) -> bool {
/// 同 key 只告警一次。返回 true = 本次真的告警了。
///
/// ⚠️ **key 必须是固定值**(与对端输入无关)—— 固定 key 永不受集合上限约束,
/// 任何时候都能告警。key 里含对端可控内容时请改用 [`warn_once_variable`]。
pub fn warn_once(key: &str, message: &str) -> bool {
/// ⚠️ **key 必须是固定值**(与对端输入无关)—— 参数类型是 `&'static str`,
/// 传一个对端派生的动态 key **编译不过**。固定 key 永不受集合上限约束,任何时候都能告警。
/// key 里含对端可控内容时请改用 `warn_once_variable`。
pub fn warn_once(key: &'static str, message: &str) -> bool {
if claim_fixed_key(fixed_warned_keys(), key) {
emit_warn(message);
true
@@ -134,12 +129,12 @@ pub fn warn_once(key: &str, message: &str) -> bool {
}
}
/// 同 key 只告警一次,但 key 集合**有界**(上限 [`WARN_ONCE_MAX_KEYS`])。
/// 同 key 只告警一次,但 key 集合**有界**(上限 `WARN_ONCE_MAX_KEYS`,满了即抑制)。
/// 返回 true = 本次真的告警了。
///
/// 用于 key 含对端可控内容(如声明的协议版本)的场景:对端即使灌爆集合,
/// 也只是挤掉旧告警,**不会**让固定 key 的告警失效。
pub fn warn_once_variable(key: &str, message: &str) -> bool {
/// 也只是让**新的**变量告警不再产生,**不会**让固定 key 的告警失效。
pub(crate) fn warn_once_variable(key: &str, message: &str) -> bool {
if claim_variable_key(variable_warned_keys(), key) {
emit_warn(message);
true
@@ -148,24 +143,27 @@ pub fn warn_once_variable(key: &str, message: &str) -> bool {
}
}
/// 需要从日志中剔除的字符:控制字符(C0/C1)与方向控制类格式字符。
/// 需要从日志中剔除的字符:控制字符(C0/C1)、行/段分隔符与方向控制类格式字符。
fn is_log_unsafe(c: char) -> bool {
c.is_control()
|| matches!(
c,
'\u{200b}'..='\u{200f}' // 零宽字符
| '\u{2028}'..='\u{2029}' // LINE / PARAGRAPH SEPARATOR(部分查看器当换行处理)
| '\u{202a}'..='\u{202e}' // 双向覆写(RLO/LRO)
| '\u{2060}'..='\u{206f}' // 双向隔离 + 隐形字符
| '\u{feff}' // BOM / ZWNBSP
)
}
/// 净化对端可控的字符串,供**日志 / 告警**用途:去控制字符(含 ANSI ESC 序列)并截断。
/// 净化对端可控的字符串,供**日志 / 告警**用途:去控制字符(含 ANSI ESC 序列)并按整字符截断。
///
/// ⚠️ **只用于日志**。安全判定([`is_protocol_compatible`] / [`is_protocol_acceptable`])
/// ⚠️ **只用于日志**。安全判定(`is_protocol_compatible` / `is_protocol_acceptable`)
/// 必须使用原值 —— 净化会引入绕过风险(如 `"1.0\u{1b}[0m"` 净化后变 `"1.0"`,
/// 反而可能被误判为兼容)。
pub fn sanitize_for_log(raw: &str) -> String {
///
/// 截断**按整字符推进**(不用 `String::truncate`)⇒ 64 字节边界切在多字节字符中间也不会 panic。
pub(crate) fn sanitize_for_log(raw: &str) -> String {
let mut out = String::new();
let mut it = raw.chars().peekable();
while let Some(c) = it.next() {
@@ -210,8 +208,9 @@ pub fn sanitize_for_log(raw: &str) -> String {
}
/// 变量 key:含**净化后**的声明值(防日志伪造 / 终端转义注入)。
fn incompatible_warn_key(declared: &str) -> String {
format!("protocol:incompatible:{}", sanitize_for_log(declared))
/// 入参必须**已经是净化过的**字符串(只净化一次,不重复净化)。
fn incompatible_warn_key(safe: &str) -> String {
format!("protocol:incompatible:{}", safe)
}
/// 闸门判定 + 一次性告警。返回 `(是否放行, 本次是否真的告警了)`。
@@ -227,13 +226,13 @@ fn check_protocol_with_warn(declared: Option<&str>) -> (bool, bool) {
);
return (true, warned);
}
// 判定用原值 `d`;日志用净化值(防日志伪造 / 终端转义注入)。
if is_protocol_compatible(d) {
return (true, false);
}
// 判定用原值;日志用净化值(防日志伪造 / 终端转义注入)。
let safe = sanitize_for_log(d);
let warned = warn_once_variable(
&incompatible_warn_key(d),
&incompatible_warn_key(&safe),
&format!(
"跨端协议版本不兼容(对端 {},本端 {}),请升级对端",
safe, PROTOCOL_VERSION
@@ -242,7 +241,7 @@ fn check_protocol_with_warn(declared: Option<&str>) -> (bool, bool) {
(false, warned)
}
/// 闸门判定 + 一次性告警。
/// 闸门判定 + 一次性告警。返回 true = 放行。
pub fn check_protocol(declared: Option<&str>) -> bool {
check_protocol_with_warn(declared).0
}
@@ -260,7 +259,7 @@ mod tests {
}
}
/// 清空全局告警状态,让用例从干净状态开始。
/// 清空全局告警状态,让用例从干净状态开始(避免用例之间抢 key)。
fn reset_warn_state() {
lock_set(fixed_warned_keys()).clear();
lock_set(variable_warned_keys()).clear();
@@ -316,6 +315,16 @@ mod tests {
// ---- 闸门本身:判定 + 告警 ----
#[test]
fn public_check_protocol_is_covered() {
// 公开 API 必须被直接断言(否则把 `.0` 写成 `.1` 也没人发现)
let _g = test_guard();
reset_warn_state();
assert!(check_protocol(None), "未声明 ⇒ 兼容期放行");
assert!(check_protocol(Some("1.4")), "同 major ⇒ 放行");
assert!(!check_protocol(Some("5.1")), "major 不同 ⇒ 拒绝");
}
#[test]
fn check_protocol_allows_missing_and_compatible_and_rejects_incompatible() {
let _g = test_guard();
@@ -365,14 +374,20 @@ mod tests {
}
// 变量 key 集合仍然有界
assert!(lock_set(variable_warned_keys()).len() <= WARN_ONCE_MAX_KEYS);
// 两个集合分开计数:变量 key 不得污染固定 key 集合
assert_eq!(
lock_set(fixed_warned_keys()).len(),
1,
"变量 key 不得污染固定 key 集合"
// 两个集合分开计数(包含性断言,不断言精确条数):
// 固定 key 记在固定集合,变量 key 不许进固定集合
assert!(
lock_set(fixed_warned_keys()).contains("test:fixed:keep"),
"固定 key 应记在固定集合"
);
assert!(
!lock_set(fixed_warned_keys()).contains("test:flood:0"),
"变量 key 不得记进固定集合"
);
assert!(
!lock_set(variable_warned_keys()).contains("test:fixed:keep"),
"固定 key 不得记进变量集合"
);
assert!(lock_set(fixed_warned_keys()).contains("test:fixed:keep"));
assert!(!lock_set(variable_warned_keys()).contains("test:fixed:keep"));
// 固定 key 仍被记住 ⇒ 不会被变量集合淘汰
assert!(
@@ -385,24 +400,68 @@ mod tests {
assert!(allowed);
assert!(warned, "变量 key 灌爆后,固定 key 仍必须能告警");
// 变量 key 路径也没被灌死:新 key 仍拿得到位置
// 变量 key 路径被上限封顶:新的声明值不再逐条告警(洪水量有界的代价)
let (allowed, warned) = check_protocol_with_warn(Some("4.2"));
assert!(!allowed);
assert!(warned, "灌爆后新出现的声明值仍应告警");
assert!(!allowed, "major 不同 ⇒ 仍然拒绝");
assert!(!warned, "变量 key 集合已满 ⇒ 新声明值不再告警");
}
#[test]
fn variable_key_set_stays_bounded() {
let local = Mutex::new(HashSet::new());
for i in 0..(WARN_ONCE_MAX_KEYS * 2) {
for i in 0..WARN_ONCE_MAX_KEYS {
assert!(
claim_variable_key(&local, &format!("k:{}", i)),
"新 key 应拿到位置"
"上限内的 key 应拿到位置"
);
}
// 超上限的 key 一律被抑制(不淘汰 ⇒ 不会把老 key 挤掉)
for i in WARN_ONCE_MAX_KEYS..(WARN_ONCE_MAX_KEYS + 32) {
assert!(
!claim_variable_key(&local, &format!("k:{}", i)),
"超上限的 key 应被抑制"
);
}
assert!(lock_set(&local).len() <= WARN_ONCE_MAX_KEYS);
}
#[test]
fn flood_cannot_amplify_log_volume() {
let _g = test_guard();
reset_warn_state();
// 洪水量必须被封顶:每进程至多 WARN_ONCE_MAX_KEYS 条变量告警
let mut warned = 0usize;
for i in 0..(WARN_ONCE_MAX_KEYS * 4) {
if warn_once_variable(&format!("test:volume:{}", i), "灌水") {
warned += 1;
}
}
assert!(
warned <= WARN_ONCE_MAX_KEYS,
"洪水量必须封顶,实际 {} 条",
warned
);
assert!(lock_set(variable_warned_keys()).len() <= WARN_ONCE_MAX_KEYS);
}
#[test]
fn fixed_key_set_is_never_capped() {
let _g = test_guard();
reset_warn_state();
// 固定集合**无上限**:超过 256 个互异 key 也必须每一个都登记成功
for i in 0..(WARN_ONCE_MAX_KEYS * 2) {
assert!(
claim_fixed_key(fixed_warned_keys(), &format!("test:fixed-flood:{}", i)),
"固定 key 永不被抑制"
);
}
// 包含性断言:集合里确实有这些 key
assert!(lock_set(fixed_warned_keys()).contains("test:fixed-flood:0"));
assert!(lock_set(fixed_warned_keys()).len() >= WARN_ONCE_MAX_KEYS * 2);
}
// ---- 日志净化(只影响日志,不影响判定) ----
#[test]
@@ -414,6 +473,27 @@ mod tests {
assert_eq!(sanitize_for_log("1.0\u{1b}[31mRED\u{1b}[0m"), "1.0RED");
assert_eq!(sanitize_for_log("1.0\u{7}2.0"), "1.02.0");
assert_eq!(sanitize_for_log("1.0\u{202e}2.0"), "1.02.0");
// U+2028 / U+2029 是行/段分隔符,部分查看器当换行处理 ⇒ 必须剔除
assert_eq!(sanitize_for_log("1.0\u{2028}2.0"), "1.02.0");
assert_eq!(sanitize_for_log("1.0\u{2029}2.0"), "1.02.0");
}
#[test]
fn sanitized_log_value_has_no_control_chars() {
let raw = "1.0\u{1b}[31m\u{2028}\u{2029}\n\u{7}\u{202e}中";
let s = sanitize_for_log(raw);
assert!(
!s.chars().any(|c| c.is_control()),
"净化后不得残留控制字符:{:?}",
s
);
assert!(
!s.contains('\u{2028}') && !s.contains('\u{2029}'),
"净化后不得残留 U+2028/U+2029:{:?}",
s
);
assert!(s.len() <= LOG_MAX_LEN);
assert!(std::str::from_utf8(s.as_bytes()).is_ok(), "必须是合法 UTF-8");
}
#[test]
@@ -423,6 +503,23 @@ mod tests {
assert_eq!(s.len(), LOG_MAX_LEN);
}
#[test]
fn sanitize_truncates_on_char_boundary_for_cjk() {
// 64 字节边界会切在多字节字符中间 ⇒ 必须整字符推进,不得 panic
let cjk = "中".repeat(100);
let s = sanitize_for_log(&cjk);
assert!(s.len() <= LOG_MAX_LEN);
assert!(s.chars().all(|c| c == '中'));
assert_eq!(s.len(), 63, "21 个中文字 = 63 字节,第 22 个会越过 64");
assert!(std::str::from_utf8(s.as_bytes()).is_ok(), "必须是合法 UTF-8");
// ASCII 占到 63 字节后再跟一个多字节字符 ⇒ 不得越界、不得 panic
let mixed = format!("{}{}", "a".repeat(LOG_MAX_LEN - 1), "中");
let s2 = sanitize_for_log(&mixed);
assert!(s2.len() <= LOG_MAX_LEN);
assert_eq!(s2.len(), LOG_MAX_LEN - 1);
}
#[test]
fn judgment_uses_raw_value_not_sanitized() {
// 净化后是 "1.0"(major 相同 ⇒ 兼容),但判定必须用原值 ⇒ 原值不可解析 ⇒ 仍判不兼容
@@ -440,11 +537,10 @@ mod tests {
#[test]
fn warn_key_uses_sanitized_value() {
assert_eq!(
incompatible_warn_key("2.0\u{1b}[0m"),
"protocol:incompatible:2.0"
);
let key = incompatible_warn_key("9.9\n伪造日志行");
let safe = sanitize_for_log("2.0\u{1b}[0m");
assert_eq!(safe, "2.0");
assert_eq!(incompatible_warn_key(&safe), "protocol:incompatible:2.0");
let key = incompatible_warn_key(&sanitize_for_log("9.9\n伪造日志行"));
assert!(!key.contains('\n'), "告警 key 不得带换行");
assert!(!key.contains('\u{1b}'), "告警 key 不得带 ESC");
}