pyobfus-mcp

Servidor MCP oficial para o ofuscador Python pyobfus — varredura de risco pré-execução, inicialização de configuração com reconhecimento de framework, mapeamento reverso de stack trace

GitHub

Experimente este MCPPatrocinado

Documentação

pyobfus — o ofuscador de Python

pyobfus (pronunciado como "ofuscador de Python") é um ofuscador de código Python moderno, baseado em AST, com predefinições cientes de frameworks, mapeamento reverso de stack traces para depuração assistida por IA e uma CLI JSON legível por máquina projetada para Claude Code, Cursor, Codex e agentes MCP. Uma alternativa transparente e de código aberto ao PyArmor.

Um ofuscador de código Python construído com transformações baseadas em AST. Suporta Python 3.9 até 3.14. Fornece renomeação confiável de identificadores, codificação de strings, achatamento de fluxo de controle, criptografia de strings AES-256 e — exclusivo do pyobfus — um fluxo de trabalho de mapeamento reverso que permite que você (ou seu assistente de codificação com IA) depure stack traces ofuscados sem abrir mão da proteção.

🔒 Edição Pro disponível — 6 mecanismos de proteção direcionados a patentes (Opacidade Seletiva, marca d'água forense, Cofre de Strings em Tempo de Execução e mais) sobrepostos ao ofuscador AST gratuito, US$ 45 pagamento único, sem assinatura. Veja Edição Pro abaixo.

🔧 Novidades na v0.5.13 — --validate-config não emite mais falsos avisos sobre preset (que --init escreve em toda configuração) nem sobre qualquer campo Pro adicionado desde a v0.5.0; o esquema do validador agora é derivado dinamicamente dos campos reais das dataclasses de ObfuscationConfig em vez de uma lista mantida manualmente que havia ficado desatualizada silenciosamente. A v0.5.12 adicionou JSON estruturado de pyobfus-trial status --json / pyobfus-license status --json (a barra de status da extensão do VS Code lê esses dados). Detalhes completos no CHANGELOG; veja Edição Pro abaixo.

🔌 Servidor MCP complementar: `pyobfus-mcp`

Este repositório inclui dois pacotes instaláveis:

Pacote	O que é	Instalação
`pyobfus`	O ofuscador de Python (CLI + biblioteca).	`pip install pyobfus`
`pyobfus-mcp`	Um servidor Model Context Protocol (MCP) que expõe as ferramentas do pyobfus a agentes de codificação com IA.	`uvx pyobfus-mcp` (sem instalação) ou `pip install pyobfus-mcp`

O servidor MCP está em pyobfus_mcp/ e é construído sobre o SDK oficial do Model Context Protocol para Python (FastMCP). Ele registra oito ferramentas MCP para que Claude Desktop, Claude Code, Cursor, Windsurf, Zed e Codex possam chamar o pyobfus diretamente das conversas com agentes — sem precisar sair para o terminal:

Ferramenta MCP	Implementação	Finalidade
`protect_project`	`pyobfus_mcp/tools.py`	Pipeline de chamada única com autoverificação: escaneia → aplica predefinição → ofusca → compila bytecode + teste de importação do resultado → retorna `verified: true/false`. O agente reporta uma verificação verde em vez de torcer para que a transformação não tenha quebrado nada
`check_obfuscation_risks`	`pyobfus_mcp/tools.py`	Escaneamento de risco pré-execução (eval/exec, atributo dinâmico, reflexão de framework)
`generate_pyobfus_config`	`pyobfus_mcp/tools.py`	Detecta automaticamente o framework → escreve um `pyobfus.yaml` funcional
`unmap_stack_trace`	`pyobfus_mcp/tools.py`	Reverte identificadores ofuscados em um stack trace de produção
`list_presets`	`pyobfus_mcp/tools.py`	Enumera predefinições da comunidade / frameworks / Pro
`explain_preset`	`pyobfus_mcp/tools.py`	Descreve o que uma predefinição nomeada altera
`recommend_tier`	`pyobfus_mcp/tools.py`	Analisa um projeto e recomenda o nível comunidade ou Pro, com justificativa
`start_pro_trial`	`pyobfus_mcp/tools.py`	Retorna orientação estruturada para iniciar o teste gratuito de 5 dias do Pro

O servidor está registrado no Registry oficial do MCP sob io.github.zhurong2020/pyobfus-mcp. O transporte é stdio. Veja pyobfus_mcp/README.md para trechos de configuração por cliente.

🧩 Skill / plugin do Claude Code

Este repositório também é um marketplace de plugins do Claude Code. A skill pyobfus-protect ensina a um agente o fluxo de trabalho completo de "proteja o Python antes de enviar — ofusque e verifique se ainda executa" (priorizando MCP, com fallback para CLI):

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

Veja skills/ para a skill e detalhes de instalação. (Isso é distinto de templates/ai-integration/, que são arquivos de regras copiáveis para o seu projeto.)

🧑‍💻 Extensão do VS Code

O pyobfus também está no VS Code Marketplace (publicador zhurong2020) — a primeira extensão focada em ofuscação nesta categoria, já que nenhum concorrente (PyArmor, Nuitka, Sourcedefender) possui uma. Diagnósticos inline de risco de ofuscação (achados de pyobfus --check renderizados via API nativa de DiagnosticCollection do VS Code — sublinhados + painel de Problemas, sem linter separado para configurar), um comando "Reverse Stack Trace", um item na barra de status mostrando seu nível atual com um menu de um clique (Check Workspace / Generate Config / Start Trial / Unlock Pro), um comando "Generate pyobfus.yaml" e clique com o botão direito em "Obfuscate with pyobfus" no Explorer ou no editor. Fonte e justificativa do design em vscode-extension/ e docs/VSCODE_EXTENSION_PLAN.md.

🤖 Recursos nativos de IA

pyobfus --check src/ — escaneamento de risco pré-execução: detecta eval/exec, acesso dinâmico a atributos e pontos de reflexão de framework antes de você ofuscar. Saída JSON com um ai_hint informando ao seu assistente de IA o que executar em seguida.
pyobfus --init src/ — integração sem configuração: escaneia o projeto, detecta FastAPI/Django/Pydantic/Click/SQLAlchemy e escreve um pyobfus.yaml pronto para uso.
pyobfus --unmap --trace error.log --mapping mapping.json — reverte identificadores ofuscados em um stack trace de produção para que você possa depurar (ou entregar o trace a um assistente de IA) sem reverter a ofuscação em si.
pyobfus … --save-mapping mapping.json --trace-marker — carimba cada arquivo ofuscado com um cabeçalho # pyobfus:obfuscated (id + nome do arquivo de mapeamento + o comando exato de --unmap) para que um agente de IA que chegue a um arquivo ofuscado a partir de um traceback saiba imediatamente que é saída do pyobfus e como reverter os nomes.
pyobfus … --provenance-manifest provenance.json — escreve um manifesto JSON local (arquivos ofuscados, hash da configuração, versão do pyobfus, resumo do mapeamento e um resumo de integridade de autoconsistência — não é uma assinatura criptográfica) para proveniência offline de builds.
Predefinições cientes de frameworks — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml com exclusões integradas para métodos de despacho, decoradores, campos ORM, migrações, wrappers de serviço de modelos e parâmetros de injeção de dependência.
--json global — todos os modos da CLI (obfuscate, --check, --unmap, --init) emitem o mesmo esquema estruturado com um campo ai_hint, pronto para consumo por Claude Code, Cursor, Windsurf e servidores MCP.

Recursos

✅ Edição gratuita

Os seguintes recursos estão totalmente implementados e disponíveis na versão atual:

Ofuscação entre arquivos: Renomeação consistente de identificadores em vários arquivos
- Reescrita automática de declarações de importação
- Atualização da lista de __all__ com nomes ofuscados
- Tabela de símbolos global com detecção de colisões
- Pipeline de ofuscação em duas fases (Scan → Transform)
- Modo de pré-visualização com a flag --dry-run
Renomeação de identificadores: Renomeia variáveis, funções, classes e atributos de classe para nomes ofuscados (I0, I1, I2...)
Remoção de comentários: Remove comentários e docstrings
Codificação de strings: Codificação Base64 para literais de string com injeção automática de decodificador
Preservação de parâmetros: Preserva nomes de parâmetros de funções para compatibilidade com argumentos nomeados (--preserve-param-names)
Suporte a múltiplos arquivos: Ofusca projetos inteiros preservando relações de importação
Filtragem de arquivos: Exclui arquivos usando padrões glob (arquivos de teste, arquivos de configuração, etc.)
Arquivos de configuração: Configuração baseada em YAML para builds reproduzíveis
Ofuscação seletiva: Preserva nomes específicos (builtins, métodos mágicos, exclusões personalizadas)
Predefinições de configuração: --preset safe | balanced | aggressive para compensações rápidas de força de ofuscação, além de predefinições cientes de frameworks — --preset fastapi | django | flask | pydantic | click | sqlalchemy | ml — com exclusões integradas para métodos de despacho, decoradores, campos ORM, migrações e parâmetros de injeção de dependência. --list-presets mostra todas elas
Escaneamento de risco pré-execução (--check): detecta eval/exec, acesso dinâmico a atributos e pontos de reflexão de framework antes de você ofuscar
Mapeamento reverso de stack traces (--unmap): reverte identificadores ofuscados em um stack trace de produção, para que você (ou um assistente de codificação com IA) possa depurar sem desofuscar o código enviado
Proveniência de builds (--provenance-manifest, v0.5.5): manifesto JSON local de uma execução de ofuscação — hashes dos arquivos de saída, hash da configuração, versão do pyobfus, resumo do mapeamento — para proveniência offline de builds, sem chamadas de rede

🔒 Edição Pro

Os seguintes recursos avançados estão disponíveis com uma licença Pro:

Criptografia de strings
- Criptografia AES-256 para strings
- Descriptografia em tempo de execução com decodificador injetado
- Geração automática de chaves
Anti-depuração
- Verificações de detecção de depuradores injetadas em funções
- Quatro métodos de detecção (v0.5.11): sys.gettrace() (tracers/depuradores em nível de Python), TracerPid via /proc/self/status (depuradores nativos no Linux — gdb, strace), WinAPI IsDebuggerPresent() (depuradores nativos no Windows) e uma verificação de desvio de tempo (captura execução passo a passo independentemente da plataforma)
- Desativado por padrão para proteger a depurabilidade por IA; ativável via --anti-debug
- Heurístico, não uma fronteira de segurança — documentado no CHANGELOG
Achatamento de fluxo de controle
- Transformação de máquina de estados para if/else/elif
- Achatamento de loops for/while
- Suporte a estruturas aninhadas
- CLI: --control-flow
Injeção de código morto
- Inserção de caminhos de código inalcançáveis
- Quatro estratégias: após-return, ramificações falsas, predicados opacos, funções isca
- CLI: --dead-code
Incorporação de licenças
- Incorporar datas de expiração: --expire 2025-12-31
- Vínculo a máquina: --bind-machine
- Limites de contagem de execuções: --max-runs 100
- Verificação offline — sem dependências externas
Política de tempo de execução (v0.5.9)
- Recusa importar fora de uma lista de permissões de plataforma definida no build — uma generalização em Python puro das restrições de plataforma do PyArmor BCC
- Lista de permissões de SO: --requires-os Linux,Darwin
- Versão mínima do Python: --requires-python-min 3.10
- Lista de permissões de arquitetura de CPU: --requires-arch x86_64,arm64
- Qualquer combinação se compõe; cada verificação é independente
Dados criptografados incorporados (v0.5.10)
- Criptografa um arquivo de recurso com AES-256-GCM no momento do build e o incorpora codificado em base85 na saída — fecha a lacuna do Nuitka Commercial "Protect Data Files" / PyArmor --bind-data
- CLI: --embed-data path/to/resource.bin
- Gera um acessor get_embedded_data() que descriptografa na chamada, não no import
Predefinições de configuração
- --preset trial - versão com limite de tempo de 30 dias
- --preset commercial - proteção máxima com vínculo a máquina
- --preset library - para bibliotecas distribuíveis via pip
- --preset maximum - maior segurança com todas as proteções
- --list-presets - ver todas as predefinições

Mecanismos direcionados a patentes (CN 202610712171X, introduzidos na v0.5.0)

Seis mecanismos, disponíveis tanto como API pyobfus_pro quanto — a partir da v0.5.1 — como flags de build pyobfus opt-in (modo single-file / --no-cross-file): --selective-opacity, --seal-code, --vault, --scrub-traceback, --fingerprint <buyer-id>, --expire-hard <date>. A v0.5.3 adiciona --period <N> (limite de contador de execuções), --opacity-config <opacity.toml> (criptografia L3 orientada por padrões pelo qualname original) e --bind-device / --bind-device-id <id> (criptografia L3 bloqueada por dispositivo). A v0.5.4 estende --bind-device também para chaves do Runtime String Vault — anteriormente apenas a camada L3 de Opacidade Seletiva era bloqueada por dispositivo, então segredos do vault eram descriptografados em qualquer máquina; agora cada chave do vault é re-derivada independentemente em tempo de execução a partir do dispositivo vinculado.

Opacidade Seletiva — camadas de proteção por símbolo (transparente / legível por IA / ofuscado / criptografado com AES-256-GCM com materialização preguiçosa __code__).
Marca d'água forense — derivação determinística de chave por comprador para rastreamento de pirataria.
Combo de vínculo de licença — vínculo de dispositivo / expiração / contagem de execuções tecido no caminho de descriptografia AES-GCM (sem verificação de licença separada e corrigível).
@seal_code — hash de integridade de bytecode em tempo de build; detecção de patch em memória em tempo de execução.
--scrub-traceback — criptografia de traceback de produção (RSA-2048 + AES-256-GCM); reverta IDs de erro com a nova CLI pyobfus-unscrub.
Runtime String Vault — namespace KV criptografado para segredos de tempo de execução com descriptografia preguiçosa por entrada.

Requer Python ≥ 3.9 a partir da v0.5.0 (3.8 removido, EOL 2024-10).

Veja ROADMAP.md para a linha do tempo completa de recursos.

Experimente os Recursos Pro GRÁTIS

Experimente todos os recursos Pro por 5 dias - sem registro ou cartão de crédito!

# 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

O que está incluído na avaliação:

Achatamento de fluxo de controle (--control-flow)
Criptografia de strings AES-256 (--string-encryption)
Proteção anti-debug (--anti-debug)
Injeção de código morto (--dead-code)
Incorporação de licença (--expire, --bind-machine, --max-runs)
Predefinições de configuração (--preset trial/commercial/library/maximum)
Arquivos e linhas de código ilimitados

Após a avaliação, compre uma licença para continuar usando os recursos Pro.

A avaliação funciona no sistema de honra. Ela armazena seu estado em um arquivo não assinado no seu diretório pessoal, e pyobfus/trial.py é código-fonte legível Apache-2.0 — portanto, é um controle de conveniência, não uma fronteira de segurança, e nós o documentamos como tal em vez de alegar proteção que não pode oferecer. Veja SECURITY.md. Observe que a Edição Comunitária não tem limites de arquivos ou linhas e não precisa de avaliação alguma — a avaliação limita apenas os mecanismos Pro.

Compre a Edição Profissional

Recursos da Edição Pro:

🔀 Achatamento de Fluxo de Controle
🧩 Injeção de Código Morto
🔐 Criptografia de Strings AES-256
📦 Ofuscação de Importação - imports importlib em tempo de execução com strings de importação criptografadas
🛡️ Verificações Anti-Debug
📅 Incorporação de Licença - Expiração, vínculo de máquina, limites de execução
⚡ Predefinições de Configuração - Configuração com um comando
🔄 Atualizações Vitalícias
💻 Até 3 dispositivos por licença
📧 Suporte por E-mail Prioritário

Preço: $45,00 USD (pagamento único)

Como Comprar

Visite nossa página de compra: pyobfus.github.io/purchase para informações detalhadas e checkout seguro.

Compra rápida: 🚀 Compre Agora - Link de checkout direto (Entrega instantânea • Garantia de reembolso de 30 dias)

Processo de Compra em 3 Etapas:

Conclua o Checkout Seguro (Stripe)
- Clique no link de compra acima ou visite a página de compra
- Insira seu e-mail (para entrega da licença)
- Conclua o pagamento com segurança via Stripe
Receba a Chave de Licença
- Chave de licença entregue no seu e-mail em minutos
- Formato: PYOB-XXXX-XXXX-XXXX-XXXX
- Verifique a pasta de Spam/Lixo eletrônico se não estiver na caixa de entrada

Ative a Licença

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

Comece a Usar os Recursos Pro

# 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

Suporte: Se você encontrar algum problema, entre em contato com zhurong0525@gmail.com com sua chave de licença.

Legal e Políticas

Ao comprar a Edição Profissional do pyobfus, você concorda com nossos:

Termos de Serviço e EULA - Contrato de licença e termos de uso
Política de Reembolso - Garantia de reembolso de 30 dias, sem perguntas
Política de Privacidade - Em conformidade com o GDPR, protegemos seus dados

Início Rápido

Instalação

Do PyPI (recomendado):

pip install pyobfus

Do código-fonte (para desenvolvimento):

git clone https://github.com/zhurong2020/pyobfus.git
cd pyobfus
pip install -e .

Uso Básico

# 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

Exemplo

Antes da ofuscação:

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

Depois da ofuscação:

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

Nota: Os nomes de variáveis (I0, I1, etc.) podem variar ligeiramente dependendo da estrutura do código, mas a funcionalidade é preservada.

Configuração

Início Rápido com Modelos

Gere um modelo de configuração para o tipo do seu projeto:

# 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

Isso cria um arquivo pyobfus.yaml com padrões sensatos para o tipo do seu projeto.

Validar Configuração

Verifique se o arquivo de configuração tem erros antes do uso:

pyobfus --validate-config pyobfus.yaml

O validador verifica:

Erros de sintaxe YAML
Opções de configuração inválidas
Erros de digitação comuns (por exemplo, exclude_pattern -> exclude_patterns)
Recursos Pro usados com nível comunitário

Descoberta Automática

Quando você executa pyobfus sem -c, ele procura automaticamente por:

pyobfus.yaml
pyobfus.yml
.pyobfus.yaml
.pyobfus.yml

Configuração Manual

Crie pyobfus.yaml:

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

Comportamento do exclude_names

A opção exclude_names preserva nomes especificados de serem renomeados durante a ofuscação:

obfuscation:
  exclude_names:
    - MyPublicClass      # Name preserved, but strings inside are still encoded
    - exported_function  # Name preserved for external callers

Importante: exclude_names afeta apenas a ofuscação de nomes, não a codificação de strings:

# 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)

Casos de uso:

Preserve nomes para APIs públicas que código externo importa
Mantenha nomes de classes/funções para depuração enquanto ainda protege o conteúdo de strings
Mantenha compatibilidade com frameworks externos que esperam nomes específicos

Filtragem de Arquivos

Padrões de exclusão suportam sintaxe glob:

test_*.py - Excluir arquivos que começam com "test_"
**/tests/** - Excluir todos os arquivos nos diretórios "tests"
**/__init__.py - Excluir todos os arquivos __init__.py
setup.py - Excluir arquivos específicos

Veja pyobfus.yaml.example para mais exemplos de configuração.

Arquitetura

pyobfus usa o módulo ast do Python para transformações cientes de sintaxe:

Parser: Analisar código-fonte Python para AST
Analisador: Construir tabela de símbolos com análise de escopo
Transformadores: Aplicar técnicas de ofuscação (mangling de nomes, codificação de strings, etc.)
Gerador: Gerar código Python ofuscado

Essa abordagem garante:

Saída sintaticamente correta
Tratamento adequado das regras de escopo do Python
Suporte para recursos modernos do Python (f-strings, operador walrus, etc.)

Desenvolvimento

Configuração

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]"

Testes

# Run unit tests
pytest tests/ -v

# With coverage
pytest tests/ -v --cov=pyobfus --cov-report=html

# Run integration tests
pytest integration_tests/ -v

Estrutura de Testes de Integração (v0.1.6+): Teste o pyobfus em código do mundo real sem enviar para o PyPI. Veja INTEGRATION_TESTING.md para detalhes.

Qualidade de Código

# Format code
black pyobfus/

# Type checking
mypy pyobfus/

# Linting
ruff check pyobfus/

Casos de Uso

Protegendo Algoritmos Proprietários

Ofusque lógica de negócios sensível antes de distribuir aplicações Python.

Fins Educacionais

Demonstre conceitos de proteção de código e técnicas de ofuscação.

Proteção de Propriedade Intelectual

Adicione uma camada adicional de proteção para software Python comercial.

Limitações

Limitações Atuais

Argumentos de Palavra-chave (✅ Resolvido na v0.1.6): Por padrão, os nomes dos parâmetros são ofuscados, o que quebra argumentos de palavra-chave. Solução: Use a flag --preserve-param-names para preservar os nomes dos parâmetros enquanto ainda ofusca os corpos das funções.

Exemplo:
```
# 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!
```
Quando usar --preserve-param-names:
- Funções/bibliotecas de API pública onde argumentos de palavra-chave são usados por clientes
- Funções com muitos parâmetros onde argumentos de palavra-chave melhoram a legibilidade
- Código que depende fortemente de argumentos somente por palavra-chave (def func(*, kwonly))
Compensação: Os nomes dos parâmetros revelam algumas informações sobre a interface da função, mas os corpos das funções e as variáveis locais ainda são totalmente ofuscados.
Imports entre arquivos: ✅ Resolvido na v0.2.0 com suporte completo a ofuscação entre arquivos
Código dinâmico: eval(), exec() com código ofuscado podem exigir ajustes
Depuração: Código ofuscado é mais difícil de depurar (por design)
Desempenho: Algumas técnicas de ofuscação podem impactar o desempenho em tempo de execução

Recomendações

Teste o código ofuscado minuciosamente antes da implantação
Mantenha o código-fonte original no controle de versão
Use arquivos de configuração para builds reproduzíveis
Para APIs públicas, use --preserve-param-names para manter a compatibilidade de argumentos de palavra-chave
Considere combinar com outros métodos de proteção (compilação, etc.)

Detalhes Técnicos

Suporte a Python: 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
Esquema de Nomes: Baseado em índice (I0, I1, I2...) - simples e eficaz
Arquitetura: Pipeline modular de transformadores com ofuscação entre arquivos em duas fases
Testes: Mais de 1.000 testes, 90% de cobertura, CI/CD multi-OS (Python 3.9-3.14 × Ubuntu / macOS / Windows)

Perguntas Frequentes

O pyobfus é Adequado para Mim?

Use o pyobfus se você:

Precisar proteger algoritmos proprietários antes de distribuir aplicações Python
Quiser uma ferramenta que "simplesmente funciona" sem conflitos de DLL ou dependências nativas
Preferir preços transparentes sem limitações ocultas de avaliação
Apoiar software de código aberto com recursos pagos opcionais

Como eu ofusco código Python?

# 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

Meu código ainda funcionará após a ofuscação?

O pyobfus é projetado para preservar o comportamento do programa para sintaxe Python suportada e padrões de frameworks, e sua matriz de compatibilidade é coberta por testes automatizados. A ofuscação ainda é uma transformação de código-fonte: execute sua própria suíte de testes e verifique o artefato construído, especialmente quando o projeto depende de imports dinâmicos, reflexão ou código gerado.

O código ofuscado roda mais devagar?

Impacto mínimo:

Mangling de nomes: Custo zero em tempo de execução (apenas identificadores renomeados)
Codificação de strings (Base64): ~0,1ms por string na inicialização
Criptografia de strings (AES-256, Pro): ~0,5ms por string na inicialização

Posso ofuscar projetos Django/Flask?

Sim! Use nossos modelos integrados:

# Django
pyobfus --init-config django

# Flask
pyobfus --init-config flask

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

Quais versões do Python são suportadas?

O pyobfus suporta Python 3.9 a 3.14. Compile e teste o artefato ofuscado com a versão do Python usada em produção; a portabilidade entre interpretadores pode depender de sintaxe, dependências e transformações habilitadas.

PyArmor vs pyobfus: Qual devo escolher?

Recurso	pyobfus	PyArmor
Preço	$45 (Pro)	$89 (Pro)
Nível gratuito	Limites claros (5 arquivos/1000 LOC)	Limitações vagas de "avaliação"
Código aberto	Sim (Núcleo: Apache 2.0, Pro: Proprietário)	Não
Dependências nativas	Nenhuma (saída Python pura)	Requer biblioteca de tempo de execução
Suporte a Python 3.9-3.14	Sim	Sim

Escolha o pyobfus se você: Quer preços transparentes, confiança em código aberto e implantação mais simples sem dependências nativas.

Veja nossa comparação detalhada para mais informações.

Posso usar o pyobfus junto com PyArmor ou Nuitka?

Sim — e para muitos projetos essa é a abordagem mais econômica. Use o pyobfus como sua camada padrão sempre ativa (cada módulo recebe mangling de AST + mapeamento para compatibilidade de depuração com IA), depois empilhe a criptografia de bytecode do PyArmor Pro ou a compilação nativa do Nuitka no pequeno conjunto de módulos que realmente precisam de proteção mais forte. A comparação agora também cobre por que a criptografia de bytecode deve ser tratada como um obstáculo mais forte, não como proteção criptográfica irreversível para Python no lado do cliente. Veja Estratégia de Implantação em Camadas em COMPARISON.md para o raciocínio completo.

Posso enviar um executável de arquivo único, como com o Nuitka?

Sim, por uma fração do custo do Nuitka Commercial: ofusque primeiro, depois empacote a saída ofuscada com o PyInstaller gratuito. As duas ferramentas resolvem problemas diferentes (mangling de nomes vs. empacotamento de um interpretador Python em um único arquivo) e se compõem de forma limpa — veja o PyInstaller Cookbook para um exemplo completo, incluindo a verificação de que os nomes de identificadores originais nunca chegam ao binário compilado e que pyobfus --unmap ainda reverte um traceback capturado do exe empacotado.

E se a ofuscação quebrar meu código?

Use --dry-run para pré-visualizar alterações antes de gravar arquivos
Use --preserve-param-names se você depende de argumentos nomeados (keyword arguments)
Adicione exclusões em pyobfus.yaml para nomes que devem permanecer inalterados
Reporte problemas no GitHub - corrigimos bugs rapidamente!

O código ofuscado pode ser revertido?

O mangling de nomes remove os identificadores originais do código-fonte emitido e aumenta o custo da análise, mas não é criptograficamente irreversível: um analista determinado pode inferir nomes e comportamento a partir do contexto. Mantenha o arquivo de mapeamento opcional privado quando precisar de um mapeamento reverso confiável. Para proteção mais forte, use os recursos Pro:

Criptografia AES-256 para strings
Verificações anti-debug para impedir análise

Nota de Segurança: Limitações da Criptografia de Strings

Importante: A criptografia de strings (AES-256) é projetada como um dissuasor contra engenharia reversa casual, não como segurança criptográfica.

Como o código ofuscado precisa descriptografar strings em tempo de execução, a chave de criptografia está necessariamente embutida na saída. Um atacante determinado com acesso ao código ofuscado pode:

Localizar a chave embutida
Extrair e descriptografar todas as strings

Esta é uma limitação fundamental de TODOS os ofuscadores do lado do cliente (incluindo PyArmor, Nuitka, etc.) - a segurança criptográfica real exigiria descriptografia no lado do servidor, o que é impraticável para a maioria dos casos de uso.

O que a criptografia de strings FORNECE:

✅ Impede que buscas casuais por strings ou grep revelem texto sensível
✅ Aumenta o esforço necessário para engenharia reversa
✅ Desencoraja usuários não técnicos de extrair informações
✅ Adiciona uma camada de proteção combinada com outras técnicas

O que a criptografia de strings NÃO fornece:

❌ Proteção contra engenheiros reversos determinados
❌ Segurança criptográfica para segredos (use variáveis de ambiente ou gerenciamento de segredos em vez disso)
❌ Proteção nível DRM

Recomendação: Para credenciais sensíveis (chaves de API, senhas), use variáveis de ambiente ou sistemas externos de gerenciamento de segredos em vez de embuti-las no código.

Como o pyobfus é diferente do Cython/Nuitka?

Ferramenta	Abordagem	Saída
pyobfus	Transformação AST	`.py` arquivos (Python puro)
Cython	Compilar para C	`.so`/`.pyd` (específico da plataforma)
Nuitka	Compilar para executável	Binário (específico da plataforma)

Escolha pyobfus se: Você precisa de arquivos .py multiplataforma sem sobrecarga de compilação.

Documentação

Para Usuários

Instalação e Início Rápido - Comece em minutos
Guia de Configuração - Configuração YAML e filtragem de arquivos
Exemplos - Exemplos de código funcionais demonstrando recursos
Casos de Uso - Cenários de aplicação no mundo real

Para Desenvolvedores

Estrutura do Projeto - Arquitetura do código e fluxo de trabalho de desenvolvimento
Guia de Contribuição - Como contribuir com código e documentação
Roteiro de Desenvolvimento - Recursos planejados e cronograma
Changelog - Histórico de versões e notas de lançamento

Comunidade e Suporte

Issues do GitHub - Relatórios de bugs e solicitações de recursos
Discussões do GitHub - Perguntas, ideias e ajuda da comunidade
Política de Segurança - Como relatar vulnerabilidades de segurança

Legal e Licença

Modelo de Licença Dupla (veja LICENSE-NOTICE.md):
- pyobfus (Núcleo): Apache 2.0 - Gratuito e de código aberto
- pyobfus_pro (Pro): Proprietário - Requer licença paga

Apoie o Projeto

Se você acha o pyobfus útil, considere apoiar seu desenvolvimento:

Compre-me um Café

Seu apoio ajuda a manter e melhorar o pyobfus. Obrigado!

Citação

Se você usar o pyobfus em trabalhos acadêmicos ou quiser referenciá-lo, por favor cite o lançamento arquivado. O DOI conceitual abaixo sempre resolve para a versão mais recente:

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}
}

Os metadados legíveis por máquina estão em CITATION.cff (o widget "Cite este repositório" do GitHub os lê).

Agradecimentos

Inspirado pela abordagem baseada em AST do Opy
Implementação de sala limpa - sem cópia de código

pyobfus-mcp

Documentação

pyobfus — o ofuscador de Python

🔌 Servidor MCP complementar: pyobfus-mcp

🧩 Skill / plugin do Claude Code

🧑‍💻 Extensão do VS Code

🤖 Recursos nativos de IA

Recursos

✅ Edição gratuita

🔒 Edição Pro

Mecanismos direcionados a patentes (CN 202610712171X, introduzidos na v0.5.0)

Experimente os Recursos Pro GRÁTIS

Compre a Edição Profissional

Como Comprar

Legal e Políticas

Início Rápido

Instalação

Uso Básico

Exemplo

Configuração

Início Rápido com Modelos

Validar Configuração

Descoberta Automática

Configuração Manual

Comportamento do exclude_names

Filtragem de Arquivos

Arquitetura

Desenvolvimento

Configuração

Testes

Qualidade de Código

Casos de Uso

Protegendo Algoritmos Proprietários

Fins Educacionais

Proteção de Propriedade Intelectual

Limitações

Limitações Atuais

Recomendações

Detalhes Técnicos

Perguntas Frequentes

O pyobfus é Adequado para Mim?

Como eu ofusco código Python?

Meu código ainda funcionará após a ofuscação?

O código ofuscado roda mais devagar?

Posso ofuscar projetos Django/Flask?

Quais versões do Python são suportadas?

PyArmor vs pyobfus: Qual devo escolher?

Posso usar o pyobfus junto com PyArmor ou Nuitka?

Posso enviar um executável de arquivo único, como com o Nuitka?

E se a ofuscação quebrar meu código?

O código ofuscado pode ser revertido?

Nota de Segurança: Limitações da Criptografia de Strings

Como o pyobfus é diferente do Cython/Nuitka?

Documentação

Para Usuários

Para Desenvolvedores

Comunidade e Suporte

Legal e Licença

Apoie o Projeto

Citação

Agradecimentos

🔌 Servidor MCP complementar: `pyobfus-mcp`