id: deserialization-security version: "1.0.0" title: "Deserialization Security" description: "Block unsafe deserialization across Java, Python, .NET, PHP, Ruby, Node.js — gadget chains, type allowlisting, safer alternatives" category: prevention severity: critical applies_to:

• "when generating code that deserializes data from any untrusted source"
• "when wiring cookies, sessions, message queues, or RPC payloads"
• "when reviewing pickle / unserialize / Marshal / ObjectInputStream / BinaryFormatter usage"

languages: ["java", "python", "csharp", "php", "ruby", "javascript", "typescript"] token_budget: minimal: 1200 compact: 1500 full: 2200 rules_path: "rules/" related_skills: ["api-security", "crypto-misuse", "supply-chain-security"] last_updated: "2026-06-20" sources:

• "OWASP Deserialization Cheat Sheet"
• "CWE-502: Deserialization of Untrusted Data"
• "CVE-2017-9805 (Struts2 XStream)"
• "CVE-2016-4437 (Shiro RememberMe)"
• "CVE-2019-2725 (WebLogic XMLDecoder)"

Deserialization Security

Rules (for AI agents)

ALWAYS

• Prefer structural, schema-validated formats (JSON with a JSON Schema

validator, Protobuf, FlatBuffers, MessagePack with an explicit type map) over polymorphic native serializers. The trade-off "save 10 lines of mapping code" is never worth the RCE primitive.

• When a polymorphic deserializer is unavoidable, configure a **strict

type allowlist** at the framework level (Jackson PolymorphicTypeValidator, fastjson safeMode, .NET KnownTypeAttribute, XStream Whitelist). The default of "any class" is the source of every modern Java deserialization CVE.

• Sign and authenticate any cookie or token that carries serialized data

with a fresh random key (HMAC-SHA-256, minimum). Never deserialize before HMAC verification.

• Run deserialization code paths under the minimum capabilities the format

needs (no filesystem, no network, no subprocess, no reflection) — e.g. Java ObjectInputFilter patterns; Python in a constrained namespace.

• Treat any of the following functions as "untrusted-input deserialization

primitives": Java ObjectInputStream.readObject, Jackson with enableDefaultTyping, SnakeYAML Yaml.load(), XStream fromXML, Python pickle.load(s) / cPickle / dill / joblib.load, yaml.load (default Loader), numpy.load(allow_pickle=True), torch.load, PHP unserialize, .NET BinaryFormatter / ObjectStateFormatter / NetDataContractSerializer / LosFormatter, Ruby Marshal.load / YAML.load (Psych ≤ 3.0). Adding one of these to a request-handling code path requires explicit security review.

NEVER

• Pass untrusted bytes to any of the primitives above without an

HMAC-authenticated wrapper. Even with a wrapper, prefer a non-polymorphic format.

• Use Java Jackson with objectMapper.enableDefaultTyping() or

@JsonTypeInfo(use = Id.CLASS). The default of LAMINAR_INTERNAL_DEFAULT produces a class-id gadget chain (ysoserial / marshalsec).

• Use SnakeYAML new Yaml() without explicitly specifying a SafeConstructor

(or Constructor with an allowlist). The default constructor is the source of common Java YAML RCE CVEs.

• Use Python pickle.loads on data from a network socket, a database

column, a Redis cache key, or anywhere that crosses a trust boundary. No amount of validation makes pickle safe.

• Use Python yaml.load(data) (without Loader=yaml.SafeLoader). PyYAML

changed the default in 6.0 to fail loudly — older code paths still ship the unsafe default.

• Use Python torch.load(path) on a downloaded checkpoint without

weights_only=True (PyTorch ≥ 2.6 defaults to True; older versions reach pickle and execute arbitrary code).

• Use PHP unserialize() on cookie / POST / GET data. PHP serialized

format has a long history of magic-method gadget chains (__wakeup, __destruct, __toString).

• Use .NET BinaryFormatter, NetDataContractSerializer,

ObjectStateFormatter, LosFormatter for any input crossing a trust boundary. Microsoft marks BinaryFormatter as obsolete and unsafe.

• Trust the contents of a Ruby Marshal.load from anywhere outside the

same process. Same restriction for YAML.load on older Psych.

KNOWN FALSE POSITIVES

• Internal RPC where both sides are operator-controlled, the data is

authenticated end-to-end (mTLS + HMAC), and the format choice is pragmatic (e.g. Java services using ObjectInputStream over a TLS+mTLS-only socket may be acceptable in some legacy stacks).

• Build-time / configuration-time deserialization of files that ship in

the repository (pickle test fixtures, etc.) — but mark them clearly and never load them from a download.

• Cryptographically-authenticated session formats like Rails' default

signed-cookie sessions are intended use of Marshal, but only because the HMAC gates the deserialization.

Context (for humans)

Deserialization vulnerabilities are the single most reliable RCE primitive in modern enterprise stacks. The economics are simple: when the serializer allows arbitrary class instantiation, the codebase has already imported thousands of classes — many of which have side-effects in their readObject, __reduce__, __wakeup, Read* callbacks. A gadget chain combines these side-effects into RCE.

ysoserial (Java), ysoserial.net (.NET), marshalsec (Java), and the Python pickle gadget catalogs are mature tooling. Every "is this exploitable?" question is "yes, with the gadgets already on your classpath."

The fix is not to filter — it is to use a format that doesn't permit arbitrary class instantiation in the first place. Most modern services ship signed JWTs / JSON over mTLS. Where a polymorphic format is unavoidable, type-allowlist + HMAC are non-negotiable.

Verify & lock (triaging a finding)

A scanner/review hit is a candidate, not a confirmed bug. Confirm it, fix it, then lock it so it can't come back.

1. Confirm it's real (probe the suspect input). Feed the deserializer a crafted

payload whose gadget fires a benign canary — e.g. a pickle/PHP object whose __reduce__/__wakeup/__destruct (or a Java readObject / SnakeYAML !!javax... / .NET gadget) touches a marker file or sleeps a fixed interval. Send it through the actual sink (pickle.loads, yaml.load, ObjectInputStream, unserialize, BinaryFormatter, Marshal.load). Real if the canary fires (file appears, request hangs) — arbitrary class instantiation is reachable. False positive if the path is HMAC-gated before deserialize, uses a SafeLoader/weights_only=True/strict type-allowlist, or only loads repo-shipped build fixtures (per KNOWN FALSE POSITIVES).

1. Fix, then lock with a regression test (unit or integration — dev's call):

swap to a non-polymorphic/schema-validated format, or a safe loader plus type allowlist (SafeConstructor, PolymorphicTypeValidator, weights_only=True) and HMAC-verify before any decode. Assert the canary payload is rejected (raises / returns no object, canary never fires) and a legitimate payload still loads into the expected type. Commit it to CI so the guard can't be silently dropped in a later refactor.

References

• rules/unsafe_deserializers.json
• OWASP Deserialization Cheat Sheet.
• CWE-502.
• ysoserial.
• ysoserial.net.
• marshalsec.