secret

secret

認証情報を読み取らせずに、コーディングエージェントに使わせます。

シェルを使えるエージェントは、.env を cat したり、printenv を実行したり、設定ファイルからトークンを grep したりできます。そうすると値がエージェントのコンテキストやログに入り、プロバイダーのサーバーに送られる可能性もあります。secret を使えば、代わりに認められた方法を使えます。エージェントにはキー名とマスクされた値の長さが表示され、コマンドに必要なキーを選ぶと、値はその子プロセスの環境に直接渡されます。

単独でも組み合わせても使える、3 つの要素があります。

要素	機能
bin/secret	CLI です。KEY=VALUE 形式のストアを解析し（読み込みはしません）、マスクされた名前を表示して、選択したキーを子プロセスに渡し、読み込んだすべての値を子プロセスの stdout と stderr から秘匿します。
hooks/guard-secrets	Claude Code と Codex の PreToolUse フックです。ストアファイルの読み取り、環境変数のダンプ、認証情報を出力するコマンド（gh auth token、security -w、pbpaste、...）、およびストアの内容を出力する検索を拒否します。
skills/secrets/SKILL.md	CLI の使い方と、チャットで値を尋ねずにガードによる拒否から回復する方法をエージェントに伝えます。

これは何ではないか

事故防止の仕組みであり、サンドボックスではありません。 エージェントが習慣や誤操作でシークレットを読み取るのを防ぎます。シェルを使える、意図的なエージェントや侵害されたエージェントは防げません。変換された出力（base64、URL エンコード、部分文字列）は秘匿されず、ガードが解析できないシェルの間接実行は、保護対象のファイルや操作を指定しない限り許可されます。MCP の検索ツールは対象外であり、入力が不正な形式の場合、ガードは判断を下しません（jq がない場合はすべてのリクエストを拒否します）。これは一層の防御として扱い、境界として扱わないでください。

インストール

オプトインの Go CLI と名前のみの MCP

正規のセットアップ手順では、インストール、承認済みのストア参照、クライアントごとの登録、検証、更新、削除について説明しています。v0.3.2 のリリースを準備中です。ここに記載された固定コマンドには公開済みのアセットが必要であり、latest を選択したり、別のバージョンにフォールバックしたりすることはありません。

前提条件：認証済みの GitHub CLI gh と、Unix では curl および Python 3、Windows では curl.exe が必要です。信頼できるチャネルからツールをインストールしてください。プライベートなターミナルでご自身で gh auth login を実行するか、信頼できる認証情報環境を通じて GH_TOKEN を設定し、表示されないようにしてください。トークンをチャットやクライアント設定に貼り付けないでください。

sh -c 'umask 077; d=$(mktemp -d) || exit
curl -fsSL https://raw.githubusercontent.com/avhn/secret/v0.3.2/install.sh -o "$d/install.sh" && sh "$d/install.sh" "$@"
status=$?; rm -rf "$d"; exit "$status"' sh

Windows PowerShell：

& { $ErrorActionPreference = 'Stop'; $d = Join-Path ([IO.Path]::GetTempPath()) ([guid]::NewGuid().ToString('N')); New-Item -ItemType Directory -Path $d | Out-Null
try { irm https://raw.githubusercontent.com/avhn/secret/v0.3.2/install.ps1 -OutFile "$d\install.ps1" -ErrorAction Stop; & (Get-Process -Id $PID).Path -NoProfile -ExecutionPolicy Bypass -File "$d\install.ps1" @args; $status = $LASTEXITCODE }
finally { Remove-Item -LiteralPath $d -Recurse -Force }; exit $status }

これらのダウンロードを先に行うスニペットは、ダウンロードが成功した場合にのみ実行され、クリーンアップ後も失敗を引き継ぎます。インストーラーのフラグは、最後の sh または閉じ中かっこの後に追加してください。詳細はセットアップを参照してください。PowerShell は -NoProfile -ExecutionPolicy Bypass を指定し、同じホストの子プロセスでファイルを実行して、クリーンアップ後に終了コードを引き継ぎます。このバイパスは、その子プロセス 1 つにのみ適用され、永続的なポリシーには影響しません。組織で一元的に適用されるグループポリシーが優先される場合もあります。

インストーラーが secret: GitHub CLI is not authenticated; run gh auth login or set GH_TOKEN, then retry と表示した場合は、プライベートな環境で gh を認証するか、信頼できる環境を修正してから、トークンを貼り付けたり表示したりせずに再試行してください。

ブートストラップでは、検証前に GitHub HTTPS、リポジトリ／タグのガバナンス、レビュー済みのインストーラーを信頼します。どちらも gh を必要とし、チェックサムだけでなくリリースのアテステーションを検証します。SECRET_RELEASE_COMMIT を設定すると、独立して認証された完全な C を任意で固定できます。Unix では curl と Python 3、Windows では curl.exe も必要です。ダウンロードしてレビューしてから実行するか、信頼できるチェックアウトを使用すると、より強固なブートストラップレビューが可能です。インストーラーが公開するのは secret-go ／ secret-go.exe のみで、絶対パスを表示します。Unix では PATH を編集しません。Windows ではそのディレクトリのみをユーザー PATH に追加します。どちらも MCP を登録せず、ストアを読み取らず、フックを有効化しません。生の実行ファイルには、チェックアウト版ランチャーのような実行ごとの再ハッシュはありません。

エージェントに貼り付けてください：https://github.com/avhn/secret/blob/v0.3.2/docs/setup.md に従って secret MCP をインストールして登録してください。正確なストア参照を私に尋ねてください。ストアの検出や読み取り、値の取り扱い、ガードの回避は決して行わないでください。

対象	サポート状況と根拠
Go CLI	v0.3.2 は Linux、macOS、Windows の amd64／arm64 を対象としています。新しいネイティブ候補／公開インストールのゲートは引き続き必須です。v0.2.3 の Linux／macOS 向け公開は完了しています。
ローカル stdio MCP	オプトイン方式の mcp --store STORE_REFERENCE。list/show/diff/health のみで、値は扱いません。メタデータから名前、ラベル、パス、アカウント ID が明らかになる可能性はあります。
デスクトップバンドル	secret-v0.3.2-desktop.mcpb：macOS ユニバーサル版と Windows amd64 版。ロック済み CLI／ネイティブのスモーク検証は、ホスト上での Desktop インストール検証ではありません。
レジストリ	名前は io.github.avhn/secret。公開は個別に所有者の承認が必要であり、ここでは公開済みとは主張していません。
プラグインとフック	4 つすべてのマニフェストは 0.3.2 です。インストール済みフックは引き続き Bash ガードです。M4.1 の Go 有効化はスポンサー待ちであり、ホスト側でフェイルクローズするとは主張していません。

ピン留め、依存関係、オフライン利用オプション、障害からの復旧については、インストールとロールバックを参照してください。また、リリースの承認も参照してください。

Bash CLI、ガード、スキル（インストール時のデフォルト）

要件：bash 3.2 以降（macOS 標準の bash で動作）、perl、およびガード用の jq が必要です。これらは、オプトインの Go 実行ファイルおよび MCP の登録とは別のままです。

CLI：

git clone https://github.com/avhn/secret ~/.local/share/secret
ln -s ~/.local/share/secret/bin/secret ~/.local/bin/secret

Claude Code プラグインとしてのガードとスキル：

/plugin marketplace add avhn/secret
/plugin install secret@secret

Codex CLI では、このリポジトリの Codex マーケットプレイスからプラグインをインストールしてください。このプラグインにはガードとスキルが含まれており、~/.codex/hooks.json は変更されません。

codex plugin marketplace add avhn/secret
codex plugin add secret@secret

Codex で /hooks を開き、インストールされたシークレットフックを信頼してから使用してください。信頼されていないフックは一覧に表示されますが、実行されません。フックが変更された場合は、内容を確認して再度信頼してください。インストール済みプラグインは /plugins で確認できます。このプラグインは bin/secret を PATH に追加しません。CLI を使う場合は別途インストールしてください（シンボリックリンクを使うには ~/.local/bin が PATH に含まれている必要があります）。

mkdir -p ~/.local/bin
# If you have not already cloned the repo in the CLI step above:
git clone https://github.com/avhn/secret ~/.local/share/secret
ln -s ~/.local/share/secret/bin/secret ~/.local/bin/secret

お使いの Codex バージョンがプラグインマーケットプレイスに対応していない場合は、このリポジトリをチェックアウトして手動でインストールしてください。フックのテンプレートを絶対パス付きのコマンドに書き換えてコピーし、ユーザースキルのルートにスキルをインストールします。

mkdir -p ~/.codex ~/.codex/skills
jq --arg command "$HOME/.local/share/secret/hooks/guard-secrets" \
  '.hooks.PreToolUse[].hooks[].command = $command' \
  ~/.local/share/secret/codex/hooks.json >~/.codex/hooks.json
ln -s ~/.local/share/secret/skills/secrets ~/.codex/skills/secrets

~/.codex/hooks.json がすでにある場合は、ファイルを置き換えるのではなく、PreToolUse グループを統合してください。Codex は config.toml 内のインライン [hooks] も受け付けます。この例では、ファイルを変更せずにコピーできるよう hooks.json を使用しています。手動で設定したフックも信頼するために、/hooks を開いてください。Codex はシェルコマンドを Bash フック名で、パッチを apply_patch で送信します。ガードを実行するには、フックの PATH に jq と perl が必要です。

ripgrep にはストアファイルを除外するよう指定できるため、ガードでは通常の rg が許可されています。保護用の設定をインストールするか、グロブを既存の設定に統合してください。

mkdir -p ~/.config/ripgrep
cp ~/.local/share/secret/examples/ripgreprc ~/.config/ripgrep/config
export RIPGREP_CONFIG_PATH="$HOME/.config/ripgrep/config"  # in your shell profile

ステージング中の Go CLI でのオプトイン age ストア

M5d では、Linux/macOS 上で明示的に age:NAME を指定する暗号化ファイルストアを追加します。レビュー済みの filippo.io/age v1.3.2 を使用し、ストア全体の読み取りを認証し、暗号文のみをアトミックに書き込みます。age-init は既存のものを変更せず新規作成のみを行い、age-rekey は新しい ID を公開前に検証します。どちらも実際の端末と、対象の明示的な確認が必要です。キー ファイルは HOME/.secrets/.age-keys/ 内でプライベートな状態にする必要があり、値を読み取るコマンドでは --age-identity FILE の明示的な指定が必要です。名前のみを扱うインターフェースでは ID は不要ですが、外部メタデータは認証されません。list --backend age を使用してください。デフォルトの検出方法と Bash CLI に変更はありません。M5a の個別の Windows CLI ゲートは通過していますが、Windows での age ファイルシステム操作には引き続き対応していません。age のセットアップ、移行、復旧、制限事項を参照してください。M5d は PR #28 でホスト型ゲートに合格しましたが、これはフックを有効化するものでも、公開を許可するものでもありません。

使用方法

ストアはKEY=VALUE形式の行を使用します。デフォルトでは~/.secrets.envと~/.secrets/*.secretを使います（SECRETS_ENVとSECRETS_DIRで変更できます）。[env=dev,region=eu]のような正確なセクションヘッダーは、後続の割り当てのスコープになります。[]でラベルなしに戻ります。それ以外の角括弧で囲まれた行は無視されます。ラベルには識別子名を使用し、値には英字、数字、アンダースコア、ピリオド、ハイフンを使用できます（先頭には英字、数字、またはアンダースコアを指定します）。ラベル付きファイルは、ほかのツールでは通常のdotenv形式ではなくなります。古いバージョンのsecretはすべてのセクションを単一のフラットなストアとして読み取るため、ヘッダーを追加する前にアップグレードしてください。

secret list                                   # store paths, never contents
secret show ~/.secrets.env                    # API_TOKEN=<40 bytes>
secret stash ~/.secrets.env API_TOKEN         # hidden prompt, atomic write
secret run -f ~/.secrets.env --key API_TOKEN -- ./deploy.sh
secret show --env dev ~/.secrets.env          # selected masked keys and unset keys
secret stash --env dev ~/.secrets.env API_TOKEN
secret run -f ~/.secrets.env --env dev --key API_TOKEN -- ./deploy.sh

明示的なkeychain:NAMEとlibsecret:NAMEの参照ではキーストアを使用します。file:PATHは、バックエンド参照のように見えるパスも含め、文字どおりのファイルパスを指定します。プレフィックスのない名前やパスでは、引き続きファイルストアが使用されます。キーストア名には英字、数字、アンダースコア、ピリオド、ハイフンのみを使用でき（先頭は英数字またはアンダースコア）、名前の途中で使用できます。各キーストアには、キー名、正規化されたラベル、ランダムなアカウント識別子のみを含み、値は一切含まない、非公開でアトミックに書き込まれる~/.secrets/NAME.keysマニフェストがあります。listとshowはマニフェストのみを使用します。showではバイト数の代わりに<stored>が表示されます。runとexecはキーを選択する前に登録済みのすべての項目を読み込むため、検索に失敗すると子プロセスは停止し、runでは選択されていない環境の値もマスキングできます。getとclipは選択した項目のみを取得します。バックエンドへの書き込みが成功した後にマニフェストの公開に失敗すると、キーストアに登録されていない項目が残ることがあります。

Linuxでは、libsecret:NAMEはsecret-toolとロック解除済みのSecret Serviceセッションを使用します。値は標準入力を通じてプロバイダーに送信され、非公開ファイルに取得されます。stashでは、末尾の改行がない値、または末尾に改行が1つある値を受け付けます（改行は削除されます）。空の値、埋め込み改行またはCR、NUL、先頭または末尾の空白、引用符で囲まれた値は拒否されます。macOSでは、keychain:NAMEはユーザーのデフォルトのKeychain、または明示的に指定されたSECRET_KEYCHAINの絶対パスを使用します（使用できる文字は英字、数字、_、.、/、-のみです。引用符が必要なパスは拒否されます）。値はsecurity -iの標準入力コマンドに16進数でエンコードされ、プロセス引数に含まれることはありません。Keychainのstashでは、Unicodeの制御文字や行区切りを含まない、印字可能なUTF-8テキストを受け付けます。security -wはテキストインターフェイスのため、この範囲外の値は拒否されます。マニフェストの公開前に、非公開ファイルへの読み戻し結果が元の値と一致する必要があります。読み取り時には、security -wが追加した改行1つだけを削除します。分離されたテストにはテスト用スタブを引き続き使用できます。実際の認証情報には決して使用しないでください。

--env devは--label env=devを意味します。複数のラベルを選択するには、--label name=valueを繰り返し指定します。セレクターを指定しない場合、ラベルなしのレコードのみが対象になります。キーごとに、最も具体的に一致するラベルセットが選ばれます。同じ具体性で異なる候補が一致した場合は、曖昧さとしてエラーになります。セレクターなしでshowを実行すると、正規化されソートされたラベルとマスクされた長さとともに、すべてのレコードが一覧表示されます。stashは完全に一致するラベルセットのみを更新します。getとclipはrunと同じレコードを選択します。

runは選択したキーのみをエクスポートします（--keyは必須、--optional-keyは任意です。セレクターを指定しない場合はすべてのキーがエクスポートされます）。また、子プロセスの出力に含まれる読み込み済みの値をすべて<redacted>に置き換えます。子プロセスが値を自身のargvに含めるとプロセス一覧に表示されるため、値は標準入力で渡すことを推奨します。

secret run -f ~/.secrets.env --key API_TOKEN -- bash -c \
  'printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -fsS -H @- https://api.example.test'

人間専用のコマンドは、ガードによってエージェントからの実行が拒否されます。

• secret get FILE KEYは値を出力します。ただし、出力先はターミナルに限られます。
• secret exec ...はマスキングを行わないrunです。バイト単位で正確な標準入出力を必要とする対話型ツールやMCPサーバーの起動ツール向けです。

secret clip FILE KEY [SECONDS]は値をクリップボードにコピーし、その後別の内容をコピーしていなければ45秒後にクリップボードを消去します。値がエージェントの出力に含まれることはないため、ガードによって許可されます。スキルは、クリップボードへのコピーを依頼された場合に限って使用するようエージェントに指示し、クリップボードの内容を読み戻す操作は拒否します。

終了ステータスを含むリファレンス全体を確認するには、secret helpを実行してください。

段階的な Go オペレーターワークフロー（M3）

M3 はホスト型 CI ゲートに合格しました（PR #8）。これらのコマンドは Go CLI に実装されていますが、出荷される bin/secret は引き続き Bash です。これは CLI やプラグインの切り替えではありません。段階的な CLI を試すには、 go build -o /absolute/private/build/secret-go ./cmd/secret を実行してください。 以下の例では、このバイナリに secret-go、ストアのパスにプレースホルダーを使用します。 オペレーターはエージェントツール経由ではなく、必ずご自身のターミナルから直接実行してください。

secret-go import --from dotenv:/absolute/source.env --into file:/absolute/team.secret
secret-go import --from op:OPAQUE_ID --into file:/absolute/team.secret --map password=API_TOKEN
secret-go export --from file:/absolute/team.secret --to libsecret:team --on-conflict=fail
secret-go rotate file:/absolute/team.secret API_TOKEN --env prod
secret-go rename file:/absolute/team.secret API_TOKEN SERVICE_TOKEN --env prod
secret-go delete file:/absolute/team.secret SERVICE_TOKEN --env prod
secret-go show --format=json file:/absolute/team.secret
secret-go diff --format=json --env dev --env prod file:/absolute/team.secret
secret-go doctor --format=json libsecret:team

オペレーターはストアにアクセスする前に、stdin と stdout の両方がターミナルであることを必要とします。その後、制御ターミナル上で、対象／キー／ラベルの各識別情報について、正確な非表示の確認を求めます。 --yes、パイプ経由の確認、オペレーター用 JSON はありません。ローテーションでは新しい値を非表示で読み取り、argv には決して含めません。ライフサイクルラベルは、対象レコードを正確に識別します。参照には file:ABS_PATH、keychain:NAME、libsecret:NAME のいずれかを明示する必要があります。インポート／エクスポートは挿入のみです。op／bw のインポートには、フィールドの対応付けを明示する必要があります。エクスポートには --on-conflict=fail、実装済みの異なるキーストアの宛先、およびラベル付きレコードの明示的なセレクターが必要です。セレクターがない場合は、ラベルのないレコードのみが対象となります。 --dry-run は名前／競合のみを一覧表示し、実際のターミナルも引き続き必要です。 Doctor は追跡対象の復旧候補と手動検証のガイダンスを報告しますが、過去に生じた孤立データの完全な一覧や、インストール済みホストの信頼性を証明するものではありません。

プライベートテンプレートでは、リテラルの {{KEY}} プレースホルダーと、選択したキーのみを使用します。

secret-go run -f file:/absolute/team.secret --key API_TOKEN \
  --template-file /absolute/client.template -- ./consumer

子プロセスには、レンダリング済みのパスを SECRET_TEMPLATE_FILE で渡します。ファイルの内容を argv で渡すことはありません。出力では、読み込まれたすべてのリテラル値が引き続き伏せられます。ファイルは SECRETS_DIR とは無関係に、固定の HOME/.secrets/.rendered/<random>/payload の下に、0700 のディレクトリと 0600 のペイロードで配置されます。存在しない／選択されていないプレースホルダー、安全でないエイリアス、exec、出力ディレクトリのオプションは拒否されます。スーパーバイザーは、通常終了、エラー、捕捉可能なシグナルによる終了時のクリーンアップに先立ち、プロセスグループを停止します。SIGKILL、クラッシュ、電源喪失によって、保護された平文が残る可能性があります。クリーンアップはベストエフォートであり、安全な消去を保証するものではありません。

list/show --format=json、diff、doctor、補完、監査クエリが公開するのはメタデータのみで、値、ハッシュ、長さは公開しません。メタデータからは、キー名、ラベル、バックエンドの種類、ストアのパス、プロバイダーのアカウント ID が明らかになる場合があります。従来のテキスト形式の show では、伏せられたバイト長と並び順が維持されます。補完が出力するのはシェルコードではなくリテラルの候補であり、明示された -f スコープのみを読み取ります。監査は、オペレーターに --audit-dir ABS_PATH が渡されない限り無効です。audit --directory ABS_PATH --format=json でクエリできます。名前のみのイベントは、1 MiB を上限とするプライベートな 0600 ファイル 4 個にローテーションして記録されます。

MCP は、たとえば secret-go mcp --store file:/absolute/team.secret --store libsecret:team のように明示的に許可リストへ登録するまで無効です。stdio サーバーが公開するのは list/show/diff/health のみで、値や変更操作は公開しません。リクエストによって、この明示された許可リストを拡張することはできません。これを設定すると、上記のパスおよびアカウントのメタデータがクライアントに届く可能性があります。ネットワークリスナーや、暗黙的なストアの検出は有効になっていません。変更されていないインストール済みフックは、新しいサブコマンドを名前のみのものも含めて保守的に拒否します。この機能によって、エージェントにフックの例外が付与されることはありません。M5a のネイティブ Windows CLI、コンソール、ストレージ、Job、Credential Manager のゲートは合格しました。Windows のサポートには制限事項と、別途保留中のリリースアセットの証拠が記載されています。インストール済みホストの保護は保証されません。ゲートについては CONTRIBUTING.md、実装の契約については M3 の計画を参照してください。

テスト

bash tests/test-secret.sh   # CLI matrix, needs perl, python3 and rg
bash tests/test-backends.sh # disposable keystore stub matrix
bash tests/test-guard.sh    # guard matrix, needs jq

テストスイートでは、使い捨てディレクトリと合成値のみを使用します。CI では、標準の /bin/bash 3.2 を含め、Linux と macOS でテストを実行します。

開発

Go への書き換えは進行中です。ROADMAP.mdでマイルストーンを追跡してください。 セットアップと PR のガイダンスについては CONTRIBUTING.md、コーディングエージェントのルールについては AGENTS.mdを参照してください。

ライセンス

GPL-3.0-or-later、著作権者 Mert Dede。

1Password のスキャフォールディング（無効）

ステージング中の Go 実装には、テスト専用の読み取り専用 1Password スキャフォールディングが含まれています。 プロバイダーを隔離した状態でのエビデンス収集とライセンスレビューが完了するまで、デフォルトでの登録、検出、読み取りは無効になっています。 有効化するための環境変数はありません。 Bash CLI、インストール済みのフック、プラグインマニフェストに変更はありません。 契約と制限事項を参照してください。Bash CLI の接続先に Go v2 マニフェストを指定しないでください。