鍵を渡さない管理人

01v0.1 の範囲

02取り付け

git clone https://github.com/kagioneko/credential-broker
cd credential-broker
python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest -q   # 84 tests

本番は systemd で動かし、ExecStartPre が secret store から tmpfs（/run/credential-broker/）に秘密を書き出し、ExecStopPost で消します。秘密ファイルは通常の永続ディスクではなく tmpfs に置く構成です。手順はリポジトリの deploy/ を参照。

03設定ファイル

AI に見えるのは credential_id（下の github_reader）と説明だけ。secret_name は .env 側のキー名で、AI には返りません。

default_ttl: 300
max_ttl: 900
rate_limit:
  request_per_min: 20
  execute_per_min: 60

credentials:
  github_reader:
    provider: dotenv
    secret_name: GITHUB_TOKEN        # .env のキー。AI には見せない
    connector: github
    description: "Read-only access to GitHub repositories and issues"
    ttl: 300
    allowed_actions:
      - list_repositories
      - get_repository
      - list_issues
      - get_issue

04MCP（AI CLI 向け）

Claude Code・Codex・Antigravity などの AI CLI からは MCP stdio で使います。AI に見えるツールは4つだけで、引数は構造的に credential_id / action / parameters に固定されていて、実キーを渡すための引数はありません。stdio のプロセス境界が信頼境界なので Bearer トークンは不要です。

python -m app.mcp_server          # 直接起動
deploy/mcp-launch.sh              # secret store → 一時ファイル → 子プロセス のラッパー

{ "mcpServers": { "credential-broker": {
    "command": "/opt/credential-broker/deploy/mcp-launch.sh"
} } }

05HTTP API

cron や他ツール向け。全エンドポイントで Authorization: Bearer $BROKER_API_TOKEN が必須です。

BROKER_API_TOKEN=xxx DOTENV_PATH=.env \
  .venv/bin/uvicorn --factory app.main:create_app --host 127.0.0.1 --port 8787 --workers 1

action ごとの主な parameters：get_repository は owner / repo、list_issues は owner / repo に加えて state（open / closed / all）など、get_issue は owner / repo / number。

06エラーコード

エラーは常に {"error": "<CODE>"} の形です。

07異常利用の検知

全操作が監査イベントを通るので、そこで疑わしいパターンを閾値で判定します。ブロックはせず、検知のみです。閾値を超えると anomaly_suspected イベントを監査ログに書き戻し、NekoGuard がそれを拾って Discord に通知できます。

08セキュリティ設計

• 未知の credential_id は設定の照合で UNKNOWN_CREDENTIAL。パスとして解釈されない
• レスポンスは allowlist で必要な項目だけを抜き出し、トークンの形の文字列をマスクし、サイズ・件数に上限。上流のヘッダは転送しない
• 期限の判定は time.monotonic()（NTP による時刻補正の影響を受けない）
• 監査ログは決まったフィールドだけを受け付ける（自由な文字列を渡せない）。ログの redaction filter も併用
• GitHub の base URL は固定、リダイレクトは追わない（SSRF のリスクを抑える）
• 上流 API への接続は TLS 証明書を検証し、環境変数のプロキシ（HTTP(S)_PROXY）や TLS 鍵ログ（SSLKEYLOGFILE）を無視する。実クレデンシャルを載せた通信を途中で横取り・傍受されにくくする設計

受け入れテスト TEST-001〜008（Secret 非開示 / TTL / Revoke / 未認可 Action / Secret 列挙 / Path Traversal / Prompt Injection / ログ漏洩）に対応するテストがあります。

09既知の制限

補助として、Claude Code の PreToolUse(Bash) フック deploy/hooks/bash-secret-guard.sh が同梱されています。登録すると、Broker を通らないコマンドについて、決まった漏洩パターン（Vault からの取得でフィールドを指定しない、トークンをコマンドラインに直書きする、取り出した値を表示する など）を拒否します。すべての漏洩経路を防ぐものではありません。

10関連パーツ