davidalmeidac/sealed-env

## 为什么会有这个项目 仅在 **2025 年**，针对 JavaScript 生态系统的供应链攻击就从 CI/CD 流水线和开发者机器上窃取了**数以千计的明文密钥**。Shai-Hulud 蠕虫（2025 年 11 月）通过扫描 `.env` 文件并将其内容渗透到公开的 GitHub 仓库，攻陷了超过 **25,000 个代码库**。 教训很简单：**明文 `.env` 已死**。而且仅靠静态加密是不够的——如果主密钥泄露（它们确实会泄露——参见 tj-actions 和 GhostAction 攻击活动），整个密钥库就会大开绿灯。 `sealed-env` 解决了这两个问题：它对静态密钥进行加密，**并且**可以在每次生产部署前要求人工操作员提供新鲜的 TOTP 验证码。即使你的 CI 流水线被完全攻破，攻击者也无法在没有操作员手机的情况下进行解密。 ## 你将获得什么 - 一个在 Node 和 Java 中**完全相同的** `.env.sealed` 文件格式。可以自由混合技术栈。 - 用户可选的**三种安全模式**：`basic` 用于开发，`team` 用于预发布，`enterprise` 用于带 TOTP 解封的生产环境。 - Node 包具有**零运行时依赖**。仅使用 Node 内置的 `crypto` 和 `fs`。 - 一份**公开的威胁模型**，准确说明了我们能防范什么，不能防范什么。 - 一个 **CLI**（`npx sealed-env`）和一个 **Spring Boot starter**（Java）。 ## 跨栈架构 ``` ┌─────────────────────────┐ ┌─────────────────────────┐ │ Node side │ │ Java side │ │ ──────────── │ │ ──────────── │ │ • CLI: sealed-env seal │ │ • SealedEnv core lib │ │ • npm: sealed-env │ │ • Spring Boot starter │ │ • writes KDF=scrypt │ │ • writes KDF=argon2id │ └────────────┬────────────┘ └────────────┬────────────┘ │ │ │ both speak SEALED-ENV-V1 │ │ (byte-for-byte spec compliance) │ ▼ ▼ ┌────────────────────────────────────────┐ │ .env.sealed │ │ ─────────────────────────── │ │ SEALED-ENV-V1 MODE=team │ │ KDF= │ │ KDF-PARAMS=... SALT=... │ │ NONCE=... AAD-DIGEST=... │ │ HMAC=... CREATED=2026-... │ │ │ │ │ └────────────────────────────────────────┘ ▲ ▲ │ a file written by one │ │ stack decrypts in the │ │ other — no conversion │ │ │ ┌────────────┴────────────┐ ┌────────────┴────────────┐ │ Node app reads it │ │ Java app reads it │ │ (loadSealed()) │ │ (Spring Environment) │ └─────────────────────────┘ └─────────────────────────┘ ``` ## 30 秒体验 (Node) ``` # 安装 npm install sealed-env # 为你的项目初始化一个 vault npx sealed-env init # → 生成一个 master key (本地保存至 .env.local，已 gitignored) # → 如果你选择 'enterprise' 模式，还会显示你的 authenticator 的 QR code # 加密你现有的 .env npx sealed-env encrypt .env # → 创建 .env.sealed (请提交此文件！) # 在代码中使用它 — 无需更改 API import 'sealed-env/config'; console.log(process.env.STRIPE_API_KEY); // works as if it were a normal .env ``` ## 30 秒体验 (Spring Boot) ``` io.github.davidalmeidac sealed-env-spring-boot-starter 0.1.0 ``` ``` # application.yml sealed-env: file: .env.sealed key-source: env ``` ``` @Value("${stripe.api.key}") // resolved transparently from .env.sealed private String stripeKey; ``` ## 三种模式 — 可视化展示 ``` basic team enterprise ───── ──── ────────── .env.sealed .env.sealed .env.sealed │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ AES-GCM │ │ HMAC │ │ HMAC │ │ decrypt │ │ verify │ │ verify │ └────┬────┘ └────┬────┘ └────┬────┘ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ plaintext │ AES-GCM │ │ TOTP │ │ decrypt │ │ token │ └────┬────┘ │ verify │ ▼ └────┬────┘ plaintext ▼ ┌─────────┐ ▲ ▲ │ deploy │ │ master_key │ + signing_key │ bind │ └────┬────┘ ▼ ┌─────────┐ │ AES-GCM │ │ decrypt │ └────┬────┘ ▼ plaintext ▲ │ + unseal token (carries │ salt-bound TOTP epoch) │ + deploy_id ``` ## 三种模式 | | basic | team | enterprise | |---|:---:|:---:|:---:| | AES-256-GCM 加密 | ✓ | ✓ | ✓ | | Argon2id 密钥派生 | ✓ | ✓ | ✓ | | HMAC 完整性标签 | — | ✓ | ✓ | | 要求 TOTP 解封 | — | — | ✓ | | 绑定部署的解封 token | — | — | ✓ | | 防重放保护 | — | — | ✓ | | 读取后擦除内存 | ✓ | ✓ | ✓ | | 主机端解密 (`deploy --remote`) | ✓ | ✓ | ✓ | | 适用场景 | 个人项目 | 预发布环境，小团队 | 生产环境，金融科技，个人身份信息 (PII) | 选择适合你威胁模型的一种模式。以后只需一条命令即可升级： ``` npx sealed-env upgrade --to enterprise ``` ## `enterprise` 模式的工作原理 ``` ┌──────────────┐ 1. push ┌──────────────┐ │ developer │ ───────────▶ │ github │ └──────────────┘ └──────────────┘ │ 2. CI runs ▼ ┌──────────────┐ │ CI pipeline │ paused, waiting for unseal └──────────────┘ │ │ 3. notifies operator ▼ ┌──────────────┐ │ operator │ 4. opens authenticator app, │ (you) │ reads 6-digit TOTP code └──────────────┘ │ │ 5. runs: │ sealed-env unseal --totp 482914 \ │ --deploy-id ▼ ┌──────────────────────────────────────┐ │ unseal token (60s lifetime, bound to │ │ this specific deploy) │ └──────────────────────────────────────┘ │ 6. paste into CI form ▼ ┌──────────────┐ │ deploy runs │ decrypts .env.sealed │ to prod │ with master_key + token └──────────────┘ If the master key leaks AFTER the deploy → attacker still needs the operator's TOTP. If the TOTP token leaks → useless for the next deploy (different commit). ``` ## 对比情况 诚实的版本。不同的工具适用于不同的威胁模型——选择适合你的那一个。 | | **sealed-env** | dotenv | dotenvx | Doppler | HashiCorp Vault | AWS Secrets Manager | jasypt | |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | **静态加密** | ✅ | ❌ 明文 | ✅ | ✅ | ✅ | ✅ | ✅ | | **跨技术栈 (Node + Java)** | ✅ 相同的传输格式 | 不适用 | 仅限 Node | 语言无关 (HTTP) | 语言无关 (HTTP) | 语言无关 (HTTP) | 仅限 Java | | **无需外部服务** | ✅ | ✅ | ✅ | ❌ 付费 SaaS | ❌ 自托管服务器 | ❌ AWS | ✅ | | **部署时的 TOTP 解封** | ✅ | ❌ | ❌ | ❌ | ⚠️ 通过插件实现 | ❌ | ❌ | | **防重放保护 (绑定部署的 token)** | ✅ | ❌ | ❌ | ❌ | ⚠️ 部分 | ❌ | ❌ | | **公开的威胁模型** | ✅ | 不适用 | 部分 | 仅限保密协议 (NDA) | ✅ | ✅ | ❌ | | **零运行时依赖 (Node)** | ✅ | ✅ | ❌ (8+ 依赖) | ❌ SDK | ❌ SDK | ❌ SDK | 不适用 | | **Spring Boot 自动配置** | ✅ | 不适用 | 不适用 | 社区 | 社区 | 社区 | 手动 | | **密钥派生后擦除内存** | ✅ | 不适用 | ❌ | ❌ | ❌ | ❌ | ❌ | | **许可证** | MIT | MIT | MIT | 专有 | MPL 2.0 | 专有 | Apache 2.0 | | **成本** | 免费 | 免费 | 免费 | $0–$15/用户/月 | 免费 / 企业版 $ | $0.40/密钥/月 | 免费 | ### 何时选择哪个工具 - **`dotenv`** — 单人开发，仅限开发环境，从不用于生产。没问题。 - **`dotenvx`** — 仅限 Node 项目，静态加密就足够了，你信任你的 CI 密钥库。没问题。 - **`Doppler` / `AWS Secrets Manager`** — 你已经为平台付费，能接受供应商锁定，希望跨多个服务进行集中轮换。很好。 - **`HashiCorp Vault`** — 你有运维能力来运行 Vault 集群，需要细粒度的策略和动态密钥（每次会话的数据库凭证）。虽然笨重但很强大。 - **`jasypt`** — 仅限 Java 项目，静态加密就足够了，你不需要跨技术栈。没问题。 - **`sealed-env`** — 你想要**静态加密 + 针对被攻陷的 CI/CD 的坚固防线**（绑定 TOTP 的部署），不需要外部服务，并且你的技术栈是 Node、Java/Spring Boot 或两者兼有。它的防御上限高于 dotenvx/jasypt；运营成本低于 Vault。 ### `sealed-env` **不是**什么 - 不是集中式密钥管理器（无轮换 API，无审计日志，无团队策略）。 - 当你需要动态的按会话凭证时，不能替代 HashiCorp Vault。 - 如果你想要 SaaS 仪表板，它不适合你。 如果你的团队需要 Doppler/Vault 的功能集，就使用它们。当你想要一个静态的、基于文件的、可版本控制的加密密钥，且具有比 `dotenvx` 更高的安全下限时，`sealed-env` 是正确的选择。 ## 可运行的示例 你可以克隆并在 60 秒内运行的预密封应用： - 📦 [examples/node-express](examples/node-express) — 使用 `import 'sealed-env/config'` 的 Node + Express 服务器 - ☕ [examples/spring-boot](examples/spring-boot) — 带有自动配置 starter 的 Java + Spring Boot 3 演示主密钥已与每个示例一起提交，以便应用程序开箱即用。**这是公开的——切勿在实际项目中使用。** ## 配套工具：sealed-env Studio (pre-alpha) 一个建立在 sealed-env 之上的桌面 GUI，专为不常在终端中工作的人员打造。目前处于设计阶段——正在寻找合作者。 [**→ github.com/davidalmeidac/sealed-env-studio**](https://github.com/davidalmeidac/sealed-env-studio) ## 文档 - 📖 [概述](docs/01-overview.md) — `sealed-env` 是什么以及不是什么 - 🔐 [威胁模型](docs/02-threat-model.md) — 它能防御哪些 2024-2026 年的攻击 - 🚀 [快速开始：Node](docs/03-quickstart-node.md) - 🍃 [快速开始：Java + Spring Boot](docs/04-quickstart-java.md) - 🔑 [Enterprise 模式演练](docs/05-enterprise-mode.md) — TOTP + 部署绑定 - 📐 [文件格式剖析](docs/06-format-anatomy.md) — `.env.sealed` 里面有什么 - 🛠️ [运维指南](docs/07-operational-guide.md) — 面向系统管理员、经理和创始人（无需代码） - ☁️ [CI/CD + 云端方案](docs/08-cicd-recipes.md) — GitHub Actions, GitLab, Bitbucket, CircleCI, Jenkins, Azure, AWS, GCP, Vercel, Railway, Docker, K8s - 🔄 [项目生命周期](docs/09-lifecycle.md) — 初始化 → 引导 → 部署作为一个完整流程 - 🎯 [解密策略](docs/10-decrypt-strategies.md) — 主机端 vs 进程内的权衡，`deploy --remote` 规范 - 📋 [格式规范](SPEC.md) — 标准传输格式 (v1) - 🛡️ [安全策略](SECURITY.md) — 如何报告漏洞 ## 项目状态 **v0.1.0 — 稳定版。** 传输格式 (`SEALED-ENV-V1`) 已被**冻结**，并将永久保持可读性。公共 API 是稳定的。错误修复和非破坏性功能更新将以 `0.1.x` 的形式发布；破坏性更改将留待 `0.2.0` 版本。 **0.1.0 包含内容：** - [x] 三种模式：`basic`、`team`、`enterprise`（绑定 TOTP 的部署） - [x] Node CLI (`init`, `encrypt`, `decrypt`, `get`/`set`/`edit`/`diff`, `exec`, `deploy`, `keychain`) - [x] 用于 Model A 主机端解密部署的 `deploy --remote` - [x] 跨技术栈：Node + Java 库读取相同的传输格式 - [x] Spring Boot 3 starter（自动配置 + `@Value` 支持） - [x] 操作系统密钥链后端 (Windows DPAPI, macOS Keychain, Linux secret-tool) - [x] 17 个平台 CI/CD 配方，包括 OIDC 联合 - [x] 在 CI 中跨技术栈验证的加密测试向量 **路线图：** - [ ] v0.1.x — `sealed-env doctor` + `install-hooks` + 库端 `.env.local` 自动加载（非破坏性） - [ ] v0.2.0 — Java CLI（通过 Maven 分发） · Shamir Secret Sharing · sidecar 模式 - [ ] v0.3.0 — `memfd_secret` Linux 内存保护 · 堆转储过滤器 - [ ] v1.0 — 硬件支持的包装 (TPM / Secure Enclave / YubiKey) **配套项目：** - [sealed-env-studio](https://github.com/davidalmeidac/sealed-env-studio) — 桌面 GUI，pre-alpha，设计阶段 ## 贡献 这是一个安全敏感项目。非常欢迎贡献，但请先阅读 [SECURITY.md](SECURITY.md)。加密相关的更改需要进行明确讨论。 ## 许可证 [MIT](LICENSE) — David Almeida, 2026.

_{在哥伦比亚布卡拉曼加公开构建。
“静态加密。部署时认证。读取时擦除。”}

标签：DevSecOps, .env保护, GNU通用公共许可证, JSONLines, JS文件枚举, Maven, MITM代理, Node.js, npm, PB级数据处理, Spring Boot, TOTP解封, 上游代理, 凭据管理, 凭证安全, 大语言模型安全, 安全, 安全助手, 安全运维, 文档结构分析, 机密管理, 漏洞验证, 环境变量加密, 环境隔离, 生产部署, 自动化攻击, 超时处理, 防供应链攻击, 零依赖, 零信任