Parselmouth is an automated Python sandbox-escape payload bypass framework that helps security researchers discover viable payload variants under strict character blacklist constraints. It automates Python sandbox bypassing by exploring AST-level transformations, minimizing payload length, and enumerating bypass strategies under character restrictions.

• Automated AST Visitors: Breaks payloads into AST components and assembles multiple bypass strategies.
• Character Blacklist/Whitelist: Supports both per-character rules and regular-expression–based rules.
• Multi-dimensional Optimal Search: Can simultaneously seek the shortest expression (--minlen) and the smallest character set (--minset).
• Pluggable Bypass Toolkit: Extend by_* strategies easily through bypass_tools.py.
• Highly Visual Debugging: Multiple verbosity levels (-v) to inspect each attempt in detail.
• Built-in Testing Framework: Use test_case.py + run_test.py for quick regression tests.

• Python >= 3.10

pip install -r requirements.txt

Display help:

python parselmouth.py -h

Typical usage:

python parselmouth.py \
  --payload "__import__('os').popen('whoami').read()" \
  --rule "__" "." "'" '"' "read" "chr" \
  --minlen \
  -v

Key parameters:

• --rule: List characters to blacklist; mutually exclusive with --re-rule.
• --re-rule: Define blacklist using regular expressions (e.g., --re-rule '[0-9]' to block all digits).
• --specify-bypass: Fine-grained bypass class/method blacklisting or whitelisting, e.g. --specify-bypass '{"black":{"Bypass_Int":["by_unicode"]}}'
• --minlen / --minset: Search for shortest expression / minimal character set.
• -v, -vv: Verbosity levels; -vv shows debug-level logs.

⚠️ On Windows terminals, double quotes must be passed as "\\"" to avoid shell-parsing issues.

Add your payload, rules, and expected results in test_case.py, then run:

python run_test.py

import parselmouth as p9h

p9h.BLACK_CHAR = {"kwd": [".", "'", '"', "chr", "dict"]}
# or using regex:
# p9h.BLACK_CHAR = {"re_kwd": r"\.|'|\"|chr|dict"}

runner = p9h.P9H(
    "__import__('os').popen('whoami').read()",
    specify_bypass_map={"black": {"Bypass_Name": ["by_unicode"]}},
    min_len=True,
    versbose=0,
)

result = runner.visit()
status, colored = p9h.color_check(result)
print(status, colored, result)

P9H key parameters:

• source_code: Payload to bypass.
• specify_bypass_map: Blacklist/whitelist for bypass classes/methods.
• min_len: Search for shortest expression.
• versbose: Log level (0–3, default 0).
• depth: Indentation control for printing; usually no need to modify.
• bypass_history: Cache for known success/failure results, e.g. {"success": {}, "failed": []}.

Before extending the framework, it is strongly recommended to read this detailed explanation as well as parselmouth.py and bypass_tools.py.

1. Guide: Customization Tutorial
2. Add New AST Types: Implement new visit_* methods inside P9H in parselmouth.py.
3. Custom Checkers: Override check to interact with the target. Returning an empty list [] means success; non-empty means failure.
4. Extend Bypass Strategies: Add new by_* methods inside the corresponding class in bypass_tools.py. The ordering determines priority.

This table preserves the original content for quick reference. More combinations can be found in the CLI output.

More combinations and contributions are collected in challenges and issue discussions.

If you would like to contribute to this project, please leave a star in the repo.

• --re-rule regex blacklist
• Payload character-set minimization (greedy)
• Display available bypass techniques
• Unit-test improvements
• exec / eval + open to run library code
• '__builtins__' → hex/Unicode encoding
• "os" → "o" + "s"
• '__buil''tins__' → str.__add__('__buil', 'tins__')
• '__buil''tins__' → %c formatting
• __import__ → getattr(__builtins__, "__import__")
• __import__ → __loader__().load_module
• str.find → vars(str)["find"]
• str.find → str.__dict__["find"]
• ",".join("123") → str.join(",", "123")
• "123"[0] → "123".__getitem__(0)
• "0123456789" → sorted(set(str(hash(()))))
• {"a": 1}["a"] → {"a": 1}.pop("a")
• More operator/iterator/boolean/generator equivalents…

(The original TODO list is preserved for community tracking.)

This project is licensed under the MIT License. See the LICENSE file for details.