SecurePy

一个修改过的 CPython 3.14 运行时，可原生执行 AES-256-GCM 加密的 Python 字节码（.epyc 文件）。

A modified CPython 3.14 runtime that natively executes AES-256-GCM encrypted Python bytecode (.epyc files).

工作原理 / How It Works

                        ┌─────────────────────────────────────────┐
  hello.py              │       构建阶段 / Build Time (spyc)       │
     │                  │                                         │
     ▼                  │   .py ──► compile ──► marshal ──► AES   │
  compile               │                                   │     │
     │                  │                                   ▼     │
     ▼                  │                              hello.epyc │
  marshal.dumps         └─────────────────────────────────────────┘
     │
     ▼
  AES-256-GCM encrypt
     │                  ┌─────────────────────────────────────────┐
     ▼                  │      运行阶段 / Run Time (SecurePy)      │
  hello.epyc            │                                         │
     │                  │   .epyc ──► detect magic ──► load key   │
     ▼                  │                                  │      │
  SecurePy Runtime      │              decrypt ◄───────────┘      │
     │                  │                │                        │
     ▼                  │                ▼                        │
  detect SPY\0 magic    │   marshal.loads ──► PyCodeObject        │
     │                  │                          │              │
     ▼                  │                          ▼              │
  load key (env var)    │                  PyEval_EvalCode         │
     │                  │                          │              │
     ▼                  │                          ▼              │
  AES-GCM decrypt       │                       output            │
     │                  └─────────────────────────────────────────┘
     ▼
  PyMarshal_ReadObjectFromString
     │
     ▼
  PyEval_EvalCode
     │
     ▼
  Hello, World!

防护目标： 防止通过 dis、uncompyle6 等工具对 .pyc 文件进行静态逆向。

Protects against: static reverse engineering of .pyc files via dis, uncompyle6, etc.

非防护目标： 不防御内存转储、调试器挂钩或高级运行时分析。

Does NOT protect against: memory dumps, debugger hooks, or advanced runtime analysis.

.epyc 文件格式 / .epyc File Format

偏移/Offset  大小/Size   字段/Field
──────────  ─────────  ──────────────────
0           4          魔数 / Magic "SPY\0"
4           2          版本 / Version (1)
6           2          算法 / Algorithm (1 = AES-256-GCM)
8           4          载荷大小 / Payload size
12          12         随机数 / Nonce
24          16         GCM 认证标签 / GCM Auth Tag
40          ...        密文 / Ciphertext (加密的 marshal 数据)

头部共 40 字节。载荷为 marshal.dumps(code_object) 经 AES-256-GCM 加密后的密文。

Total header: 40 bytes. Payload is marshal.dumps(code_object) encrypted with AES-256-GCM.

项目结构 / Project Structure

SecurePy/
├── README.md
├── hello.py                    # 测试文件 / Test file
├── patch/                      # CPython 源码覆盖层（保持原始路径）
│   │                           # CPython source overlay (preserves original paths)
│   ├── Include/internal/
│   │   └── pycore_securepy.h       # [新增/NEW] 头文件：格式定义、API 声明
│   ├── Python/
│   │   ├── securepy.c              # [新增/NEW] 解密 + 加载器实现
│   │   └── pythonrun.c             # [修改/MOD] .epyc 检测 + 调度
│   └── Makefile.pre.in             # [修改/MOD] 构建集成 + OpenSSL 静态链接
├── build/                      # Docker 构建系统 / Docker build system
│   ├── Dockerfile                  # 多阶段构建 / Multi-stage build (debian:bookworm)
│   └── build.sh                    # 构建镜像 + 启动容器 / Build image + start container
└── cmd/spyc/
    └── spyc.py                     # 命令行工具（依赖 cryptography）/ CLI tool

构建 SecurePy 运行时 / Building the SecurePy Runtime

所有依赖都在 Docker 内处理，宿主机只需要安装 Docker 并准备 CPython 3.14 源码。

All dependencies are handled inside Docker. Your host machine only needs Docker and CPython 3.14 source code.

前置条件 / Prerequisites

1. Docker
2. CPython 3.14 源码放在 cpython-3.14/ 目录下 / CPython 3.14 source code placed at cpython-3.14/

git clone --depth 1 --branch v3.14.0 https://github.com/python/cpython.git cpython-3.14

构建 / Build

./build/build.sh

脚本会自动完成以下步骤 / The script will automatically:

1. 构建包含修改版 CPython 运行时的 Docker 镜像 / Build the Docker image with modified CPython runtime
2. 启动容器，将项目目录挂载到 /app / Start a container with the project directory mounted at /app
3. 进入容器的交互式 Shell / Drop you into an interactive shell inside the container

使用 spyc 命令行工具 / Using spyc (CLI Tool)

spyc 是将 Python 源码编译并加密为 .epyc 文件的构建工具。

spyc is the build tool that compiles and encrypts Python source into .epyc files.

在容器内执行 / Run inside the container:

pip3 install cryptography

# 生成密钥 / Generate a key
python3 /app/cmd/spyc/spyc.py keygen -o /app/key.bin
# 输出 / Output: Key base64: base64:xxxxxxxx

# 一步构建：.py -> .epyc / One-step build: .py -> .epyc
python3 /app/cmd/spyc/spyc.py build /app/hello.py --key-file /app/key.bin -o /app/hello.epyc

# 或者分步执行 / Or step by step:
python3 /app/cmd/spyc/spyc.py compile /app/hello.py                           # -> hello.pyc
python3 /app/cmd/spyc/spyc.py encrypt /app/hello.pyc --key-file /app/key.bin   # -> hello.epyc

命令列表 / Commands

命令/Command	说明/Description
keygen	生成 AES-256 密钥 / Generate AES-256 key
compile	编译 .py 为 .pyc / Compile .py to .pyc
encrypt	加密 .pyc 为 .epyc / Encrypt .pyc to .epyc
build	一步完成 .py 到 .epyc / All-in-one .py to .epyc

运行 .epyc 文件 / Running .epyc Files

在容器内通过环境变量传递解密密钥 / Run inside the container, pass the decryption key via environment variable:

# 使用密钥文件 / Using key file
SECUREPY_KEY=/app/key.bin python3 /app/hello.epyc

# 或使用 base64 内联密钥 / Or using base64 inline key
SECUREPY_KEY_DATA=base64:xxxxxxxx python3 /app/hello.epyc

环境变量/Env Variable	格式/Format	说明/Description
SECUREPY_KEY_DATA	base64:<base64-encoded>	内联密钥（优先）/ Inline key (priority 1)
SECUREPY_KEY	/path/to/keyfile	密钥文件路径 / Path to 32-byte key file (priority 2)

CPython 修改概要 / CPython Modifications Summary

仅修改 2 个文件，新增 2 个文件：

Only 2 files modified, 2 files added:

文件/File	变更/Change	说明/Description
Include/internal/pycore_securepy.h	新增/NEW	SecurePycHeader 结构体、API 声明 / Struct and API declarations
Python/securepy.c	新增/NEW	密钥加载、OpenSSL AES-256-GCM 解密、marshal 反序列化 / Key loading, decryption, deserialization
Python/pythonrun.c	修改/MOD	maybe_pyc_file() 识别 .epyc 扩展名；run_pyc_file() 检测 SPY\0 魔数并调度解密 / Recognize .epyc, detect magic and dispatch
Makefile.pre.in	修改/MOD	添加 securepy.o，OpenSSL 静态链接标志 / Add securepy.o, OpenSSL static link flags

许可证 / License

PSF-2.0（与 CPython 一致 / same as CPython）