If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/pwntester/ysoserial.net shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 14 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago
• ⚠ Concentrated ownership — top contributor handles 56% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live pwntester/ysoserial.net repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/pwntester/ysoserial.net.

What it runs against: a local clone of pwntester/ysoserial.net — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in pwntester/ysoserial.net | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 532 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pwntester/ysoserial.net. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pwntester/ysoserial.net.git
#   cd ysoserial.net
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of pwntester/ysoserial.net and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "pwntester/ysoserial.net(\\.git)?\\b" \\
  && ok "origin remote is pwntester/ysoserial.net" \\
  || miss "origin remote is not pwntester/ysoserial.net (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "ysoserial/Program.cs" \\
  && ok "ysoserial/Program.cs" \\
  || miss "missing critical file: ysoserial/Program.cs"
test -f "ysoserial/Generators/IGenerator.cs" \\
  && ok "ysoserial/Generators/IGenerator.cs" \\
  || miss "missing critical file: ysoserial/Generators/IGenerator.cs"
test -f "ysoserial/Helpers/SerializersHelper.cs" \\
  && ok "ysoserial/Helpers/SerializersHelper.cs" \\
  || miss "missing critical file: ysoserial/Helpers/SerializersHelper.cs"
test -f "ysoserial/Plugins/IPlugin.cs" \\
  && ok "ysoserial/Plugins/IPlugin.cs" \\
  || miss "missing critical file: ysoserial/Plugins/IPlugin.cs"
test -f "ysoserial/Helpers/InputArgs.cs" \\
  && ok "ysoserial/Helpers/InputArgs.cs" \\
  || miss "missing critical file: ysoserial/Helpers/InputArgs.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 532 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~502d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/pwntester/ysoserial.net"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ysoserial.net is a deserialization payload generator that crafts serialized .NET objects exploiting unsafe deserialization vulnerabilities through property-oriented programming (POP) gadget chains in common .NET libraries. It takes a command and wraps it in a gadget chain (like ObjectDataProvider, WindowsIdentity, or ClaimsPrincipal), serializes it via BinaryFormatter or other .NET formatters, and outputs an exploit payload that executes arbitrary code when deserialized by vulnerable .NET applications. Monolithic Visual Studio solution (ysoserial.sln) with three projects: core ysoserial/ containing 30+ IGenerator implementations in Generators/ (each gadget as a separate class like ObjectDataProviderGenerator.cs), TestConsoleApp/ for integration testing, and ExploitClass/ for advanced scenarios. Main driver Program.cs routes command-line arguments to selected generators, which serialize payloads via BinaryFormatter or custom formatters (referenced in Helpers/).

Defensive security researchers, penetration testers, and .NET security auditors who need to test and validate their applications' resilience against deserialization attacks; also used by security teams to understand POP gadget exploitation and build mitigations.

Actively developed with 8.1k+ GitHub stars and organized CI/CD via GitHub Actions (build.yml), covering ~1.2M lines of C# across 30+ generator implementations. The project has a mature structure with multiple serialization backends, comprehensive gadget coverage for .NET Framework and .NET Core, and clear licensing. Regular releases available—solid production-ready status for security research.

Single-maintainer project (pwntester) with no visible public issue tracker or PR activity in the snapshot; last commit date not provided, raising concerns about update latency for new .NET CVEs. Since this is a security exploitation tool, lag between public vulnerability disclosure and patch availability is a real risk. No visible test suite coverage (no TestConsoleApp tests in Generators/), making regression detection difficult.

No specific PR/issue data visible in the snapshot, but the build.yml GitHub Actions workflow is configured, indicating active CI. The presence of v2 branch badge suggests feature/version work in parallel branches. Generator count (~30) implies ongoing gadget chain discovery and addition.

git clone https://github.com/pwntester/ysoserial.net
cd ysoserial.net
# Install Visual Studio 2022 Community, NuGet, MSBuild Community Tasks via Chocolatey (Windows)
choco install visualstudio2022community visualstudio2022-workload-nativedesktop msbuild.communitytasks nuget.commandline
# Or build directly with MSBuild
msbuild ysoserial.sln /p:Configuration=Release
# Run the compiled binary
.\ysoserial\bin\Release\ysoserial.exe --list  # list available gadgets
.\ysoserial\bin\Release\ysoserial.exe -f BinaryFormatter -g ObjectDataProvider -c "whoami" | base64

Daily commands:

# Build in Visual Studio 2022 or via command line
msbuild ysoserial.sln /p:Configuration=Release /p:Platform=x64

# Run from command line
cd ysoserial\bin\Release
ysoserial.exe -f BinaryFormatter -g ObjectDataProvider -c "cmd.exe /c calc.exe" -o base64

# Or use TestConsoleApp to deserialize and test locally
cd TestConsoleApp\bin\Release
TestConsoleApp.exe

• ysoserial/Program.cs — Main entry point orchestrating payload generation and serialization—all contributors must understand command-line parsing and plugin initialization flow
• ysoserial/Generators/IGenerator.cs — Core abstract interface defining the contract for all gadget chain generators—essential for implementing new payloads
• ysoserial/Helpers/SerializersHelper.cs — Central utility managing formatter selection and serialization logic across all supported formatters (BinaryFormatter, Json.NET, etc.)
• ysoserial/Plugins/IPlugin.cs — Plugin architecture interface enabling extensibility for third-party gadget chains and specialized exploit scenarios
• ysoserial/Helpers/InputArgs.cs — Command-line argument parser and validation—must be updated when adding new options or generators
• ysoserial/Generators/ObjectDataProviderGenerator.cs — Most versatile and widely-used gadget chain leveraging .NET's ObjectDataProvider for arbitrary code execution
• ysoserial/Generators/ActivitySurrogateSelectorGenerator.cs — Advanced activity surrogate-based exploitation technique requiring deep understanding of BinaryFormatter internals

Add a New Gadget Chain Generator

1. Create a new class inheriting from GenericGenerator in ysoserial/Generators/ (ysoserial/Generators/MyNewGenerator.cs (new file))
2. Implement CanGenerateWithArguments(string[] args) to accept your command signature (ysoserial/Generators/MyNewGenerator.cs)
3. Implement Generate(string cmd, string formatter, bool minify) assembling your gadget chain using reflection and object instantiation (ysoserial/Generators/MyNewGenerator.cs)
4. Register your generator in Program.cs by adding an entry to the generators list passed to GetPayload() (ysoserial/Program.cs)
5. Test serialization by running: ysoserial.exe -g MyNewGenerator -f BinaryFormatter -c "calc.exe" (TestConsoleApp/Program.cs)

Add a New Serialization Formatter Support

1. Add a new FormatterType enum value in ysoserial/Helpers/FormatterType.cs (ysoserial/Helpers/FormatterType.cs)
2. Create a serialization helper method in ysoserial/Helpers/SerializersHelper.cs following the JsonHelper or XmlHelper pattern (ysoserial/Helpers/SerializersHelper.cs)
3. Modify SerializersHelper.Serialize() to dispatch to your new formatter handler based on FormatterType (ysoserial/Helpers/SerializersHelper.cs)
4. Update InputArgs.cs to accept your formatter name via --formatter argument (ysoserial/Helpers/InputArgs.cs)
5. Validate with existing generators: ysoserial.exe -g ObjectDataProvider -f YourNewFormatter -c "cmd.exe /c calc" (TestConsoleApp/Program.cs)

Add a New Plugin for Library-Specific Exploitation

1. Create a new plugin class implementing IPlugin interface in ysoserial/Plugins/ (ysoserial/Plugins/MyLibraryPlugin.cs (new file))
2. Implement Name property, Vulnerable() check, and Generator collection with IGenerator instances targeting your library's gadgets (ysoserial/Plugins/MyLibraryPlugin.cs)
3. Register plugin in Program.cs by instantiating and adding to the plugins list used in generator discovery (ysoserial/Program.cs)
4. Test plugin activation: ysoserial.exe --plugins and verify your plugin appears in output (TestConsoleApp/Program.cs)

Add Support for a New .NET Deserialization Vulnerability

1. Identify the vulnerable type chain (e.g., Source → Gadget → Sink) and add types to an existing or new Generator (ysoserial/Generators/MyVulnGenerator.cs (new file))
2. If BinaryFormatter-specific, implement custom type confusion or surrogate selection in ModifiedVulnerableBinaryFormatters/binaryobjectreader.cs (ysoserial/Helpers/ModifiedVulnerableBinaryFormatters/binaryobjectreader.cs)
3. Add method invocation sink in your generator using System.Reflection to instantiate and wire the gadget chain (ysoserial/Generators/MyVulnGenerator.cs)
4. Test with all compatible formatters (BinaryFormatter, Json.NET, etc.) via SerializersHelper (ysoserial/Helpers/SerializersHelper.cs)

No public API docs: Generator behavior and arguments are CLI-only; study Program.cs to understand generator registration and naming. Windows-only: No .NET Core abstraction; Unix compatibility requires wine/Mono (untested). Reference vs. execution: TestConsoleApp can deserialize locally but requires runtime gadgets (e.g., System.Windows.Forms, System.Data.DataSetSerializationFormat); different .NET Framework versions have different gadget availability. No built-in sandboxing: Deserialization in TestConsoleApp executes code—only run on isolated machines. BinaryFormatter obsolescence: .NET 5+ deprecated BinaryFormatter; some generators may not work on modern .NET without custom formatter implementation.

• Property-Oriented Programming (POP) — Core exploitation technique this tool uses; chaining property getters/setters and method invocations on gadget classes to trigger arbitrary code execution without direct method calls
• BinaryFormatter Serialization — Primary serialization format targeted by most generators; understanding its type information encoding and delegate invocation patterns is critical to payload crafting
• Gadget Chain (Exploit Chain) — Sequence of chained object instantiations and property accesses that leads to code execution; this tool discovers and wraps commands in these chains
• .NET Reflection — Used extensively in generators to dynamically instantiate gadget classes, set properties, and invoke methods at runtime to build exploitation payloads
• Type Confusion / Type Spoofing — Techniques used by generators like ActivitySurrogateDisableTypeCheck and TypeConfuseDelegateGenerator to bypass .NET type safety checks during deserialization
• ObjectDataProvider (XAML Gadget) — Most versatile gadget in WPF/.NET stack; allows arbitrary method invocation through XAML property binding, frequently the basis for multi-stage exploit chains
• Unsafe Deserialization Vulnerability — The vulnerability pattern this tool exploits; occurs when applications deserialize untrusted data without validation, trusting object type information from the serialized stream

• frohoff/ysoserial — The original Java ysoserial project that inspired this .NET port; same POP gadget chain exploitation concepts but targets Java serialization
• microsoft/dotnet-framework-docker — Official .NET Framework Docker images; useful for setting up vulnerable test environments and validating payload execution across .NET versions
• yallie/msgpack.cli — Alternative .NET serialization library; relevant for understanding the broader .NET serialization landscape and bypass techniques
• pwntester/marshalsec — Java-based marshaller exploitation tool by the same author; demonstrates similar POP gadget techniques in Java ecosystem
• Accenture/Defender-IaC — IaC security tool that uses ysoserial.net as a dependency to generate test payloads for validating .NET deserialization defenses in infrastructure

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Generators with TestConsoleApp integration

The repo has 40+ generator classes (ActivitySurrogateSelectorGenerator, ObjectDataProviderGenerator, etc.) but TestConsoleApp/Program.cs appears minimal. Each generator needs isolated unit tests to verify payload generation correctness and prevent regressions when gadget chains are modified. This is critical for a security tool where payload validity directly impacts exploit reliability.

• [ ] Create TestConsoleApp/GeneratorTests/ directory with test classes for 5-10 high-risk generators (ObjectDataProvider, ActivitySurrogate, DataSet variants)
• [ ] Add tests in TestConsoleApp_YSONET.csproj that verify each generator produces valid serialized output
• [ ] Test both success paths (valid payload generation) and failure modes (invalid formatter arguments)
• [ ] Reference existing Generators/ structure to ensure test coverage matches generator complexity

Implement .NET formatter detection and validation helper in ysoserial/Helpers/

FormatterType.cs exists but appears minimal. The repo supports multiple formatters (BinaryFormatter, ObjectStateFormatter, MessagePack, etc.) across 40+ generators. A dedicated validation/detection helper would prevent developers from generating incompatible payloads (e.g., BinaryFormatter payload for Json formatter), reducing support burden and improving tool reliability.

• [ ] Extend ysoserial/Helpers/FormatterType.cs with enum values for all supported formatters found across Generators/
• [ ] Add FormatterValidationHelper.cs to validate generator-formatter compatibility (e.g., BinaryFormatterMinifier for BinaryFormatter only)
• [ ] Add static compatibility matrix methods checking which generators work with which formatters
• [ ] Update InputArgs.cs to use validation before payload generation

Document and refactor GadgetSurrogates pattern across ObjectDataProviderSurrogates and GetterSettingsPropertyValueSurrogates

Two surrogate implementations exist (ysoserial/Helpers/GadgetSurrogates/*.cs) but their relationship, reusability, and extension pattern are undocumented. As new gadget chains are discovered, contributors need clear guidance on creating new surrogates. Refactoring into a common base pattern would reduce code duplication and lower barrier for gadget chain contributions.

• [ ] Create ysoserial/Helpers/GadgetSurrogates/ISurrogatePattern.cs base interface documenting surrogate contract
• [ ] Refactor ObjectDataProviderSurrogates.cs and GetterSettingsPropertyValueSurrogates.cs to inherit from common base/interface
• [ ] Create ysoserial/Helpers/GadgetSurrogates/SURROGATE_DEVELOPMENT.md with step-by-step guide for adding new surrogates
• [ ] Add surrogate examples in documentation linking to refactored implementations

• Add unit tests for Generators/: Most IGenerator implementations lack test coverage. Create a test class GeneratorTests.cs in TestConsoleApp that instantiates each generator, calls GeneratePayload(), and validates output is non-null serialized bytes. Start with simpler ones like WindowsIdentityGenerator.
• Document generator gadget chains in README.md: Add a table listing each generator name, .NET version support (Framework 4.7 vs. Core 5+), required gadgets (e.g., System.Windows.Forms), and example command-line usage. Reference frohoff/ysoserial Java docs as a model.
• Add support for additional formatters (LosFormatter, ObjectStateFormatter): Currently BinaryFormatter-centric. Create IFormatter interface in Helpers/, extract serialization logic from BinaryFormatterMinifier.cs, implement LosFormatterSerializer.cs and ObjectStateFormatterSerializer.cs, wire into Program.cs argument parsing for -f LosFormatter.

• Critical · Deserialization Payload Generation Tool - Inherent Security Risk — ysoserial/Generators/*.cs (all generator files). This codebase is specifically designed to generate deserialization payloads that exploit unsafe .NET object deserialization. While this is a proof-of-concept/educational tool, the generated payloads are inherently dangerous and could be weaponized for remote code execution (RCE) attacks. The tool generates gadget chains for multiple formatters (BinaryFormatter, DataSet, ObjectDataProvider, etc.) that can bypass security controls. Fix: This tool should only be used in controlled security testing environments. Implement strict access controls, usage logging, and network isolation. Consider adding rate limiting and output validation.
• High · BinaryFormatter Usage in Modified Vulnerable Formatters — ysoserial/Helpers/ModifiedVulnerableBinaryFormatters/binaryformatter.cs and related files. The codebase includes modified implementations of vulnerable binary formatters in 'ModifiedVulnerableBinaryFormatters' directory. BinaryFormatter has been deprecated by Microsoft due to security vulnerabilities and cannot be disabled. The custom implementations maintain these vulnerabilities. Fix: Replace BinaryFormatter usage with safer alternatives like JSON serializers. If this must remain for testing purposes, isolate it to sandboxed environments with no network access.
• High · Unrestricted Code Compilation in LocalCodeCompiler — ysoserial/Helpers/LocalCodeCompiler.cs. The LocalCodeCompiler helper allows dynamic compilation of arbitrary C# code at runtime. This could enable code injection if user input is not properly validated before being passed to the compiler. Fix: Implement strict input validation and sandboxing for any user-supplied code. Restrict compilation to whitelisted code patterns only. Consider removing dynamic compilation entirely if possible.
• High · Potential Command Injection in CommandArgSplitter — ysoserial/Helpers/CommandArgSplitter.cs. The CommandArgSplitter utility may be vulnerable to command injection if its output is used to construct system commands without proper escaping or validation. Fix: Ensure all outputs from CommandArgSplitter are properly escaped before use in any shell or system command execution. Use parameterized APIs instead of string concatenation.
• High · File-Based Payload Generation Without Validation — ysoserial/Generators/ActivitySurrogateSelectorFromFileGenerator.cs, ysoserial/Generators/DataSetOldBehaviourFromFileGenerator.cs. Several generators load payloads from files (e.g., ActivitySurrogateSelectorFromFileGenerator, DataSetOldBehaviourFromFileGenerator) without apparent validation of file content or path traversal checks. Fix: Implement strict file path validation, canonicalization, and whitelist allowed directories. Validate file contents before processing. Implement file size limits.
• High · Missing Input Validation in InputArgs — ysoserial/Helpers/InputArgs.cs. The InputArgs helper processes user-supplied arguments without apparent comprehensive validation, which could lead to injection attacks or unexpected behavior. Fix: Implement comprehensive input validation including type checking, length limits, regex validation for all user inputs. Use allowlists for formatter types and gadget chains.
• Medium · Unencrypted Configuration in App.config — ysoserial/App.config, TestConsoleApp/App.config. Configuration files (App.config) may contain sensitive settings. If any credentials or API keys are stored here, they would be in plaintext. Fix: Never store credentials in configuration files. Use encrypted configuration sections, environment variables, or secure vaults. If configuration exists, review for exposed secrets.
• Medium · XAML-based Payload Generation Security — ysoserial/Generators/XamlAssemblyLoadFromFileGenerator.cs. XamlAssemblyLoadFromFileGenerator and related XAML generators can load arbitrary assemblies, potentially enabling assembly injection attacks. Fix: Restrict assembly loading to a whitelist of known-safe assemblies. Validate XAML content before processing. Implement assembly signature verification.
• Medium · JSON and YAML Deserialization Helpers — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.