zhurong2020/pyobfus

🛡️ Modern Python code obfuscator - Enterprise-grade protection at 50% lower cost than PyArmor - zhurong2020/pyobfus

2 stars · 2 forks · 0 watchers

README

pyobfus — the Python obfuscator

pyobfus (pronounced as "Python obfuscator") is a modern, AST-based python-obfuscator / code-obfuscator with framework-aware presets, reverse stack-trace mapping for AI-assisted debugging, and a machine-readable JSON CLI designed for Claude Code, Cursor, and MCP agents. A transparent, open-source alternative to PyArmor.

A Python code obfuscator built with AST-based transformations. Supports Python 3.9 through 3.14. Provides reliable name mangling, string encoding, control-flow flattening, AES-256 string encryption, and — unique to pyobfus — a reverse-mapping workflow that lets you (or your AI coding assistant) debug obfuscated stack traces without giving up the protection.

🆕 What's new in v0.5.4 — --bind-device now device-locks Runtime String Vault keys too, not just Selective Opacity's L3 layer. Vault keys previously shipped as baked literals, so vault secrets decrypted on any machine; now each vault's key is re-derived at runtime from the bound device and a wrong machine is refused. The other patent-targeted Pro mechanisms remain one-line flags: Selective Opacity (per-symbol AES-256 layers), forensic watermarking, @seal_code integrity, traceback scrubbing, --period (run-counter limit) and --opacity-config (pattern-driven L3 encryption by original qualname). Pro flags are used as pyobfus SRC -o OUT --level pro --<flag>. Full details in the CHANGELOG; see Pro Edition below.

🔌 Companion MCP server: pyobfus-mcp This repository ships two installable packages:

Package What it is Install

pyobfus The Python obfuscator (CLI + library). pip install pyobfus

pyobfus-mcp A Model Context Protocol (MCP) server that exposes pyobfus's tools to AI coding agents. uvx pyobfus-mcp (zero-install) or pip install pyobfus-mcp

The MCP server lives in pyobfus_mcp/ and is built on the official Model Context Protocol Python SDK (FastMCP). It registers eight MCP tools so Claude Desktop, Claude Code, Cursor, Windsurf, and Zed can call pyobfus directly from agent conversations — no shelling out:

MCP tool Implementation Purpose

protect_project pyobfus_mcp/tools.py One-call, self-verifying pipeline: scan → preset → obfuscate → byte-compile + import-smoke-test the output → return verified: true/false. The agent reports a green check instead of hoping the transform didn't break anything

check_obfuscation_risks pyobfus_mcp/tools.py Pre-flight risk scan (eval/exec, dynamic attribute, framework reflection)

generate_pyobfus_config pyobfus_mcp/tools.py Auto-detect framework → write a working pyobfus.yaml

unmap_stack_trace pyobfus_mcp/tools.py Reverse obfuscated identifiers in a production stack trace

list_presets pyobfus_mcp/tools.py Enumerate community / framework / Pro presets

explain_preset pyobfus_mcp/tools.py Describe what a named preset changes

recommend_tier pyobfus_mcp/tools.py Analyze a project and recommend community vs Pro tier, with reasoning

start_pro_trial pyobfus_mcp/tools.py Return structured guidance for starting the 5-day Pro trial

The server is registered in the official MCP Registry under io.github.zhurong2020/pyobfus-mcp. The transport is stdio. See pyobfus_mcp/README.md for per-client configuration snippets. 🧩 Claude Code skill / plugin This repo is also a Claude Code plugin marketplace. The pyobfus-protect skill teaches an agent the full "protect Python before shipping — obfuscate and verify it still runs" workflow (MCP-first, CLI fallback): /plugin marketplace add zhurong2020/pyobfus /plugin install pyobfus@pyobfus

See skills/ for the skill and install details. (This is distinct from templates/ai-integration/, which are copy-in rule files for your project.) 🤖 AI-native features

pyobfus --check src/ — pre-flight risk scan: detects eval/exec, dynamic attribute access, and framework reflection points before you obfuscate. JSON output with an ai_hint telling your AI assistant what to run next. pyobfus --init src/ — zero-config onboarding: scans the project, detects FastAPI/Django/Pydantic/Click/SQLAlchemy, and writes a ready-to-use pyobfus.yaml. pyobfus --unmap --trace error.log --mapping mapping.json — reverse obfuscated identifiers in a production stack trace so you can debug (or hand the trace to an AI assistant) without reversing the obfuscation itself. pyobfus … --save-mapping mapping.json --trace-marker — stamp each obfuscated file with a # pyobfus:obfuscated header (id + mapping filename + the exact --unmap command) so an AI agent that lands in an obfuscated file from a traceback immediately knows it's pyobfus output and how to reverse the names. Framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters. Global --json — every CLI mode (obfuscate, --check, --unmap, --init) emits the same structured schema with an ai_hint field, ready for Claude Code, Cursor, Windsurf, and MCP servers to consume.

Features ✅ Free Edition The following features are fully implemented and available in the current version:

🆕 Cross-File Obfuscation (v0.2.0): Consistent name obfuscation across multiple files

Automatic import statement rewriting _all_ list updates with obfuscated names Global symbol table with collision detection Two-phase obfuscation pipeline (Scan → Transform) Preview mode with --dry-run flag

Name Mangling: Rename variables, functions, classes, and class attributes to obfuscated names (I0, I1, I2...)

Comment Removal: Strip comments and docstrings

String Encoding: Base64 encoding for string literals with automatic decoder injection

Parameter Preservation: Preserve function parameter names for keyword argument compatibility (--preserve-param-names)

Multi-file Support: Obfuscate entire projects with preserved import relationships

File Filtering: Exclude files using glob patterns (test files, config files, etc.)

Configuration Files: YAML-based configuration for repeatable builds

Selective Obfuscation: Preserve specific names (builtins, magic methods, custom exclusions)

🔒 Pro Edition (Available Now) The following advanced features are available with a Pro license:

String Encryption (v0.1.6+)

AES-256 encryption for strings Runtime decryption with injected decoder Automatic key generation

Anti-Debugging (v0.1.6+)

Debugger detection checks injected into functions Multiple detection methods (sys.gettrace, sys.settrace) Configurable behavior

Control Flow Flattening (v0.3.0+)

State machine transformation for if/else/elif For/while loop flattening Nested structure support CLI: --control-flow

Dead Code Injection (v0.3.0+)

Insertion of unreachable code paths Four strategies: after-return, false branches, opaque predicates, decoy functions CLI: --dead-code

License Embedding (v0.3.0+)

Embed expiration dates: --expire 2025-12-31 Machine binding: --bind-machine Run count limits: --max-runs 100 Offline verification - no external dependencies

Configuration Presets (v0.3.0+)

--preset trial - 30-day time-limited version --preset commercial - Maximum protection with machine binding --preset library - For pip-distributable libraries --preset maximum - Highest security with all protections --list-presets - View all presets

New in v0.5.0 — patent-targeted mechanisms (CN 202610712171X) Six mechanisms, available both as the pyobfus_pro API and — as of v0.5.1 — as opt-in pyobfus build flags (single-file / --no-cross-file mode): --selective-opacity, --seal-code, --vault, --scrub-traceback, --fingerprint <buyer-id>, --expire-hard <date>. v0.5.3 adds --period <N> (run-counter limit), --opacity-config <opacity.toml> (pattern-driven L3 encryption by original qualname), and --bind-device / --bind-device-id <id> (device-locked L3 encryption).

Selective Opacity — per-symbol protection layers (transparent / ai-readable / obfuscated / AES-256-GCM encrypted with lazy _code_ materialization). Forensic watermarking — per-buyer deterministic key derivation for piracy traceback. License binding combo — device / expiry / run-count binding woven into the AES-GCM decryption path (no separate patchable license check). @seal_code — build-time bytecode integrity hash; runtime in-memory-patch detection. --scrub-traceback — production traceback encryption (RSA-2048 + AES-256-GCM); reverse error IDs with the new pyobfus-unscrub CLI. Runtime String Vault — encrypted KV namespace for runtime secrets with lazy per-entry decryption.

Requires Python ≥ 3.9 as of v0.5.0 (3.8 dropped, EOL 2024-10).

See ROADMAP.md for the full feature timeline. Try Pro Features FREE Try all Pro features for 5 days - no registration or credit card required!

Start your free trial

Check trial status

Use Pro features during trial

Control flow flattening (--control-flow) AES-256 string encryption (--string-encryption) Anti-debugging protection (--anti-debug) Dead code injection (--dead-code) License embedding (--expire, --bind-machine, --max-runs) Configuration presets (--preset trial/commercial/library/maximum) Unlimited files and lines of code

After your trial, purchase a license to continue using Pro features.

The trial runs on the honor system. It stores its state in an unsigned file in your home directory, and pyobfus/trial.py is readable Apache-2.0 source — so it is a convenience control, not a security boundary, and we document it as such rather than claiming protection it cannot deliver. See SECURITY.md. Note that the Community Edition has no file or line limits and needs no trial at all — the trial gates only the Pro mechanisms.

Purchase Professional Edition Pro Edition Features:

🔀 Control Flow Flattening (v0.3.0+) 🧩 Dead Code Injection (v0.3.0+) 🔐 AES-256 String Encryption 🛡️ Anti-Debugging Checks 📅 License Embedding (v0.3.0+) - Expiration, machine binding, run limits ⚡ Configuration Presets (v0.3.0+) - One-command setup 🔄 Lifetime Updates 💻 Up to 3 devices per license 📧 Priority Email Support

Price: $45.00 USD (one-time payment) How to Purchase Visit our purchase page: pyobfus.github.io/purchase for detailed information and secure checkout. Quick purchase: 🚀 Buy Now - Direct checkout link (Instant delivery • 30-day money-back guarantee) 3-Step Purchase Process:

Complete Secure Checkout (Stripe)

Click the buy link above or visit the purchase page Enter your email (for license delivery) Complete payment securely via Stripe

Receive License Key

License key delivered to your email within minutes Format: PYOB-XXXX-XXXX-XXXX-XXXX Check Spam/Junk folder if not in inbox

Activate License pip install --upgrade pyobfus pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX pyobfus-license status

Start Using Pro Features

Quick start with presets

Individual features

License restrictions

All Pro features

Support: If you encounter any issues, contact zhurong0525@gmail.com with your license key. Legal & Policies By purchasing pyobfus Professional Edition, you agree to our:

Terms of Service & EULA - License agreement and usage terms Refund Policy - 30-day money-back guarantee, no questions asked Privacy Policy - GDPR compliant, we protect your data

Quick Start Installation From PyPI (recommended): pip install pyobfus From source (for development): git clone https://github.com/zhurong2020/pyobfus.git cd pyobfus pip install -e . Basic Usage

Obfuscate a single file

Obfuscate a directory (cross-file mode - default in v0.2.0+)

Preview obfuscation without writing files (v0.2.0+)

Legacy single-file mode (v0.2.0+)

With configuration file

Preserve parameter names for keyword arguments (v0.1.6+)

Verbose output with progress indicators (v0.2.0+)

patient_age = 55 patient_score = 150 risk = calculate_risk(patient_age, patient_score) print(f"Risk score: {risk}") After obfuscation: def I0(I1, I2): I3 = 0.1 if I2 > 100: I3 = 0.5 return I1 * I3 I4 = 55 I5 = 150 I6 = I0(I4, I5) print(f'Risk score: {I6}') Note: Variable names (I0, I1, etc.) may vary slightly depending on code structure, but functionality is preserved. Configuration Quick Start with Templates Generate a configuration template for your project type:

For Django projects

For Flask projects

For Python libraries

For general projects

YAML syntax errors Invalid configuration options Common typos (e.g., exclude_pattern -> exclude_patterns) Pro features used with community level

Auto-Discovery When you run pyobfus without -c, it automatically searches for:

pyobfus.yaml pyobfus.yml .pyobfus.yaml .pyobfus.yml

Manual Configuration Create pyobfus.yaml: obfuscation: level: community exclude_patterns: - "test_*.py" - "/tests/" - "_init_.py" exclude_names: - "logger" - "config" - "main" remove_docstrings: true remove_comments: true exclude_names Behavior The exclude_names option preserves specified names from being renamed during obfuscation: obfuscation: exclude_names: - MyPublicClass # Name preserved, but strings inside are still encoded - exported_function # Name preserved for external callers Important: exclude_names only affects name obfuscation, not string encoding:

Original

With exclude_names: [SECRET_KEY] and string_encoding: true

✅ Name 'SECRET_KEY' is preserved

✅ String content is still encoded (Base64)

Preserve names for public APIs that external code imports Keep class/function names for debugging while still protecting string content Maintain compatibility with external frameworks expecting specific names

File Filtering Exclude patterns support glob syntax:

test_*.py - Exclude files starting with "test_" /tests/ - Exclude all files in "tests" directories **/_init_.py - Exclude all _init_.py files setup.py - Exclude specific files

See pyobfus.yaml.example for more configuration examples. Architecture pyobfus uses Python's ast module for syntax-aware transformations:

Parser: Parse Python source to AST Analyzer: Build symbol table with scope analysis Transformers: Apply obfuscation techniques (name mangling, string encoding, etc.) Generator: Generate obfuscated Python code

This approach ensures:

Syntactically correct output Proper handling of Python scoping rules Support for modern Python features (f-strings, walrus operator, etc.)

Development Setup git clone https://github.com/zhurong2020/pyobfus.git cd pyobfus python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -e ".[dev]" Testing

Run unit tests

With coverage

Run integration tests

Format code

Type checking

Linting

Keyword Arguments (✅ Resolved in v0.1.6): By default, parameter names are obfuscated, which breaks keyword arguments. Solution: Use the --preserve-param-names flag to preserve parameter names while still obfuscating function bodies. Example:

Before obfuscation

result = process(data_path='./data', output_dir='./output') # ✅ Works

After obfuscation (default behavior)

result = process(data_path='./data', output_dir='./output') # ❌ TypeError!

After obfuscation (with --preserve-param-names)

result = I0(data_path='./data', output_dir='./output') # ✅ Works! When to use --preserve-param-names:

Public API functions/libraries where keyword arguments are used by clients Functions with many parameters where keyword arguments improve readability Code that relies heavily on keyword-only arguments (def func(*, kwonly))

Trade-off: Parameter names reveal some information about the function's interface, but function bodies and local variables are still fully obfuscated.

Cross-file imports: ✅ Resolved in v0.2.0 with full cross-file obfuscation support

Dynamic code: eval(), exec() with obfuscated code may require adjustments

Debugging: Obfuscated code is harder to debug (by design)

Performance: Some obfuscation techniques may impact runtime performance

Recommendations

Test obfuscated code thoroughly before deployment Keep original source in version control Use configuration files for reproducible builds For public APIs, use --preserve-param-names to maintain keyword argument compatibility Consider combining with other protection methods (compilation, etc.)

Technical Details

Python Support: 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 Naming Scheme: Index-based (I0, I1, I2...) - simple and effective Architecture: Modular transformer pipeline with two-phase cross-file obfuscation Testing: 1,000+ tests, 90% coverage, multi-OS CI/CD (Python 3.9-3.14 × Ubuntu / macOS / Windows)

Frequently Asked Questions Is pyobfus Right for Me? Use pyobfus if you:

Need to protect proprietary algorithms before distributing Python applications Want a tool that "just works" without DLL conflicts or native dependencies Prefer transparent pricing without hidden trial limitations Support open-source software with optional paid features

How do I obfuscate Python code?

Install

Obfuscate a single file

Obfuscate an entire project

Preview without writing files

Name mangling: Zero runtime cost (just renamed identifiers) String encoding (Base

source