5.8 KiB

Raw Blame History

rube

A Ruby object-deserialization security lab.

A gadget chain is a Rube Goldberg machine. One untrusted blob goes in, a dozen unrelated standard-library methods knock each other over, and code execution falls out the far end. This project builds the machine, then builds the thing that stops it.

Why this exists

Marshal.load on untrusted input is arbitrary code execution. So is YAML.unsafe_load, JSON.load with additions enabled, and Oj.load in its default mode. This is not a Ruby quirk. It is the same class of bug as Java deserialization, PHP POP chains, and Python pickle, and it sits at CWE-502 in the CISA Known Exploited Vulnerabilities catalog with a 34.8% known-ransomware rate against a 20.1% baseline across the catalog as a whole.

Most write-ups on this topic teach the exploit. Fewer teach why the obvious defense does not work. This one does both, because the second half is where the actual lesson lives:

You cannot make Marshal.load safe with an allowlist. The proc you pass runs in r_post_proc, which marshal.c invokes after load_funcall(... s_mload ...). By the time your allowlist sees the object, marshal_load has already run. The pattern widely copied off Stack Overflow is a post-mortem, not a veto.

Psych's allowlist genuinely is a veto — for exactly one reason. It checks the tag before revival, where Marshal checks the object after construction. Identical intent, opposite outcome, decided entirely by where the check sits.

Status

All six pieces are built and tested.

Marshal stream parser — parses the binary format, extracts referenced class names and gadget sinks, and validates structure, all without ever calling Marshal.load. Rejects truncated streams, unsupported versions, unknown tags, out-of-bounds object links and symlinks, oversized fixnum widths, trailing bytes, and excessive nesting.
Version-compatibility matrix — probes six pinned Ruby images and reports where the published git gadget and the ERB @_init guard actually change.
Reflection-based gadget scanner — walks ObjectSpace for auto-invoked methods and classifies them by whether Marshal.load can reach them. It counts every error it swallows, names the site, and treats a method it could not analyse as reachable rather than inert, so under-reporting is visible instead of silent.
Payload builder — version-scoped chains carrying their own affected ranges.
Vulnerable containerized target — a Sinatra app with one endpoint that loads a session cookie and one that inspects it first.
Boundary detector — the defensive layer, with an explicit written statement of what it cannot do.

Usage

require "rube"

payload = Marshal.dump(Gem::Requirement.new(">= 0"))
result = Rube::Marshal::Parser.new(payload).parse

result.class_names
# => ["Gem::Requirement", "Gem::Version"]

result.sinks.map { |s| "#{s.class_name}##{s.sink_method}" }
# => ["Gem::Requirement#marshal_load", "Gem::Version#marshal_load"]

Parser.new enforces Rube::Marshal::Limits.new unless you say otherwise. Every ceiling is opt-out, never opt-in — pass limits: Rube::Marshal::Limits.permissive if you are doing forensics on a stream you already trust and want it parsed whole.

To make a decision rather than inspect a stream, use the detector, which applies a policy and hands back a frozen snapshot:

detector = Rube::Marshal::BoundaryDetector.new(allowed_class_names: %w[Hash String])
decision = detector.inspect_stream(untrusted_bytes)

decision.blocked?    # => true
decision.reason      # => "stream reaches Gem::Requirement#marshal_load during load, ..."

A decision is in exactly one of three states, and proceed? is the only one that gates a load:

Marshal.load(decision.snapshot) if decision.proceed?

proceed? means the policy found no violation. blocked? means it found one and refused. observed? is the third state, and it exists because POLICY_OBSERVE_AND_LOG is non-blocking by design: a violation was found, reported, and deliberately not enforced. Such a decision still carries its snapshot, so a caller running in monitoring mode opts in by naming that state out loud:

Marshal.load(decision.snapshot) if decision.proceed? || decision.observed?

There is no accepted?. The question "did the policy permit this" and the question "is this stream free of violations" have different answers under observe-and-log, and one predicate cannot answer both.

Read Rube::Marshal::BoundaryDetector::LIMITATION_NOTICE before relying on proceed?. A stream that proceeds is not a safe one, and the notice says so in detail.

Nothing above instantiates a class, calls a constructor, or invokes Marshal.load.

Development

Everything runs in Docker against a pinned Ruby.

just test       run the minitest suites
just control    run the negative controls
just check      both
just corpus     print every adversarial corpus case and its verdict
just scan       run the gadget scanner over loaded modules
just matrix     probe six pinned Ruby images and render the compatibility matrix
just exploit    prove the chain fires on a vulnerable image and is blocked on a patched one
just target     stand up the vulnerable app and attack it over HTTP
just detector   prove the defensive layer rejects the payload the target executes
just gate       everything above, in order
just build      build the gem with --strict
just manifest   list exactly what would ship in the .gem

A note on the object-link index

Ruby's Marshal format documentation states that object links are one-indexed. They are zero-indexed. A self-referential array dumps as 04 08 5b 06 40 00, where the trailing 00 is a link to the outermost object at index 0. The parser is written against the observed bytes, not the documentation.

License

AGPL-3.0-or-later. See LICENSE.

5.8 KiB Raw Blame History