README.md

July 29, 2026 · View on GitHub

YSoNet logo

YSoNet is a fork of the original YSoSerial.Net, currently maintained by @irsdl.

Build License Download

A proof-of-concept tool for generating payloads that exploit unsafe .NET object deserialization.

What is YSoNet

YSoNet (previously known as ysoserial.net) is a collection of utilities and property-oriented programming "gadget chains" discovered in common .NET libraries that can, under the right conditions, exploit .NET applications performing unsafe deserialization of objects. You give it a command and a gadget chain; it wraps the command in the chain and serializes the result to stdout. When a vulnerable application deserializes that data, the chain runs and your command executes on the host.

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.
  • Usage and Examples - command-line options and worked examples.
  • Gadgets and Plugins - the full gadget and plugin catalog.
  • References - background reading, talks, related tools, and uses in the wild.
  • Credits - who built the tool and found the gadgets and plugins.

Quick start (interactive mode)

New to this tool? The easiest way to start is interactive mode: a menu-driven wizard that lists the gadgets and plugins, explains each setting, and builds the payload for you - no need to memorize flags first.

.\ysonet.exe -i

(interactive, wizard, and --interactive work too.) You need ysonet.exe first - see Getting Started. Full wizard walkthrough is there too.

Quick start (command line)

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

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.

Tab completion (PowerShell)

ysonet.exe can tab-complete options, gadget names (-g), plugin names (-p), formatters (-f), and output formats (-o) in PowerShell. The completion values come live from the tool, so they stay correct as gadgets and plugins are added.

Enable it for the current session (works in any PowerShell, nothing written to disk, not affected by execution policy):

.\ysonet.exe completion powershell | Out-String | Invoke-Expression

Then press Tab, for example .\ysonet.exe -g A then Tab.

To make it permanent in PowerShell 7+ (pwsh):

.\ysonet.exe completion install     # then reload with:  . $PROFILE

Install targets PowerShell 7+ (pwsh) only, because Windows PowerShell 5.1 is often AllSigned or Restricted and cannot load an unsigned profile; in that case use the per-session line above (it needs no policy change). Run ysonet.exe completion status to see what is detected, and ysonet.exe completion uninstall to remove it. More detail in tools/completions/.

Disclaimer

This software has been created purely for the purposes of academic research and for the development of effective defensive techniques, and is not intended to be used to attack systems except where explicitly authorized. Project maintainers are not responsible or liable for misuse of the software. Use responsibly.

This software is a personal project and not related to any companies, including the project owner's and contributors' employers.

Building and testing

  • Build from source: nuget restore ysonet.sln then msbuild ysonet.sln -p:Configuration=Release (or Debug). Full steps in Getting Started.
  • Tests: a Debug build runs the fast test suite automatically (a failed test fails the build). To run the exhaustive FULL suite (every gadget x formatter x variant, payload firing into test-owned sinks, bridged chains, and the plugin matrix), set YSONET_FULL_TESTS=1 and build Debug, or run ysonet\bin\Debug\ysonet.Tests.exe --full. See Getting Started -> Testing.
  • Extending the project (new gadgets, plugins, serializers, or test cases): start with the code map in docs/ARCHITECTURE.md ("How to add things" and the ysonet.Tests section) and CONTRIBUTING.md. Never weaken a test to make it pass - see the "Test integrity policy" in CONTRIBUTING.md.

Contributing

Canonical repository: https://github.com/irsdl/ysonet

  1. Fork this repo (irsdl/ysonet) to your account.
  2. Create a branch from master.
  3. Push your branch to your fork.
  4. Open a PR to irsdl/ysonet:master using this link (replace YOUR_USER and YOUR_BRANCH): https://github.com/irsdl/ysonet/compare/master...YOUR_USER:ysonet:YOUR_BRANCH
  5. For breaking changes, call them out clearly in the PR description.

See CONTRIBUTING.md for the short version.

Credits

YSoNet is developed and maintained by Soroush Dalili (@irsdl). YSoSerial.Net was originally developed by Alvaro Muñoz (@pwntester). Run ysonet.exe --credit for the full gadget and plugin credits, or see Credits. To learn more about the underlying issues, see References.

License

YSoNet is licensed under the MIT License. The license preserves the original ysoserial.net copyright notice for Alvaro Muñoz and the YSoNet copyright notice for Soroush Dalili. Both notices and the MIT permission notice must remain in all copies or substantial portions of the software.