pyobfus — the Python obfuscator

<p align="center"> <img src="https://raw.githubusercontent.com/zhurong2020/pyobfus/main/docs/assets/logo.jpeg" alt="pyobfus Logo" width="200"> </p>

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, Codex, 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.

🔒 Pro Edition available — 6 patent-targeted protection mechanisms (Selective Opacity, forensic watermarking, Runtime String Vault, and more) layered on top of the free AST obfuscator, $45 one-time, no subscription. See Pro Edition below.

🔧 What's new in v0.5.13 — --validate-config no longer false-warns on preset (which --init itself writes into every config) or any Pro field added since v0.5.0; the validator's schema is now derived live from ObfuscationConfig's actual dataclass fields instead of a hand-maintained list that had silently drifted stale. v0.5.12 added pyobfus-trial status --json / pyobfus-license status --json structured JSON (the VS Code extension's status bar reads these). 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, Zed, and Codex 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.)

🧑‍💻 VS Code extension

pyobfus is also on the VS Code Marketplace (publisher zhurong2020) — the first obfuscation-focused extension in this category, since no competitor (PyArmor, Nuitka, Sourcedefender) has one. Inline obfuscation-risk diagnostics (pyobfus --check findings rendered via VS Code's native DiagnosticCollection API — squiggles + Problems panel, no separate linter to configure), a "Reverse Stack Trace" command, a status bar item showing your current tier with a one-click menu (Check Workspace / Generate Config / Start Trial / Unlock Pro), a "Generate pyobfus.yaml" command, and right-click "Obfuscate with pyobfus" from the Explorer or editor. Source and design rationale in vscode-extension/ and docs/VSCODE_EXTENSION_PLAN.md.

🤖 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.
• pyobfus … --provenance-manifest provenance.json — write a local JSON manifest (obfuscated files, config hash, pyobfus version, mapping digest, and a self-consistency integrity digest — not a cryptographic signature) for offline build provenance.
• Framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, model-serving wrappers, 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: 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)

• Configuration Presets: --preset safe | balanced | aggressive for quick obfuscation-strength tradeoffs, plus framework-aware presets — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml — with built-in exclusions for dispatch methods, decorators, ORM fields, migrations, and dependency-injection parameters. --list-presets shows them all

• Pre-flight Risk Scanning (--check): detects eval/exec, dynamic attribute access, and framework reflection points before you obfuscate

• Reverse Stack-Trace Mapping (--unmap): reverse obfuscated identifiers in a production stack trace, so you (or an AI coding assistant) can debug without un-obfuscating the shipped code

• Build Provenance (--provenance-manifest, v0.5.5): local JSON manifest of an obfuscation run — output file hashes, config hash, pyobfus version, mapping digest — for offline build provenance, no network calls

🔒 Pro Edition

The following advanced features are available with a Pro license:

• String Encryption

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

• Anti-Debugging

  • Debugger detection checks injected into functions
  • Four detection methods (v0.5.11): sys.gettrace() (Python-level tracers/debuggers), TracerPid via /proc/self/status (native debuggers on Linux — gdb, strace), WinAPI IsDebuggerPresent() (native debuggers on Windows), and a timing-skew check (catches single-stepping regardless of platform)
  • Default OFF to protect AI-debuggability; opt-in via --anti-debug
  • Heuristic, not a security boundary — documented in the CHANGELOG

• Control Flow Flattening

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

• Dead Code Injection

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

• License Embedding

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

• Runtime Policy (v0.5.9)

  • Refuse to import outside a build-time platform allowlist — a pure-Python generalization of PyArmor BCC's platform restrictions
  • OS allowlis