{"slug": "show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable", "title": "Show HN: I built a Python obfuscator that keeps production traces debuggable", "summary": "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.", "body_md": "**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.\n\nA 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.\n\n🆕 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`\n\nnow device-locks Runtime String Vault keys tooPro mechanismsremain one-line flags: Selective Opacity (per-symbol AES-256 layers), forensic watermarking,`@seal_code`\n\nintegrity, traceback scrubbing,`--period`\n\n(run-counter limit) and`--opacity-config`\n\n(pattern-driven L3 encryption by original qualname). Pro flags are used as`pyobfus SRC -o OUT --level pro --<flag>`\n\n. Full details in the[CHANGELOG]; see[Pro Edition]below.\n\n## 🔌 Companion MCP server: `pyobfus-mcp`\n\n`pyobfus-mcp`\n\nThis repository ships **two installable packages**:\n\n| Package | What it is | Install |\n|---|---|---|\n`pyobfus` |\n\n`pip install pyobfus`\n\n`pyobfus-mcp`\n\n**Model Context Protocol (MCP) server** that exposes pyobfus's tools to AI coding agents.`uvx pyobfus-mcp`\n\n(zero-install) or `pip install pyobfus-mcp`\n\nThe MCP server lives in [ pyobfus_mcp/](/zhurong2020/pyobfus/blob/main/pyobfus_mcp) and is built on the official\n\n[Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)(FastMCP). It registers eight MCP tools so\n\n**Claude Desktop, Claude Code, Cursor, Windsurf, and Zed** can call pyobfus directly from agent conversations — no shelling out:\n\n| MCP tool | Implementation | Purpose |\n|---|---|---|\n`protect_project` |\n`pyobfus_mcp/tools.py` |\n\n**One-call, self-verifying pipeline**: scan → preset → obfuscate → byte-compile + import-smoke-test the output → return`verified: true/false`\n\n. The agent reports a green check instead of hoping the transform didn't break anything`check_obfuscation_risks`\n\n`pyobfus_mcp/tools.py`\n\n`generate_pyobfus_config`\n\n`pyobfus_mcp/tools.py`\n\n`pyobfus.yaml`\n\n`unmap_stack_trace`\n\n`pyobfus_mcp/tools.py`\n\n`list_presets`\n\n`pyobfus_mcp/tools.py`\n\n`explain_preset`\n\n`pyobfus_mcp/tools.py`\n\n`recommend_tier`\n\n`pyobfus_mcp/tools.py`\n\n`start_pro_trial`\n\n`pyobfus_mcp/tools.py`\n\nThe server is registered in the **official MCP Registry** under\n\n`io.github.zhurong2020/pyobfus-mcp`\n\n. The transport is stdio. See [for per-client configuration snippets.](/zhurong2020/pyobfus/blob/main/pyobfus_mcp/README.md)\n\n`pyobfus_mcp/README.md`\n\nThis repo is also a **Claude Code plugin marketplace**. The `pyobfus-protect`\n\nskill teaches an agent the full \"protect Python before shipping — obfuscate **and** verify it still runs\" workflow (MCP-first, CLI fallback):\n\n```\n/plugin marketplace add zhurong2020/pyobfus\n/plugin install pyobfus@pyobfus\n```\n\nSee [ skills/](/zhurong2020/pyobfus/blob/main/skills) for the skill and install details. (This is distinct from\n\n[, which are copy-in rule files for](/zhurong2020/pyobfus/blob/main/templates/ai-integration)\n\n`templates/ai-integration/`\n\n*your*project.)\n\n— pre-flight risk scan: detects`pyobfus --check src/`\n\n`eval`\n\n/`exec`\n\n, dynamic attribute access, and framework reflection points before you obfuscate. JSON output with an`ai_hint`\n\ntelling 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/`\n\n`pyobfus.yaml`\n\n.— 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`\n\n— stamp each obfuscated file with a`pyobfus … --save-mapping mapping.json --trace-marker`\n\n`# pyobfus:obfuscated`\n\nheader (id + mapping filename + the exact`--unmap`\n\ncommand) 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`\n\nwith built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters.**Global**— every CLI mode (`--json`\n\n`obfuscate`\n\n,`--check`\n\n,`--unmap`\n\n,`--init`\n\n) emits the same structured schema with an`ai_hint`\n\nfield, ready for Claude Code, Cursor, Windsurf, and MCP servers to consume.\n\nThe following features are **fully implemented and available** in the current version:\n\n-\n**🆕 Cross-File Obfuscation**(v0.2.0): Consistent name obfuscation across multiple files- Automatic import statement rewriting\n`__all__`\n\nlist updates with obfuscated names- Global symbol table with collision detection\n- Two-phase obfuscation pipeline (Scan → Transform)\n- Preview mode with\n`--dry-run`\n\nflag\n\n-\n**Name Mangling**: Rename variables, functions, classes, and class attributes to obfuscated names (I0, I1, I2...) -\n**Comment Removal**: Strip comments and docstrings -\n**String Encoding**: Base64 encoding for string literals with automatic decoder injection -\n**Parameter Preservation**: Preserve function parameter names for keyword argument compatibility (`--preserve-param-names`\n\n) -\n**Multi-file Support**: Obfuscate entire projects with preserved import relationships -\n**File Filtering**: Exclude files using glob patterns (test files, config files, etc.) -\n**Configuration Files**: YAML-based configuration for repeatable builds -\n**Selective Obfuscation**: Preserve specific names (builtins, magic methods, custom exclusions)\n\nThe following advanced features are available with a Pro license:\n\n-\n**String Encryption**(v0.1.6+)- AES-256 encryption for strings\n- Runtime decryption with injected decoder\n- Automatic key generation\n\n-\n**Anti-Debugging**(v0.1.6+)- Debugger detection checks injected into functions\n- Multiple detection methods (sys.gettrace, sys.settrace)\n- Configurable behavior\n\n-\n**Control Flow Flattening**(v0.3.0+)- State machine transformation for if/else/elif\n- For/while loop flattening\n- Nested structure support\n- CLI:\n`--control-flow`\n\n-\n**Dead Code Injection**(v0.3.0+)- Insertion of unreachable code paths\n- Four strategies: after-return, false branches, opaque predicates, decoy functions\n- CLI:\n`--dead-code`\n\n-\n**License Embedding**(v0.3.0+)- Embed expiration dates:\n`--expire 2025-12-31`\n\n- Machine binding:\n`--bind-machine`\n\n- Run count limits:\n`--max-runs 100`\n\n- Offline verification - no external dependencies\n\n- Embed expiration dates:\n-\n**Configuration Presets**(v0.3.0+)`--preset trial`\n\n- 30-day time-limited version`--preset commercial`\n\n- Maximum protection with machine binding`--preset library`\n\n- For pip-distributable libraries`--preset maximum`\n\n- Highest security with all protections`--list-presets`\n\n- View all presets\n\nSix mechanisms, available both as the `pyobfus_pro`\n\nAPI and — as of **v0.5.1** —\nas opt-in `pyobfus`\n\nbuild flags (single-file / `--no-cross-file`\n\nmode):\n`--selective-opacity`\n\n, `--seal-code`\n\n, `--vault`\n\n, `--scrub-traceback`\n\n,\n`--fingerprint <buyer-id>`\n\n, `--expire-hard <date>`\n\n. **v0.5.3** adds\n`--period <N>`\n\n(run-counter limit), `--opacity-config <opacity.toml>`\n\n(pattern-driven L3 encryption by original qualname), and `--bind-device`\n\n/\n`--bind-device-id <id>`\n\n(device-locked L3 encryption).\n\n**Selective Opacity**— per-symbol protection layers (transparent / ai-readable / obfuscated / AES-256-GCM encrypted with lazy`__code__`\n\nmaterialization).**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`\n\n— production traceback encryption (RSA-2048 + AES-256-GCM); reverse error IDs with the new`--scrub-traceback`\n\n`pyobfus-unscrub`\n\nCLI.**Runtime String Vault**— encrypted KV namespace for runtime secrets with lazy per-entry decryption.\n\nRequires Python ≥ 3.9 as of v0.5.0 (3.8 dropped, EOL 2024-10).\n\nSee [ROADMAP.md](/zhurong2020/pyobfus/blob/main/docs/ROADMAP.md) for the full feature timeline.\n\n**Try all Pro features for 5 days - no registration or credit card required!**\n\n```\n# Start your free trial\npyobfus-trial start\n\n# Check trial status\npyobfus-trial status\n\n# Use Pro features during trial\npyobfus input.py -o output.py --level pro\n```\n\n**What's included in the trial:**\n\n- Control flow flattening (\n`--control-flow`\n\n) - AES-256 string encryption (\n`--string-encryption`\n\n) - Anti-debugging protection (\n`--anti-debug`\n\n) - Dead code injection (\n`--dead-code`\n\n) - License embedding (\n`--expire`\n\n,`--bind-machine`\n\n,`--max-runs`\n\n) - Configuration presets (\n`--preset trial/commercial/library/maximum`\n\n) - Unlimited files and lines of code\n\nAfter your trial, purchase a license to continue using Pro features.\n\nThe trial runs on the honor system.It stores its state in an unsigned file in your home directory, and`pyobfus/trial.py`\n\nis 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.\n\n**Pro Edition Features**:\n\n- 🔀 Control Flow Flattening (v0.3.0+)\n- 🧩 Dead Code Injection (v0.3.0+)\n- 🔐 AES-256 String Encryption\n- 🛡️ Anti-Debugging Checks\n- 📅 License Embedding (v0.3.0+) - Expiration, machine binding, run limits\n- ⚡ Configuration Presets (v0.3.0+) - One-command setup\n- 🔄 Lifetime Updates\n- 💻 Up to 3 devices per license\n- 📧 Priority Email Support\n\n**Price**: $45.00 USD (one-time payment)\n\n**Visit our purchase page**: ** pyobfus.github.io/purchase** for detailed information and secure checkout.\n\n**Quick purchase**: ** 🚀 Buy Now** - Direct checkout link (Instant delivery • 30-day money-back guarantee)\n\n**3-Step Purchase Process**:\n\n-\n**Complete Secure Checkout**(Stripe)- Click the buy link above or visit the purchase page\n- Enter your email (for license delivery)\n- Complete payment securely via Stripe\n\n-\n**Receive License Key**- License key delivered to your email within minutes\n- Format:\n`PYOB-XXXX-XXXX-XXXX-XXXX`\n\n**Check Spam/Junk folder** if not in inbox\n\n-\n**Activate License**\n\n```\npip install --upgrade pyobfus\npyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX\npyobfus-license status\n```\n\n-\n**Start Using Pro Features**\n\n```\n# Quick start with presets\npyobfus src/ -o dist/ --preset commercial   # Maximum protection\npyobfus src/ -o dist/ --preset trial        # 30-day trial version\npyobfus src/ -o dist/ --preset library      # For pip distribution\n\n# Individual features\npyobfus input.py -o output.py --string-encryption\npyobfus input.py -o output.py --anti-debug\npyobfus input.py -o output.py --control-flow\npyobfus input.py -o output.py --dead-code\n\n# License restrictions\npyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine --max-runs 100\n\n# All Pro features\npyobfus input.py -o output.py --string-encryption --anti-debug --control-flow --dead-code\n```\n\n**Support**: If you encounter any issues, contact [zhurong0525@gmail.com](mailto:zhurong0525@gmail.com) with your license key.\n\nBy purchasing pyobfus Professional Edition, you agree to our:\n\n- 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)\n\n**From PyPI** (recommended):\n\n```\npip install pyobfus\n```\n\n**From source** (for development):\n\n```\ngit clone https://github.com/zhurong2020/pyobfus.git\ncd pyobfus\npip install -e .\n# Obfuscate a single file\npyobfus input.py -o output.py\n\n# Obfuscate a directory (cross-file mode - default in v0.2.0+)\npyobfus src/ -o dist/\n\n# Preview obfuscation without writing files (v0.2.0+)\npyobfus src/ -o dist/ --dry-run\n\n# Legacy single-file mode (v0.2.0+)\npyobfus src/ -o dist/ --no-cross-file\n\n# With configuration file\npyobfus src/ -o dist/ --config pyobfus.yaml\n\n# Preserve parameter names for keyword arguments (v0.1.6+)\npyobfus src/ -o dist/ --preserve-param-names\n\n# Verbose output with progress indicators (v0.2.0+)\npyobfus src/ -o dist/ --verbose\n```\n\n**Before obfuscation**:\n\n``` python\ndef calculate_risk(age, score):\n    \"\"\"Calculate risk factor.\"\"\"\n    risk_factor = 0.1\n    if score > 100:\n        risk_factor = 0.5\n    return age * risk_factor\n\npatient_age = 55\npatient_score = 150\nrisk = calculate_risk(patient_age, patient_score)\nprint(f\"Risk score: {risk}\")\n```\n\n**After obfuscation**:\n\n``` python\ndef I0(I1, I2):\n    I3 = 0.1\n    if I2 > 100:\n        I3 = 0.5\n    return I1 * I3\nI4 = 55\nI5 = 150\nI6 = I0(I4, I5)\nprint(f'Risk score: {I6}')\n```\n\n*Note: Variable names (I0, I1, etc.) may vary slightly depending on code structure, but functionality is preserved.*\n\nGenerate a configuration template for your project type:\n\n```\n# For Django projects\npyobfus --init-config django\n\n# For Flask projects\npyobfus --init-config flask\n\n# For Python libraries\npyobfus --init-config library\n\n# For general projects\npyobfus --init-config general\n```\n\nThis creates a `pyobfus.yaml`\n\nfile with sensible defaults for your project type.\n\nCheck your configuration file for errors before use:\n\n```\npyobfus --validate-config pyobfus.yaml\n```\n\nThe validator checks for:\n\n- YAML syntax errors\n- Invalid configuration options\n- Common typos (e.g.,\n`exclude_pattern`\n\n->`exclude_patterns`\n\n) - Pro features used with community level\n\nWhen you run `pyobfus`\n\nwithout `-c`\n\n, it automatically searches for:\n\n`pyobfus.yaml`\n\n`pyobfus.yml`\n\n`.pyobfus.yaml`\n\n`.pyobfus.yml`\n\nCreate `pyobfus.yaml`\n\n:\n\n```\nobfuscation:\n  level: community\n  exclude_patterns:\n    - \"test_*.py\"\n    - \"**/tests/**\"\n    - \"__init__.py\"\n  exclude_names:\n    - \"logger\"\n    - \"config\"\n    - \"main\"\n  remove_docstrings: true\n  remove_comments: true\n```\n\nThe `exclude_names`\n\noption preserves specified names from being renamed during obfuscation:\n\n```\nobfuscation:\n  exclude_names:\n    - MyPublicClass      # Name preserved, but strings inside are still encoded\n    - exported_function  # Name preserved for external callers\n```\n\n**Important**: `exclude_names`\n\nonly affects **name obfuscation**, not **string encoding**:\n\n```\n# Original\nSECRET_KEY = \"admin-password-123\"\n\n# With exclude_names: [SECRET_KEY] and string_encoding: true\nSECRET_KEY = _decode_str('YWRtaW4tcGFzc3dvcmQtMTIz')\n# ✅ Name 'SECRET_KEY' is preserved\n# ✅ String content is still encoded (Base64)\n```\n\n**Use cases**:\n\n- Preserve names for public APIs that external code imports\n- Keep class/function names for debugging while still protecting string content\n- Maintain compatibility with external frameworks expecting specific names\n\nExclude patterns support glob syntax:\n\n`test_*.py`\n\n- Exclude files starting with \"test_\"`**/tests/**`\n\n- Exclude all files in \"tests\" directories`**/__init__.py`\n\n- Exclude all`__init__.py`\n\nfiles`setup.py`\n\n- Exclude specific files\n\nSee `pyobfus.yaml.example`\n\nfor more configuration examples.\n\npyobfus uses Python's `ast`\n\nmodule for syntax-aware transformations:\n\n**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\n\nThis approach ensures:\n\n- Syntactically correct output\n- Proper handling of Python scoping rules\n- Support for modern Python features (f-strings, walrus operator, etc.)\n\n```\ngit clone https://github.com/zhurong2020/pyobfus.git\ncd pyobfus\npython -m venv venv\nsource venv/bin/activate  # Windows: venv\\Scripts\\activate\npip install -e \".[dev]\"\n# Run unit tests\npytest tests/ -v\n\n# With coverage\npytest tests/ -v --cov=pyobfus --cov-report=html\n\n# Run integration tests\npytest integration_tests/ -v\n```\n\n**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.\n\n```\n# Format code\nblack pyobfus/\n\n# Type checking\nmypy pyobfus/\n\n# Linting\nruff check pyobfus/\n```\n\nObfuscate sensitive business logic before distributing Python applications.\n\nDemonstrate code protection concepts and obfuscation techniques.\n\nAdd an additional layer of protection for commercial Python software.\n\n-\n**Keyword Arguments**(✅ Resolved in v0.1.6): By default, parameter names are obfuscated, which breaks keyword arguments.** Solution**: Use the`--preserve-param-names`\n\nflag to preserve parameter names while still obfuscating function bodies.Example:\n\n``` python\n# Before obfuscation\ndef process(data_path, output_dir):\n    temp_file = data_path + \".tmp\"\n    return temp_file\n\nresult = process(data_path='./data', output_dir='./output')  # ✅ Works\n\n# After obfuscation (default behavior)\ndef I0(I1, I2):\n    I3 = I1 + \".tmp\"\n    return I3\n\nresult = process(data_path='./data', output_dir='./output')  # ❌ TypeError!\n\n# After obfuscation (with --preserve-param-names)\ndef I0(data_path, output_dir):\n    I3 = data_path + \".tmp\"\n    return I3\n\nresult = I0(data_path='./data', output_dir='./output')  # ✅ Works!\n```\n\n**When to use**:`--preserve-param-names`\n\n- Public API functions/libraries where keyword arguments are used by clients\n- Functions with many parameters where keyword arguments improve readability\n- Code that relies heavily on keyword-only arguments (\n`def func(*, kwonly)`\n\n)\n\n**Trade-off**: Parameter names reveal some information about the function's interface, but function bodies and local variables are still fully obfuscated. -\n**Cross-file imports**: ✅ Resolved in v0.2.0 with full cross-file obfuscation support -\n**Dynamic code**:`eval()`\n\n,`exec()`\n\nwith obfuscated code may require adjustments -\n**Debugging**: Obfuscated code is harder to debug (by design) -\n**Performance**: Some obfuscation techniques may impact runtime performance\n\n**Test obfuscated code thoroughly** before deployment- Keep original source in version control\n- Use configuration files for reproducible builds\n- For public APIs, use\n`--preserve-param-names`\n\nto maintain keyword argument compatibility - Consider combining with other protection methods (compilation, etc.)\n\n**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)\n\n**Use pyobfus if you:**\n\n- Need to protect proprietary algorithms before distributing Python applications\n- Want a tool that \"just works\" without DLL conflicts or native dependencies\n- Prefer transparent pricing without hidden trial limitations\n- Support open-source software with optional paid features\n\n```\n# Install\npip install pyobfus\n\n# Obfuscate a single file\npyobfus script.py -o script_obf.py\n\n# Obfuscate an entire project\npyobfus src/ -o dist/\n\n# Preview without writing files\npyobfus src/ -o dist/ --dry-run\n```\n\npyobfus 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.\n\nMinimal impact:\n\n**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\n\nYes! Use our built-in templates:\n\n```\n# Django\npyobfus --init-config django\n\n# Flask\npyobfus --init-config flask\n\n# Then run obfuscation\npyobfus src/ -o dist/ -c pyobfus.yaml\n```\n\npyobfus supports **Python 3.9 through 3.14**. Build and test the obfuscated\nartifact with the Python version used in production; cross-interpreter\nportability can depend on syntax, dependencies, and enabled transformations.\n\n| Feature | pyobfus | PyArmor |\n|---|---|---|\nPrice |\n$45 (Pro) | $89 (Pro) |\nFree tier |\nClear limits (5 files/1000 LOC) | Vague \"trial\" limitations |\nOpen source |\nYes (Core: Apache 2.0, Pro: Proprietary) | No |\nNative dependencies |\nNone (pure Python output) | Requires runtime library |\nPython 3.12 support |\nYes | Yes |\n\n**Choose pyobfus if:** You want transparent pricing, open-source trust, and simpler deployment without native dependencies.\n\nSee our [detailed comparison](/zhurong2020/pyobfus/blob/main/docs/COMPARISON.md) for more information.\n\nYes — 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.\n\n**Use** to preview changes before writing files`--dry-run`\n\n**Use** if you rely on keyword arguments`--preserve-param-names`\n\n**Add exclusions** in`pyobfus.yaml`\n\nfor names that must stay unchanged**Report issues** on[GitHub](https://github.com/zhurong2020/pyobfus/issues)- we fix bugs quickly!\n\nName 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:\n\n**AES-256 encryption** for strings**Anti-debugging** checks to prevent analysis\n\n**Important**: String encryption (AES-256) is designed as a **deterrent against casual reverse engineering**, not as cryptographic security.\n\nBecause 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:\n\n- Locate the embedded key\n- Extract and decrypt all strings\n\n**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.\n\n**What string encryption DOES provide:**\n\n- ✅ Prevents casual\n`strings`\n\nor`grep`\n\nsearches from revealing sensitive text - ✅ Increases effort required for reverse engineering\n- ✅ Deters non-technical users from extracting information\n- ✅ Adds a layer of protection combined with other techniques\n\n**What string encryption does NOT provide:**\n\n- ❌ Protection against determined reverse engineers\n- ❌ Cryptographic security for secrets (use environment variables or secret management instead)\n- ❌ DRM-level protection\n\n**Recommendation**: For sensitive credentials (API keys, passwords), use environment variables or external secret management systems rather than embedding them in code.\n\n| Tool | Approach | Output |\n|---|---|---|\npyobfus |\nAST transformation | `.py` files (pure Python) |\nCython |\nCompile to C | `.so` /`.pyd` (platform-specific) |\nNuitka |\nCompile to executable | Binary (platform-specific) |\n\n**Choose pyobfus if:** You need cross-platform `.py`\n\nfiles without compilation overhead.\n\n- 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)\n\n- 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)\n\n- 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)\n\n**Dual License Model**(see):`LICENSE-NOTICE.md`\n\n**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\n\nIf you find pyobfus helpful, consider supporting its development:\n\nYour support helps maintain and improve pyobfus. Thank you!\n\nIf 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:\n\n**APA**\n\nZhu, R. (2026).\n\npyobfus: An AST-based Python obfuscator with reverse stack-trace mapping for AI-assisted development. Zenodo.[https://doi.org/10.5281/zenodo.20846053]\n\n**BibTeX**\n\n```\n@software{zhu_pyobfus,\n  author    = {Zhu, Rong},\n  title     = {pyobfus: An AST-based Python obfuscator with reverse stack-trace mapping for AI-assisted development},\n  year      = {2026},\n  publisher = {Zenodo},\n  doi       = {10.5281/zenodo.20846053},\n  url       = {https://doi.org/10.5281/zenodo.20846053}\n}\n```\n\nMachine-readable metadata is in [ CITATION.cff](/zhurong2020/pyobfus/blob/main/CITATION.cff) (GitHub's \"Cite this repository\" widget reads it).\n\n- Inspired by\n[Opy](https://github.com/QQuick/Opy)'s AST-based approach - Clean room implementation - no code copying", "url": "https://wpnews.pro/news/show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable", "canonical_source": "https://github.com/zhurong2020/pyobfus", "published_at": "2026-08-01 02:00:45+00:00", "updated_at": "2026-08-01 02:22:17.693084+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["pyobfus", "Zhurong2020", "PyArmor", "Claude Code", "Cursor", "MCP", "FastMCP", "Windsurf"], "alternates": {"html": "https://wpnews.pro/news/show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable", "markdown": "https://wpnews.pro/news/show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable.md", "text": "https://wpnews.pro/news/show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable.txt", "jsonld": "https://wpnews.pro/news/show-hn-i-built-a-python-obfuscator-that-keeps-production-traces-debuggable.jsonld"}}