セキュリティモデル（AI安全設計）

secretctl は「Access Without Exposure」原則に従い、AI エージェントがシークレットを見ることなく使用できるようにします。

コア原則

1. AI エージェントは平文のシークレットを受け取ることがない
2. シークレットは実行時に環境変数として注入される
3. コマンド出力は漏洩したシークレットを編集するために自動的にサニタイズされる
4. ポリシーファイルが AI が実行できるコマンドを制御する

この設計は、シークレット管理の業界ベストプラクティスに沿っています。

仕組み

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│  AI Agent   │────▶│ secretctl MCP    │────▶│   Command   │
│ (Claude)    │     │ Server           │     │ (aws, etc)  │
└─────────────┘     └──────────────────┘     └─────────────┘
       │                    │                       │
       │  "Run aws s3 ls    │  Inject secrets      │
       │   with aws/*"      │  as env vars         │
       │                    │                       │
       ▼                    ▼                       ▼
   シークレット値        シークレットと         安全に環境変数
   を見ない             ポリシーを管理          を受け取る

AI エージェントができること

機能	説明
シークレット一覧	キー名とメタデータを見る（値ではない）
存在確認	シークレットキーが存在するか確認
マスク値取得	末尾4文字のみ表示（****WXYZ）
コマンド実行	シークレット注入で許可されたコマンドを実行

AI エージェントができないこと

制限	理由
平文の読み取り	secret_get ツールが存在しない
ブロックされたコマンドへのアクセス	ポリシー適用
出力サニタイズのバイパス	自動編集
任意のコマンド実行	許可リストのみのポリシー

ポリシー設定

デフォルト拒否

ポリシーでは常に default_action: deny を使用:

version: 1
default_action: deny  # 推奨
allowed_commands:
  - aws
  - gcloud
  - kubectl

デフォルトでブロックされるコマンド

default_action: allow でも、これらのコマンドは常にブロック:

• env - すべての環境変数を漏洩する可能性
• printenv - すべての環境変数を漏洩する可能性
• set - シェル状態を漏洩する可能性
• export - すべてのエクスポートを漏洩する可能性

拒否コマンド

危険なコマンドを明示的に拒否:

denied_commands:
  - rm
  - dd
  - mkfs

出力サニタイズ

secret_run でコマンドが実行されると、出力はシークレット値について自動的にスキャンされます。マッチした箇所は [REDACTED:key] に置換されます。

例:

aws/secret_key に AKIAIOSFODNN7EXAMPLE が含まれている場合:

# オリジナル出力
Access key: AKIAIOSFODNN7EXAMPLE

# サニタイズ後の出力
Access key: [REDACTED:aws/secret_key]

制限事項

出力サニタイズは完全一致を使用します。以下は検出されません:

• Base64 エンコードされたシークレット
• Hex エンコードされたシークレット
• 部分文字列のマッチ

脅威カテゴリ

secretctl の AI安全設計はこれらの脅威カテゴリから保護します:

1. 直接シークレット公開

脅威	保護	状態
AI が平文シークレットを要求	secret_get ツールが存在しない	✅ 軽減
AI がコマンド出力から抽出	出力サニタイズ	✅ 軽減
AI が部分データから推測	固定長マスキング（****WXYZ）	✅ 軽減

2. プロンプトインジェクション攻撃

脅威	保護	状態
悪意のあるプロンプトがシークレットを要求	ツールレベルの制限	✅ 軽減
secret_run への注入コマンド	コマンド許可リストポリシー	✅ 軽減
エンコードされたシークレット抽出	検出されない（制限事項参照）	⚠️ 未軽減

3. コマンド実行リスク

脅威	保護	状態
環境変数ダンプ	env/printenv/set ブロック	✅ 軽減
シェルエスケープシーケンス	コマンド検証	✅ 軽減
タイムアウト/リソース枯渇	300秒タイムアウト、リソース制限	✅ 軽減
任意のコマンド実行	デフォルト拒否ポリシー	✅ 軽減

4. 間接的な開示

脅威	保護	状態
タイミング攻撃	該当なし（ローカルのみ）	N/A
出力長によるサイドチャネル	固定マスキング形式	✅ 軽減
モデル学習データ漏洩	AI に平文を渡さない	✅ 軽減

サニタイズ詳細

サニタイズはコマンド出力でシークレット値を置換するために完全一致を使用します。

検出されるもの

パターン	例	置換
完全一致	AKIAIOSFODNN7EXAMPLE	[REDACTED:aws/key]
JSON 出力内	{"key": "secret123"}	{"key": "[REDACTED:api/key]"}
URL 内	https://api.example.com?token=abc123	[REDACTED:api/token]

検出されないもの

⚠️ 既知の制限事項:

パターン	例	検出されない理由
Base64 エンコード	QUtJQUlPU0ZPRE5ON0VYQU1QTEU=	完全一致のみ
Hex エンコード	414b494149...	完全一致のみ
URL エンコード	%41%4B%49%41...	完全一致のみ
部分一致	シークレットの最初の10文字	完全一致のみ
大文字小文字の違い	SECRET123 vs secret123	大文字小文字を区別
分割出力	SEC + RET123（行をまたぐ）	単一パス検出
圧縮データ	gzip/deflate エンコード	バイナリは未スキャン

サニタイズのタイミング

コマンド実行 → stdout/stderr キャプチャ → サニタイズ実行 → 結果を AI に
                                                    ↑
                                           すべてのシークレット値をチェック

重要: サニタイズはコマンド完了後に発生します。シークレットはサブプロセスに公開されますが、AI には返されません。

ベストプラクティス

1. 強力なマスターパスワードを使用 - MCP サーバーはマスターパスワードを要求
2. 許可コマンドを制限 - 実際に必要なコマンドのみを許可
3. 定期的にポリシーをレビュー - 許可コマンドリストを監査
4. キープレフィックスを使用 - シークレットをプレフィックスで整理（例: aws/, db/）
5. 有効期限を設定 - 機密シークレット設定時に --expires を使用
6. 監査ログを監視 - secretctl audit list で異常なアクティビティを確認
7. シークレットのエンコードを避ける - base64/hex エンコードされた値をシークレットとして保存しない
8. 短命トークンを使用 - 長期間有効な認証情報より有効期限付きトークンを優先