pyobfus-mcp
Servidor MCP oficial para el ofuscador de Python pyobfus: escaneo de riesgos previo, inicialización de configuración con detección de frameworks y mapeo inverso de trazas de pila.
Documentación
pyobfus: el ofuscador de Python
pyobfus (pronunciado como "ofuscador de Python") es un moderno ofuscador de Python / ofuscador de código basado en AST, para desarrolladores que necesitan ofuscar antes de publicar mientras mantienen los fallos diagnosticables. Presets conscientes del framework, mapeo inverso de stack traces y una CLI JSON legible por máquina permiten que Claude Code, Cursor, GitHub Copilot, Codex, CodeBuddy y cualquier agente de IA compatible con MCP ayuden a depurar stack traces ofuscados. Una alternativa transparente y de código abierto a PyArmor.
Un ofuscador de código Python construido con transformaciones basadas en AST. Compatible con Python 3.9 hasta 3.14. Proporciona alteración confiable de nombres, codificación de cadenas, aplanamiento de flujo de control, cifrado de cadenas AES-256 y, exclusivo de pyobfus, un flujo de trabajo de mapeo inverso que te permite a ti (o a tu asistente de IA) depurar stack traces ofuscados sin renunciar a la protección.
🔒 Edición Pro disponible. Seis mecanismos de protección dirigidos por patentes (Opacidad Selectiva, marca de agua forense, Bóveda de Cadenas en Tiempo de Ejecución y más) superpuestos al ofuscador AST gratuito. $45 de pago único, sin suscripción. Consulta Edición Pro a continuación.
🔎 Novedades en v0.5.30: Las compilaciones Pro ahora pueden advertir antes de una expiración estricta sin detener el artefacto (
--expire-warn-days N), y las claves L3 de Opacidad Selectiva pueden provenir de un proveedor controlado por la aplicación o de una variable de entorno base64 (--bind-key-env NAME). Eso permite que un artefacto protegido se ejecute en cualquier máquina que tu aplicación autorice, sin incrustar la clave sin procesar ni recompilar por separado para cada dispositivo. Consultapyobfus --helppara las reglas de compatibilidad.
🔔 Marcar este repositorio con estrella no te notifica sobre nuevos lanzamientos. GitHub solo envía notificaciones de lanzamiento a quienes explícitamente lo Observan. Haz clic en Observar → Personalizado → Lanzamientos (parte superior de esta página) para recibir un aviso en el momento en que se publique una nueva versión, sin el ruido de cada commit/issue.
🔌 Servidor MCP complementario: pyobfus-mcp
Este repositorio incluye dos paquetes instalables:
| Paquete | Qué es | Instalación |
|---|---|---|
pyobfus | El ofuscador de Python (CLI + biblioteca). | pip install pyobfus |
pyobfus-mcp | Un servidor de Protocolo de Contexto de Modelo (MCP) que expone las herramientas de pyobfus a agentes de IA. | uvx pyobfus-mcp (sin instalación) o pip install pyobfus-mcp |
El servidor MCP vive en pyobfus_mcp/ y está construido sobre el SDK oficial de Python del Protocolo de Contexto de Modelo (FastMCP). Registra ocho herramientas MCP para que Claude Desktop, Claude Code, Cursor, Windsurf, Zed y Codex puedan llamar a pyobfus directamente desde conversaciones de agentes, sin necesidad de shell:
| Herramienta MCP | Implementación | Propósito |
|---|---|---|
protect_project | pyobfus_mcp/tools.py | Canalización de una llamada y autoverificación: escaneo → preset → ofuscación → compilación de bytes + prueba de importación del resultado → devuelve verified: true/false. El agente informa una marca verde en lugar de esperar que la transformación no haya roto nada |
check_obfuscation_risks | pyobfus_mcp/tools.py | Escaneo de riesgos previo al vuelo; pasa verify_dependencies_online=true para verificar los nombres de paquetes declarados contra PyPI público. |
generate_pyobfus_config | pyobfus_mcp/tools.py | Detección automática de framework → escribe un pyobfus.yaml funcional |
unmap_stack_trace | pyobfus_mcp/tools.py | Invierte identificadores ofuscados en un stack trace de producción |
list_presets | pyobfus_mcp/tools.py | Enumera presets de comunidad / framework / Pro |
explain_preset | pyobfus_mcp/tools.py | Describe qué cambia un preset con nombre |
recommend_tier | pyobfus_mcp/tools.py | Analiza un proyecto y recomienda nivel comunidad vs Pro, con razonamiento |
start_pro_trial | pyobfus_mcp/tools.py | Devuelve orientación estructurada para iniciar la prueba Pro de 5 días |
El servidor está registrado en el Registro MCP oficial bajo io.github.zhurong2020/pyobfus-mcp. El transporte es stdio. Consulta pyobfus_mcp/README.md para fragmentos de configuración por cliente.
🧩 Habilidad / plugin de Claude Code
Este repositorio también es un marketplace de plugins de Claude Code, que incluye dos habilidades divididas según si cambian algo:
| Habilidad | Qué hace | ¿Escribe? |
|---|---|---|
pyobfus-protect | El flujo de trabajo completo de "proteger Python antes de publicar: ofuscar y verificar que aún se ejecuta" (primero MCP, CLI como respaldo) | Sí, produce una compilación |
pyobfus-review | Responde la pregunta que viene primero: ¿es seguro ofuscar este proyecto, qué se rompería y qué artefactos emitiría una compilación? --check consciente de configuración más --dry-run, nada más | No, solo lectura |
Ambas siguen el formato SKILL.md de agentskills.io, por lo que también funcionan en el modo agente de GitHub Copilot, Cursor y Codex CLI, que leen habilidades desde .github/skills/ en tu propio repositorio.
/plugin marketplace add zhurong2020/pyobfus
/plugin install pyobfus@pyobfus
Consulta skills/ para ambas habilidades y detalles de instalación. (Esto es distinto de templates/ai-integration/, que son archivos de reglas copiados para tu proyecto).
🧑💻 Extensión de VS Code
pyobfus también está en el Mercado de VS Code y Open VSX (editor zhurong2020, misma versión en ambos; Open VSX cubre VSCodium, Gitpod, Eclipse Theia y code-server). Es la primera extensión centrada en ofuscación en esta categoría, ya que ningún competidor (PyArmor, Nuitka, Sourcedefender) tiene una. Diagnósticos en línea de riesgo de ofuscación (hallazgos pyobfus --check renderizados mediante la API nativa DiagnosticCollection de VS Code: subrayados + panel de Problemas, sin linter separado que configurar), un comando "Invertir Stack Trace", un elemento de barra de estado que muestra tu nivel actual con un menú de un clic (Verificar Espacio de Trabajo / Generar Configuración / Iniciar Prueba / Desbloquear Pro), un comando "Generar pyobfus.yaml" y clic derecho "Ofuscar con pyobfus" desde el Explorador o el editor. Fuente y justificación de diseño en vscode-extension/ y docs/VSCODE_EXTENSION_PLAN.md.
🤖 Funciones nativas de IA
pyobfus --check src/ejecuta un análisis de riesgo previo al vuelo consciente de la configuración. Detectaeval/exec, acceso dinámico a atributos, puntos de reflexión del framework y dependencias declaradas que no existen en PyPI público antes de ofuscar. Respeta la misma configuración explícita/descubierta y los mismos ajustes preestablecidos que una compilación; los hallazgos de archivos excluidos se informan por separado sin afectar el resultado principal. Use--no-configpara el análisis sin filtrar heredado y--offlinepara omitir las búsquedas en PyPI. El JSON incluyeeffective_config,excluded_findingsy unai_hintque le indica a su asistente de IA qué ejecutar a continuación. Agregue--sarif pyobfus.sarifpara también emitir un informe SARIF 2.1.0 para GitHub Code Scanning (consultedocs/SARIF_CODE_SCANNING.md).uses: zhurong2020/pyobfus-action@v1ejecuta el análisis previo al vuelo o una compilación ofuscada en GitHub Actions, con SARIF conectado a Code Scanning y una tabla de hallazgos en el resumen del trabajo. Separa los hallazgos de los errores de herramientas, por lo quefail-on: neverpermite que una carga de SARIF se ejecute primero sin que la solución alternativa de|| truese trague una ruta mal escrita. Repositorio: zhurong2020/pyobfus-action · Marketplace.pyobfus --init src/es la incorporación sin configuración: escanea el proyecto, detecta FastAPI/Django/Pydantic/Click/SQLAlchemy y escribe unpyobfus.yamllisto para usar.pyobfus --unmap --trace error.log --mapping mapping.jsonrevierte los identificadores ofuscados en un seguimiento de pila de producción para que pueda depurar (o entregar el seguimiento a un asistente de IA) sin revertir la ofuscación en sí.pyobfus … --save-mapping mapping.json --trace-markersella cada archivo ofuscado con un encabezado# pyobfus:obfuscated(id + nombre del archivo de mapeo + el comando exacto de--unmap) para que un agente de IA que aterrice en un archivo ofuscado desde un traceback sepa inmediatamente que es salida de pyobfus y cómo revertir los nombres.pyobfus … --no-community-markerdesactiva el marcador# pyobfus:generatedversionado con el que normalmente se abren los archivos generados. El marcador nombra la versión de la herramienta, la edición y la ruta de origen relativa al proyecto, de modo que cualquiera (o cualquier agente) que abra el archivo sepa que es salida generada y no algo para editar. Nunca contiene una ruta absoluta, id de comprador, clave de licencia o hash. Es atribución transparente (un comentario simple que puede eliminar), no una verificación de licencia ni una medida antipiratería, y suprimirlo es una función de nivel gratuito, no de pago. Distinto de--trace-marker, que trata sobre revertir tracebacks.pyobfus … --provenance-manifest provenance.jsonescribe un manifiesto JSON local (hashes de entrada/salida, hash de configuración, versión de pyobfus, commit de git cuando esté disponible, resumen del mapeo, relaciones de componentes compatibles con CycloneDX y un resumen de integridad de autoconsistencia, no una firma criptográfica) para la procedencia de compilación sin conexión. Consultedocs/PROVENANCE_MANIFEST.md.pyobfus --verify-provenance-manifest provenance.json --jsonvalida la estructura del manifiesto, las relaciones compatibles con CycloneDX y el resumen de integridad local antes de archivarlo o enviarlo.pyobfus … --dry-run --jsonprevisualiza un objetoplanversionado antes de que se escriba nada: la configuración efectiva, qué archivos se seleccionan o excluyen (y por qué) y los artefactos que produciría una compilación, cada uno etiquetado comoship/retain-internal/optional. Solo etiquetas relativas (sin fuente, secretos ni rutas absolutas); es una vista previa, no un archivo de aplicación guardado.pyobfus … --verify-syntaxes una verificación posterior a la compilación opcional: compila cada.pygenerado en memoria (sin importación, sin ejecución, sin__pycache__) e informasyntax_validen JSON. Un fallo bloquea la entrega; no hace ninguna afirmación sobre la corrección en tiempo de ejecución.pyobfus … --build-report build-report.jsonescribe un modelo de hechos determinista y seguro para la privacidad después de una compilación exitosa: selección/configuración, contadores de transformación y caché, evidencia de verificación, hashes de salida, roles de artefactos, estado del marcador y vínculo de procedencia. Consultedocs/VERIFIABLE_BUILD_REPORT.md.- Paquetes que reexportan. Un
__init__.pyque reexporta (from .core import run, conrunen__all__) conserva el nombre que se le dio a su definición, por lo que el paquete generado sigue siendo importable yfrom pkg import *sigue funcionando. Los nombres reexportados de paquetes de terceros se dejan intactos. (v0.5.25) - Compilaciones reproducibles (v0.5.25). La misma entrada y configuración producen los mismos bytes de salida, de modo que quien reciba una compilación pueda volver a ejecutarla y compararla con los resúmenes en
--build-reporten lugar de confiar en ellos. El alcance es deliberado:--numeric-obfuscationy el cifrado de cadenas AES extraen aleatoriedad nueva por compilación y se espera que difieran. - Procedencia de lanzamiento. pyobfus y pyobfus-mcp se publican a través de PyPI Trusted Publishing con atestaciones PEP 740; consulte
docs/RELEASE_PROVENANCE_VERIFICATION.mdpara ver los comandos de verificación y la instantánea actual. - Ajustes preestablecidos conscientes del framework.
--preset fastapi | django | flask | pydantic | click | sqlalchemy | mlcon exclusiones integradas para métodos de despacho, decoradores, campos ORM, migraciones, envoltorios de servicio de modelos y parámetros de inyección de dependencias. - Matriz de soporte. Lo que realmente se verifica y con qué, en tres etiquetas honestas (probado / verificado una vez / solo asesoramiento). Las celdas que no pueden apuntar a un trabajo de CI o un registro fechado se marcan como solo asesoramiento en lugar de asumirse. Consulte
docs/SUPPORT_MATRIX.md. - Libros de recetas de compatibilidad. Combine pyobfus con canalizaciones de entrega reales: hook de importación / archivo cifrado (SOURCEdefender
.pye), empaquetado compilado (Nuitka / Cython) y servicio de modelos de ML.pyobfus --checktambién emite hallazgos decompatibility_advisorypara estos. Consultedocs/IMPORT_HOOK_COOKBOOK.md,docs/COMPILED_PACKAGING_COOKBOOK.mdydocs/MODEL_SERVING_COOKBOOK.md. Para un despliegue endurecido de Python 3.14+ que use protección antidebug,--checktambién marca la exposición de depuración remota PEP 768 (que debe deshabilitarse al inicio del intérprete, no por el ofuscador); consultedocs/REMOTE_DEBUG_HARDENING.md. --jsonglobal. Cada modo CLI (obfuscate,--check,--unmap,--init) emite el mismo esquema estructurado con un campoai_hint, listo para que lo consuman Claude Code, Cursor, Windsurf y servidores MCP.
Características
✅ Edición gratuita
Las siguientes características están completamente implementadas y disponibles en la versión actual:
-
La ofuscación entre archivos mantiene los símbolos renombrados consistentes en todos los archivos de un proyecto:
- Reescritura automática de declaraciones de importación
- Actualizaciones de la lista
__all__con nombres ofuscados - Tabla de símbolos global con detección de colisiones
- Canalización de ofuscación en dos fases (Escaneo → Transformación)
- Modo de vista previa con la bandera
--dry-run
-
La alteración de nombres renombra variables, funciones, clases y atributos de clase a nombres basados en índices (I0, I1, I2...).
-
La eliminación de comentarios elimina comentarios y docstrings.
-
La codificación de cadenas envuelve los literales de cadena en Base64 e inyecta el decodificador por usted.
-
La ofuscación numérica / de constantes (
--numeric-obfuscation) reemplaza los literales de enteros y flotantes con expresiones opacas que preservan el valor (int → identidades XOR/suma/resta, float →float.fromhex) para que las constantes originales ya no aparezcan en el código fuente enviado. -
La eliminación de procedencia de IA (
--strip-ai-artifacts) elimina los marcadores de generación de IA (p. ej.,Generated by Claude,Co-Authored-By: Claude) de docstrings y dunders de atribución, para que el código asistido por IA no se envíe con huellas de "esto fue generado por IA". -
Las compilaciones incrementales (
--incremental) omiten una reconstrucción de directorio cuando cada archivo de entrada y la configuración no han cambiado desde la última compilación exitosa (caché en<output>/.pyobfus-cache/), útil en canalizaciones de CI que almacenan en caché artefactos. -
La preservación de parámetros (
--preserve-param-names) mantiene los nombres de los parámetros de función para que los argumentos de palabra clave sigan funcionando. -
Proyectos completos se pueden ofuscar en una sola ejecución, con las relaciones de importación preservadas.
-
El filtrado de archivos excluye archivos por patrón glob (archivos de prueba, archivos de configuración, etc.).
-
Un archivo de configuración YAML hace que las compilaciones sean repetibles.
-
La ofuscación selectiva preserva nombres específicos (builtins, métodos mágicos, exclusiones personalizadas).
-
Ajustes preestablecidos:
--preset safe | balanced | aggressivepara compensaciones rápidas de fuerza de ofuscación, además de los conscientes del framework (--preset fastapi | django | flask | pydantic | click | sqlalchemy | ml) con exclusiones integradas para métodos de despacho, decoradores, campos ORM, migraciones y parámetros de inyección de dependencias.--list-presetslos muestra todos. -
Escaneo de riesgo previo al vuelo (
--check) detectaeval/exec, acceso dinámico a atributos y puntos de reflexión del framework antes de ofuscar; agregue--sarif PATHpara exportar hallazgos como SARIF 2.1.0 para GitHub Code Scanning. -
Mapeo inverso de seguimiento de pila (
--unmap) revierte los identificadores ofuscados en un seguimiento de pila de producción, para que usted (o un asistente de codificación de IA) pueda depurar sin desofuscar el código enviado. -
Procedencia de compilación (
--provenance-manifest, v0.5.5+) escribe un manifiesto JSON local de una ejecución de ofuscación (hashes de archivos de entrada/salida, hash de configuración, versión de pyobfus, commit de git cuando esté disponible, resumen del mapeo y relaciones de componentes compatibles con CycloneDX) para la procedencia de compilación sin conexión. Sin llamadas de red. -
Validación de procedencia (
--verify-provenance-manifest) verifica la forma del manifiesto, las relaciones compatibles con CycloneDX y el resumen de integridad local; la salida JSON está disponible para uso de CI/agente. -
Plan de ejecución en seco estructurado (
--dry-run --json, v0.5.19+) emite un objetoplanversionado: configuración efectiva, archivos seleccionados/excluidos con razones y artefactos etiquetados comoship/retain-internal/optional. Solo etiquetas relativas, solo vista previa (no aplicable). -
Verificación de salida solo de sintaxis (
--verify-syntax, v0.5.19+) compila el Python generado en memoria después de una compilación (sin importación, sin ejecución, sin__pycache__) e informasyntax_validen JSON. Un fallo bloquea la entrega; no hace ninguna afirmación sobre la corrección en tiempo de ejecución. -
Informe de compilación verificable (
--build-report, v0.5.24+) registra hechos JSON deterministas y seguros para la privacidad que vinculan el modelo de selección/configuración de la ejecución en seco con contadores de transformación reales, evidencia de verificación, hashes de salida, roles de artefactos, estado del marcador y procedencia. -
Atestaciones de lanzamiento: un libro de ejecución de PyPI Integrity API / PEP 740 para verificar los artefactos de lanzamiento de pyobfus y pyobfus-mcp.
🔒 Edición Pro
Las siguientes características avanzadas están disponibles con una licencia Pro:
-
Cifrado de cadenas
- Cifrado AES-256 para cadenas
- Descifrado en tiempo de ejecución con decodificador inyectado
- Generación automática de claves
-
Antidepuración
- Verificaciones de detección de depuradores inyectadas en funciones
- Cuatro métodos de detección (v0.5.11):
sys.gettrace()(trazadores/depuradores a nivel de Python), TracerPid a través de/proc/self/status(depuradores nativos en Linux: gdb, strace), WinAPIIsDebuggerPresent()(depuradores nativos en Windows) y una verificación de desviación de tiempo (detecta el paso a paso independientemente de la plataforma) - DESACTIVADO de forma predeterminada para proteger la depurabilidad de IA; opt-in a través de
--anti-debug - Heurístico, no un límite de seguridad; documentado en el CHANGELOG
-
Aplanamiento del flujo de control
- Transformación de máquina de estados para if/else/elif
- Aplanamiento de bucles for/while
- Soporte de estructuras anidadas
- CLI:
--control-flow
-
Inyección de código muerto
- Inserción de rutas de código inalcanzables
- Cuatro estrategias: después del retorno, ramas falsas, predicados opacos, funciones señuelo
- CLI:
--dead-code
-
Incrustación de licencias
- Incrustar fechas de caducidad:
--expire 2025-12-31 - Vinculación de máquina:
--bind-machine - Límites de recuento de ejecuciones:
--max-runs 100 - Verificación sin conexión: sin dependencias externas
- Incrustar fechas de caducidad:
-
Política de tiempo de ejecución (v0.5.9)
- Rechazar la importación fuera de una lista de permitidos de plataforma en tiempo de compilación, una generalización de Python puro de las restricciones de plataforma de PyArmor BCC
- Lista de permitidos de SO:
--requires-os Linux,Darwin - Versión mínima de Python:
--requires-python-min 3.10 - Lista de permitidos de arquitectura de CPU:
--requires-arch x86_64,arm64 - Cualquier combinación se compone; cada verificación es independiente
-
Datos cifrados integrados (v0.5.10)
- Cifra un archivo de recursos con AES-256-GCM en tiempo de compilación y lo integra codificado en base85 en la salida. Esto cubre la brecha de "Proteger archivos de datos" de Nuitka Commercial / PyArmor
--bind-data - CLI:
--embed-data path/to/resource.bin - Genera un accessor
get_embedded_data()que descifra al llamarse, no al importarse
- Cifra un archivo de recursos con AES-256-GCM en tiempo de compilación y lo integra codificado en base85 en la salida. Esto cubre la brecha de "Proteger archivos de datos" de Nuitka Commercial / PyArmor
-
Ajustes preestablecidos de configuración
--preset trial- Versión con límite de tiempo de 30 días--preset commercial- Protección máxima con vinculación a máquina--preset library- Para librerías distribuibles por pip--preset maximum- Seguridad máxima con todas las protecciones--list-presets- Ver todos los ajustes preestablecidos
Mecanismos dirigidos por patente (CN 202610712171X, introducidos en v0.5.0)
Seis mecanismos, disponibles tanto como API pyobfus_pro y, a partir de v0.5.1,
como indicadores de compilación pyobfus opcionales (modo de archivo único / --no-cross-file):
--selective-opacity, --seal-code, --vault, --scrub-traceback,
--fingerprint <buyer-id>, --expire-hard <date>. v0.5.3 añade
--period <N> (límite de contador de ejecuciones), --opacity-config <opacity.toml>
(cifrado L3 dirigido por patrones según el qualname original) y --bind-device /
--bind-device-id <id> (cifrado L3 bloqueado por dispositivo). --expire-warn-days <N> adds an advisory pre-expiry warning to --expire-hard que permite que el
artefacto siga ejecutándose mientras alerta al host. --bind-key-env <NAME> vincula
la clave L3 al material clave que tu aplicación proporciona (una
retrollamada pyobfus_runtime.set_key_provider o una variable de entorno base64) en lugar de
la huella de la máquina, de modo que un artefacto se ejecuta dondequiera que tu
propio sistema de autorización libere la clave. v0.5.4 extiende
--bind-device también a las claves de la Bóveda de Cadenas en Tiempo de Ejecución. Anteriormente solo
la capa L3 de Opacidad Selectiva estaba bloqueada por dispositivo, por lo que los secretos de la bóveda se descifraban en
cualquier máquina; ahora cada clave de la bóveda se vuelve a derivar de forma independiente en tiempo de ejecución a partir del
dispositivo vinculado.
- Opacidad Selectiva. Capas de protección por símbolo (transparente / legible por IA / ofuscado / cifrado AES-256-GCM con materialización perezosa
__code__). - Marca de agua forense. Derivación de clave determinista por comprador para el rastreo de piratería.
- Combinación de vinculación de licencia. Vinculación de dispositivo / caducidad / contador de ejecuciones integrada en la ruta de descifrado AES-GCM (sin comprobación de licencia parcheable separada).
@seal_code. Hash de integridad del bytecode en tiempo de compilación; detección de parches en memoria en tiempo de ejecución.--scrub-traceback. Cifrado de trazas de producción (RSA-2048 + AES-256-GCM); IDs de error inversos con la nueva CLIpyobfus-unscrub.- Bóveda de Cadenas en Tiempo de Ejecución. Espacio de nombres KV cifrado para secretos en tiempo de ejecución con descifrado perezoso por entrada.
Los artefactos generados que usan estas funciones respaldadas por tiempo de ejecución dependen del
paquete pyobfus-runtime redistribuible por separado, no del compilador Pro completo. Instala pyobfus-runtime>=0.1,<1 junto al artefacto protegido. Las máquinas de compilación
siguen requiriendo una licencia Pro válida; las máquinas de destino no necesitan clave
de licencia. pyobfus ahora declara ese mismo requisito, por lo que una máquina de compilación
obtiene el tiempo de ejecución con pip install --upgrade pyobfus, y un
--provenance-manifest lo registra como runtime_requirement siempre que una compilación
lo necesite. El tiempo de ejecución se publicó como 0.1.0 antes de la versión del compilador que
emite su espacio de nombres de importación. Los artefactos 0.5.x existentes siguen funcionando mediante
alias de compatibilidad.
Requiere Python ≥ 3.9 a partir de v0.5.0 (se eliminó 3.8, fin de soporte 2024-10).
Consulta la guía de configuración de opacidad selectiva
para conocer el formato completo opacity.toml, las reglas de coincidencia, la precedencia y las
limitaciones actuales de la CLI.
Consulta CURRENT_PLAN_ZH.md para conocer el plan y las prioridades actuales del proyecto.
Prueba las funciones Pro GRATIS
Prueba todas las funciones Pro durante 5 días: ¡sin registro ni tarjeta 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
Qué incluye la prueba:
- Aplanamiento del flujo de control (
--control-flow) - Cifrado de cadenas AES-256 (
--string-encryption) - Protección anti-depuración (
--anti-debug) - Inyección de código muerto (
--dead-code) - Incrustación de licencia (
--expire,--bind-machine,--max-runs) - Ajustes preestablecidos de configuración (
--preset trial/commercial/library/maximum)
Después de la prueba, compra una licencia para seguir usando las funciones Pro.
La prueba se basa en el sistema de honor. Almacena su estado en un archivo sin firmar en tu directorio personal, y
pyobfus/trial.pyes código fuente Apache-2.0 legible, por lo que es un control de conveniencia, no un límite de seguridad, y lo documentamos como tal en lugar de afirmar una protección que no puede ofrecer. Consulta SECURITY.md. Ten en cuenta que la Edición Comunitaria no tiene límites de archivos ni de líneas y no necesita ninguna prueba; la prueba solo limita los mecanismos Pro.
Compra la Edición Profesional
Características de la Edición Pro:
- 🔀 Aplanamiento del flujo de control
- 🧩 Inyección de código muerto
- 🔐 Cifrado de cadenas AES-256
- 📦 Ofuscación de importaciones: importaciones
importliben tiempo de ejecución con cadenas de importación cifradas - 🛡️ Comprobaciones anti-depuración
- 📅 Incrustación de licencia: caducidad, vinculación a máquina, límites de ejecución
- ⚡ Ajustes preestablecidos de configuración: configuración con un solo comando
- 🔄 Actualizaciones de por vida
- 💻 Hasta 3 dispositivos por licencia
- 📧 Soporte prioritario por correo electrónico
Precio: $45.00 USD (pago único)
Métodos de pago: tarjeta de crédito/débito, Apple Pay y WeChat Pay (微信支付) para compradores en China, además de las otras opciones que Stripe muestra para tu región al finalizar la compra.
Cómo comprar
Visita nuestra página de compra: zhurong2020.github.io/pyobfus para obtener información detallada y pago seguro.
Compra rápida: 🚀 Comprar ahora - Enlace de pago directo (entrega instantánea • garantía de devolución de 30 días)
Proceso de compra en 3 pasos:
-
Completa el pago seguro (Stripe)
- Haz clic en el enlace de compra anterior o visita la página de compra
- Introduce tu correo electrónico (para la entrega de la licencia)
- Completa el pago de forma segura a través de Stripe
-
Recibe la clave de licencia
- La clave de licencia se envía a tu correo electrónico en minutos
- Formato:
PYOB-XXXX-XXXX-XXXX-XXXX - Revisa la carpeta de spam/no deseado si no está en la bandeja de entrada
-
Activa la licencia
pip install --upgrade pyobfus pyobfus-license register PYOB-XXXX-XXXX-XXXX-XXXX pyobfus-license status -
Empieza a usar las funciones 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
Soporte: Para activación de licencia, facturación o preguntas sobre la cuenta, envía un correo a zhurong0525@gmail.com con tu clave de licencia. Para informes de errores o preguntas de uso, abre un problema en GitHub o inicia una discusión, para que la respuesta esté disponible para la próxima persona que encuentre lo mismo.
Legal y políticas
Al comprar pyobfus Edición Profesional, aceptas nuestros:
- Términos de servicio y EULA - Acuerdo de licencia y términos de uso
- Política de reembolso - Garantía de devolución de 30 días, sin preguntas
- Política de privacidad - Cumple con el RGPD, protegemos tus datos
Inicio rápido
Instalación
Desde PyPI (recomendado):
pip install pyobfus
Desde el código fuente (para desarrollo):
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
Ejemplo
Antes de la ofuscación:
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}")
Después de la ofuscación:
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: Los nombres de variables (I0, I1, etc.) pueden variar ligeramente según la estructura del código, pero la funcionalidad se conserva.
Configuración
Inicio rápido con plantillas
Genera una plantilla de configuración para tu tipo de proyecto:
# 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
Esto crea un archivo pyobfus.yaml con valores predeterminados adecuados para tu tipo de proyecto.
Validar configuración
Comprueba si tu archivo de configuración tiene errores antes de usarlo:
pyobfus --validate-config pyobfus.yaml
El validador comprueba:
- Errores de sintaxis YAML
- Opciones de configuración no válidas
- Errores tipográficos comunes (p. ej.,
exclude_pattern->exclude_patterns) - Funciones Pro usadas con nivel comunitario
Detección automática
Cuando ejecutas pyobfus sin -c, busca automáticamente:
pyobfus.yamlpyobfus.yml.pyobfus.yaml.pyobfus.yml
Configuración manual
Crea pyobfus.yaml:
obfuscation:
level: community
exclude_patterns:
- "test_*.py"
- "**/tests/**"
- "__init__.py"
exclude_names:
- "logger"
- "config"
- "main"
remove_docstrings: true
remove_comments: true
Comportamiento de exclude_names
La opción exclude_names conserva los nombres especificados para que no se renombren durante la ofuscación:
obfuscation:
exclude_names:
- MyPublicClass # Name preserved, but strings inside are still encoded
- exported_function # Name preserved for external callers
Importante: exclude_names solo afecta a la ofuscación de nombres, no a la codificación de cadenas:
# 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:
- Conservar nombres para API públicas que el código externo importa
- Mantener nombres de clases/funciones para depuración mientras se sigue protegiendo el contenido de las cadenas
- Mantener la compatibilidad con marcos externos que esperan nombres específicos
Filtrado de archivos
Los patrones de exclusión admiten sintaxis glob:
test_*.py- Excluir archivos que empiezan por "test_"**/tests/**- Excluir todos los archivos en directorios "tests"**/__init__.py- Excluir todos los archivos__init__.pysetup.py- Excluir archivos específicos
Consulta pyobfus.yaml.example para ver más ejemplos de configuración.
Arquitectura
pyobfus usa el módulo ast de Python para transformaciones conscientes de la sintaxis:
- Analizador: Analiza el código fuente de Python a AST
- Analizador de símbolos: Construye la tabla de símbolos con análisis de ámbito
- Transformadores: Aplican técnicas de ofuscación (renombrado de nombres, codificación de cadenas, etc.)
- Generador: Genera código Python ofuscado
Este enfoque garantiza:
- Salida sintácticamente correcta
- Manejo adecuado de las reglas de ámbito de Python
- Soporte para funciones modernas de Python (f-strings, operador walrus, etc.)
Desarrollo
Configuración
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]"
Pruebas
# Run unit tests
pytest tests/ -v
# With coverage
pytest tests/ -v --cov=pyobfus --cov-report=html
# Run integration tests
pytest integration_tests/ -v
Marco de pruebas de integración (v0.1.6+): Prueba pyobfus en código del mundo real sin subirlo a PyPI. Consulta INTEGRATION_TESTING.md para obtener más detalles.
Calidad del código
# Format code
black pyobfus/
# Type checking
mypy pyobfus/
# Linting
ruff check pyobfus/
Casos de uso
Protección de algoritmos propietarios
Ofusca la lógica empresarial sensible antes de distribuir aplicaciones Python.
Fines educativos
Demuestra conceptos de protección de código y técnicas de ofuscación.
Protección de la propiedad intelectual
Añade una capa adicional de protección para software comercial en Python.
Limitaciones
Limitaciones actuales
-
Argumentos de palabra clave (✅ Resuelto en v0.1.6): De forma predeterminada, los nombres de parámetros se ofuscan, lo que rompe los argumentos de palabra clave. Solución: Usa el indicador
--preserve-param-namespara conservar los nombres de parámetros mientras se siguen ofuscando los cuerpos de las funciones.Ejemplo:
# 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!Cuándo usar
--preserve-param-names:- Funciones/API públicas donde los clientes usan argumentos de palabra clave
- Funciones con muchos parámetros donde los argumentos de palabra clave mejoran la legibilidad
- Código que depende en gran medida de argumentos solo de palabra clave (
def func(*, kwonly))
Compensación: Los nombres de parámetros revelan cierta información sobre la interfaz de la función, pero los cuerpos de las funciones y las variables locales siguen completamente ofuscados.
-
Importaciones entre archivos: resuelto en v0.2.0 con soporte completo de ofuscación entre archivos.
-
eval()yexec()sobre código ofuscado pueden necesitar ajustes. -
El código ofuscado es más difícil de depurar (por diseño;
--unmapexiste precisamente para eso). -
Algunas técnicas cuestan rendimiento en tiempo de ejecución; las preguntas frecuentes a continuación tienen los números.
Recomendaciones
- Prueba el código ofuscado a fondo antes de la implementación
- Mantén el código fuente original en el control de versiones
- Usa archivos de configuración para compilaciones reproducibles
- Para API públicas, usa
--preserve-param-namespara mantener la compatibilidad con argumentos de palabra clave - Considera combinar con otros métodos de protección (compilación, etc.)
Detalles técnicos
- Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, incluidas las compilaciones 3.14 sin bloqueo global del intérprete (
python3.14t, verificado: suite de pruebas completa + un ciclo real de ofuscar→ejecutar→descifrar con sello/limpieza de trazas) - Esquema de nombres basado en índices (I0, I1, I2...).
- Canalización de transformadores modulares con ofuscación entre archivos en dos fases.
- Más de 1000 pruebas, 90 % de cobertura, CI multiplataforma (Python 3.9-3.14 × Ubuntu / macOS / Windows).
Preguntas frecuentes
¿Es pyobfus adecuado para mí?
Usa pyobfus si:
- Necesitas proteger algoritmos propietarios antes de distribuir aplicaciones Python
- Quieres una herramienta que "simplemente funcione" sin conflictos de DLL ni dependencias nativas
- Prefieres precios transparentes sin limitaciones ocultas de prueba
- Apoyas el software de código abierto con funciones de pago opcionales
¿Cómo 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 es una comprobación opcional posterior a la compilación: compila el código Python generado
en memoria, no crea ningún __pycache__, e informa de syntax_valid en JSON.
No importa ni ejecuta el proyecto y no es una garantía de compatibilidad en tiempo de ejecución.
¿Cómo ofusco Python antes de venderlo o entregarlo?
Ejecuta pyobfus --check primero, compila en un directorio de salida separado y mantén
el mapping.json opcional fuera del artefacto del cliente. Entrega el árbol transformado
y luego ejecuta tus pruebas normales o el paso de empaquetado contra esa salida exacta.
Las guías de PyInstaller,
empaquetado compilado y
hook de importación cubren los formatos de entrega más comunes.
¿Cómo depuro un fallo ofuscado con un asistente de IA?
Compila con --save-mapping mapping.json. Cuando llegue un traceback de producción,
ejecuta pyobfus --unmap --trace error.log --mapping mapping.json; los identificadores
restaurados pueden ser leídos por ti, Claude Code, Cursor, Copilot u otro asistente
de IA sin entregar al cliente tu archivo de mapeo privado.
¿Existe un servidor MCP para ofuscación de Python?
Sí. uvx pyobfus-mcp expone ocho herramientas locales para escaneo de riesgos, generación
de configuración, protección de proyectos, verificación, guía de presets y mapeo
de tracebacks. Las rutas de origen se validan localmente y pyobfus no sube código
del proyecto ni requiere una clave API.
¿Mi código seguirá funcionando después de la ofuscación?
pyobfus está diseñado para preservar el comportamiento del programa para la sintaxis de Python compatible y los patrones de frameworks, y su matriz de compatibilidad está cubierta por pruebas automatizadas. La ofuscación sigue siendo una transformación de código fuente: ejecuta tu propia suite de pruebas y verifica el artefacto compilado, especialmente cuando el proyecto depende de importaciones dinámicas, reflexión o código generado.
¿El código ofuscado es más lento?
Impacto mínimo:
- Ofuscación de nombres: costo de ejecución cero (solo identificadores renombrados)
- Codificación de cadenas (Base64): ~0.1ms por cadena al inicio
- Cifrado de cadenas (AES-256, Pro): ~0.5ms por cadena al inicio
¿Puedo ofuscar proyectos Django/Flask?
¡Sí! Usa nuestras plantillas integradas:
# Django
pyobfus --init-config django
# Flask
pyobfus --init-config flask
# Then run obfuscation
pyobfus src/ -o dist/ -c pyobfus.yaml
¿Qué versiones de Python están soportadas?
pyobfus soporta Python 3.9 hasta 3.14. Compila y prueba el artefacto ofuscado con la versión de Python utilizada en producción; la portabilidad entre intérpretes puede depender de la sintaxis, las dependencias y las transformaciones habilitadas.
PyArmor vs pyobfus: ¿Cuál debería elegir?
| Característica | pyobfus | PyArmor |
|---|---|---|
| Precio | $45 (Pro, pago único) | $89 (Pro, pago único) |
| Tamaño de proyecto en plan gratuito | Sin límites de archivos o líneas | La prueba se limita a alrededor de 935-940 líneas/archivo (medido el 2026-05-09) |
| Código abierto | Sí (Core: Apache 2.0, Pro: Propietario) | No |
| Dependencias nativas | Ninguna (salida Python pura) | Requiere biblioteca de ejecución |
| Soporte Python 3.9-3.14 | Sí | Sí |
Elige pyobfus si: Quieres precios transparentes, confianza de código abierto y una implementación más simple sin dependencias nativas.
Consulta la descripción general de comparación, o ve directamente al que buscabas: PyArmor, Nuitka, Cython, PyLocket, Oxyry, ofuscadores basados en navegador.
¿Puedo usar pyobfus junto con PyArmor o Nuitka?
Sí, y para muchos proyectos este es el enfoque más rentable. Usa pyobfus como tu capa predeterminada siempre activa (cada módulo recibe ofuscación AST + mapeo para compatibilidad de depuración con IA), y luego apila el cifrado de bytecode de PyArmor Pro o la compilación nativa de Nuitka en el pequeño conjunto de módulos que realmente necesitan una protección más fuerte. La comparación ahora también cubre por qué el cifrado de bytecode debe tratarse como un obstáculo más fuerte, no como una protección criptográfica irreversible para Python del lado del cliente. Consulta Estrategia de implementación en capas en COMPARISON.md para el razonamiento completo.
¿Puedo enviar un ejecutable de un solo archivo, como con Nuitka?
Sí, a una fracción del costo de Nuitka Commercial: ofusca primero y luego empaqueta la salida ofuscada con el PyInstaller gratuito. Las dos herramientas resuelven problemas diferentes (ofuscación de nombres vs. empaquetar un intérprete de Python en un archivo) y se combinan limpiamente; consulta la Guía de PyInstaller para un ejemplo completo, incluida la verificación de que los nombres de identificadores originales nunca llegan al binario compilado y que pyobfus --unmap aún revierte un traceback capturado del exe empaquetado.
¿Qué pasa si la ofuscación rompe mi código?
- Usa
--dry-runpara previsualizar los cambios antes de escribir archivos - Usa
--preserve-param-namessi dependes de argumentos de palabra clave - Agrega exclusiones en
pyobfus.yamlpara nombres que deben permanecer sin cambios - Reporta problemas en GitHub - ¡arreglamos errores rápidamente!
¿Se puede revertir el código ofuscado?
La ofuscación de nombres elimina los identificadores originales del código fuente emitido y aumenta el costo del análisis, pero no es criptográficamente irreversible: un analista decidido puede inferir nombres y comportamiento del contexto. Mantén el archivo de mapeo opcional privado cuando necesites un mapeo inverso confiable. Para una protección más fuerte, usa las funciones Pro:
- Cifrado AES-256 para cadenas
- Comprobaciones anti-depuración para prevenir el análisis
Nota de seguridad: Limitaciones del cifrado de cadenas
Importante: El cifrado de cadenas (AES-256) está diseñado como un disuasivo contra la ingeniería inversa casual, no como seguridad criptográfica.
Debido a que el código ofuscado debe descifrar cadenas en tiempo de ejecución, la clave de cifrado está necesariamente incrustada en la salida. Un atacante decidido con acceso al código ofuscado puede:
- Localizar la clave incrustada
- Extraer y descifrar todas las cadenas
Esta es una limitación fundamental de TODOS los ofuscadores del lado del cliente (incluidos PyArmor, Nuitka, etc.): la seguridad criptográfica real requeriría descifrado del lado del servidor, lo cual es poco práctico para la mayoría de los casos de uso.
Lo que el cifrado de cadenas SÍ proporciona:
- ✅ Evita que búsquedas casuales de
stringsogreprevelen texto sensible - ✅ Aumenta el esfuerzo requerido para la ingeniería inversa
- ✅ Disuade a usuarios no técnicos de extraer información
- ✅ Agrega una capa de protección combinada con otras técnicas
Lo que el cifrado de cadenas NO proporciona:
- ❌ Protección contra ingenieros inversos decididos
- ❌ Seguridad criptográfica para secretos (usa variables de entorno o gestión de secretos en su lugar)
- ❌ Protección a nivel de DRM
Recomendación: Para credenciales sensibles (claves API, contraseñas), usa variables de entorno o sistemas externos de gestión de secretos en lugar de incrustarlas en el código.
¿En qué se diferencia pyobfus de Cython/Nuitka?
| Herramienta | Enfoque | Salida |
|---|---|---|
| pyobfus | Transformación AST | Archivos .py (Python puro) |
| Cython | Compilar a C | .so/.pyd (específico de plataforma) |
| Nuitka | Compilar a ejecutable | Binario (específico de plataforma) |
Elige pyobfus si: Necesitas archivos .py multiplataforma sin sobrecarga de compilación.
Documentación
Para usuarios
- Instalación e inicio rápido - Comienza en minutos
- Guía de configuración - Configuración YAML y filtrado de archivos
- Ejemplos - Ejemplos de código funcionales que demuestran las características
- Casos de uso - Escenarios de aplicación en el mundo real
Para desarrolladores
- Estructura del proyecto - Arquitectura del código y flujo de trabajo de desarrollo
- Guía de contribución - Cómo contribuir con código y documentación
- Plan actual - Estado actual del proyecto y prioridades
- Registro de cambios - Historial de versiones y notas de lanzamiento
Comunidad y soporte
- Problemas de GitHub - Informes de errores y solicitudes de funciones
- Discusiones de GitHub - Preguntas, ideas y ayuda de la comunidad
- Política de seguridad - Cómo reportar vulnerabilidades de seguridad
Legal y licencia
- Modelo de licencia dual (ver
LICENSE-NOTICE.md):- pyobfus (Core): Apache 2.0 - Gratis y de código abierto
- pyobfus_pro (Pro): Propietario - Requiere licencia de pago
- Diseño piloto de afiliados - Solo diseño aprobado; el programa no está lanzado y no tiene inscripción pública
Apoya el proyecto
Si encuentras útil pyobfus, considera apoyar su desarrollo:
Tu apoyo ayuda a mantener y mejorar pyobfus. ¡Gracias!
Cita
Si usas pyobfus en trabajos académicos o quieres referenciarlo, cita la versión archivada. El DOI conceptual a continuación siempre resuelve a la última versión:
APA
Zhu, R. (2026). pyobfus: Un ofuscador de Python basado en AST con mapeo inverso de tracebacks para desarrollo asistido 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}
}
Los metadatos legibles por máquina están en CITATION.cff (el widget "Citar este repositorio" de GitHub lo lee).
Agradecimientos
- Inspirado en el enfoque basado en AST de Opy
- Implementación en sala limpia: sin copia de código
