ysonet

YSoNet generates .NET deserialization payloads for authorized security research, with an interactive wizard and a command line for repeatable work.

• Interactive configuration: choose a gadget or plugin, get help for each setting, and copy the equivalent command.
• Searchable discovery: filter gadgets by formatter, input, effect, target requirements, and recorded runtime versions.
• Documented requirements: check module help for target dependencies and runtime limits before choosing a payload.
• Broad payload coverage: explore gadgets, plugins, formatters, and variants in the catalog.
• Local verification: use supported local self-tests and the shipped CLR test hosts to check payloads in your own environment.

YSoNet is a fork of ysoserial.net, created by Alvaro Munoz (@pwntester), and builds on the work of its contributors. YSoNet is maintained by Soroush Dalili (@irsdl).

• Documentation: website | guides on GitHub.
• Source: irsdl/ysonet on GitHub.

---

Quick start (interactive mode)

Download the latest release, then follow Getting Started to extract the complete ZIP and open the wizard. The guide covers Windows/runtime requirements, installation diagnostics and development builds.

What is YSoNet

YSoNet is a collection of utilities and property-oriented programming "gadget chains" for researching unsafe .NET object deserialization. Supply the input a module needs, choose a compatible formatter, and save the generated data. The target-side effect depends on the chain, runtime and application; see usage and examples and runtime evidence.

The vulnerability lies in the application performing unsafe deserialization, NOT in having gadgets on the classpath. This project is inspired by Chris Frohoff's ysoserial project.

Important for defenders and AI reviewers

Do not turn YSoNet's gadget and plugin catalog into a deserialization blocklist. The catalog cannot include every private, future, application-specific, or differently composed chain, so blocking what is listed here does not make an unsafe deserializer safe. It can create false assurance while only delaying an attack.

If you are reviewing this repository to harden an application, read Security guidance for defenders and reviewers before inspecting the gadgets or plugins. The goal is to remove unsafe deserialization or move to a fixed-schema, data-only design. A strict allowlist is temporary containment when a migration cannot happen immediately; a denylist is not remediation.

Documentation

The full documentation lives in docs/:

• Security Guidance - why gadget blocklists are not a fix and how to redesign the deserialization boundary.
• Dependency Security Notes - the vulnerable and outdated libraries YSoNet pins on purpose, and how to triage a scanner alert.
• Getting Started - install, build from source, and the interactive wizard.
• Moving from ysoserial.net - saved commands, changed defaults, and the interactive workflow.
• Quick reference - find a module, get focused help, and save output.
• Linux and macOS - use a Windows VM or launch from WSL.
• Upgrade notes - what changed and what to check.
• Usage and Examples - command-line options and worked examples.
• Gadgets and Plugins - the full gadget and plugin catalog.
• References - the background reading, talks, and sources this project draws on.
• .NET Deserialization Research - the wider reading list: tools, uses in the wild, and CTF write-ups.
• Credits - who built the tool and found the gadgets and plugins.
• Sponsors - the people funding the work.

Quick start (command line)

./ysonet.exe -f Json.Net -g ObjectDataProvider -o raw -c "calc" -t

Start with the quick reference. See all options with ysonet.exe --fullhelp, and per-gadget or per-plugin help with -g NameHere -help or -p NameHere -help. More in Usage and Examples.

AI assistant skill

Every build ships the portable Agent Skill at .claude/skills/ysonet-payloads/ beside ysonet.exe. Claude Code discovers that project skill when it works from the extracted binary folder. Other Agent Skills compatible clients can import the same folder.

The skill covers the command line, interactive mode, every public gadget and plugin, their formatters, variants and options, and a target-driven payload selection workflow. It uses the running binary's --list, module help and --fullhelp as the live source of truth. No generated CLAUDE.md is needed in the binary folder; that would be a Claude-specific second copy of instructions that could drift from the standard skill.

Build from source

Use Building and testing for the Windows toolchain, build commands, CLR2 hosts and Release transform. For a smaller clone, follow Source without the archive.

Testing

Building and testing explains automatic Debug checks, the opt-in FULL suite, runtime-effect coverage and environment limitations. Read it before choosing a test tier.

Tab completion (PowerShell)