面向 Crystal 的硬件绑定与云门控二进制执行及防篡改信封密封。

什么是 Pyrite？

Pyrite 确保你编译后的 Crystal 二进制文件仅在你授权的基础设施上执行。如果对手提取、泄露、窃取或修改了该二进制文件，执行会在任何应用逻辑或机密暴露之前立即停止。

核心安全保障

硬件与云执行绑定：二进制文件在静态时是不完整的。核心运行配置和密钥被封存在一个信封中，只有物理主板的 TPM 2.0 芯片（systemd-creds）或 Google Cloud Run IAM / Cloud KMS 才能解密。
实时自完整性（防篡改）：在启动时，Pyrite 计算 /proc/self/exe 的 SHA-256 摘要，并将其与从信封中解密出的授权哈希进行比对。任何 1 字节的改动都会立即终止进程。
防逆向工程：剥离符号的原生 LLVM 机器码（strip -s）不包含任何符号表、反射元数据或明文配置。反编译只能得到一个无用的解密包装器。
零运行时开销：加密门控在启动期间运行一次（约 15–25 毫秒），对持续请求处理增加 0.00% 开销。零外部分片依赖。

快速开始

1. 添加到 `shard.yml`

dependencies:
  pyrite:
    github: renich/pyrite
    version: ~> 0.2.0

2. 在应用代码中引导

require "pyrite"
require "kemal"

# Define strongly-typed application configuration
struct AppConfig
  include JSON::Serializable

  getter database_url : String
  getter session_secret : String
  getter api_token : String
end

# 1-line verification & bootstrap:
config = Pyrite.bootstrap!(AppConfig)

puts "Pyrite verified binary integrity. Starting application..."

get "/" do
  "Secure service running on authorized hardware."
end

Kemal.run

3. 零信任故障关闭架构

Pyrite 强制执行绝对的零信任、故障关闭策略：

二进制文件严格需要授权的硬件 TPM 2.0 或 Cloud KMS 锚点才能解封其配置信封。
如果在未授权环境中执行（例如在攻击者没有 TPM 或 Cloud IAM 角色的工作站上），Pyrite 会立即以 Pyrite::HardwareAuthError 中止，并以代码 1 退出。
机密和业务逻辑绝不会暴露给指定硬件/云信任边界之外的内存。

构建与密封 CLI（`bin/pyrite`）

安装后，Pyrite 提供一个编译好的 CLI 工具，用于自动化 LLVM 编译、ELF 符号剥离、SHA-256 摘要哈希和信封密封。

# Build & Seal for Google Cloud Run (KMS):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=gcp \
    --kms-key="projects/my-p/locations/global/keyRings/my-r/cryptoKeys/app-key" \
    --config=config/production.json

# Build & Seal for Bare-Metal Fedora (TPM 2.0 / systemd-creds):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=baremetal \
    --pcr=0,7 \
    --config=config/production.json

# Build & Seal for AWS (ECS / Lambda / KMS):
bin/pyrite build \
    --input=src/main.cr \
    --output=bin/app \
    --target=aws \
    --kms-key="arn:aws:kms:us-east-1:123456789012:key/..." \
    --config=config/production.json

支持的信任锚点

环境	提供者	信任根	保护
Google Cloud Run	`Pyrite::Providers::GCPKMS`	Google Cloud IAM + Cloud KMS	BinAuthz + 实例元数据 OIDC
Fedora / 裸金属	`Pyrite::Providers::SystemdCreds`	主机 TPM 2.0（PCR 0,7）	`systemd-creds` + Linux 内核 IMA
裸金属直连	`Pyrite::Providers::TPM2Direct`	`/dev/tpmrm0` 芯片	直接 TPM2 PCR 解封（`tpm2-tools`）
AWS（ECS / Lambda）	`Pyrite::Providers::AWSKMS`	IMDSv2 + AWS KMS	AWS IAM 任务角色解密

文档

详尽的技术文档、规范和架构决策记录以 reStructuredText 格式维护在 docs/ 下：

指南	范围与要点	直接链接
业务背景与策略	问题陈述、威胁态势、利益相关者画像（Devon、Rénich、Sam）以及可量化的 ROI 目标。	业务规范 • 用户画像 • 问题陈述
功能规范	需求 [FUNC-001]–[FUNC-005]：执行门控、实时自完整性、信封密封、开发者体验和 CLI 编排。	功能规范 • 执行门控 • 自完整性
技术架构	规范 [TECH-001]–[TECH-005]：核心反序列化引擎、流式 16KB SHA-256 哈希器、提供者驱动程序和正式的 STRIDE 威胁模型。	技术规范 • 核心引擎 • 威胁模型
架构决策记录	不可变的 ADR，记录信封加密与客户端 DRM 的对比，以及零依赖标准库设计。	ADR 索引 • ADR 001（信封加密） • ADR 002（仅标准库）
项目路线图与跟踪	按顺序的三阶段交付跟踪、验证标准以及跨核心引擎、提供者和 CLI 的里程碑交付物。	路线图 • 阶段 1 • 阶段 2 • 阶段 3
Crystal API 参考	完整的交互式类型层次结构、方法签名和编译器生成的参考。	API 参考

贡献与荣誉准则

所有贡献都必须遵守通用荣誉准则和贡献指南。

许可证

软件：GNU 通用公共许可证 v3.0 或更高版本（LICENSE）。
文档：GNU 自由文档许可证 v1.3 或更高版本（LICENSE-DOCS）。

支持与捐赠

如果你觉得 Pyrite 有用并希望支持其持续开发，请考虑捐赠：

pyrite

最受欢迎