Deserialization Security

---
name: deserialization-security
description: "Block unsafe deserialization and unsafe XML parsing in Java, Python, .NET, PHP, and Ruby: gadget chains, unrestricted type resolution, external entity expansion, and safer formats. Use when parsing or deserializing data from an untrusted source, wiring cookies, sessions, queues, or RPC payloads, or reviewing pickle, unserialize, Marshal, ObjectInputStream, BinaryFormatter, or XML parser configuration."
---

<!-- Native skill bundle for agent-skills (cross-tool convention). Generated by `secure-vibe dev regenerate`. -->
<!-- Do not edit by hand; the source of truth is skills/deserialization-security/SKILL.md. -->

# Deserialization Security

Block unsafe deserialization and unsafe XML parsing in Java, Python, .NET, PHP, and Ruby: gadget chains, unrestricted type resolution, external entity expansion, and safer formats. Use when parsing or deserializing data from an untrusted source, wiring cookies, sessions, queues, or RPC payloads, or reviewing pickle, unserialize, Marshal, ObjectInputStream, BinaryFormatter, or XML parser configuration.

## ALWAYS

- Prefer data-only serialization formats — JSON, Protobuf, MessagePack with an explicit type map — over formats that reconstruct arbitrary runtime objects. What makes a format safe here is not schema validation; it is whether the parser can instantiate a class the payload names.
- Constrain polymorphic type resolution to an explicit set of expected application types. Never let payload data choose the runtime class — that is the mechanism behind every gadget chain, whichever serializer is involved.
- Treat an object-reconstructing deserializer crossing a trust boundary as high risk: `pickle`, `ObjectInputStream`, `BinaryFormatter`, `unserialize`, `Marshal.load` and their framework equivalents. Adding one to a request-handling path needs explicit review — check the platform reference for the exact API and the version behaviour before accepting or remediating a use.
- Disable external entity resolution and DTD processing on every XML parser that receives untrusted input. A parser that resolves entities is a file-read and server-side request primitive before it is a parser; `ssrf-prevention` owns where the outbound request lands.
- Where serialized state carries a signature or MAC, verify it **before** invoking the deserializer — and treat that as defense in depth, not a licence to keep an unsafe format. `crypto-misuse` owns the signing key, its algorithm and its rotation.
- Apply parser and object-graph limits — type filters, graph depth, array length, stream size — as defense in depth. Where legacy native deserialization is unavoidable and execution isolation is genuinely required, isolate at the OS, process or container boundary: a deserializer filter constrains what may be constructed, never what the constructed code may then do.

## NEVER

- Deserialize attacker-controlled or unauthenticated bytes with a native, object-reconstructing format.
- Assume a MAC, a signature, TLS, or a trusted network makes an unsafe serializer safe. Some serializers cannot be made safe at any level of authentication, and their own vendors say so.
- Allow unrestricted class-name or type resolution from serialized input.
- Treat a type or object-graph filter as a process sandbox.
- Re-enable a serializer the platform vendor classifies as unsafe for compatibility alone. That needs a recorded legacy risk acceptance, strict filtering, a least-privilege execution boundary, and a migration plan — not a false-positive waiver.
- Copy a framework-specific deserialization example without checking it against the installed library version. Defaults in this area have moved repeatedly, and an example that was correct three releases ago may name an API that no longer exists.

## KNOWN FALSE POSITIVES

- Build-time or configuration-time deserialization of files that ship in the repository — test fixtures, vendored config — provided they are never loaded from a download.
- A parser that is hardened by its library's current defaults is not a finding merely because an older release of the same library was unsafe. Check the installed version, not the library name.
- A cryptographically authenticated session format where the MAC genuinely gates the deserializer and the framework's own current default serializer is in use.

## Reference files

Read these only when the task calls for them.

- `references/dotnet.md`
- `references/java.md`
- `references/php-ruby.md`
- `references/python.md`
- `references/verifying-findings.md`
- `references/xml.md`