面向 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.1.0

2. 在应用程序代码中引导

require "pyrite"
require "kemal"

# 定义强类型应用程序配置
struct AppConfig
  include JSON::Serializable

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

# 1 行验证与引导：
config = Pyrite.bootstrap!(AppConfig)

puts "Pyrite 已验证二进制完整性。正在启动应用程序..."

get "/" do
  "安全服务正在授权硬件上运行。"
end

Kemal.run

3. 本地开发模式

在开发或单元测试期间（crystal spec），您不需要活跃的云凭证或物理 TPM。只需创建 .pyrite.dev.json 或设置 PYRITE_DEV=1：

{
  "database_url": "postgresql://postgres:pass@localhost:5432/dev",
  "session_secret": "insecure-dev-secret-key",
  "api_token": "dev-token"
}

Pyrite 将在终端中打印清晰的视觉警告，并传递您的本地配置。

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

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

# 为 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

# 为裸机 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

支持的信任锚点

文档

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

贡献与行为准则

所有贡献必须遵守通用行为准则和贡献指南。

许可证

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

支持与捐赠

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

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 任务角色解密
本地开发	`Pyrite::Providers::DevMock`	本地文件（`.pyrite.dev.json`）	无摩擦的本地开发

业务背景与战略	问题陈述、威胁态势、利益相关者画像（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（仅标准库）
项目路线图与跟踪	按顺序排列的 3 阶段交付跟踪、验证标准和跨核心引擎、提供方及 CLI 的里程碑交付物。	路线图 • 阶段 1 • 阶段 2 • 阶段 3
Crystal API 参考	完整的交互式类型层次结构、方法签名和编译器生成的参考。	API 参考

pyrite

最受欢迎