动态筛选别吞客户端 filter:值绑定、字段白名单与操作符注入

动态筛选别吞客户端 filter:值绑定、字段白名单与操作符注入

Hello,我是小兔大白糖。 同事说「我们用的是 Mongo / ORM,不会有 SQL 注入」——下一秒,登录接口被 { "password": { "$ne": null } } 一类文档绕过去了。写成这篇,给要做 动态筛选 / Query Builder(查询构造器)注入面 调研的初中级后端同学:不是某仓库的安全工单,而是业界可复述的防护心智模型。

说明:下文伪流程、字段名均为教学脱敏示意。读完带走的是「值绑定 ≠ 整包 filter 安全」「字段名必须允许名单」——不是可粘贴的内部包路径。查询组装落在哪一层,见姊妹篇 /blog/service_repository_boundary/;错误里别回传完整 filter,见 /blog/pii_never_in_logs_urls_errors/。

估计阅读时间:8 分钟


目录


为什么现在要关心

文档库「绑值」通常挡住拼接注入;挡不住「用户输入被当成操作符文档」。

ORM、Query Builder、以及「把前端 filter JSON 丢进数据库」都很常见。驱动用 BSON / 占位符绑定值时,相对不容易踩经典字符串拼接坑。但若同时满足下面任一条件,攻击面就回来了:

你看到的现象常见真相
「Mongo 不会 SQL 注入」却被登录绕过客户端塞进了 $ne / $gt 等运算符(operator),不是普通字符串值
筛选「很灵活」——任意字段名都能查字段名来自用户,可枚举敏感键或撞索引外路径
管理端直接 Unmarshal 整包 filter用户输入被当成 filter AST(抽象语法树),服务端不再解释形状
支持「高级表达式」搜全文开了 $where / 原始表达式字符串,接近服务端脚本面

SQL 侧经典事故是拼字符串;文档库侧经典事故是用户输入被当成操作符文档。两套语法,同一类合同错误:把「不可信输入」放进了「查询结构位」。


心智模型:点餐单 vs 后厨刀法

主比喻:餐厅。

  • 菜单上的菜名 = 字段允许名单(allowlist):客人只能点列出的项。
  • 口味备注 = 绑定后的值:咸淡、份量——进锅前由后厨按类型校验。
  • 刀法说明 = $ne / $gt / $where 一类操作符:只能后厨写死,不能客人写进点菜单。
  • 进后厨改菜谱 = 原样接收整包 filter JSON,或放开任意表达式。
点餐单 vs 后厨刀法:客人只能选菜单菜名与口味备注;刀法与菜谱由后厨写死
点餐单 vs 后厨刀法:客人只能选菜单菜名与口味备注;刀法与菜谱由后厨写死 · 点击查看 SVG 原图

类比局限一句说清:点餐单解释「谁有权决定查询结构」;解释不了索引选择、投影泄露、还是聚合管道里的另一套操作符面——那些要另开合同,别指望白名单字段 alone 包圆。


精确定义:三条硬规则

删掉比喻后,你仍应能复述这三条:

  1. 值用驱动绑定;字段名只用允许名单。
  2. 禁止把客户端 JSON 直接当作 filter AST;只接受已知形状的 DTO(数据传输对象),再由服务端组装查询文档 / 参数化 SQL。
  3. 禁用或默认关闭危险操作符(如 $where、任意表达式字符串);对输入长度与嵌套深度设上限。

人话对照:

位置谁写不可信输入能否决定
字段名 / 键服务端 allowlist否
比较操作符($gte 等)服务端写死否
标量值(状态枚举、年龄数字)客户端 → 绑定 / 类型校验仅值本身,且形状已知
值绑定安全 vs 整包 filter 危险:绑值挡住拼接;原样 Unmarshal 打开运算符注入面
值绑定安全 vs 整包 filter 危险:绑值挡住拼接;原样 Unmarshal 打开运算符注入面 · 点击查看 SVG 原图

「Mongo 用 BSON 所以安全」只覆盖了值转义这一层;键名与操作符文档形状仍是你的合同。


业界常见模式对照

下面不是某框架说明书,是后端里 常见落法归纳(公开概念,可和同事核对)。

模式做法优点代价 / 副作用适用
A. 拼接查询串Sprintf / 字符串拼 filter写起来快最快出事禁止
B. 值绑定 + 固定字段代码写死字段;值走占位符 / BSON面最小、好审灵活度低大多数 CRUD
C. 字段白名单 Builder用户选字段 ∈ allowlist;值校验类型;操作符服务端写动态筛选可控要维护名单;新字段要审对公动态筛选默认
D. 原样接收 filter JSONUnmarshal 进 map 丢给 Find前端极自由运算符注入面大禁止对公网
E. 服务端查询 DSL自研安全子集再编译成原生查询复杂搜索产品可演进设计与维护成本高搜索中台 / 高级筛选产品

教学基线:对公 API 默认 C(或退回 B);内部工具也尽量避免 D。真要「任意组合条件」,走 E 的安全子集,而不是把 D 洗成「内部人可信」。

代价必须说清:C 的白名单是持续税——漏审一个键名,等于开了半扇 D;名单过严,产品会逼着人走「临时加字段」旁路,旁路往往又滑回 D。


教学示意:DTO 组装,不吞 AST

结论:客户端只提交已知形状;$gte 等操作符只出现在服务端字面量里。

白名单字段 + 服务端写死操作符:DTO 进门,组装层输出查询文档
白名单字段 + 服务端写死操作符:DTO 进门,组装层输出查询文档 · 点击查看 SVG 原图

伪流程(教学脱敏,非某语言 API 契约):

// 危险:整包当 AST
filter := unmarshal(clientJSON)   // 可能含 "$ne": null

// 安全:已知 DTO → 服务端组装
dto := { status?: enum, minAge?: int }
q := {}
if dto.status in allowlist_values { q.status = dto.status }
if dto.minAge != nil { q.age = { "$gte": dto.minAge } }  // 操作符服务端写死

Builder 形态同理:Where(field, value) 的内部第一步应是 field ∈ allowlist,再写入绑定值;不要提供「任意 map 直通 Find」的快捷入口给 handler。

组装落点与 /blog/service_repository_boundary/ 一致:查询形状在受控层(仓储 / 专用 Builder)收口,不在 HTTP handler 裸拼。


常见坑

「有驱动绑定」≠「查询合同安全」。

误判实际风险
「Mongo 不会 SQL 注入」忽略运算符注入(operator injection):$ne、$gt、$regex 等改语义
白名单了集合 / 表名子文档键、投影字段、排序键仍任意 → 字段枚举与意外路径
错误信息回传完整 filter助攻探测;亦踩可观测 / 对外平面红线(见 /blog/pii_never_in_logs_urls_errors/)
GraphQL / JSON 里 password: { "$gt": "" }类型声明是 string,运行时却进了对象 → 忘了类型校验等于放行操作符文档
「内部工具可以 D」凭证一漏或 SSRF / 被劫持的前端,内部面即公网面

单测至少覆盖三类:$ne 登录绕过样例、超长 / 深嵌套 map、未知 $ 键名被拒绝。


选型结论

  1. 公开查询入口:DTO + 字段 / 枚举白名单 + 服务端组装;默认拒绝未知 $ 操作符键。
  2. Builder API:Where(field, value) 内校验 field;不要给 handler「任意 filter map」后门。
  3. 危险能力默认关:$where、任意表达式字符串;长度与嵌套深度设上限。
  4. 单测当合同:运算符注入样例、超长输入、嵌套 map——和功能用例同级。
  5. 分层一致:组装在受控仓储 / Builder;错误与日志不回传完整 filter(边界篇 + PII 篇)。

下一步:把现有「动态筛选」入口画成一张表——客户端能决定的是「字段名 / 操作符 / 仅值」哪一列。若出现「操作符或任意键」且对公网开放,优先收到模式 C,而不是加长黑名单赌运气。


Checklist「润色」自检

  • 已读 polish.md §0;调性:分享向;业界通用
  • Hello 开篇;Hook → 模型 → 定义 → 对比 → 示例 → 坑 → 小结
  • 各 H2 BLUF;少代码;三图 <Diagram>;内链尾斜杠
  • 推荐方案写了代价(C 的白名单税 / E 的 DSL 成本);未发明内部 API;无项目工单口吻
  • 无重复 H1;HTML 注释 frontmatter date=2026-11-04
  • 可链 /blog/service_repository_boundary/、/blog/pii_never_in_logs_urls_errors/

[TECH-CHECK]

无。文中 $ne / $gt / $where、BSON 绑定、运算符注入均为公开可核对的 MongoDB / NoSQL 安全概念;未断言某厂官方内部实现。