Brakeman 反序列化漏洞检测指南:Marshal、YAML、CSV 与 Oj 的不安全反序列化扫描
Brakeman 反序列化漏洞检测指南:Marshal、YAML、CSV 与 Oj 的不安全反序列化扫描
本文围绕 Brakeman 对 Ruby 对象反序列化的安全检测展开,系统说明 Marshal、YAML、CSV 以及 Oj 等序列化 API 为什么危险、Brakeman 如何发现它们、不同置信度如何判定,并结合仓库源码与测试用例给出可复现的实战验证方式。读完本文,你将掌握不安全反序列化(Unsafe Deserialization)这一警告类型在 Brakeman 中的完整检测逻辑、触发场景与修复思路。
背景:Ruby 序列化机制与反序列化风险
Ruby 对象可以被序列化为字符串,常用的途径包括:
- 标准库
Marshal,提供二进制格式的对象序列化; YAML库,可将 Ruby 对象 dump 为 YAML 文本,再通过YAML.load还原;JSON库,与上述类似但通常只还原普通数据结构;CSV库,同样提供load方法可以从字符串创建对象。
反序列化(deserialization)的本质是"从数据重建任意对象"。当被反序列化的内容由攻击者控制时,攻击者可以在序列化负载中嵌入特殊构造的对象(例如带 _ruby 类型标签的 YAML 节点、精心构造的 Marshal 字节流),诱导应用在还原对象时执行任意代码。正如关联文档 unsafe_deserialization/index.markdown 所指出的,反序列化任意对象可以导致远程代码执行(Remote Code Execution),最著名的实例是 CVE-2013-0156——Rails 的 XML 参数解析通过 YAML 类型标签触发的代码执行漏洞。
Brakeman 对该问题的态度非常明确:只要用户输入流向了 Marshal、YAML 或 CSV 的加载类方法,就发出警告;而 JSON 相关路径则由独立的 CVE 检查(CVE-2013-0333)覆盖,避免重复告警。
检测范围总览:哪些 API 会被盯上
Brakeman 的反序列化检查由 lib/brakeman/checks/check_deserialize.rb 中的 Brakeman::CheckDeserialize 实现,其描述为 "Checks for unsafe deserialization of objects"。run_check 方法依次执行四个分支:
def run_check
check_yaml
check_csv
check_marshal
check_oj
end
对应的检测目标与方法如下表:
| 库/类 | 被检测的方法 | 说明 |
|---|---|---|
YAML |
load、load_documents、load_stream、parse_documents、parse_stream |
load 仅在未使用 safe_yaml 时直接全查;若项目引入 safe_yaml gem,则额外检查 safe: true 选项是否真正生效 |
CSV |
load |
从字符串重建对象,可能触发任意对象构造 |
Marshal |
load、restore |
二进制格式,restore 是 load 的别名,同样危险 |
Oj |
object_load、load |
object_load 无论什么模式都判定不安全;load 依据默认模式与调用参数判断 |
需要特别说明的是:Oj 的检测是 check_deserialize.rb 对关联文档内容的源码级延伸。Oj(Optimized JSON)是一个高性能 JSON 解析库,其 load 在不同 mode 下行为差异极大,Brakeman 对此做了精细建模,详见下文"Oj 的模式感知检测"。
检测原理:从源码看告警如何产生
统一的调用查找入口
check_methods 使用 tracker 的 find_call 在全部代码中定位目标调用:
def check_methods target, *methods
tracker.find_call(:target => target, :methods => methods ).each do |result|
check_deserialize result, target
end
end
find_call 是 Brakeman 核心的调用索引机制,能够跨控制器、模型、视图与库代码定位指定接收者和方法的调用点,即便调用发生在方法内部、经过中间变量传递,也能被追踪到。
置信度三级判定
check_deserialize 根据用户输入与调用参数的距离判定置信度:
if input = has_immediate_user_input?(arg)
confidence = :high
elsif input = include_user_input?(arg)
confidence = :medium
elsif target == :Marshal
confidence = :low
message = msg("Use of ", msg_code("#{target}.#{method}"), " may be dangerous")
end
- High(高置信度):用户输入(如
params[:x]、cookies[:x])被直接作为反序列化方法的首个参数传入; - Medium(中置信度):用户输入经过方法调用、变量赋值或字符串拼接后间接流入参数(
include_user_input?能穿透一层中间转换); - Low(低置信度):仅针对
Marshal——即使没有识别到明确的用户输入,只要调用了Marshal.load/Marshal.restore也会给出低置信度提示,消息为 "Use of Marshal.load may be dangerous"。这体现了Marshal格式本身的不可信性:任何来源不明的Marshal字节流都不应被加载。
告警内容的生成
命中后生成一条警告记录:
warn :result => result,
:warning_type => "Remote Code Execution",
:warning_code => :unsafe_deserialize,
:message => message,
:user_input => input,
:confidence => confidence,
:link_path => "unsafe_deserialization",
:cwe_id => [502]
关键字段解读:
warning_type为 "Remote Code Execution",即该问题归入 RCE 大类,但通过link_path => "unsafe_deserialization"关联到本文对应的警告类型文档;warning_code为:unsafe_deserialize,在 lib/brakeman/warning_codes.rb 中对应数值25,可用于精确过滤与指纹比对;cwe_id为 CWE-502(Deserialization of Untrusted Data),方便对接 SARIF、Sonar 等安全报告格式;message形如 "YAML.loadcalled with parameter value",其中msg_input会标注具体用户输入来源。
safe_yaml 特殊处理
当项目依赖中包含 safe_yaml gem 时,YAML.load 的行为会改变(safe_yaml 会为 load 注入安全默认值)。此时检查逻辑变为:
if uses_safe_yaml?
tracker.find_call(target: :YAML, method: :load).each do |result|
call = result[:call]
options = call.second_arg
if hash? options and true? hash_access(options, :safe)
next
else
check_deserialize result, :YAML
end
end
else
check_methods :YAML, :load
end
即:显式传入 YAML.load(data, safe: true) 时放行(next 跳过告警),否则仍按不安全处理。注意 safe_yaml 的 safe: 选项只对 load 生效,load_documents、load_stream、parse_documents、parse_stream 等批量方法不在豁免范围内,始终会被检查。
实战触发样例:测试应用中的告警与放行
仓库的测试应用为验证检测行为提供了真实可运行的样例。在 test/apps/rails3/app/controllers/home_controller.rb 中集中展示了各类触发场景:
def test_yaml_file_access
#Should not warn about access, but about remote code execution
YAML.load "some/path/#{params[:user][:file]}"
#Should warn
YAML.parse_file("whatever/" + params[:file_name])
end
def test_yaml_load
YAML.load params[:input]
YAML.load some_method #No warning
YAML.load x(cookies[:store])
YAML.load User.first.bad_stuff
end
def test_more_yaml_methods
YAML.load_documents params[:input]
YAML.load_stream cookies[:thing]
YAML.parse_documents "a: #{params[:a]}"
YAML.parse_stream User.find(1).upload
end
这段样例透露了三条边界行为:
- 参数来自
params或cookies时告警:YAML.load params[:input]、YAML.load x(cookies[:store])均触发; - 字符串字面量或模型属性不告警:
YAML.load some_method和YAML.load User.first.bad_stuff没有用户输入成分,注释明确标记 "No warning"; YAML.parse_file等文件读取路径虽然也涉及用户输入,但归属为 RCE 类告警而非 File Access,注释 "Should not warn about access, but about remote code execution" 说明了警告类型的取舍。
Oj 场景在 test/apps/rails5.2/app/controllers/users_controller.rb 中同样有完整对照:
def some_api
Oj.load(params[:json]) # Unsafe by default
Oj.load(params[:json], mode: :object) # Unsafe, regardless of default
Oj.object_load(params[:json], mode: :strict) # Always unsafe, regardless of mode
Oj.load(params[:json], mode: :strict) # Safe
end
四行代码分别对应四种判定结果,注释已给出预期:默认模式下的 Oj.load、显式 mode: :object、以及任何模式下的 Oj.object_load 都是不安全的;只有显式 mode: :strict(或 :compat、:safe 等非 object 模式)才安全。
Oj 的模式感知检测
Oj.load 的危险性与运行模式强相关,Brakeman 在 check_oj 中做了两项判断:
def check_oj
check_methods :Oj, :object_load # Always unsafe, regardless of mode
unsafe_mode = :object
safe_default = oj_safe_default?
tracker.find_call(:target => :Oj, :method => :load).each do |result|
call = result[:call]
options = call.second_arg
if options and hash? options and mode = hash_access(options, :mode)
if symbol? mode and mode.value == unsafe_mode
check_deserialize result, :Oj
end
elsif not safe_default
check_deserialize result, :Oj
end
end
end
逻辑要点:
Oj.object_load无条件告警:该 API 专门用于还原 Ruby 对象,任何模式下都危险;- 显式传参优先:调用带
mode:选项时,只对mode: :object告警,mode: :strict等安全模式放行; - 未传参时看默认配置:若项目通过
Oj.default_options = { mode: :strict }设置了安全默认值,或启用了Oj.mimic_JSON(此时Oj.load行为对齐JSON.parse),未传mode的调用不告警;否则默认按不安全处理。
默认配置的推断逻辑在 oj_safe_default? 与 oj_safe_mode? 中实现:只要存在 Oj.mimic_JSON 调用,或 Oj.default_options= 的入参 mode 不是 :object,就认为默认安全。相关配置样例见 test/apps/rails5.2/config/initializers/oj.rb,回归测试见 test/tests/oj.rb——该测试通过 OjSettingsTests 在 rescanner 场景下验证:取消注释 Oj.mimic_JSON 或 Oj.default_options 后,原有的 1 条不安全告警被修复(assert_fixed 1);而追加 Oj.default_options = { whatever: false } 这种非安全 mode 的配置则不会消除告警(assert_fixed 0)。
与 JSON / YAML CVE 检查的边界划分
关联文档特别指出:"JSON is covered by the checks for CVE-2013-0333"。这意味着 Brakeman 对反序列化风险的覆盖是分层的:
- 通用反序列化检查(本文主题):
Marshal、YAML、CSV、Oj的任意用户输入加载调用,由check_deserialize.rb负责; - Rails 框架层漏洞检查:Rails 的 XML 参数解析经由 YAML 类型标签触发的 CVE-2013-0156,由 lib/brakeman/checks/check_yaml_parsing.rb 按版本检查;JSON 解析相关的 CVE-2013-0333 与 CVE-2013-0269 由 lib/brakeman/checks/check_json_parsing.rb 覆盖。这两类检查按 Rails/依赖版本号触发,与本文针对"应用代码显式调用反序列化 API"的检查互补,避免对同一漏洞重复告警。
修复建议与最佳实践
Brakeman 在 lib/brakeman/report/config/remediation.yml 中为该警告类型提供了修复成本参考值 2000000(该项用于 CodeClimate 类报告的成本估算),而实际的修复思路应遵循以下原则:
- 永远不要反序列化不可信数据:
Marshal.load、YAML.load、CSV.load、Oj.load(object 模式)只应处理自己生成的、经完整性校验的数据; - 优先使用安全替代 API:YAML 用
YAML.safe_load(或Psych.safe_load)并显式指定允许的类白名单;JSON 用JSON.parse;Marshal场景尽量改用JSON或数据库持久化; - Oj 项目显式固定安全模式:在 initializer 中设置
Oj.default_options = { mode: :strict }或启用Oj.mimic_JSON,使未显式传mode的Oj.load也保持安全默认,Brakeman 会识别这类配置并减少误报; - 接入 CWE-502 上下文:告警的
cwe_id: [502]与 warning_code25可在 CI 门禁、SARIF 导入与告警去重指纹中直接使用。
延伸阅读
- 警告类型的原始定义文档:docs/warning_types/unsafe_deserialization/index.markdown
- RCE 大类说明:docs/warning_types/remote_code_execution/index.markdown;YAML 加载导致的 RCE 专门说明:docs/warning_types/remote_code_execution_yaml_load/index.markdown
- 检测实现源码:lib/brakeman/checks/check_deserialize.rb
- 警告码定义:lib/brakeman/warning_codes.rb
- 相关框架层检查:lib/brakeman/checks/check_yaml_parsing.rb、lib/brakeman/checks/check_json_parsing.rb
总而言之,不安全反序列化是 Brakeman 判定为远程代码执行的高危告警之一。理解其"用户输入流向加载类方法即告警、Marshal 无输入也低置信度提示、Oj 依赖模式建模"的三层判定逻辑,能帮助你在扫描报告中准确区分真实风险与安全调用,并把修复动作落在"改用安全反序列化 API + 固定安全默认配置"这两个关键点上。