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 の使用

このレイアウトを使用するリポジトリでは、デプロイ環境ごとに 1 つずつ、sops で暗号化した dotenv ファイルとしてシークレットを Git にコミットします。ファイルは secrets/dev.env と secrets/prod.env です。ファイルの復号には age の ID を使用します。.env も、シークレットサービスも、ログインセッションもありません。すべてのチェックアウト、ワークツリー、クラウドサンドボックスには、クローン時点で暗号化ファイルがあります。必要な入力は age の秘密鍵だけです。

pnpm secrets（tools/secrets.ts）が唯一のインターフェースです。ラッパーがあるリポジトリでは、sops を直接実行しないでください。

ID

ID範囲秘密鍵の保存場所復号できるファイル
agentユーザー共通エージェントが実行される各マシンの ~/.config/sops/age/keys.txt。クラウドサンドボックスでは SOPS_AGE_KEYdev.env
personalユーザー共通ユーザーのパスワードマネージャー公開鍵が記載されたファイル
prodプロジェクトごとそのプロジェクトの本番プラットフォームと、パスワードマネージャーに記録された項目prod.env

.sops.yaml には公開鍵による受信者が記載されています。暗号化には秘密鍵は必要ありませんが、復号や編集には受信者のいずれかの秘密鍵が必要です。agent と personal はすべてのプロジェクトで共有するローカル開発用の鍵です。prod はプロジェクトごとに生成されるため、デプロイ用変数が漏えいしても、影響を受けるのは 1 つのプロジェクトだけです。これらは運用上の慣例であり、受信者が必ず存在するとは限りません。既存のリポジトリでは、共有の dev 鍵と prod 鍵のみが使われている場合があります。鍵を選ぶ前に、リポジトリのシークレットガイドと .sops.yaml を確認してください。どの ID で復号できるかは、暗号化ファイルの受信者メタデータによって決まります。

エージェントのワークフロー

開発用シークレットは、許可を求めずに自分で管理できます。

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 は復号した値を子プロセスの環境変数として設定し（シェルの環境変数より優先）、SOPS_AGE_KEY* を削除し、シグナルを転送して、子プロセスの終了ステータスで終了します。

許可済みのタスクで本番用シークレットが必要になった場合は、自分で権限を昇格してください。ユーザーにコマンドの実行や、すでに許可されたタスクの再確認を求めてはいけません。

  1. pnpm secrets exec prod -- true でアクセスを確認します。このコマンドはシークレットの値を一切表示しません。.age/elevated ファイルが存在するだけでは、そのファイルの鍵で本番環境を復号できる証明にはなりません。
  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 を削除するまで有効です。別のワークツリーにコピーしてはいけません。

変数を追加するときは、環境変数スキーマと、復号できるすべての secrets/<env>.env に追加します。本番環境を復号できない場合は、PR でその旨を明記してください。値を設定するまで型付き環境変数チェックが本番環境の起動を失敗させますが、これは意図された通知です。

AGE-SECRET-KEY-... を追跡対象のファイル、ログ、コミットに書き込んではいけません。クラウド環境に personal や prod を含めてはいけません。

ユーザーによる設定

鍵の生成、sops と age のインストール、agent 鍵のエージェントツールとクラウドサンドボックスへの設定、本番プラットフォームの設定、鍵のローテーションなど、一度だけ行う手順については references/setup.md を読んでください。ユーザーから手順の再確認を求められた場合は、そのファイルの順に案内してください。

設計で前提としている sops と age の動作（ID の統合、updatekeys、exec-env の制限、dotenv の癖）については、references/sops-notes.md を読んでください。

コメント

Markdown 対応