Show HN: I built a Python obfuscator that keeps production traces debuggable

Zhurong2020 released pyobfus v0.5.4, an open-source AST-based Python obfuscator supporting Python 3.9 through 3.14, with framework-aware presets, reverse stack-trace mapping for AI-assisted debugging, and a machine-readable JSON CLI for AI coding agents. The new version adds device-locked Runtime String Vault keys and includes a companion MCP server, pyobfus-mcp, registered in the official MCP Registry, enabling Claude Code, Cursor, and other agents to call pyobfus tools directly.

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 https://claude.com/claude-code , Cursor https://cursor.com/ , 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—, 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 --bind-device now device-locks Runtime String Vault keys tooPro mechanismsremain 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 pyobfus-mcp This repository ships two installable packages : | Package | What it is | Install | |---|---|---| pyobfus | pip install pyobfus pyobfus-mcp 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/ /zhurong2020/pyobfus/blob/main/pyobfus mcp and is built on the official Model Context Protocol Python SDK https://github.com/modelcontextprotocol/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 generate pyobfus config pyobfus mcp/tools.py pyobfus.yaml unmap stack trace pyobfus mcp/tools.py list presets pyobfus mcp/tools.py explain preset pyobfus mcp/tools.py recommend tier pyobfus mcp/tools.py start pro trial pyobfus mcp/tools.py The server is registered in the official MCP Registry under io.github.zhurong2020/pyobfus-mcp . The transport is stdio. See for per-client configuration snippets. /zhurong2020/pyobfus/blob/main/pyobfus mcp/README.md pyobfus mcp/README.md 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/ /zhurong2020/pyobfus/blob/main/skills for the skill and install details. This is distinct from , which are copy-in rule files for /zhurong2020/pyobfus/blob/main/templates/ai-integration templates/ai-integration/ your project. — pre-flight risk scan: detects pyobfus --check src/ 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.— zero-config onboarding: scans the project, detects FastAPI/Django/Pydantic/Click/SQLAlchemy, and writes a ready-to-use pyobfus --init src/ pyobfus.yaml .— 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 --unmap --trace error.log --mapping mapping.json — stamp each obfuscated file with a pyobfus … --save-mapping mapping.json --trace-marker 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 — every CLI mode --json 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. 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 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 - Embed expiration dates: - 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 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 .— build-time bytecode integrity hash; runtime in-memory-patch detection. @seal code — production traceback encryption RSA-2048 + AES-256-GCM ; reverse error IDs with the new --scrub-traceback 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 /zhurong2020/pyobfus/blob/main/docs/ROADMAP.md for the full feature timeline. Try all Pro features for 5 days - no registration or credit card required Start your free trial pyobfus-trial start Check trial status pyobfus-trial status Use Pro features during trial pyobfus input.py -o output.py --level pro What's included in the 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 theCommunity Edition has no file or line limits and needs no trial at all— the trial gates only the Pro mechanisms. 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 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 pyobfus src/ -o dist/ --preset commercial Maximum protection pyobfus src/ -o dist/ --preset trial 30-day trial version pyobfus src/ -o dist/ --preset library For pip distribution Individual features pyobfus input.py -o output.py --string-encryption pyobfus input.py -o output.py --anti-debug pyobfus input.py -o output.py --control-flow pyobfus input.py -o output.py --dead-code License restrictions pyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine --max-runs 100 All Pro features pyobfus input.py -o output.py --string-encryption --anti-debug --control-flow --dead-code Support : If you encounter any issues, contact zhurong0525@gmail.com mailto:zhurong0525@gmail.com with your license key. By purchasing pyobfus Professional Edition, you agree to our: - License agreement and usage terms Terms of Service & EULA /zhurong2020/pyobfus/blob/main/docs/legal/TERMS OF SERVICE.md - 30-day money-back guarantee, no questions asked Refund Policy /zhurong2020/pyobfus/blob/main/docs/legal/REFUND POLICY.md - GDPR compliant, we protect your data Privacy Policy /zhurong2020/pyobfus/blob/main/docs/legal/PRIVACY POLICY.md From PyPI recommended : pip install pyobfus From source for development : git clone https://github.com/zhurong2020/pyobfus.git cd pyobfus pip install -e . Obfuscate a single file pyobfus input.py -o output.py Obfuscate a directory cross-file mode - default in v0.2.0+ pyobfus src/ -o dist/ Preview obfuscation without writing files v0.2.0+ pyobfus src/ -o dist/ --dry-run Legacy single-file mode v0.2.0+ pyobfus src/ -o dist/ --no-cross-file With configuration file pyobfus src/ -o dist/ --config pyobfus.yaml Preserve parameter names for keyword arguments v0.1.6+ pyobfus src/ -o dist/ --preserve-param-names Verbose output with progress indicators v0.2.0+ pyobfus src/ -o dist/ --verbose Before obfuscation : python def calculate risk age, score : """Calculate risk factor.""" risk factor = 0.1 if score 100: risk factor = 0.5 return age risk factor patient age = 55 patient score = 150 risk = calculate risk patient age, patient score print f"Risk score: {risk}" After obfuscation : python 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. Generate a configuration template for your project type: For Django projects pyobfus --init-config django For Flask projects pyobfus --init-config flask For Python libraries pyobfus --init-config library For general projects pyobfus --init-config general This creates a pyobfus.yaml file with sensible defaults for your project type. Check your configuration file for errors before use: pyobfus --validate-config pyobfus.yaml The validator checks for: - YAML syntax errors - Invalid configuration options - Common typos e.g., exclude pattern - exclude patterns - Pro features used with community level When you run pyobfus without -c , it automatically searches for: pyobfus.yaml pyobfus.yml .pyobfus.yaml .pyobfus.yml Create pyobfus.yaml : obfuscation: level: community exclude patterns: - "test .py" - " /tests/ " - " init .py" exclude names: - "logger" - "config" - "main" remove docstrings: true remove comments: true 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 SECRET KEY = "admin-password-123" With exclude names: SECRET KEY and string encoding: true SECRET KEY = decode str 'YWRtaW4tcGFzc3dvcmQtMTIz' ✅ Name 'SECRET KEY' is preserved ✅ String content is still encoded Base64 Use cases : - 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 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. 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. 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 " Run unit tests pytest tests/ -v With coverage pytest tests/ -v --cov=pyobfus --cov-report=html Run integration tests pytest integration tests/ -v Integration Testing Framework v0.1.6+ : Test pyobfus on real-world code without uploading to PyPI. See INTEGRATION TESTING.md /zhurong2020/pyobfus/blob/main/docs/INTEGRATION TESTING.md for details. Format code black pyobfus/ Type checking mypy pyobfus/ Linting ruff check pyobfus/ Obfuscate sensitive business logic before distributing Python applications. Demonstrate code protection concepts and obfuscation techniques. Add an additional layer of protection for commercial Python software. - 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: python Before obfuscation def process data path, output dir : temp file = data path + ".tmp" return temp file result = process data path='./data', output dir='./output' ✅ Works After obfuscation default behavior def I0 I1, I2 : I3 = I1 + ".tmp" return I3 result = process data path='./data', output dir='./output' ❌ TypeError After obfuscation with --preserve-param-names def I0 data path, output dir : I3 = data path + ".tmp" return I3 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 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. 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 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 Install pip install pyobfus Obfuscate a single file pyobfus script.py -o script obf.py Obfuscate an entire project pyobfus src/ -o dist/ Preview without writing files pyobfus src/ -o dist/ --dry-run pyobfus is designed to preserve program behavior for supported Python syntax and framework patterns, and its compatibility matrix is covered by automated tests. Obfuscation is still a source transformation: run your own test suite and verify the built artifact, especially when the project relies on dynamic imports, reflection, or generated code. Minimal impact: Name mangling : Zero runtime cost just renamed identifiers String encoding Base64 : ~0.1ms per string at startup String encryption AES-256, Pro : ~0.5ms per string at startup Yes Use our built-in templates: Django pyobfus --init-config django Flask pyobfus --init-config flask Then run obfuscation pyobfus src/ -o dist/ -c pyobfus.yaml pyobfus supports Python 3.9 through 3.14 . Build and test the obfuscated artifact with the Python version used in production; cross-interpreter portability can depend on syntax, dependencies, and enabled transformations. | Feature | pyobfus | PyArmor | |---|---|---| Price | $45 Pro | $89 Pro | Free tier | Clear limits 5 files/1000 LOC | Vague "trial" limitations | Open source | Yes Core: Apache 2.0, Pro: Proprietary | No | Native dependencies | None pure Python output | Requires runtime library | Python 3.12 support | Yes | Yes | Choose pyobfus if: You want transparent pricing, open-source trust, and simpler deployment without native dependencies. See our detailed comparison /zhurong2020/pyobfus/blob/main/docs/COMPARISON.md for more information. Yes — and for many projects this is the most cost-effective approach. Use pyobfus as your always-on default layer every module gets AST mangling + mapping for AI-debug compatibility , then stack PyArmor Pro's bytecode encryption or Nuitka's native compilation on the small set of modules that genuinely need stronger protection. See Layered Deployment Strategy in COMPARISON.md /zhurong2020/pyobfus/blob/main/docs/COMPARISON.md layered-deployment-strategy for the full reasoning. Use to preview changes before writing files --dry-run Use if you rely on keyword arguments --preserve-param-names Add exclusions in pyobfus.yaml for names that must stay unchanged Report issues on GitHub https://github.com/zhurong2020/pyobfus/issues - we fix bugs quickly Name mangling removes the original identifiers from the emitted source and raises the cost of analysis, but it is not cryptographically irreversible: a determined analyst may infer names and behavior from context. Keep the optional mapping file private when you need reliable reverse mapping. For stronger protection, use Pro features: AES-256 encryption for strings Anti-debugging checks to prevent analysis Important : String encryption AES-256 is designed as a deterrent against casual reverse engineering , not as cryptographic security. Because obfuscated code must decrypt strings at runtime, the encryption key is necessarily embedded in the output. A determined attacker with access to the obfuscated code can: - Locate the embedded key - Extract and decrypt all strings This is a fundamental limitation of ALL client-side obfuscators including PyArmor, Nuitka, etc. - true cryptographic security would require server-side decryption, which is impractical for most use cases. What string encryption DOES provide: - ✅ Prevents casual strings or grep searches from revealing sensitive text - ✅ Increases effort required for reverse engineering - ✅ Deters non-technical users from extracting information - ✅ Adds a layer of protection combined with other techniques What string encryption does NOT provide: - ❌ Protection against determined reverse engineers - ❌ Cryptographic security for secrets use environment variables or secret management instead - ❌ DRM-level protection Recommendation : For sensitive credentials API keys, passwords , use environment variables or external secret management systems rather than embedding them in code. | Tool | Approach | Output | |---|---|---| pyobfus | AST transformation | .py files pure Python | Cython | Compile to C | .so / .pyd platform-specific | Nuitka | Compile to executable | Binary platform-specific | Choose pyobfus if: You need cross-platform .py files without compilation overhead. - Get started in minutes Installation & Quick Start installation - YAML configuration and file filtering Configuration Guide configuration - Working code examples demonstrating features Examples https://github.com/zhurong2020/pyobfus/tree/main/examples - Real-world application scenarios Use Cases use-cases - Codebase architecture and development workflow Project Structure https://github.com/zhurong2020/pyobfus/blob/main/docs/PROJECT STRUCTURE.md - How to contribute code and documentation Contributing Guide https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md - Planned features and timeline Development Roadmap https://github.com/zhurong2020/pyobfus/blob/main/docs/ROADMAP.md - Version history and release notes Changelog https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md - Bug reports and feature requests GitHub Issues https://github.com/zhurong2020/pyobfus/issues - Questions, ideas, and community help GitHub Discussions https://github.com/zhurong2020/pyobfus/discussions - How to report security vulnerabilities Security Policy https://github.com/zhurong2020/pyobfus/blob/main/SECURITY.md Dual License Model see : LICENSE-NOTICE.md pyobfus Core : Apache 2.0 https://github.com/zhurong2020/pyobfus/blob/main/LICENSE - Free and open source pyobfus pro Pro : Proprietary https://github.com/zhurong2020/pyobfus/blob/main/pyobfus pro/LICENSE - Requires paid license If you find pyobfus helpful, consider supporting its development: Your support helps maintain and improve pyobfus. Thank you If you use pyobfus in academic work or want to reference it, please cite the archived release. The concept DOI below always resolves to the latest version: APA Zhu, R. 2026 . pyobfus: An AST-based Python obfuscator with reverse stack-trace mapping for AI-assisted development. Zenodo. https://doi.org/10.5281/zenodo.20846053 BibTeX @software{zhu pyobfus, author = {Zhu, Rong}, title = {pyobfus: An AST-based Python obfuscator with reverse stack-trace mapping for AI-assisted development}, year = {2026}, publisher = {Zenodo}, doi = {10.5281/zenodo.20846053}, url = {https://doi.org/10.5281/zenodo.20846053} } Machine-readable metadata is in CITATION.cff /zhurong2020/pyobfus/blob/main/CITATION.cff GitHub's "Cite this repository" widget reads it . - Inspired by Opy https://github.com/QQuick/Opy 's AST-based approach - Clean room implementation - no code copying