Brakeman 反序列化漏洞检测指南:Marshal、YAML、CSV 与 Oj 的不安全反序列化扫描

原创2026-09-28 15:51:221,696 阅读
文章标签:SAST应用安全开发工具

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.load called 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

这段样例透露了三条边界行为:

  1. 参数来自 params 或 cookies 时告警:YAML.load params[:input]、YAML.load x(cookies[:store]) 均触发;
  2. 字符串字面量或模型属性不告警:YAML.load some_method 和 YAML.load User.first.bad_stuff 没有用户输入成分,注释明确标记 "No warning";
  3. 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 类报告的成本估算),而实际的修复思路应遵循以下原则:

  1. 永远不要反序列化不可信数据:Marshal.load、YAML.load、CSV.load、Oj.load(object 模式)只应处理自己生成的、经完整性校验的数据;
  2. 优先使用安全替代 API:YAML 用 YAML.safe_load(或 Psych.safe_load)并显式指定允许的类白名单;JSON 用 JSON.parse;Marshal 场景尽量改用 JSON 或数据库持久化;
  3. Oj 项目显式固定安全模式:在 initializer 中设置 Oj.default_options = { mode: :strict } 或启用 Oj.mimic_JSON,使未显式传 mode 的 Oj.load 也保持安全默认,Brakeman 会识别这类配置并减少误报;
  4. 接入 CWE-502 上下文:告警的 cwe_id: [502] 与 warning_code 25 可在 CI 门禁、SARIF 导入与告警去重指纹中直接使用。

延伸阅读

总而言之,不安全反序列化是 Brakeman 判定为远程代码执行的高危告警之一。理解其"用户输入流向加载类方法即告警、Marshal 无输入也低置信度提示、Oj 依赖模式建模"的三层判定逻辑,能帮助你在扫描报告中准确区分真实风险与安全调用,并把修复动作落在"改用安全反序列化 API + 固定安全默认配置"这两个关键点上。

登录后查看全文
brakeman