mcpField
U
using-sops

using-sops

github.com/jssblck安全01.7k 次安装3 周前更新
代码仓库

关于 using-sops

用于管理仓库中经 sops 加密的 dotenv 密钥，要求通过项目的 `pnpm secrets` 封装工具操作。它说明开发与经授权的生产密钥流程，并强调避免将私钥写入文件或日志。

主要功能

  1. 01加密 dotenv 密钥工作流
  2. 02项目的 `pnpm secrets` 封装工具
  3. 03开发密钥读取与编辑命令
  4. 04经授权的生产访问流程
  5. 05私钥处理防护措施

适用场景

  1. 01读取或更新开发密钥
  2. 02使用解密后的环境变量运行进程
  3. 03为获授权的任务访问生产密钥
  4. 04在环境变量架构和密钥文件中添加变量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jssblck/agents --skill using-sops

安装后在 Claude Code 中输入/using-sops确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
setup.md
sops-notes.md

详细介绍

使用 sops

采用此布局的仓库会将机密作为经 sops 加密的 dotenv 文件提交到 git，每个部署环境对应一个文件：secrets/dev.env、secrets/prod.env。这些文件使用 age 身份解密。没有 .env，没有机密服务，也无需登录。每次克隆时，所有 checkout、worktree 和云沙箱都会包含这些加密文件；唯一需要的输入是 age 私钥。

pnpm secrets（tools/secrets.ts）是唯一接口。在包含此封装工具的仓库中，不要直接调用 sops。

身份

身份范围私钥所在位置可解密
agent用户级每台运行 Agent 的机器上的 ~/.config/sops/age/keys.txt；云沙箱中的 SOPS_AGE_KEYdev.env
personal用户级用户的密码管理器列出其公钥的文件
prod每个项目该项目的生产平台和文档记录的密码管理器条目prod.env

.sops.yaml 按公钥列出接收者。加密不需要私钥；解密或编辑则需要某个接收者的私钥。agent 和 personal 是所有项目共享的本地开发密钥；prod 则按项目单独生成，因此泄露一个部署变量只会暴露一个项目。这些是约定，并不保证一定存在相应接收者。现有仓库可能只使用共享的 dev 和 prod 密钥。选择密钥前，请阅读仓库的机密指南和 .sops.yaml；加密文件的接收者元数据决定了哪些身份可以解密它。

Agent 工作流

开发环境的密钥由你自行管理，无需询问：

pnpm secrets show dev                    # everything, decrypted
pnpm secrets get dev STRIPE_KEY
pnpm secrets set dev STRIPE_KEY sk_test_1
pnpm secrets unset dev STRIPE_KEY
pnpm secrets exec dev -- node apps/worker/src/main.ts

exec 会将解密后的值放入子进程的环境中（覆盖 shell 环境），从中移除 SOPS_AGE_KEY*，转发信号，并以子进程的状态退出。

当已授权的任务需要生产环境密钥时，请自行执行提权。不要要求用户运行命令，也不要要求用户再次确认已授权的任务。

  1. 使用 pnpm secrets exec prod -- true 检查访问权限，该命令不会输出任何密钥值。 仅有现成的 .age/elevated 文件并不能证明其中的密钥可以解密 prod。
  2. 如果访问失败，请阅读仓库的密钥指南和接收方配置。使用文档中指定的账户、保险库、条目和字段来获取匹配的密钥。不要假定使用 Personal 保险库、age-personal 接收方或 CLI 的默认账户。
  3. 自行运行文档中说明的读取命令，并将密钥直接传入包装器： op read 'op://VAULT/ITEM/FIELD' --account ACCOUNT | pnpm secrets elevate。 将占位符替换为查明的标识符；切勿输出密钥。
  4. 使用 pnpm secrets exec prod -- true 确认可以解密，然后继续执行任务。

如果文档中记录的 1Password 位置不存在，请使用 op account list --format json 和 op vault list --account ACCOUNT --format json 来查明正确的账户和保险库。使用 op item list --account ACCOUNT --vault VAULT --format json 搜索该保险库中的条目元数据， 仅检查匹配的条目。后续读取时请传入 --account。Private、Personal 和 Shared 是 不同的名称，不能互换。如果找到了密钥但无法解密，请将其公钥与文件中的接收方进行比较，而不是反复尝试不同的保险库名称。切勿让私钥出现在工具输出中。

仅当任务进展需要用户介入时才询问用户，例如需要解锁 1Password 或授予当前不可用的访问权限。请说明实际阻碍。提权仅适用于当前检出目录，在删除 .age/elevated 前一直有效；不要将其复制到其他工作树。

添加变量时，请将其加入环境变量 schema，以及所有你能够解密的 secrets/<env>.env 文件。如果无法解密 prod，请在 PR 中说明：类型化环境变量检查会导致 prod 启动失败，直到设置该值为止；这正是预期的提示信号。

绝不要将 AGE-SECRET-KEY-... 写入受版本控制的文件、日志或提交中。绝不要将 personal 或 prod 用作云环境。

人工设置

关于一次性步骤（生成密钥、安装 sops 和 age、将 agent 密钥接入 Agent 工具和云沙盒、配置 prod 平台以及轮换密钥），请阅读 references/setup.md。当用户要求你提醒他们这些步骤时，请按顺序引导他们完成该文件中的内容。

关于设计所依赖的 sops 和 age 行为（身份联合、updatekeys、exec-env 的限制、dotenv 的特殊行为），请阅读 references/sops-notes.md。

评论

支持 Markdown