Skip to main content

pyprotect

Python 代码保护与授权工具集 — Cython 编译 / NaCl 加密 / Ed25519 License 三合一。

安装

pip install pyprotectx

# 需要 Cython 编译功能:
pip install pyprotectx[compile]

平台支持:macOS 已实测;Windows / Linux 理论兼容(.enc 加密路径为纯 Python、无平台差异;Cython 编译路径在 Windows 需 MSVC Build Tools),尚未在真实环境回归验证。

客户侧运行时包 pyprotectx-protected:PyPI 版只带占位符密钥,需厂商注入密钥后自行分发,见运行时包与厂商定制。

同类工具对比

特性 pyprotect PyArmor pyconcrete SOURCEdefender
保护方式 Cython 编译 → 机器码(.so);NaCl 加密兜底(.enc) 字节码混淆(v8+ 已有公开解密工具);BCC 函数→C(暂无公开解密工具) AES-128 加密,密钥嵌 C 扩展 AES-256 加密,密钥由官方服务管理
授权能力 Ed25519 签名 + 机器绑定,全离线 机器绑定 + 过期(付费档) 无 过期(SaaS 托管)
构建要求 需 C 编译器,.so 按平台分别构建 无需编译器,产物跨平台 需自行编译安装(无预编译包) 无需编译器
费用 MIT 免费档限评估/非商用,商业需买断(Basic/Pro/Group,CI 按年) Apache-2.0 完全免费 试用24h;正式收费

pyprotect 的差异化定位:

  • 唯一「代码保护 + 离线机器绑定授权」双全且免费开源(MIT)的方案:授权只嵌公钥(Ed25519),无 SaaS、无订阅、无付费墙
  • Cython 机器码免疫字节码级公开解密工具;每个项目构建时生成随机 NaCl 密钥
  • 预编译 wheel 开箱即用(对比 pyconcrete 需自行编译安装)

共同短板:三类方案(含本工具)的加密强度都取决于「密钥从二进制中被提取的难度」,没有绝对安全——选型应基于威胁模型而非营销词。


使用方式

1. License 授权

1.1 生成密钥对(一次性)

pyprotect license init -o keys/
# → keys/license_ed25519.key  (私钥,妥善保管)
# → keys/license_ed25519.pub  (公钥,随产品发布)

1.2 为客户生成授权文件

pyprotect license generate \
  --machine-id <客户机器ID> \
  --expire-days 365 \
  --private-key keys/license_ed25519.key \
  -o license.lic

客户在目标机器上获取 machine-id:

平台 获取命令
Linux cat /etc/machine-id
macOS ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}'
Windows PowerShell:(Get-CimInstance Win32_ComputerSystemProduct).UUID

机器码在重装系统 / 更换主板后会变化。容器环境没有稳定机器码,见 §4 的容器部署说明。

1.3 (可选)本地验证授权文件

pyprotect license verify \
  --license-file license.lic \
  --machine-id <机器ID> \
  --public-key keys/license_ed25519.pub

2. 项目初始化

在需要保护的 Python 项目根目录执行:

pyprotect init . --packages myapp --packages lib --packages utils --keep-plain main.py

会在项目根目录生成 pyprotect.yaml 并复制 _bootstrap.py 和 license_verify.py 模板。

pyprotect.yaml 配置说明

packages:             # 要保护的包目录(相对于项目根)
  - myapp
  - lib
keep_plain:           # 保留为明文 .py 的文件(适用场景见下文 keep_plain 说明)
  - main.py
ed25519_public_key: keys/license_ed25519.pub   # 公钥路径

keep_plain:哪些文件不适合编译

keep_plain 是排除清单——列出的 .py 既不编译也不加密,保留明文。它只对 packages 内的文件生效(项目根目录的文件本就不参与保护)。典型场景:

  1. 程序入口:python x.py 直接运行的文件不能是 .so——编译产物是可导入模块,无法直接执行。入口放项目根目录天然安全;入口在包内(如 python -m myapp.cli 对应的 myapp/cli.py)时必须 keep_plain。
  2. 依赖动态特性的代码:读取自身源码的内省(如 inspect.getsource)、exec/eval 拼接自身路径、硬编码 .py 后缀的 __file__ 路径运算等,编译后行为会改变。
  3. 需要用户可见/可改的内容:配置默认值、常量表等。

说明:Cython 编译失败的文件会自动降级为 NaCl 加密(.enc),因此 keep_plain 只该留给「确实既不能编译也不能加密」的文件。注意:明文 = 零保护,敏感逻辑不要放进 keep_plain。

3. 构建保护

pyprotect build . --pub-key keys/license_ed25519.pub

前置条件:需要 C 编译器(macOS 自带 Xcode CLT;Linux 用 gcc;Windows 需安装 MSVC Build Tools)。没有编译器的环境可用 --skip-cython 走纯加密路径。

构建流程:

[1/5] 注入 Ed25519 公钥 → license_verify.py
[2/5] 生成随机 NaCl 密钥 → _bootstrap.py
[3/5] Cython 编译 _bootstrap.py → _bootstrap.so
[4/5] 批量 Cython 编译所有 .py → .so(编译失败则 NaCl 加密 → .enc)
[5/5] 清理 .py/.pyc/.c 源文件

输出:项目只剩 .so/.enc + 显式保留的 .py 文件。

关键选项

选项 说明
--skip-cython 跳过 Cython,全部走 NaCl 加密
--no-license 不注入 License 公钥(纯代码混淆)
--pub-key <path> 覆盖 yaml 中的公钥路径
--nacl-key <hex> 指定 64 位十六进制 NaCl 密钥(默认随机)。若客户侧用打过补丁的运行时包解密 .enc,需与 runtime-patch 传同一把密钥
--packages / --keep-plain 覆盖 yaml 配置(多值需重复 flag:-p a -p b)

4. 目标项目接入

在项目入口 main.py 中:

import sys

import _bootstrap                    # 必须最先导入,注册 .enc 导入钩子
from license_verify import verify_license

if not verify_license():
    print("License 无效或已过期,请联系供应商")
    sys.exit(1)

# 正常启动...
from myapp import App
App().run()

客户部署:LICENSE_FILE 指向授权文件即可,机器码默认自动探测(Windows 注册表 MachineGuid / Linux /etc/machine-id / macOS IOPlatformUUID),无需额外设置:

export LICENSE_FILE=/path/to/license.lic

仅以下情况需用 LICENSE_MACHINE_ID 显式覆盖:

容器部署(容器内没有稳定机器码)——为每个部署指定固定身份,容器重建、宿主机重启均不受影响:

# docker-compose.yml
services:
  app:
    environment:
      LICENSE_FILE: /app/license.lic
      LICENSE_MACHINE_ID: "prod-cluster-01"   # 向厂商按此 ID 申请授权

自动探测失败时(运行日志会明确提示)。

绑定强度说明:自动探测时机器码来自真实硬件,客户谎报即自失效;手动覆盖时绑定强度取决于部署纪律。

5. 授权校验行为(fail-closed)

verify_license() 默认失败即拒绝:未设置 LICENSE_FILE、文件不存在、签名无效、机器不匹配、已过期 → 一律 valid=False(建议业务直接退出);授权有效且未过期才放行。

开发调试需跳过授权时,必须显式设置:

export PYPROTECT_ALLOW_DEV=1   # 仅限开发环境,受保护产品请勿携带

pyprotect license verify 校验失败时以 exit code 1 退出,便于脚本化判断。

6. Docker 构建集成

FROM python:3.12-slim AS build
RUN pip install pyprotectx[compile]
COPY . /project
WORKDIR /project
RUN pyprotect build . --pub-key keys/license_ed25519.pub

FROM python:3.12-slim AS runtime
COPY --from=build /project /app
# 受保护代码运行只需 pynacl:.so 内的导入钩子自带密钥,无需运行时包
RUN pip install pynacl
CMD ["python", "/app/main.py"]

加密原理

层 技术 说明
Cython 编译 .py → .c → .so 原生机器码,反编译几乎不可能
NaCl 加密 XSalsa20-Poly1305 编译失败的文件走加密兜底
运行时解密 _bootstrap.so 导入钩子 sys.meta_path 拦截 import,自动解密 .enc
License 签名 Ed25519 公钥嵌入 .so,私钥不留存

Nonce 策略:每次加密生成随机 24 字节 nonce,拼在密文头部。


完整示例

# 1. 生成密钥对
pyprotect license init -o keys/

# 2. 获取当前机器 ID,生成 License(其他平台命令见 §1.2 对照表)
MACHINE=$(cat /etc/machine-id)
pyprotect license generate --machine-id $MACHINE --expire-days 365 \
  --private-key keys/license_ed25519.key -o license.lic

# 3. 初始化并构建
pyprotect init . --packages myapp --keep-plain main.py
pyprotect build . --pub-key keys/license_ed25519.pub

# 4. 验证运行
LICENSE_FILE=license.lic LICENSE_MACHINE_ID=$MACHINE python main.py

运行时包 pyprotectx-protected 与厂商定制

PyPI 上的运行时包只带占位符密钥(开箱无法解密 .enc、无法校验真实授权),是留给厂商二次加工的"空白模板"。

厂商工作流(runtime-patch)

# 1. 固定一把 NaCl 密钥,build 时显式传入
NACL_KEY=$(python -c "import os; print(os.urandom(32).hex())")
pyprotect build . --pub-key keys/license_ed25519.pub --nacl-key $NACL_KEY

# 2. 同一把密钥 + 同一个公钥注入运行时包源码(默认原地修改;加 --out 输出副本,避免密钥进入版本库)
pyprotect runtime-patch --pub-key keys/license_ed25519.pub --nacl-key $NACL_KEY

# 3. 构建"你专属"的运行时 wheel,分发给客户(私有源或直接发文件)
cd pyprotect-protected && python -m build

⚠️ 补丁后的运行时包含真实密钥,严禁发布到公共 PyPI,只能走私有渠道。

客户环境(安装厂商分发的补丁版):

import pyprotect_protected              # 自动注册 .enc 导入钩子
from pyprotect_protected import verify_license

if not verify_license():
    sys.exit(1)

License

MIT

Metadata

Release files for pyprotectx 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyprotectx 0.2.0
File Size Uploaded Provenance Actions
pyprotectx-0.2.0.tar.gz 70.1 kB Without provenance Details for pyprotectx-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyprotectx 0.2.0
File Interpreter ABI Platform Actions
pyprotectx-0.2.0-py3-none-any.whl Python 3 none any Details for pyprotectx-0.2.0-py3-none-any.whl

Total release size: 90.4 kB

Release files / pyprotectx-0.2.0.tar.gz

Download URL pyprotectx-0.2.0.tar.gz
Size 70.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e139c5261b980783f2aa98171256b92ab9027d9934dca52a0d770c4c35dbe951
BLAKE2b-256 checksum
How to use checksums
565ee813c269f99cbfa80b7747e83613464f4ed91bf58e22ab024988033e0bad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Release files / pyprotectx-0.2.0-py3-none-any.whl

Download URL pyprotectx-0.2.0-py3-none-any.whl
Size 20.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
41a7df7ad872cc3e2a8d48047b2d8cc9bd666b21fdfa68357873a6774e5db194
BLAKE2b-256 checksum
How to use checksums
310cfcbdbe5648228b2b8e916e0cbd3585cf2a38a47fedf3a1cc8fffd7207524
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.3

Security for pyprotectx 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page