アーキテクチャ概要
このドキュメントでは、コンポーネントの関係、データフロー、セキュリティ境界を含む secretctl の高レベルアーキテクチャを説明します。
システムコンポーネント
┌─────────────────────────────────────────────────────────────────────────────┐
│ secretctl アーキテクチャ │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ CLI │ │ デスクトップ │ │ MCP サーバー │ ユーザーインターフェース │
│ │ (Cobra) │ │ (Wails) │ │ (stdio) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ │ 完全信頼 │ 完全信頼 │ 制限付き（AI安全設計） │
│ │ │ │ │
│ └────────────────┼────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ Vault コア (pkg/vault) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ マネージャー │ │ シークレット │ │ 監査 │ │ ポリシー │ │ │
│ │ │ │──│ ストア │──│ ログ │ │ エンジン │ │ │
│ │ │(ライフサイクル)│ │ (CRUD) │ │ (HMAC) │ │ (MCPのみ) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ 暗号レイヤー (pkg/crypto) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Argon2id │ │ AES-256 │ │ HMAC-256 │ │ │
│ │ │ (KDF) │ │ (GCM) │ │ (Chain) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ ストレージレイヤー (SQLite) │ │
│ │ ┌───────────────────────────────────────────────────────────────┐ │ │
│ │ │ vault.db (0600) │ vault.salt (0600) │ vault.meta (0600) │ │ │
│ │ └───────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
コンポーネントの責務
| コンポーネント | 責務 | パッケージ |
|---|---|---|
| CLI | コマンドラインインターフェース、ユーザーインタラクション | cmd/secretctl |
| デスクトップ | ネイティブ GUI アプリケーション | desktop/ |
| MCP サーバー | AI エージェント連携、AI安全設計の適用 | internal/mcp |
| Vault マネージャー | ライフサイクル（init、lock、unlock）、セッション管理 | pkg/vault |
| シークレットストア | CRUD 操作、メタデータ処理 | pkg/vault |
| 監査ログ | HMAC チェーンイベントログ、整合性検証 | pkg/vault |
| ポリシーエンジン | MCP コマンド許可リスト、デフォルト拒否 | internal/mcp |
| 暗号レイヤー | 鍵導出、暗号化、HMAC | pkg/crypto |
| ストレージレイヤー | SQLite 永続化、ファイル権限 | pkg/vault |
データフロー図
シークレット設定操作
ユーザー CLI Vault Crypto
│ │ │ │
│ set KEY (stdin) │ │ │
│─────────────────────▶│ │ │
│ │ Store(key, value) │ │
│ │───────────────────────▶│ │
│ │ │ Encrypt(DEK, value) │
│ │ │──────────────────────▶│
│ │ │ │
│ │ │◀──────────────────────│
│ │ │ ciphertext │
│ │ │ │
│ │ │ INSERT INTO secrets │
│ │ │──────────▶ [SQLite] │
│ │ │ │
│ │ │ Log(SET, key_hash) │
│ │ │──────────▶ [Audit] │
│ │◀───────────────────────│ │
│◀─────────────────────│ success │ │
│ OK │ │ │
MCP secret_run 操作（AI安全設計）
AI エージェント MCP サーバー Vault サブプロセス
│ │ │ │
│ secret_run │ │ │
│ (keys, cmd) │ │ │
│──────────────────▶│ │ │
│ │ │ │
│ │ ValidatePolicy(cmd)│ │
│ │────────────────────▶│ │
│ │◀────────────────────│ │
│ │ allowed │ │
│ │ │ │
│ │ GetSecrets(keys) │ │
│ │────────────────────▶│ │
│ │◀────────────────────│ │
│ │ values │ │
│ │ │ │
│ │ Exec(cmd, env=secrets) │
│ │─────────────────────────────────────────▶│
│ │ │
│ │◀─────────────────────────────────────────│
│ │ stdout, stderr │
│ │ │ │
│ │ Sanitize(output, secrets) │
│ │ [REDACTED] 置換 │
│ │ │ │
│◀──────────────────│ │ │
│ サニタイズ出力 │ │ │
│ (平文なし) │ │ │
脅威モデル
信頼境界
┌─────────────────────────────────────────────────────────────────────────────┐
│ 信頼境界 1 │
│ (ユーザーのローカル環境) │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 信頼されるアクター 信頼される操作 │ │
│ │ ────────────── ────────────── │ │
│ │ • 人間ユーザー (CLI) • 平文シークレットの読み取り │ │
│ │ • 人間ユーザー (デスクトップ) • シークレットの書き込み/変更 │ │
│ │ • シークレットの削除 │ │
│ │ • Vault のエクスポート │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ AI安全設計境界 │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 制限されるアクター 制限される操作 │ │
│ │ ───────────────── ───────────────── │ │
│ │ • AI エージェント (MCP) • キー名の一覧（値なし） │ │
│ │ • 自動化ツール • 存在確認 │ │
│ │ • マスクされた値の取得 │ │
│ │ • コマンド実行（許可リストのみ） │ │
│ │ │ │
│ │ 拒否される操作 │ │
│ │ ───────────────── │ │
│ │ ✗ 平文シークレットの読み取り │ │
│ │ ✗ シークレットの書き込み/変更 │ │
│ │ ✗ シークレットの削除 │ │
│ │ ✗ Vault のエクスポート │ │
│ │ ✗ ブロックされたコマンドの実行（env、printenv など） │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
脅威カテゴリと緩和策
| カテゴリ | 脅威 | 緩和策 | 実装 |
|---|---|---|---|
| T1: シークレット露出 | AI が平文を抽出 | secret_get ツールなし | internal/mcp |
| T2: 出力漏洩 | コマンド出力にシークレット含む | 出力サニタイズ | pkg/vault/sanitizer.go |
| T3: プロンプトインジェクション | 悪意のあるプロンプトがデータ要求 | ツールレベル制限 | MCP ツール定義 |
| T4: コマンドインジェクション | 注入されたシェルコマンド | コマンド許可リスト | mcp-policy.yaml |
| T5: 環境ダンプ | env/printenv がシークレット露出 | ブロックコマンドリスト | internal/mcp/policy.go |
| T6: ブルートフォース | マスターパスワード推測 | Argon2id（メモリハード） | pkg/crypto |
| T7: 保存データ | Vault へのディスクアクセス | AES-256-GCM 暗号化 | pkg/crypto |
| T8: ログ改ざん | 監査ログの変更 | HMAC チェーン整合性 | pkg/vault/audit.go |
| T9: ファイル権限 | 不正なファイルアクセス | 0600/0700 権限 | pkg/vault |
STRIDE 分析
| 脅威タイプ | 該当 | 緩和策 |
|---|---|---|
| Spoofing（なりすまし） | なし | ローカル専用、ネットワーク認証なし |
| Tampering（改ざん） | あり | HMAC チェーン監査ログ、暗号化ストレージ |
| Repudiation（否認） | あり | タイムスタンプ付き監査ログ |
| Information Disclosure（情報漏洩） | あり | AI安全設計、出力サニタイズ |
| Denial of Service（サービス拒否） | 限定的 | コマンドタイムアウト（300秒） |
| Elevation of Privilege（権限昇格） | あり | 信頼境界の適用 |
鍵階層
┌─────────────────────────────────────────────────────────────────────────────┐
│ 鍵階層 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ユーザー入力: マスターパスワード │
│ │ │
│ │ + Salt (128ビット、ランダム) │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Argon2id │ │
│ │ ───────── │ │
│ │ メモリ: 64 MiB │ │
│ │ 時間: 3 イテレーション │ │
│ │ スレッド: 4 │ │
│ │ 出力: 256 ビット │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ マスターキー (256ビット) ──────── 保存されない ──────── │
│ │ │
│ │ HKDF-SHA256 ("dek-v1") │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ DEK (データ暗号化キー) - 256ビット │ │
│ │ ───────────────────────────────── │ │
│ │ • vault.db に暗号化して保存 │ │
│ │ • パスワードローテーション時にすべてのシークレットの │ │
│ │ 再暗号化が不要 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ AES-256-GCM │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 暗号化されたシークレット │ │
│ │ ───────────────── │ │
│ │ • 各シークレットは一意の nonce で暗号化 │ │
│ │ • 保存形式: nonce (12B) || ciphertext || auth_tag (16B) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ 監査ログキー (256ビット) │
│ ──────────────────────── │
│ • マスターキーから HKDF-SHA256 ("audit-log-v1") で導出 │
│ • HMAC チェーン計算に使用 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
データベーススキーマ
-- シークレットテーブル
CREATE TABLE secrets (
id TEXT PRIMARY KEY,
key TEXT UNIQUE NOT NULL,
encrypted_value BLOB NOT NULL,
notes TEXT,
url TEXT,
tags TEXT, -- JSON 配列
expires_at DATETIME,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL
);
-- 監査ログテーブル
CREATE TABLE audit_log (
id TEXT PRIMARY KEY,
action TEXT NOT NULL, -- get, set, delete, list, run
key_hash TEXT, -- キーの SHA-256（平文ではない）
source TEXT NOT NULL, -- cli, mcp, ui
success BOOLEAN NOT NULL,
error_msg TEXT,
timestamp DATETIME NOT NULL,
prev_hash TEXT, -- HMAC チェーン
hash TEXT NOT NULL -- このレコードの HMAC
);
-- メタデータテーブル
CREATE TABLE metadata (
key TEXT PRIMARY KEY,
value TEXT NOT NULL
);
ファイル構造
~/.secretctl/
├── vault.db # SQLite データベース（暗号化された値）
│ # 権限: 0600
│
├── vault.salt # Argon2id salt (128 ビット)
│ # 権限: 0600
│
├── vault.meta # Vault メタデータ (JSON)
│ # 権限: 0600
│ # 内容: version, created_at
│
└── mcp-policy.yaml # MCP コマンドポリシー（オプション）
# 権限: 0600
# 検証: シンボリックリンク禁止
セキュリティ境界サマリー
| インターフェース | 信頼レベル | 平文読み取り可 | 変更可 | 削除可 |
|---|---|---|---|---|
| CLI | 完全 | はい | はい | はい |
| デスクトップ | 完全 | はい | はい | はい |
| MCP | 制限付き | いいえ | いいえ | いいえ |
次のステップ
- 暗号化詳細 - 暗号仕様
- MCP セキュリティモデル - AI エージェント制限
- セキュリティの仕組み - 詳細なセキュリティメカニズム