Claude Code のシークレット管理とトラスト境界設計 — エージェント時代の秘匿情報ハンドリング本番ガイド

シークレット注入の3パターンと使い分け

ローカル開発で実用的な注入パターンは、ほぼ次の3つに集約されます。

パターン A: .env 直書き（最低限の防御）

最もシンプルですが、最もリスクが高い方法です。導入は容易ですが、.gitignore への追加と、コミット時のスキャンを必須にする前提で使います。

# .env (Git管理外)
ANTHROPIC_API_KEY=sk-ant-XXXXXXXXXXXX
 
# 起動時に読み込む（npm script例）
"scripts": {
  "start": "node --env-file=.env server.js"
}

.gitignore に .env と .env.* を必ず追加し、後述する pre-commit フックでパターンを検出するのが最低条件です。この方法は試作・検証フェーズには許容できますが、本番アプリケーションで継続使用するべきではありません。

パターン B: 1Password CLI / Doppler によるオンデマンド注入（推奨）

シークレットを保管庫に置いておき、コマンド実行のたびにメモリ上に展開する方式です。私が最も多用している構成で、流出時の影響範囲を「そのプロセスが生きている間」に限定できます。

# 1Password CLI を使う例
# 事前に op signin で認証しておく
op run --env-file=.env.template -- npm run start
 
# .env.template の中身（実値ではなく参照）
ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key
DATABASE_URL=op://Personal/Supabase/connection-string

このやり方の優れている点は、.env.template を Git にコミットしてもキー本体は流出しないことです。また op run 終了時にプロセス環境からシークレットが消えるため、レイヤー 4 への滞在時間が最小化されます。Doppler を使う場合も同様で、doppler run -- npm start の形で透過的に注入できます。

パターン C: 起動時に OS Keychain から読み出す（個人開発向け）

macOS で完結する個人開発なら、security コマンド経由で Keychain から取り出すのが軽量かつ安全です。

#!/usr/bin/env bash
# scripts/start-with-keychain.sh
 
set -euo pipefail
 
# Keychain から取得（事前に security add-generic-password で登録済み）
ANTHROPIC_API_KEY=$(security find-generic-password \
  -a "$USER" \
  -s "anthropic-api-key" \
  -w 2>/dev/null) || {
    echo "❌ Anthropic API key not found in Keychain" >&2
    exit 1
  }
 
# サブシェルでのみ環境変数を露出させる
ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" exec node server.js

exec を使うことで現在のシェルの環境を汚染せずプロセスを置き換えられる点と、set -euo pipefail で取得失敗時に即座に止まる点がポイントです。エラーハンドリングを省略すると「キーが空のまま起動してしまう」事故が起きやすいので、必ず取得失敗を検出するようにします。

3 パターンの選び方は、運用するアプリケーションの数 × 関与する人数でほぼ決まります。アプリケーション 1〜2 個で個人なら C、複数個で個人なら B、チームなら無条件で B（または HashiCorp Vault のような中央集権方式）を選びます。

MCP サーバーへのシークレット引き渡し設計

MCP サーバーにシークレットを渡す場面は、設計の最大の悩みどころです。claude_desktop_config.json の env フィールドに直書きする例が公式ドキュメントで多用されているため、それをそのまま採用してしまいがちですが、ここには注意点があります。

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_XXXXXXXXXXXXX"
      }
    }
  }
}

このファイルはホームディレクトリ直下にあるため、別のエージェントセッションや、うっかりエディタで開いて画面共有している瞬間に晒されるリスクがあります。私は次のラッパースクリプト方式に切り替えました。

{
  "mcpServers": {
    "supabase": {
      "command": "/Users/me/.claude/mcp-launchers/supabase.sh",
      "args": []
    }
  }
}

#!/usr/bin/env bash
# ~/.claude/mcp-launchers/supabase.sh
set -euo pipefail
 
# Keychain or 1Password CLI から取り出す
TOKEN=$(security find-generic-password -a "$USER" -s "supabase-access-token" -w 2>/dev/null) || {
  echo "FATAL: supabase token missing" >&2
  exit 1
}
 
export SUPABASE_ACCESS_TOKEN="$TOKEN"
exec npx -y @supabase/mcp-server-supabase "$@"

このラッパー設計には3つの利点があります。第一に claude_desktop_config.json 自体には機密が一切載らないため、誤ってチームと共有しても安全です。第二に、ラッパー側にロギング・監査・許可確認のフックを後から追加できます。第三に、シークレットローテーション時の差し替えがラッパー単体で完結します。

環境変数の読み込み順序や .env ファイルが読まれない事象に出会ったときの対処は Claude Code の環境変数設定とフラグ運用ガイド でまとめていますので、ラッパー設計と合わせて参照してください。

流出を機械的に防ぐ — pre-commit と PreToolUse の二段構え

人間の注意力に頼ったシークレット保護は破綻します。私は Git コミット境界 と エージェント実行境界 の2箇所に自動チェックを置いています。

Git コミット境界: pre-commit フック + gitleaks

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail
 
# gitleaks がインストールされていない場合は警告のみ
if ! command -v gitleaks >/dev/null 2>&1; then
  echo "⚠️  gitleaks not installed — skipping secret scan" >&2
  exit 0
fi
 
# ステージングされた変更のみスキャン
gitleaks protect --staged --redact --verbose || {
  echo "" >&2
  echo "🚨 Potential secret detected in staged changes" >&2
  echo "   Review the output above. To bypass intentionally:" >&2
  echo "   git commit --no-verify   (use with extreme caution)" >&2
  exit 1
}

--redact を付けるとログ出力でシークレットの本体が伏字になるため、CI 失敗時のログから二次流出する事故を防げます。--no-verify でのバイパスは「自分で実害を確認した上での意図的な操作」のみに限定し、ペアレビューを通すルールにしておくと安全です。

エージェント実行境界: PreToolUse フック

Claude Code の PreToolUse フックを使うと、Bash 実行や File 読み取りの直前にシェルスクリプトを差し挟めます。シークレットを露出させる典型的な操作をブロックする例です。

#!/usr/bin/env bash
# .claude/hooks/pretooluse-bash-secret-guard.sh
# Claude Code が Bash ツールを呼び出す前に評価される
 
set -euo pipefail
 
# stdin から JSON を受け取る（Claude Code の仕様）
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
 
# 危険パターン: 環境変数全表示・credentials の cat・curl で外部送信
DANGER_PATTERNS=(
  'printenv($|[^A-Z_])'
  '\benv\b\s*$'
  'cat\s+.*\.env'
  'cat\s+.*credentials'
  'curl\s+.*-d\s+.*\$\{?[A-Z_]+API_KEY'
  'echo\s+.*\$\{?[A-Z_]+_(KEY|TOKEN|SECRET)'
)
 
for pattern in "${DANGER_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qE "$pattern"; then
    cat <<JSON
{
  "decision": "block",
  "reason": "Command matches secret-exposure pattern: $pattern. If intentional, run manually outside Claude Code."
}
JSON
    exit 0
  fi
done
 
# 通過
echo '{"decision": "approve"}'

.claude/settings.json に次のように登録します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/pretooluse-bash-secret-guard.sh" }
        ]
      }
    ]
  }
}

このフックは「正しい使い方を妨げないか？」のチューニングが鍵です。最初は誤検知を許容して走らせ、ログを見ながら正規表現を磨いていく運用が現実的です。

なお Claude Code の .env がそもそも読み込まれない・反映されないというトラブルに当たったときは、.env が読み込まれないときの診断ガイド の手順で切り分けると早く解決できます。

ローテーションと監査ログを軽量に回す

完璧なローテーション運用は重く、個人開発だと続きません。私は次の3点だけを最低ラインにしています。

第一に、ローテーションのトリガーをカレンダーで自動化します。具体的には Cowork のスケジュールタスクで「90 日ごとに『API キーを再発行して 1Password に登録する』というリマインダーを TODO 化する」処理を仕込み、人手では覚えない仕組みに寄せています。

第二に、監査ログを構造化 JSON で残す。MCP ラッパー内で「いつ・どのキーを・どのプロセスが取り出したか」を記録します。

# ラッパーにログ追記する例
LOG_FILE="$HOME/.claude/logs/secret-access.jsonl"
mkdir -p "$(dirname "$LOG_FILE")"
 
jq -n \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg key "supabase-access-token" \
  --arg pid "$$" \
  --arg parent "${PPID:-unknown}" \
  '{ts: $ts, key: $key, pid: $pid, parent_pid: $parent}' \
  >> "$LOG_FILE"

JSONL 形式にしておくと jq で横断検索でき、不審な読み出しタイミング（深夜の連続アクセスなど）を後から発見できます。

第三に、漏洩発覚時の手順書をテキストで保管しておきます。インシデント対応では落ち着いて手を動かす能力よりも、決まった順番を機械的に実行する仕組みの方が役に立ちます。「キーをコンソールで失効 → 1Password を更新 → 関連プロセスを再起動 → 監査ログで影響範囲を特定」のような順序を、runbooks/secret-leak.md にチェックリストで置いておくと冷静さを保てます。

よくある落とし穴 5 選

ここまでの設計を実装するなかで、私が実際にハマった落とし穴を 5 つ共有します。

① claude_desktop_config.json を Git に追加してしまう: Cowork や Claude Code の設定をチームと共有したい欲求は強いのですが、env フィールドに本物のキーが入ったままコミットしがちです。共有用と個人用を claude_desktop_config.shared.json と claude_desktop_config.local.json に分け、起動スクリプトでマージするのが安全です。

② シェルヒストリーへの記録: export API_KEY=xxx を直接打つと ~/.bash_history に残ります。HISTCONTROL=ignorespace を設定し、機密を含むコマンドは行頭に空白を入れて実行する習慣をつけてください。

③ ログファイルへの実値書き込み: アプリのデバッグログに console.log(process.env) を入れると環境変数が丸ごと出力され、CI のアーティファクトに残ります。本番では process.env のシリアライズを禁止する eslint ルールを入れる価値があります。

④ MCP サーバーの過剰権限: たとえば Supabase MCP に Service Role Key を渡すと RLS をバイパスできてしまうため、エージェントが誤って全テーブルを読めます。可能な限り Anon Key と適切な RLS ポリシーで運用し、本当に管理権限が必要な操作は別の MCP サーバーに切り出す設計が望ましいです。

⑤ シークレット名の予測可能性: OPENAI_API_KEY や STRIPE_SECRET_KEY はパターンマッチで一発で見つかります。ラッパー側の環境変数名を INTERNAL_AI_PROVIDER_TOKEN のように汎用化することで、流出時の即時悪用ハードルを少しだけ上げられます。気休めではありますが、攻撃側のコストを増やすことには意味があります。

このあたりの脆弱性スキャンを CI に組み込むやり方は Claude Code でのセキュリティ脆弱性スキャン実装ガイド でも触れていますので、本記事の設計と組み合わせるとカバー範囲が広がります。

マルチサイト運用での実装例

最後に、私が運用している 4 つのサイト（Claude Lab / Gemini Lab / Antigravity Lab / Rork Lab）でのシークレット構成を、参考までに共有します。

サイトごとに独立した GitHub Personal Access Token を用意し、それぞれを 1Password の独立した Vault に保管しています。op:// 参照を使った .env.template をリポジトリにコミットすることで、新しい開発環境を立ち上げるときも op run --env-file=.env.template -- npm install だけでビルド可能になります。

# .env.template (Git管理対象)
GITHUB_TOKEN=op://Dolice-Labs/Claude-Lab-PAT/token
ANTHROPIC_API_KEY=op://Dolice-Labs/Anthropic/api-key
STRIPE_SECRET_KEY=op://Dolice-Labs/Stripe-Claude-Lab/secret-key
KV_NAMESPACE_ID=op://Dolice-Labs/Cloudflare-Claude-Lab/kv-namespace

スケジュールタスクからの呼び出しでは、サイト名から該当 Vault を選んで op run でラップする統一スクリプトを噛ませています。これによってタスク本体は「どのサイトの操作か」だけを意識すればよく、シークレットの所在を逐一気にせずに済みます。

公開している記事執行用のスクリプトでは Bash の trap で SIGINT / SIGTERM をフックし、スクリプト終了時に一時ファイルを必ず削除するようにしています。エージェントが意図せず Ctrl+C で中断されても、シークレットを含む途中ファイルが残らない作りです。

実装パターンの背景にある脅威モデルや、エージェント特有のセキュリティ視点をさらに深く

シークレット管理は、設計を一度終えれば終わるタスクではなく、運用と一緒に育てていく仕組みです。本記事の8つのトピックのうち、まずは1Password または OS Keychain への移行から着手することをおすすめします。.env の値を一つだけでも保管庫に移し、op run または security find-generic-password 経由で取り出す経験を1度通すと、残りの設計判断が驚くほど自然に決まっていきます。今日のうちに最も使用頻度の高いキーを1つ移行してみてください。