Add pickle package for generating exploit payloads

[vlobstein-vc]

Summary

The framework already ships dedicated packages for the deserialization sinks it sees most: dotnet/ for .NET BinaryFormatter / SOAPFormatter and java/gadgets/ for Java. Python pickle has not had the same treatment. This PR fills that gap with a pickle/ package modelled on the existing dotnet API.

og-rek already exposes a Call{Callable: Class{Module, Name}, Args: Tuple{...}} type whose encoder emits GLOBAL + tuple + REDUCE, so the byte-level capability has been there. The package this PR ships re-implements that primitive in-tree to keep the framework dep-free and adds an offsec-shaped API on top:

• Low-level opcode emitters (Proto, Global, BinUnicode, Tuple1/2/3, ...) named after Lib/pickle.py for easy cross-reference, plus a length-prefix helper that drives BinUnicode / BinUnicode8 / ShortBinUnicode / BinBytes / ShortBinBytes from a single function.

• Typed Fragment composition: primitives Str/Int/Bool/Bytes/None, composites TupleOf/ListOf/DictOf, callables Call/CallFragment/Method/Build, top-level wrapper Dump. Every primitive returns a Fragment that pushes one value onto the unpickler stack, and Fragments nest arbitrarily.

// Quick path:
payload := pickle.CreateOSSystem(cmd)

// Or build directly:
payload := pickle.Dump(pickle.Call("builtins", "exec", pickle.Str(code)))

// Nested chains, e.g. eval(open("/etc/passwd").read()):
payload := pickle.Dump(pickle.Call("builtins", "eval",
    pickle.Method(pickle.Call("builtins", "open", pickle.Str("/etc/passwd")), "read"),
))

Create* shortcuts ship for the canonical gadgets: CreateOSSystem, CreateNTSystem, CreateExec, CreateEval, CreateSubprocessPopen. Method / Build cover the getattr and __setstate__ chain patterns that go-exploit modules will reach for.

A pure-Go Disassemble walks a stream into named opcodes; the test suite uses it instead of calling pickle.loads on attacker-shaped bytes. 17 tests, all golden hex or disassembly round-trip, no Python interpreter required at test time.

Default protocol is 2: universally supported across Python 2.3+ and 3.x, deterministic output across CPython versions.

[Copilot]

Pull request overview

Adds a new pickle/ package to generate attacker-controlled Python pickle byte streams (protocol 2 by default) and to disassemble pickle streams into named opcodes for inspection/testing, aligning with existing deserialization-sink support in the framework.

Changes:

• Introduces low-level opcode emitters (Proto, Global, BinUnicode, integer encoders, etc.) and higher-level composable Fragment builders (Str, Int, TupleOf, ListOf, DictOf, Call, Method, Build, Dump).
• Adds common exploit “shortcut” gadgets (e.g., CreateOSSystem, CreateExec, CreateSubprocessPopen).
• Adds a pure-Go disassembler and a golden/disassembly-based test suite for deterministic verification without needing Python at test time.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
pickle/pickle.go	Package docs and protocol constant for the new pickle payload generator.
pickle/opcodes.go	Low-level opcode constants and byte emitters for pickle encoding.
pickle/fragments.go	High-level fragment composition API and Dump wrapper.
pickle/gadgets.go	Convenience gadget constructors for common RCE primitives.
pickle/disasm.go	Pure-Go pickle disassembler used by tests and for safe inspection.
pickle/pickle_test.go	Golden-hex and disassembly-shape tests covering emitters, gadgets, and disassembler behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lobsterjerusalem]

Just added the bit about standardizing the length checking throughout.

Btw this is awesome, it was actually something on my TODO list that I can knock off now 👍.

[lobsterjerusalem]

Made a slight change to the pickle docs for example usage to match the update. But looks good to go.