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, para desenvolvedores que precisam ofuscar antes de enviar enquanto mantêm falhas diagnosticáveis. Predefinições cientes de frameworks, mapeamento reverso de stack traces e uma CLI JSON legível por máquina permitem que Claude Code, Cursor, GitHub Copilot, Codex, CodeBuddy e qualquer agente de IA compatível com MCP ajudem a depurar stack traces ofuscados. 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 IA) depure stack traces ofuscados sem abrir mão da proteção.

🔒 Edição Pro disponível. Seis 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.30: builds Pro agora podem avisar antes de uma expiração rígida sem interromper o artefato (--expire-warn-days N), e chaves de Opacidade Seletiva L3 podem vir de um provedor controlado pelo aplicativo ou variável de ambiente base64 (--bind-key-env NAME). Isso permite que um artefato protegido rode em qualquer máquina que seu aplicativo autorize, sem incorporar a chave bruta ou recompilar separadamente para cada dispositivo. Veja pyobfus --help para as regras de compatibilidade.

🔔 Marcar este repositório com estrela não notifica você sobre novos lançamentos. O GitHub só envia notificações de lançamento para pessoas que explicitamente Observam (Watch) o repositório. Clique Watch → Custom → Releases (no topo desta página) para ser avisado no momento em que uma nova versão for lançada, sem o ruído de cada commit/issue.

🔌 Servidor MCP complementar: `pyobfus-mcp`

Este repositório entrega 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 IA.	`uvx pyobfus-mcp` (zero-instalação) ou `pip install pyobfus-mcp`

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

Ferramenta MCP	Implementação	Propósito
`protect_project`	`pyobfus_mcp/tools.py`	Pipeline de chamada única e autoverificável: scan → predefinição → ofuscar → byte-compilar + teste de importação do resultado → retornar `verified: true/false`. O agente reporta um check verde em vez de torcer para que a transformação não tenha quebrado nada
`check_obfuscation_risks`	`pyobfus_mcp/tools.py`	Scan de risco pré-voo; passe `verify_dependencies_online=true` para verificar nomes de pacotes declarados contra o PyPI público.
`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 / framework / 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 nível comunidade vs Pro, com justificativa
`start_pro_trial`	`pyobfus_mcp/tools.py`	Retorna orientação estruturada para iniciar o teste Pro de 5 dias

O servidor está registrado no MCP Registry oficial 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, com duas skills divididas por se alteram algo:

Skill	O que faz	Escreve?
`pyobfus-protect`	O fluxo de trabalho completo "proteja Python antes de enviar: ofusque e verifique se ainda roda" (MCP-first, fallback CLI)	Sim, produz um build
`pyobfus-review`	Responde à pergunta que vem primeiro: este projeto é seguro para ofuscar, o que quebraria e quais artefatos um build emitiria. `--check` ciente de configuração mais `--dry-run`, nada mais	Não, somente leitura

Ambas seguem o formato SKILL.md do agentskills.io, então também funcionam no modo agente do GitHub Copilot, Cursor e Codex CLI, que leem skills de .github/skills/ no seu próprio repositório.

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

Veja skills/ para ambas as skills e detalhes de instalação. (Isso é distinto de templates/ai-integration/, que são arquivos de regras copiados para seu projeto.)

🧑‍💻 Extensão VS Code

O pyobfus também está no VS Code Marketplace e no Open VSX (publicador zhurong2020, mesma versão em ambos; Open VSX cobre VSCodium, Gitpod, Eclipse Theia e code-server). É a primeira extensão focada em ofuscação nesta categoria, já que nenhum concorrente (PyArmor, Nuitka, Sourcedefender) tem uma. Diagnósticos inline de risco de ofuscação (achados pyobfus --check renderizados via API nativa DiagnosticCollection do VS Code: sublinhados + painel Problems, sem linter separado para configurar), um comando "Reverse Stack Trace", um item de 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 botão direito "Obfuscate with pyobfus" no Explorer ou editor. Fonte e justificativa de design em vscode-extension/ e docs/VSCODE_EXTENSION_PLAN.md.

🤖 Recursos nativos de IA

pyobfus --check src/ executa uma varredura de risco pré-voo ciente da configuração. Ele detecta eval/exec, acesso dinâmico a atributos, pontos de reflexão de frameworks e dependências declaradas que não existem no PyPI público antes de você ofuscar. Ele respeita a mesma configuração explícita/descoberta e predefinições de um build; descobertas de arquivos excluídos são relatadas separadamente sem afetar o resultado principal. Use --no-config para a varredura legada sem filtro e --offline para pular consultas ao PyPI. O JSON inclui effective_config, excluded_findings e um ai_hint informando ao seu assistente de IA o que executar em seguida. Adicione --sarif pyobfus.sarif para também emitir um relatório SARIF 2.1.0 para GitHub Code Scanning (veja docs/SARIF_CODE_SCANNING.md).
uses: zhurong2020/pyobfus-action@v1 executa a varredura pré-voo ou um build ofuscado no GitHub Actions, com SARIF conectado ao Code Scanning e uma tabela de descobertas no resumo do job. Ele separa descobertas de erros de ferramenta, então fail-on: never permite que um upload SARIF seja executado primeiro sem o workaround do || true engolir um caminho digitado incorretamente. Repositório: zhurong2020/pyobfus-action · Marketplace.
pyobfus --init src/ é onboarding com configuração zero: ele varre 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 caia em um arquivo ofuscado a partir de um traceback saiba imediatamente que é saída do pyobfus e como reverter os nomes.
pyobfus … --no-community-marker desativa o marcador # pyobfus:generated versionado com o qual os arquivos gerados normalmente abrem. O marcador nomeia a versão da ferramenta, a edição e o caminho relativo do arquivo ao projeto, para que qualquer pessoa (ou agente) que abra o arquivo saiba que é saída gerada, e não algo para editar. Ele nunca contém caminho absoluto, id do comprador, chave de licença ou hash. É atribuição transparente (um comentário simples que você pode excluir), não uma verificação de licença ou medida antipirataria, e suprimi-lo é um recurso do nível gratuito, não pago. Distinto de --trace-marker, que trata de reverter tracebacks.
pyobfus … --provenance-manifest provenance.json escreve um manifesto JSON local (hashes de entrada/saída, hash de configuração, versão do pyobfus, commit git quando disponível, digest do mapeamento, relacionamentos de componentes compatíveis com CycloneDX e um digest de integridade de autoconsistência, não uma assinatura criptográfica) para proveniência de build offline. Veja docs/PROVENANCE_MANIFEST.md.
pyobfus --verify-provenance-manifest provenance.json --json valida a estrutura do manifesto, os relacionamentos compatíveis com CycloneDX e o digest de integridade local antes de arquivar ou enviar.
pyobfus … --dry-run --json pré-visualiza um objeto plan versionado antes que qualquer coisa seja escrita: a configuração efetiva, quais arquivos são selecionados ou excluídos (e por quê) e os artefatos que um build produziria, cada um marcado como ship / retain-internal / optional. Apenas rótulos relativos (sem fonte, segredos ou caminhos absolutos); é uma pré-visualização, não um arquivo de aplicação salvo.
pyobfus … --verify-syntax é uma verificação pós-build opcional: ele compila cada .py gerado em memória (sem import, sem execução, sem __pycache__) e relata syntax_valid em JSON. Uma falha bloqueia a entrega; não faz nenhuma afirmação sobre correção em tempo de execução.
pyobfus … --build-report build-report.json escreve um modelo de fatos determinístico e seguro para privacidade após um build bem-sucedido: seleção/configuração, contadores de transformação e cache, evidência de verificação, hashes de saída, papéis de artefatos, estado do marcador e vínculo de proveniência. Veja docs/VERIFIABLE_BUILD_REPORT.md.
Pacotes que reexportam. Um __init__.py que reexporta (from .core import run, com run em __all__) mantém o nome que sua definição recebeu, para que o pacote gerado permaneça importável e from pkg import * ainda funcione. Nomes reexportados de pacotes de terceiros são deixados intactos. (v0.5.25)
Builds reproduzíveis (v0.5.25). A mesma entrada e configuração produzem os mesmos bytes de saída, para que quem receber um build possa reexecutá-lo e comparar com os digests em --build-report em vez de confiar neles. O escopo é deliberado: --numeric-obfuscation e a criptografia de strings AES extraem aleatoriedade nova por build e espera-se que difiram.
Proveniência de lançamento. pyobfus e pyobfus-mcp são publicados via PyPI Trusted Publishing com atestações PEP 740; veja docs/RELEASE_PROVENANCE_VERIFICATION.md para comandos de verificação e o snapshot atual.
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 modelo e parâmetros de injeção de dependência.
Matriz de suporte. O que é realmente verificado e por quê, em três rótulos honestos (testado / verificado uma vez / somente consultivo). Células que não podem apontar para um job de CI ou um registro datado são marcadas como somente consultivo em vez de assumidas. Veja docs/SUPPORT_MATRIX.md.
Cookbooks de compatibilidade. Combine pyobfus com pipelines de entrega reais: hook de import / arquivo criptografado (SOURCEdefender .pye), empacotamento compilado (Nuitka / Cython) e serviço de modelo ML. pyobfus --check também emite descobertas compatibility_advisory para esses casos. Veja docs/IMPORT_HOOK_COOKBOOK.md, docs/COMPILED_PACKAGING_COOKBOOK.md e docs/MODEL_SERVING_COOKBOOK.md. Para uma implantação endurecida em Python 3.14+ que usa proteção anti-debug, --check também sinaliza exposição de depuração remota PEP 768 (que deve ser desativada na inicialização do interpretador, não pelo ofuscador); veja docs/REMOTE_DEBUG_HARDENING.md.
--json global. Todo modo de CLI (obfuscate, --check, --unmap, --init) emite o mesmo esquema estruturado com um campo ai_hint, pronto para Claude Code, Cursor, Windsurf e servidores MCP consumirem.

Recursos

✅ Edição Gratuita

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

Ofuscação entre arquivos mantém símbolos renomeados consistentes em todos os arquivos de um projeto:
- Reescrita automática de declarações de import
- Atualizações de lista __all__ com nomes ofuscados
- Tabela de símbolos global com detecção de colisão
- Pipeline de ofuscação em duas fases (Scan → Transform)
- Modo de pré-visualização com flag --dry-run
Mangling de nomes renomeia variáveis, funções, classes e atributos de classe para nomes baseados em índice (I0, I1, I2...).
Remoção de comentários remove comentários e docstrings.
Codificação de strings envolve literais de string em Base64 e injeta o decodificador para você.
Ofuscação numérica / de constantes (--numeric-obfuscation) substitui literais inteiros e de ponto flutuante por expressões opacas que preservam valor (int → identidades XOR/add/sub, float → float.fromhex) para que as constantes originais não apareçam mais no código-fonte enviado.
Remoção de proveniência de IA (--strip-ai-artifacts) remove marcadores de geração por IA (ex.: Generated by Claude, Co-Authored-By: Claude) de docstrings e dunders de atribuição, para que código assistido por IA não seja enviado com impressões digitais de "isto foi gerado por IA".
Builds incrementais (--incremental) pulam um rebuild de diretório quando cada arquivo de entrada e a configuração estão inalterados desde o último build bem-sucedido (cache em <output>/.pyobfus-cache/), útil em pipelines de CI que armazenam artefatos em cache.
Preservação de parâmetros (--preserve-param-names) mantém nomes de parâmetros de função para que argumentos de palavra-chave ainda funcionem.
Projetos inteiros podem ser ofuscados em uma única execução, com relacionamentos de import preservados.
Filtragem de arquivos exclui arquivos por padrão glob (arquivos de teste, arquivos de configuração, etc.).
Um arquivo de configuração YAML torna os builds reproduzíveis.
Ofuscação seletiva preserva nomes específicos (builtins, métodos mágicos, exclusões personalizadas).
Predefinições: --preset safe | balanced | aggressive para compensações rápidas de força de ofuscação, além das 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.
Varredura de risco pré-voo (--check) detecta eval/exec, acesso dinâmico a atributos e pontos de reflexão de frameworks antes de você ofuscar; adicione --sarif PATH para exportar descobertas como SARIF 2.1.0 para GitHub Code Scanning.
Mapeamento reverso de stack trace (--unmap) reverte identificadores ofuscados em um stack trace de produção, para que você (ou um assistente de codificação de IA) possa depurar sem desofuscar o código enviado.
Proveniência de build (--provenance-manifest, v0.5.5+) escreve um manifesto JSON local de uma execução de ofuscação (hashes de arquivos de entrada/saída, hash de configuração, versão do pyobfus, commit git quando disponível, digest do mapeamento e relacionamentos de componentes compatíveis com CycloneDX) para proveniência de build offline. Sem chamadas de rede.
Validação de proveniência (--verify-provenance-manifest) verifica a forma do manifesto, os relacionamentos compatíveis com CycloneDX e o digest de integridade local; saída JSON está disponível para uso em CI/agente.
Plano estruturado de dry-run (--dry-run --json, v0.5.19+) emite um objeto plan versionado: configuração efetiva, arquivos selecionados/excluídos com motivos e artefatos marcados como ship / retain-internal / optional. Apenas rótulos relativos, somente pré-visualização (não aplicável).
Verificação de saída somente por sintaxe (--verify-syntax, v0.5.19+) compila Python gerado em memória após um build (sem import, sem execução, sem __pycache__) e relata syntax_valid em JSON. Uma falha bloqueia a entrega; não faz nenhuma afirmação sobre correção em tempo de execução.
Relatório de build verificável (--build-report, v0.5.24+) registra fatos JSON determinísticos e seguros para privacidade vinculando o modelo de seleção/configuração do dry-run a contadores reais de transformação, evidência de verificação, hashes de saída, papéis de artefatos, estado do marcador e proveniência.
Atestações de lançamento: um runbook da PyPI Integrity API / PEP 740 para verificar artefatos de lançamento do pyobfus e pyobfus-mcp.

🔒 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-Debugging
- Verificações de detecção de depurador 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 single-stepping independentemente da plataforma)
- Desligado por padrão para proteger a capacidade de depuração por IA; opt-in via --anti-debug
- Heurístico, não um limite 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 retorno, ramos falsos, predicados opacos, funções iscas
- CLI: --dead-code
Incorporação de Licença
- Incorporar datas de expiração: --expire 2025-12-31
- Vínculo de 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 de importar fora de uma lista de permissões de plataforma definida no tempo de 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 compõe; cada verificação é independente
Dados Criptografados Embutidos (v0.5.10)
- Criptografa um arquivo de recurso com AES-256-GCM em tempo de build e o embute codificado em base85 na saída. Isso elimina a lacuna do "Protect Data Files" do Nuitka Commercial / PyArmor --bind-data
- CLI: --embed-data path/to/resource.bin
- Gera um acessor get_embedded_data() que descriptografa na chamada, não na importação
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 de máquina
- --preset library - Para bibliotecas distribuíveis via pip
- --preset maximum - Segurança máxima 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 opcionais (modo arquivo único / --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 contagem 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). --expire-warn-days <N> adds an advisory pre-expiry warning to --expire-hard que permite que o artefato continue funcionando enquanto alerta o host. --bind-key-env <NAME> vincula a chave L3 ao material de chave que seu aplicativo fornece (um callback pyobfus_runtime.set_key_provider ou uma variável de ambiente base64) em vez de à impressão digital da máquina, para que um artefato funcione onde quer que seu próprio sistema de autorização libere a chave. A v0.5.4 estende --bind-device também para chaves do Runtime String Vault. Anteriormente, apenas a camada L3 da Opacidade Seletiva era bloqueada por dispositivo, então os segredos do vault eram descriptografados em qualquer máquina; agora cada chave do vault é rederivada de forma independente 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 de __code__).
Marca d'água forense. Derivação de chave determinística por comprador para rastreamento de pirataria.
Combinação de vínculo de licença. Vínculo de dispositivo / expiração / contagem de execuções integrado ao caminho de descriptografia AES-GCM (sem verificação de licença separada e corrigível).
@seal_code. Hash de integridade do 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); IDs de erro reversos 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.

Os artefatos gerados que usam esses recursos baseados em tempo de execução dependem do pacote pyobfus-runtime redistribuível separadamente, não do builder Pro completo. Instale pyobfus-runtime>=0.1,<1 ao lado do artefato protegido. As máquinas de build ainda exigem uma licença Pro válida; as máquinas de destino não precisam de chave de licença. O próprio pyobfus agora declara esse mesmo requisito, então uma máquina de build obtém o runtime com pip install --upgrade pyobfus, e um --provenance-manifest o registra como runtime_requirement sempre que um build precisar dele. O runtime foi publicado como 0.1.0 antes do lançamento do builder que emite seu namespace de importação. Os artefatos 0.5.x existentes continuam funcionando por meio de aliases de compatibilidade.

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

Consulte o guia de configuração de opacidade seletiva para obter o formato opacity.toml completo, regras de correspondência, precedência e limitações atuais da CLI.

Consulte CURRENT_PLAN_ZH.md para o plano de projeto atual e prioridades.

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)

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 Apache-2.0 legível, portanto é um controle de conveniência, não um limite de segurança, e nós o documentamos como tal em vez de alegar proteção que não pode oferecer. Consulte SECURITY.md. Observe que a Edição Comunitária não tem limites de arquivo ou linha 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 - importações 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 em um comando
🔄 Atualizações Vitalícias
💻 Até 3 dispositivos por licença
📧 Suporte Prioritário por E-mail

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

Métodos de pagamento: cartão de crédito/débito, Apple Pay e WeChat Pay (微信支付) para compradores na China, além das outras opções que o Stripe mostra para sua região no checkout.

Como Comprar

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

Compra rápida: 🚀 Comprar 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
- A chave de licença é entregue no seu e-mail em minutos
- Formato: PYOB-XXXX-XXXX-XXXX-XXXX
- Verifique a pasta 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: Para ativação de licença, cobrança ou dúvidas sobre a conta, envie um e-mail para zhurong0525@gmail.com com sua chave de licença. Para relatórios de bugs ou dúvidas de uso, abra uma issue no GitHub ou inicie uma discussão, para que a resposta fique disponível para a próxima pessoa que encontrar o mesmo problema.

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

# Machine-readable plan: effective config, included/excluded files, artifacts
pyobfus src/ -o dist/ --dry-run --json

# Write output, then compile every generated .py in memory (no import/execution)
pyobfus src/ -o dist/ --verify-syntax --json

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

Observação: Os nomes das 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 há erros no seu arquivo de configuração antes de usar:

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 pesquisa 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 de exclude_names

A opção exclude_names preserva nomes especificados para que não sejam 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:

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

Filtragem de Arquivos

Os padrões de exclusão suportam sintaxe glob:

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

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

Arquitetura

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

Parser: Analisa o código-fonte Python para AST
Analisador: Constrói tabela de símbolos com análise de escopo
Transformadores: Aplicam técnicas de ofuscação (mangling de nomes, codificação de strings, etc.)
Gerador: Gera 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. Consulte INTEGRATION_TESTING.md para detalhes.

Qualidade do 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 comercial Python.

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/APIs públicas onde argumentos de palavra-chave são usados pelos 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))
Trade-off: 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.
Importações entre arquivos: resolvido na v0.2.0 com suporte completo de ofuscação entre arquivos.
eval() e exec() sobre código ofuscado podem precisar de ajustes.
Código ofuscado é mais difícil de depurar (por design; --unmap existe exatamente para esse motivo).
Algumas técnicas custam desempenho em tempo de execução; o FAQ abaixo tem os números.

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

Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, incluindo builds 3.14 com free-threading (python3.14t, verificado: suíte de testes completa + um ciclo real de ofuscar→executar→descriptografar com seal/scrub-traceback)
Esquema de nomenclatura baseado em índice (I0, I1, I2...).
Pipeline de transformadores modular com ofuscação entre arquivos em duas fases.
Mais de 1.000 testes, 90% de cobertura, CI multi-OS (Python 3.9-3.14 × Ubuntu / macOS / Windows).

Perguntas Frequentes

O pyobfus é Adequado para Mim?

Use o pyobfus se você:

Precisa proteger algoritmos proprietários antes de distribuir aplicações Python
Quer uma ferramenta que "simplesmente funciona" sem conflitos de DLL ou dependências nativas
Prefere preços transparentes sem limitações ocultas de avaliação
Apoia 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

# Preview a structured, non-applicable protection plan for an AI/CI consumer
pyobfus src/ -o dist/ --dry-run --json

--verify-syntax é uma verificação opcional pós-build: ela compila o código Python gerado em memória, não cria __pycache__, e reporta syntax_valid em JSON. Ela não importa nem executa o projeto e não é uma garantia de compatibilidade em tempo de execução.

Como ofuscar Python antes de vender ou entregar?

Execute pyobfus --check primeiro, compile em um diretório de saída separado e mantenha o mapping.json opcional fora do artefato do cliente. Envie a árvore transformada e então execute seus testes normais ou etapa de empacotamento contra essa saída exata. Os cookbooks de PyInstaller, empacotamento-compilado e import-hook cobrem formatos de entrega comuns.

Como depurar um crash ofuscado com um assistente de IA?

Compile com --save-mapping mapping.json. Quando um traceback de produção chegar, execute pyobfus --unmap --trace error.log --mapping mapping.json; os identificadores restaurados podem então ser lidos por você, Claude Code, Cursor, Copilot ou outro assistente de IA sem entregar ao cliente seu arquivo de mapeamento privado.

Existe um servidor MCP para ofuscação de Python?

Sim. uvx pyobfus-mcp expõe oito ferramentas locais para varredura de risco, geração de configuração, proteção de projeto, verificação, orientação de presets e mapeamento de traceback. Os caminhos de origem são validados localmente e o pyobfus não envia código do projeto nem exige chave de API.

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 framework, e sua matriz de compatibilidade é coberta por testes automatizados. A ofuscação ainda é uma transformação de fonte: execute sua própria suíte de testes e verifique o artefato compilado, 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 templates integrados:

# Django
pyobfus --init-config django

# Flask
pyobfus --init-config flask

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

Quais versões de Python são suportadas?

O pyobfus suporta Python 3.9 até 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, pagamento único)	$89 (Pro, pagamento único)
Tamanho do projeto no plano gratuito	Sem limites de arquivo ou linhas	Trial limitado a cerca de 935-940 linhas/arquivo (medido em 2026-05-09)
Código aberto	Sim (Core: Apache 2.0, Pro: Proprietário)	Não
Dependências nativas	Nenhuma (saída Python pura)	Requer biblioteca de runtime
Suporte a Python 3.9-3.14	Sim	Sim

Escolha o pyobfus se: Você quer preço transparente, confiança de código aberto e implantação mais simples sem dependências nativas.

Veja a visão geral de comparação, ou vá direto ao que você procura: PyArmor, Nuitka, Cython, PyLocket, Oxyry, ofuscadores baseados em navegador.

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 (todo módulo recebe mangling de AST + mapeamento para compatibilidade de depuração com IA) e então 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 e depois empacote a saída ofuscada com o PyInstaller gratuito. As duas ferramentas resolvem problemas diferentes (mangling de nomes vs. empacotar um interpretador Python em um arquivo) e se compõem de forma limpa; veja o Cookbook do PyInstaller para um exemplo completo, incluindo 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 mudanças antes de gravar arquivos
Use --preserve-param-names se você depende de argumentos nomeados
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 da fonte emitida 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 reversão confiável. Para proteção mais forte, use recursos Pro:

Criptografia AES-256 para strings
Verificações anti-debugging 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 no lado do cliente (incluindo PyArmor, Nuitka, etc.) - segurança criptográfica real exigiria descriptografia no servidor, o que é impraticável para a maioria dos casos de uso.

O que a criptografia de strings FORNECE:

✅ Impede buscas casuais de strings ou grep de revelar texto sensível
✅ Aumenta o esforço necessário para engenharia reversa
✅ Dissuade 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)
❌ 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 de AST	Arquivos `.py` (Python puro)
Cython	Compilar para C	`.so`/`.pyd` (específico da plataforma)
Nuitka	Compilar para executável	Binário (específico da plataforma)

Escolha o pyobfus se: Você precisa de arquivos .py multiplataforma sem custo 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 desenvolvimento
Guia de Contribuição - Como contribuir com código e documentação
Plano Atual - Status atual do projeto e prioridades
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 reportar vulnerabilidades de segurança

Legal e Licença

Modelo de Licença Dupla (veja LICENSE-NOTICE.md):
- pyobfus (Core): Apache 2.0 - Gratuito e de código aberto
- pyobfus_pro (Pro): Proprietário - Requer licença paga
Design piloto de afiliados - Apenas design aprovado; o programa não foi lançado e não tem inscrição pública

Apoie o Projeto

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

Buy Me A Coffee

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, cite o lançamento arquivado. O DOI conceitual abaixo sempre resolve para a versão mais recente:

APA

Zhu, R. (2026). pyobfus: Um ofuscador Python baseado em AST com mapeamento reverso de stack-trace para desenvolvimento assistido por IA. 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}
}

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

Agradecimentos

Inspirado pela abordagem baseada em AST do Opy
Implementação em clean room - 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 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 de exclude_names

Filtragem de Arquivos

Arquitetura

Desenvolvimento

Configuração

Testes

Qualidade do 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?

Como ofuscar Python antes de vender ou entregar?

Como depurar um crash ofuscado com um assistente de IA?

Existe um servidor MCP para ofuscação de 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 de 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`