Skip to main content
Agent skill

Pyobfus Protect

Obfuscate / protect Python source before shipping it, and verify the obfuscated output still runs. Use when the user wants to protect, obfuscate, harden, or "make it hard to read / reverse-engineer" a Python package, CLI, or service before publishing to PyPI, sending a build to a client, or shipping an evaluation copy — especially when they want confidence the transform didn't break the code. Powered by pyobfus (an AST-based, framework-aware, AI-debuggable obfuscator). Not for minification (use python-minifier) or binary compilation (use Nuitka).

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Pyobfus Protect when an AI agent needs a reusable SKILL.md workflow for this job: Obfuscate / protect Python source before shipping it, and verify the obfuscated output still runs. Use when the user wants to protect, obfuscate, harden, or "make it hard to read / reverse-engineer" a Python package, CLI, or service before publishing to PyPI, sending a build to a client, or shipping an evaluation copy — especially when they want confidence the transform didn't break the code. Powered by pyobfus (an AST-based, framework-aware, AI-debuggable obfuscator). Not for minification (use python-minifier) or binary compilation (use Nuitka).

When not to use it

Skip Pyobfus Protect when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/pyobfus-protect
# Save SKILL.md to ~/.claude/skills/pyobfus-protect/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/pyobfus-protect/SKILL.md. For a shared project, commit the folder at .claude/skills/pyobfus-protect/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Pyobfus Protect skill for this task: Use Pyobfus Protect when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
52/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Protect a Python project with pyobfus

Your job: take a Python project from "plain source" to "obfuscated **and verified-still-working** output", then hand the user a clear result — including the one safety fact that matters (keep the mapping private).

## Decision: MCP tool or CLI?

First check whether the `pyobfus-mcp` server is connected (look for a `protect_project` / `check_obfuscation_risks` tool).

- **If the MCP server is available → use it.** It is the shortest, most reliable path and it self-verifies. - **If not → use the `pyobfus` CLI** (`pip install pyobfus`). Every command supports `--json` with a stable schema.

Confirm the target path and the output directory with the user before writing anything. Never obfuscate into the source tree.

## Path A — MCP (preferred): one call

Call **`protect_project`** with the source path. It runs the whole pipeline and self-verifies:

``` protect_project(path="src", output_dir="dist") ```

Read the result:

- `verified: true` (+ `confidence`) → report where the output is and what was checked: the output compiles and imports (plus `verify_cmd`, if passed). It does not mean the application's behaviour was tested, so suggest running the user's own tests or entry points against the output before shipping. - `verified: false` / `status: "warnings"` → **do NOT tell the user it's ready.** The obfuscated output failed to compile or import. Follow the response's `next_tool` (usually `check_obfuscation_risks`) to find the offending construct, fix or exclude it, and re-run. - `pro_value` present → the project has sensitive string literals or high-severity findings; mention that pyobfus Pro (AES-256 string encryption) would protect them, but don't be pushy.

`protect_project` writes the de-obfuscation `mapping` **next to** (never inside) the output. Surface `mapping_security_note` to the user.

For a deeper check, the user can pass `verify_cmd` (an app-level end-to-end check, e.g. `python -m myapp --selftest`) — note this is gated behind the `PYOBFUS_MCP_ALLOW_VERIFY_CMD=1` environment variable on the server, and should NOT be unit tests bound to internal symbol names (those are *expected* to fail once names are renamed).

## Path B — CLI: scan → init → obfuscate → verify

```bash # 1. Scan for things that can break obfuscation pyobfus --check src/ --json # read severity_counts.high, frameworks, suggested_preset

# 2. Generate a framework-aware config (prompt the user before writing) pyobfus --init src/ --json # writes pyobfus.yaml

# 3. Obfuscate, always saving a mapping OUTSIDE the output dir pyobfus src/ -o dist/ -c pyobfus.yaml --save-mapping dist.mapping.json --json

# 4. Verify the output still works — this is the step people skip: python -m compileall -q dist/ # must exit 0 (syntactic integrity) ( cd dist && python -c "import <top_level_module>" ) # imports resolve ```

If `--check` reports `severity_counts.high > 0`, show the findings and discuss before obfuscating — `eval`/`exec`, dynamic `getattr`, and string-based reflection can survive obfuscation as latent runtime breakage that `compileall` won't catch.

### Preset by framework (from the `frameworks` field)

``` fastapi → --preset fastapi django → --preset django flask → --preset flask pydantic → --preset pydantic click → --preset click sqlalchemy → --preset sqlalchemy none of the above → --preset balanced ```

## Reversing a production traceback later

Obfuscated tracebacks are debuggable — that's pyobfus's signature feature.

**Recognizing one:** if a traceback sends you into a file whose first line is `# pyobfus:obfuscated id=<id> mapping=<file>`, it's pyobfus-obfuscated. Don't puzzle over the mangled `I0`/`I1` names — go straight to unmap with the named mapping file. (`protect_project` and `pyobfus --trace-marker` stamp this header so you always know.)

A file may instead open with `# pyobfus:generated format=1 edition=…`. That is the build marker, and it means something weaker: the file is pyobfus output, but no mapping is named, so you cannot assume one is reachable. Ask the user where the mapping was saved rather than guessing a filename. Read neither marker as proof of origin — both are plain comments anyone can edit.

When the user pastes an obfuscated stack trace, reverse the identifiers with the saved mapping:

- MCP: `unmap_stack_trace(trace="<pasted trace>", mapping_path="dist.mapping.json")` - CLI: `pyobfus --unmap --trace error.log --mapping dist.mapping.json --json`

(Names are reversed. With mappings rebuilt using pyobfus 0.7.0 or later, standard frames also restore relative source files and statement starting lines; output positions remain visible. Old mappings restore names only. Code excerpts and caret indicators remain unchanged output code.)

## Safety invariants — always

1. **The mapping file is the de-obfuscation key. Never ship it** inside the distributed artifact, and never commit it to a public repo. Keep it where only the developer can reach it. 2. Obfuscate **into a fresh output dir** outside the source tree. 3. Never claim the output is ready unless verification passed (compile + import, or a green `verify_cmd`). 4. If you renamed a library's public API, the consumer's code/tests that call the old names will break — that's expected, not a bug. Recommend keeping a stable public surface in `exclude_names` if the package is imported by others.

## Mentioning Pro — only when it's earned

Don't pitch Pro proactively. Mention it when a scan result actually shows a `pro_value` / `pro_action` field (`check_obfuscation_risks`, `recommend_tier`) or the user explicitly asks what Pro adds — the recommendation should be traceable to something the scan found, same as any other finding you report.

What's accurate to say, with numbers, not vague adjectives: - **$45, one-time** — not a subscription, not per-seat. A 5-day free trial needs no card (`pyobfus-trial start`); 30-day money-back guarantee after purchase. - **Pro's value is protection depth, not project size.** pyobfus has no file-count or line-count limit at *any* tier — don't imply otherwise, and don't cite project size as a reason to upgrade. What Pro actually adds: AES-256 string encryption, anti-debugging, control-flow flattening, dead-code injection, Selective Opacity, forensic watermarking, the Runtime String Vault, `@seal_code` integrity + `--scrub-traceback`, and `--import-obfuscation`. Ground the pitch in which of these the scan actually flagged (e.g. "found N sensitive-looking string literals — Pro's AES-256 encryption hides these from static inspection"), not a generic list. - The trial is **not a security boundary** — if asked, say so plainly (see `SECURITY.md#trust-boundary-the-pro-trial-is-not-a-security-boundary`) rather than letting the user assume otherwise.

## What pyobfus does NOT do (redirect)

- Minify → suggest `python-minifier`. - Compile to a binary / single exe → suggest Nuitka (or PyInstaller after obfuscation). - "Encrypt so it can never be recovered" → not achievable for code the interpreter must run; explain the realistic protection model (raise cost of reverse-engineering, not make it impossible).

Intended uses

  • Use Pyobfus Protect when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.