pyobfus

https://github.com/zhurong2020/pyobfus
Admin
pyobfus is a modern, AST-based Python code obfuscator designed with framework-aware presets, reverse...
Tokens:70,891
Snippets:1,073
Trust Score:6.2
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### Setup development environment

Source: https://github.com/zhurong2020/pyobfus/blob/main/AGENTS.md

Initializes the local virtual environment and installs development dependencies.

```bash
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
git config core.hooksPath .githooks   # once per clone — enables the PII pre-commit guard
```

--------------------------------

### Setup PyArmor Trial Environment

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/PYARMOR_TRIAL_LIMIT_EXPERIMENT.md

Commands to create a virtual environment and install the PyArmor trial version for testing.

```bash
mkdir -p /tmp/pyarmor-limit-test
cd /tmp/pyarmor-limit-test
python3 -m venv venv
source venv/bin/activate
pip install pyarmor                # installs latest, was 9.2.4 on test date
pyarmor --version                  # confirms "trial" + "Can't obfuscate big script and mix str"
```

--------------------------------

### Install Wrangler and Authenticate

Source: https://github.com/zhurong2020/pyobfus/blob/main/cloudflare-worker/README.md

Initial setup commands to install the Wrangler CLI and authenticate with a Cloudflare account.

```bash
# Install Wrangler CLI
npm install -g wrangler

# Login to Cloudflare
wrangler login
```

--------------------------------

### Manual Configuration Example

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Example of a manual configuration file in YAML format.

```yaml
obfuscation:
  level: community
  exclude_patterns:
    - "test_*.py"
    - "**/tests/**"
    - "__init__.py"
  exclude_names:
    - "logger"
    - "config"
    - "main"
  remove_docstrings: true
  remove_comments: true
```

--------------------------------

### Install and Use mcp-publisher

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/mcp-registry-publish-plan.md

Commands to install the publisher CLI, authenticate via GitHub, and publish the server configuration.

```bash
# Linux:
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

# Authenticate (opens GitHub device-flow prompt):
mcp-publisher login github

# Publish from the pyobfus_mcp/ dir where server.json lives:
cd pyobfus_mcp/
mcp-publisher publish
```

--------------------------------

### Install and verify pyobfus

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/article-01-claude-code-mcp-integration.md

Install the package and run an initial check on the project.

```bash
pip install pyobfus pyobfus-mcp
pyobfus --check your-project/ --json
```

--------------------------------

### Generated Configuration File Example

Source: https://github.com/zhurong2020/pyobfus/blob/main/llms-full.txt

An example of the YAML configuration file generated by the --init command.

```yaml
# pyobfus.yaml — generated by `pyobfus --init` on 2026-04-22 15:00 UTC
# pyobfus v0.5.6
# Scanned: /path/to/src  (23 Python file(s))
# Detected frameworks: FastAPI, Pydantic
# Risks: 2 high, 3 medium — run `pyobfus --check` for details.
obfuscation:
  preset: fastapi
  exclude_patterns:
    - "**/routers/**"
    - "**/dependencies.py"
    - "**/main.py"
    - "test_*.py"
    - "**/tests/**"
    - "**/__pycache__/**"
  exclude_names: []
  preserve_param_names: true
  remove_docstrings: false
```

--------------------------------

### Install and Basic Obfuscation Workflow

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/launch-v0.5.4/devto.md

Install the package and perform a standard obfuscation run, generating a mapping file for future trace recovery.

```bash
pip install pyobfus
pyobfus --check src/ --json
pyobfus src/ -o dist/ --save-mapping mapping.json
```

--------------------------------

### Install Pro features

Source: https://github.com/zhurong2020/pyobfus/blob/main/examples/README.md

Command to install the Pro Edition of pyobfus.

```bash
pip install pyobfus[pro]
```

--------------------------------

### Setting up the development environment

Source: https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md

Commands to clone the repository, create a virtual environment, and install development dependencies.

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/pyobfus.git
cd pyobfus

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Run tests to verify setup
pytest tests/ -v
```

--------------------------------

### Install Pyobfus and MCP server

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/post-reddit-rpython.md

Use pip to install the core obfuscator and the MCP server component.

```bash
pip install pyobfus pyobfus-mcp
```

--------------------------------

### Setup Windows Codex Pilot

Source: https://github.com/zhurong2020/pyobfus/blob/main/benchmarks/llm_resistance/README.md

Install the Codex CLI and download the required Python runtime for the Windows-based pilot.

```powershell
npm install --global @openai/codex
codex login

$runtimeZip = "$env:TEMP\python-3.11.9-embed-amd64.zip"
Invoke-WebRequest `
  -Uri "https://www.python.org/ftp/python/3.11.9/python-3.11.9-embed-amd64.zip" `
  -OutFile $runtimeZip
(Get-FileHash $runtimeZip -Algorithm SHA256).Hash
```

--------------------------------

### start_pro_trial

Source: https://github.com/zhurong2020/pyobfus/blob/main/pyobfus_mcp/README.md

Provides guidance on starting the Pro trial.

```APIDOC
## start_pro_trial()

### Description
Returns structured guidance for initiating the 5-day Pro trial.
```

--------------------------------

### Install pyobfus-mcp via uv

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/llms.txt

Optional installation for the MCP server using uv or pip.

```bash
uvx pyobfus-mcp
# or: pip install pyobfus-mcp
```

--------------------------------

### Start and manage a free trial

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/LICENSE_ACTIVATION_GUIDE.md

Commands to initiate a 5-day trial, test Pro features, and check the remaining trial duration.

```bash
# Start a free trial (no credit card required)
pyobfus-trial start --email your@email.com

# Test Pro features during trial
pyobfus input.py -o output.py --string-encryption --anti-debug

# Check trial status
pyobfus-trial status
```

--------------------------------

### Use Pro features

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/LICENSE_ACTIVATION_GUIDE.md

Command-line examples for applying string encryption and anti-debugging features to input files.

```bash
# AES-256 string encryption
pyobfus input.py -o output.py --string-encryption

# Anti-debugging checks
pyobfus input.py -o output.py --anti-debug

# Both features combined
pyobfus input.py -o output.py --string-encryption --anti-debug --preserve-param-names
```

--------------------------------

### Register License

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/LICENSE_ACTIVATION_GUIDE.md

Install the package and register a new license key on a device.

```bash
pip install pyobfus
pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX
```

--------------------------------

### Install pyobfus via pip

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/COMPARISON.md

Standard installation command for the pyobfus package.

```bash
pip install pyobfus
```

--------------------------------

### Install the pyobfus-mcp server

Source: https://github.com/zhurong2020/pyobfus/blob/main/skills/README.md

Install the MCP server package to enable direct tool calls for project protection within the chat interface.

```bash
pip install pyobfus-mcp
```

--------------------------------

### Example MCP session

Source: https://github.com/zhurong2020/pyobfus/blob/main/pyobfus_mcp/README.md

Demonstration of interaction between a user and the agent using pyobfus tools.

```text
User:  Can you check whether this Python project is safe to obfuscate?
       Path: /Users/me/code/my-api

Agent: [invokes check_obfuscation_risks("/Users/me/code/my-api")]
       I found 2 high-severity and 3 medium-severity patterns. FastAPI is
       detected, so I'd suggest the `fastapi` preset. Want me to generate
       the config?

User:  Yes please, write it.

Agent: [invokes generate_pyobfus_config("/Users/me/code/my-api",
         preset_override="fastapi", write=True)]
       Wrote pyobfus.yaml. Next: pyobfus /Users/me/code/my-api -o dist/
       -c pyobfus.yaml
```

--------------------------------

### Use Pro Obfuscation Features

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Command-line examples for applying presets, individual obfuscation techniques, and license restrictions.

```bash
# 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 --import-obfuscation
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 --import-obfuscation --anti-debug --control-flow --dead-code
```

--------------------------------

### Install or upgrade pyobfus

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/LICENSE_ACTIVATION_GUIDE.md

Commands to install the initial package or update to the latest version.

```bash
pip install pyobfus
```

```bash
pip install --upgrade pyobfus
```

--------------------------------

### Example pyobfus.yaml configuration

Source: https://github.com/zhurong2020/pyobfus/blob/main/examples/README.md

A sample configuration file defining obfuscation levels, exclusion patterns, and cleanup options.

```yaml
obfuscation:
  level: community
  exclude_patterns:
    - "test_*.py"
    - "**/tests/**"
    - "__init__.py"
  exclude_names:
    - "logger"
    - "config"
  remove_docstrings: true
  remove_comments: true
```

--------------------------------

### Manage pyobfus Trial

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Commands to start, check, and utilize the 5-day Pro feature trial.

```bash
# 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
```

--------------------------------

### Activate pyobfus License

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Steps to install the latest version and register a purchased license key.

```bash
pip install --upgrade pyobfus
pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX
pyobfus-license status
```

--------------------------------

### Manage pyobfus Trial and Obfuscation

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/index.md

Commands for starting a trial, running obfuscation with various flags, and checking trial status.

```bash
# Start a free trial (no registration, no credit card required)
pyobfus-trial start

# Quick start with presets
pyobfus src/ -o dist/ --preset commercial

# Or use individual features
pyobfus input.py -o output.py --control-flow --string-encryption --anti-debug --dead-code

# With license restrictions
pyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine

# Check trial status
pyobfus-trial status
```

--------------------------------

### POST /api/verify Request and Responses

Source: https://github.com/zhurong2020/pyobfus/blob/main/cloudflare-worker/README.md

Example request body and success/failure responses for license verification.

```json
{
  "license_key": "PYOBFUS-XXXX-XXXX-XXXX-XXXX",
  "device_id": "unique-device-id"
}
```

```json
{
  "valid": true,
  "license_key": "PYOBFUS-XXXX-XXXX-XXXX-XXXX",
  "email": "customer@example.com",
  "created_at": "2025-11-12T00:00:00Z",
  "expires_at": null,
  "features": {
    "string_encryption": true,
    "anti_debug": true,
    "control_flow": false
  }
}
```

```json
{
  "valid": false,
  "error": "Invalid license key"
}
```

--------------------------------

### Obfuscation CLI Usage

Source: https://github.com/zhurong2020/pyobfus/blob/main/CHANGELOG.md

Examples of using the pyobfus CLI to apply presets and custom restrictions to source code.

```bash
# Create a 30-day trial version
pyobfus src/ -o dist/ --preset trial

# Commercial distribution with machine binding
pyobfus src/ -o dist/ --preset commercial

# Custom restrictions
pyobfus src/ -o dist/ --expire 2025-12-31 --bind-machine
```

--------------------------------

### Verifying tool integrity

Source: https://github.com/zhurong2020/pyobfus/blob/main/pyobfus_mcp/README.md

Run the verification command to ensure installed tool descriptions match the manifest shipped at release time.

```bash
pyobfus-mcp-verify
# OK: tool descriptions match the shipped manifest (digest 5cf4c902d460...).
```

--------------------------------

### GET /api/health Response

Source: https://github.com/zhurong2020/pyobfus/blob/main/cloudflare-worker/README.md

Example JSON response for the health check endpoint.

```json
{
  "status": "ok",
  "service": "pyobfus-license-server",
  "version": "1.0.0",
  "timestamp": "2025-11-12T00:00:00Z"
}
```

--------------------------------

### Initialize Configuration

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Generate a configuration template based on the project type.

```bash
# 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
```

--------------------------------

### Obfuscated traceback example

Source: https://github.com/zhurong2020/pyobfus/blob/main/examples/ai_debugging/README.md

An example of a traceback generated from obfuscated code where identifiers are mangled.

```text
  File "dist/pricing.py", line 14, in I5
    I1 = I7 * I3[0]['discount_rate']
KeyError: 'discount_rate'
```

--------------------------------

### Init project

Source: https://github.com/zhurong2020/pyobfus/blob/main/llms-full.txt

Initializes a project by generating a pyobfus.yaml configuration file.

```APIDOC
## CLI: --init

### Description
Scans the directory and generates a pyobfus.yaml configuration file based on detected frameworks and project structure.

### Usage
`pyobfus --init [source_dir] [options]`

### Options
- **--json** (flag) - Overwrite existing config silently and emit structured result
```

--------------------------------

### Minimal reproduction code example

Source: https://github.com/zhurong2020/pyobfus/blob/main/CONTRIBUTING.md

Use this format when reporting bugs to provide a minimal code example that reproduces the issue.

```python
def foo(): pass
def bar(): pass
```

--------------------------------

### Generate configuration file

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/article-01-claude-code-mcp-integration.md

Initialize the project configuration, which creates a pyobfus.yaml file with framework-specific settings.

```bash
pyobfus --init src/ --json
```

--------------------------------

### Obfuscation Example

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Comparison of Python code before and after the obfuscation process.

```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}")
```

```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}')
```

--------------------------------

### Configure obfuscation for frameworks

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Initialize configuration templates for Django or Flask projects before running the obfuscation process.

```bash
# Django
pyobfus --init-config django

# Flask
pyobfus --init-config flask

# Then run obfuscation
pyobfus src/ -o dist/ -c pyobfus.yaml
```

--------------------------------

### GET /api/health

Source: https://github.com/zhurong2020/pyobfus/blob/main/cloudflare-worker/README.md

Checks the health status of the license server.

```APIDOC
## GET /api/health

### Description
Health check endpoint to verify the service is running.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **status** (string) - Service status
- **service** (string) - Service name
- **version** (string) - Service version
- **timestamp** (string) - Current server timestamp

### Response Example
{
  "status": "ok",
  "service": "pyobfus-license-server",
  "version": "1.0.0",
  "timestamp": "2025-11-12T00:00:00Z"
}
```

--------------------------------

### Performing cryptographic verification

Source: https://github.com/zhurong2020/pyobfus/blob/main/docs/RELEASE_PROVENANCE_VERIFICATION.md

Install the pypi-attestations tool and verify the artifact against the project repository.

```bash
python -m pip install pypi-attestations

pypi-attestations verify pypi \
  --repository https://github.com/zhurong2020/pyobfus \
  https://files.pythonhosted.org/packages/.../pyobfus-0.5.14-py3-none-any.whl
```

--------------------------------

### Display obfuscated stack trace

Source: https://github.com/zhurong2020/pyobfus/blob/main/_drafts/article-01-claude-code-mcp-integration.md

Example of a crash report showing mangled identifiers.

```text
File "dist/routers/users.py", line 23
AttributeError: 'I0' object has no attribute 'I2'
```

--------------------------------

### Manually download baseline files

Source: https://github.com/zhurong2020/pyobfus/blob/main/templates/python-baseline/README.md

Downloads individual configuration files for CodeQL, pre-commit hooks, and security policies if the automated bootstrap script is not desired.

```bash
# CodeQL workflow
mkdir -p .github/workflows .github/codeql
curl -fsSL https://raw.githubusercontent.com/zhurong2020/pyobfus/main/.github/workflows/codeql.yml -o .github/workflows/codeql.yml
curl -fsSL https://raw.githubusercontent.com/zhurong2020/pyobfus/main/.github/codeql/codeql-config.yml -o .github/codeql/codeql-config.yml

# Pre-commit (genericized template)
mkdir -p .githooks
curl -fsSL https://raw.githubusercontent.com/zhurong2020/pyobfus/main/templates/python-baseline/pre-commit.template -o .githooks/pre-commit
chmod +x .githooks/pre-commit

# SECURITY.md template
curl -fsSL https://raw.githubusercontent.com/zhurong2020/pyobfus/main/templates/python-baseline/SECURITY.md.template -o SECURITY.md
```

--------------------------------

### Add Claude Code plugin

Source: https://github.com/zhurong2020/pyobfus/blob/main/README.md

Commands to add and install the pyobfus skill for Claude Code.

```bash
/plugin marketplace add zhurong2020/pyobfus
/plugin install pyobfus@pyobfus
```

--------------------------------

### Run obfuscation on a project

Source: https://github.com/zhurong2020/pyobfus/blob/main/examples/README.md

Command to apply the configuration file to a specific project directory.

```bash
pyobfus your_project/ -o obfuscated/ --config pyobfus.yaml
```
Tokens:
Raw