vaultshell

vaultshell

英語 | 简体中文

公式 MCP レジストリで利用できます：io.github.SoWhatI/vaultshell

シークレットをローカルのセキュアストレージに保存し、ルールに基づいてシェルの子プロセスに実行時に注入する MCP サーバーです。シークレットの平文がモデルコンテキストに決して到達しないことを保証します。ツールの応答にも、ログにも、監査記録にも含まれません。

閉ループ：参照ベースの保存＋条件付き注入＋必須の出力マスキング。

ステータス：M3 — 単発コマンド＋永続セッション＋認証情報プロキシ＋外部 CLI バックエンド。詳細は CHANGELOG と docs/design-spec.md を参照してください。

絶対的なルール

• MCP ツールがシークレットの平文を返すことは決してありません。応答に含まれるのは名前、マスク（[REDACTED:NAME]）、およびマスキング済みの出力のみです。
• リゾルバーはランチャー内でのみ呼び出されます。値は子プロセスの env に直接渡され、ツールレイヤーを通過することはありません。
• shell_exec に自由形式の env パラメーターはありません。シークレットの受け渡しにはルール参照のみを使用します。
• リダクターに障害が発生した場合はフェイルクローズとなります。出力は破棄され、生のまま返されることはありません。

クイックスタート

Node.js 20 以降が必要です。

GitHub からインストール（npm レジストリアカウント不要）

# Run on demand directly from the repo (npm installs devDependencies and
# builds dist/ via the `prepare` script):
npx -y github:SoWhatI/vaultshell

# Or install globally:
npm i -g github:SoWhatI/vaultshell

これは npm レジストリパッケージと同じコードを、Git からインストールする方法です。npm がリポジトリをクローンし、prepare（→ npm run build）を実行して、vaultshell バイナリをリンクします。再現性を確保するにはタグを固定してください： npx -y github:SoWhatI/vaultshell#v0.1.1。

Docker（ghcr.io）

docker run -i --rm \
  -e MASTER_KEY=<64 hex chars> \
  -v ~/.vaultshell:/home/node/.vaultshell \
  ghcr.io/sowhati/vaultshell:latest

Docker を使用する MCP クライアントの設定：

{
  "mcpServers": {
    "vaultshell": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MASTER_KEY=<64 hex chars>",
        "-v", "~/.vaultshell:/home/node/.vaultshell",
        "ghcr.io/sowhati/vaultshell:latest"
      ]
    }
  }
}

イメージは root 以外の node ユーザーとして実行されるため（HOME=/home/node）、データボリュームは /home/node/.vaultshell にマウントされます。node-pty はイメージから除外されているため、コンテナー内のセッションは自動的にパイプモード（pty: false）にフォールバックします。注入とマスキングの動作は変わりません。web サブコマンドはそのまま実行されます（docker run … ghcr.io/sowhati/vaultshell web — コンテナー内のループバックであり、用途は限られます）。

Smithery では配布しません： Smithery はホスト型のみになりました（独自のインフラにデプロイされたサーバーのみ受け付けます）。vaultshell のシークレットは設計上、ユーザーのマシン上に保持する必要があります。サードパーティによるホスティングは脅威モデルと両立しないため、意図的に公開していません。

ソースから

# Run via npx (after publish) or from source:
npm install && npm run build

# 1. Create a master key for the encrypted-file backend
export MASTER_KEY=$(openssl rand -hex 32)

# 2. Create ~/.vaultshell/config.yaml and ~/.vaultshell/rules.yaml
#    (full annotated examples: docs/user-guide.md)

# 3. Store a secret (never echoed back) and run with injection
#    via your MCP client's tools: secret_set, then shell_exec

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "vaultshell": {
      "command": "npx",
      "args": ["-y", "vaultshell"],
      "env": { "MASTER_KEY": "<64 hex chars>" }
    }
  }
}

セットアップ、設定リファレンス、ルール作成ガイド、クライアント連携、FAQ の詳細：docs/user-guide.md。

MCP ツール

ツール	目的	戻り値
shell_exec	ルールごとのインジェクションを適用して、1回限りのコマンドを実行します。パラメーター：command、cwd?、profile?、extraEnv?（許可リスト）、dryRun?、timeoutSeconds?（≤3600）	{exitCode, stdout, stderr}（機密情報をマスキング）、injected:[names]、ruleId、redactedCount、timedOut、truncated、warnings。dryRun → {dryRun:true, ruleId, injected, envKeys, denied}
shell_session_open	永続セッションを開きます。シークレットは作成時に一度だけインジェクションされます	{sessionId, cwd, injected:[names], pty, ttlSeconds}
shell_session_send	セッションにコマンドを送信します	{output}（結合済み、機密情報をマスキング）、exitCode、redactedCount
shell_session_close	セッションを終了します。プロセスとともにシークレットも消去されます	{ok}
shell_session_list	実行中のセッションを一覧表示します	メタデータのみ
shell_session_revoke	シークレットを含まない状態でセッションを終了し、再構築します	{sessionId}（新規）
shell_proxy_start	127.0.0.1 で認証情報をインジェクションするリバースプロキシを起動します	{proxyId, port, expiresAt, upstreamHost}
shell_proxy_stop	プロキシを停止します	{ok}
shell_proxy_list	実行中のプロキシを一覧表示します	メタデータのみ（シークレットの名前を含み、値は含みません）
secret_list	名前とメタデータ（バックエンド参照、解決可能）を一覧表示します	値は返しません
secret_set	バックエンドに書き込みます。永続化され、値は返されません	{name, ok}
secret_delete	削除して登録を解除します	{name, ok}
secret_probe	参照先が解決可能か確認します	{ok, masked:"****"}
rule_list	ルールと静的警告（例：inject-everywhere）	—
rule_validate	静的検出結果：不明なシークレット、到達不能なルール、inject-everywhere、結合リスク、requireConfirm の機能	{ok, findings[]}
audit_query	監査ログのエントリーを読み取ります	名前と機密情報をマスキングしたコマンドのみ

実行制限（M3）

• shell_exec の dryRun: true は、実行せずに、実際に適用される ruleId、injected の名前、最終的な環境変数の キー 一覧（値は含みません）、および拒否リストの判定を報告します。
• timeoutSeconds（デフォルトは defaults.execTimeoutSeconds = 120、上限は 3600）はコマンドを終了し、timedOut: true を返します。
• defaults.maxOutputBytes（デフォルトは 1 MiB）は各出力ストリームを切り詰め、 truncated: true を設定します。切り詰めは Redactor の処理後に行われるため、 機密情報のマスキングを回避することはありません。
• defaults.maxConcurrentExecs（デフォルトは 8）は、上限を超える同時実行中の shell_exec 呼び出しを明確なエラーで拒否します（キューには入りません）。
• 上記のすべては監査ログに記録されます（dryRun／timedOut／ truncated フラグ）。

Web 設定 UI

vaultshell web            # loopback-only HTTP UI on a random port
vaultshell web --port 5317

http://127.0.0.1:5317/?token=… のような一度限りのトークン付き URL を出力します。URL を開くと、シークレットの管理（書き込み専用）、ルールの編集（静的検証の警告をリアルタイム表示し、マッチャーのドライランも実行）、設定の編集、機密情報をマスキングした監査ログの閲覧ができます。トークンはプロセスの終了とともに無効になり、すべての API 呼び出しにトークンが必要です。変更には同一オリジンからの application/json リクエストが必要で、シークレットの値を返すエンドポイントはありません。ポートフォワーディングしないでください。設計と脅威モデル： docs/web-config-ui-design.md。

認証情報プロキシ（M3）

機密性の高い API トークンでは、シークレットを環境変数にまったく含めない方法を優先してください。config.yaml でプロキシを宣言します。

proxies:
  - id: stripe
    upstreamHost: https://api.stripe.com
    secretRef: STRIPE_KEY                          # registry name or full ref
    headerTemplate: "Authorization: Bearer ${value}"

次に shell_proxy_start { "id": "stripe" } → { port, expiresAt } を実行すると、コマンドは https://api.stripe.com/v1/charges の代わりに http://127.0.0.1:<port>/v1/charges を呼び出します。プロキシはヘッダーをメモリ内でのみインジェクションし、TTL の経過後に自動停止します（デフォルトは 300s）。監査ログにはホストとシークレット名が記録されますが、ヘッダーの値は記録されません。

境界：上流は http://／https:// のみです（プロキシから上流への TLS は適切に検証されます。CONNECT トンネリングおよび TLS 終端はありません）。クライアントからプロキシへの通信は 127.0.0.1 上の平文であり、脅威モデルと同じ UID のローカルプロセス境界が適用されます。

永続セッション（M2）

shell_session_open は、一致したルールのシークレットを作成時に注入して、長時間実行されるシェルを起動します。セッションはアイドル状態の TTL（defaults.sessionTtlSeconds、デフォルトは 900s。ルールごとに ttlSeconds で、または呼び出しごとに上書き可能）が経過すると再作成されます。プロセスが終了すると、シークレットも消去されます。 shell_session_revoke は、侵害された可能性のあるセッションをただちに終了し、シークレットを一切含まない状態で再構築します。

セッションでは node-pty を通じて実際の PTY を使用します（オプションの依存関係です。ネイティブビルドが必要で、macOS では Xcode CLT、Linux では build-essential と python3 が必要です）。node-pty を読み込めない場合や起動できない場合、vaultshell は自動的にプレーンな child_process シェルにフォールバックし、shell_session_open の応答では pty: false と示されます。注入と秘匿化の動作は同じですが、対話性のみ低下します。セッションの出力は stdout/stderr を統合し（PTY の仕様）、同じ Redactor を通過します。

バックエンドのサポート状況

バックエンド	参照スキーム	ステータス	プラットフォーム	備考
暗号化ファイル	encfile://NAME	✅ 実装済み	すべて	AES-256-GCM。マスターキーは env:MASTER_KEY または macOS キーチェーンから取得。デフォルト
ローカルキーチェーン	keychain://svc/acct	⚠️ macOS のみ	macOS	security CLI を起動。Linux／Windows では明確なエラーを表示
プロセス環境変数	env://NAME	✅ 実装済み	すべて	読み取り専用。CI に適しています
ファイル	file://path	✅ 実装済み	すべて	先頭行を使用。0600 を超える権限は拒否
インライン	inline:	⚠️ 制限あり	すべて	設定内に平文で保存。デフォルトでは無効。有効にすると起動時に警告
1Password	op://vault/item/field	✅ CLI 経由	すべて	認証済みの op CLI が必要。読み取り専用
Vault	vault://path#field	✅ CLI 経由	すべて	認証済みの vault CLI が必要。読み取り専用
Infisical	infisical://proj/env/KEY	✅ CLI 経由	すべて	認証済みの infisical CLI が必要。読み取り専用
Doppler	doppler://proj/config/KEY	✅ CLI 経由	すべて	認証済みの doppler CLI が必要。読み取り専用

詳細、各バックエンドのセットアップ方法、プラグインリゾルバーの登録方法については、 docs/backends.md を参照してください。

脅威モデル

脅威	緩和策
モデルコンテキストの漏えい	構造的に防止：値がツール層を越えることはなく、名前とマスクのみを扱います
コマンド出力にシークレットが含まれる	必須の秘匿化（完全一致＋URL／Base64 形式＋汎用パターン）。フェイルクローズ
エージェントによる環境変数のダンプ（env、printenv、/proc/*/environ など）	拒否リストで厳格にブロック（security.dangerousCommands で設定可能：パターンの追加、または mode: warn で監査付きの許可）＋shell_exec_blocked 監査イベント
同じ UID のローカルプロセスによる /proc/PID/environ の読み取り	OS レベルの制約であり、完全には解決できません。コマンドごとの注入で露出時間を短縮します。明示的な境界です。
シークレットの長時間保持	デフォルトではコマンドごとに注入。セッションはアイドル TTL による再作成と即時の revoke に対応
ルールの設定ミスによるあらゆる場所への注入	rule_validate／rule_list で静的警告を表示。mergeStrategy のデフォルトは override。requireConfirm ルールでは対話型の承認が必要（エリシテーションが利用できない場合はフェイルクローズ）
設定ファイルからの漏えい	設定に保存されるのは参照のみで、値は保存されません。inline: はデフォルトで無効。ストアファイルの権限を 0600 に強制

詳しくは docs/design-spec.md §7 を参照してください。 脆弱性は SECURITY.md に従って非公開で報告してください。

データ配置

~/.vaultshell/
  config.yaml     # main config
  rules.yaml      # injection rules + secret refs (refs only, never values)
  secrets.enc     # encrypted-file backend (0600)
  audit/          # JSONL audit, redacted

VAULTSHELL_HOME でデータディレクトリを上書きできます（テストで使用）。

開発

npm run build   # tsc
npm test        # vitest — redactor property tests, backend round-trips,
                # rule matching, shell_exec end-to-end

すべての PR が遵守すべきセキュリティ上の禁止事項を含め、 CONTRIBUTING.md を参照してください。

ライセンス

MIT © 2026 vaultshell コントリビューター