ツール権限とセキュリティ

Elftia の Agent システムは AI に強力な実行能力を与える一方で、多層のセキュリティ保護メカニズムも提供します。このページでは、権限モード、ツールの機密度分類、確認ダイアログの流れ、各セキュリティ層の仕組みについて詳しく説明します。

権限モード

権限モードは、Agent がツールを実行するときのセキュリティレベルを決定します。Agent 設定の permissionMode フィールドで設定します。

モード概要

モード	ID	動作	適した用途
デフォルト	`default`	機密性の高いツールは毎回ユーザー確認が必要	日常利用、セキュリティ優先
編集を許可	`acceptEdits`	ファイルの読み取りと書き込みは自動承認され、Shell/MCP ツールは引き続き確認が必要	ファイル操作を信頼できるコーディング場面
権限をバイパス	`bypassPermissions`	すべてのツールを自動実行	Agent を完全に信頼する場合
計画	`plan`	読み取り専用ツールのみ許可	情報収集、分析、計画立案

モード動作の比較

ツール	default	acceptEdits	bypassPermissions	plan
Read / Glob / Grep	自動	自動	自動	自動
Write / Edit	確認	自動	自動	ブロック
Bash	確認	確認	自動	ブロック
spawn_agent	確認	確認	自動	ブロック
MCP ツール	確認	確認	自動	ブロック
WebSearch / WebFetch	自動	自動	自動	自動

plan モードで許可されるツール

plan モードでは、次の読み取り専用ツールのみが許可されます。

Read — ファイルを読み取る
ListDir — ディレクトリを一覧表示する
Glob — ファイルをマッチングする
Grep — 内容を検索する
WebSearch — Web 検索
WebFetch — Web ページを取得する
list_skills — スキルを一覧表示する
read_skill — スキルを読み取る

ツールの機密度分類

TinyElf エンジンはツールを 安全なツール と 機密ツール の 2 つのカテゴリに分類します。

安全なツール（確認不要）

ツール	説明
`Read`	ファイル内容を読み取る
`ListDir`	ディレクトリを一覧表示する
`Glob`	ファイル名パターンを検索する
`Grep`	ファイル内容を検索する
`WebSearch`	Web 検索
`WebFetch`	Web コンテンツを取得する
`list_skills`	利用可能なスキルを一覧表示する
`read_skill`	スキル内容を読み取る
`Notify`	デスクトップ通知を送信する
`SessionsYield`	Agent ループを終了する
`SessionsHistory`	セッション履歴を表示する

機密ツール（確認の要否は権限モードに依存）

ツール	リスクの説明
`Bash`	任意のシェルコマンドを実行できる
`Write`	ファイルを作成または上書きできる
`Edit`	既存ファイルの内容を変更できる
`spawn_agent`	サブ Agent を起動してタスクを実行できる
MCP ツール（`mcp__*`）	挙動を予測できない外部ツール

:::info MCP ツールはデフォルトで機密扱いすべての MCP ツールはデフォルトで機密ツールとして扱われます。MCP ツールは外部サーバーから提供されるため、その挙動を Elftia が事前に監査できないからです。 :::

確認ダイアログの流れ

Agent が機密ツールを使用しようとした場合（確認が必要な権限モードの場合）、システムはユーザーに確認ダイアログを表示します。

デスクトップモードの流れ

Agent requests to execute Bash("npm test")
     ↓
System sends a permission request (IPC: permissionRequest)
     ↓
Frontend displays confirmation dialog:
  ┌─────────────────────────────┐
  │  Bash: npm test             │
  │                             │
  │  [Allow] [Deny] [Allow for Session] │
  └─────────────────────────────┘
     ↓
User chooses → result returned to the Agent

ユーザーの選択肢

選択肢	動作
許可	今回の 1 回の実行を承認する
拒否	今回の実行を拒否し、Agent は拒否通知を受け取る
セッション中は許可	今回を承認し、同じセッション内で同じツールが以後呼び出された場合も自動承認する

セッション単位のツール許可リスト

「セッション中は許可」を選択すると、ツール名が現在のセッションの許可リストに追加されます。同じツールの以後の呼び出しは、追加確認なしで自動的に承認されます。許可リストはセッション終了時にクリアされます。

タイムアウト処理

ユーザーが確認ダイアログに 5 分以内 に応答しない場合、システムはリクエストを自動的に拒否します。

3 層のセキュリティ保護

TinyElf エンジンは 3 層のセキュリティ保護パイプラインを実装しており、次の順序で実行されます。

Tool call request
     ↓
[Layer 1] ExecutionFirewall — path and command validation
     ↓ (pass)
[Layer 2] GuardianAgent — AI security assessment
     ↓ (pass)
[Layer 3] Permission Callback — user confirmation
     ↓ (pass)
Execute tool

いずれかの層がリクエストを拒否した場合、ツール実行はただちに終了します。

レイヤー 1: ExecutionFirewall

ExecutionFirewall は決定論的なセキュリティゲートウェイであり、パスルールに基づいて機密性の高いシステムファイルやディレクトリへのアクセスをブロックします。

ブロックされるパスの種類:

パスの種類	例	操作
システムディレクトリ	`C:\Windows\`、`/etc/`、`/usr/`	読み取りと書き込みの両方をブロック
プログラムディレクトリ	`C:\Program Files\`、`/sbin/`	読み取りと書き込みの両方をブロック
認証情報ファイル	`.ssh/`、`.aws/`、`.gnupg/`	読み取りと書き込みの両方をブロック
SSH キー	`id_rsa`、`id_ed25519`	読み取りと書き込みの両方をブロック
環境変数ファイル	`.env`、`.env.production`	読み取りと書き込みの両方をブロック
ブラウザデータ	Chrome/Firefox/Edge のユーザーデータ	読み取りと書き込みの両方をブロック
レジストリ	`System32\config\SAM` など	読み取りと書き込みの両方をブロック
設定ファイル	`.gitconfig`、`.bashrc`、`.npmrc`	読み取り可能、書き込み不可

レイヤー 2: GuardianAgent

GuardianAgent は LLM を使用してツール呼び出しのセキュリティ評価を行います。これは任意機能であり、設定によって有効化します。

動作モード:

モード	ID	動作
オフ	`off`	無効（オーバーヘッドなし）
モニター	`monitor`	機密ツールをレビューするが、ログのみ記録してブロックしない
ガード	`guard`	機密ツールをレビューし、高リスクおよび重大リスクをブロックする
厳格	`strict`	すべてのツールをレビューし、中リスク以上をブロックする

リスクレベル:

リスクレベル	意味	例
`none`	完全に安全	ワークスペース内のファイルを読み取る
`low`	低リスク	プロジェクトファイルを書き込む
`medium`	中リスク	npm パッケージのインストール、状態の変更
`high`	高リスク	機密パスへのアクセス、ネットワーク操作
`critical`	重大リスク	`rm -rf`、権限昇格、データ持ち出し

重要ルール（常に high/critical としてフラグ付け）:

ワークスペース外でのファイル削除
再帰的な削除コマンド
システムディレクトリ操作
権限昇格（sudo、runas）
パイプ実行（curl | sh）
認証情報へのアクセスまたは持ち出し
セキュリティ機能のバイパス

エラー処理方針:

モード	タイムアウト/エラー時の動作
`monitor` / `guard`	フェイルオープン（実行を許可）
`strict`	フェイルクローズ（実行を拒否）

レイヤー 3: Permission Callback

最後の層はユーザー確認です。IPC メッセージを通じてフロントエンドに確認リクエストを送信します。

Channel 権限ゲーティング

Agent が Channel（Discord、Telegram など）経由でメッセージを受信した場合、権限確認の流れは異なります。

Channel ユーザーロール

ロール	ツール使用	確認の要否
Admin	許可	権限モードに従う
Member	許可	すべてのツールで確認が必要
Guest	不可	どのツールも使用できない

Channel での確認フロー

Channel セッションでの確認は、デスクトップダイアログではなく Channel メッセージを通じて処理されます。

Agent が機密ツールの実行をリクエストする
システムが Channel に確認メッセージを送信する
ユーザーが y（許可）/ n（拒否）/ always（常に許可）で返信する

「常に許可」の範囲:

always 返信の範囲は、「ツール名 + 引数フィンガープリント」の組み合わせに限定されます。例:

Bash: npm test を許可しても、Bash: rm -rf / は自動的には許可されません
コマンドやパスの組み合わせが異なるたびに、個別の承認が必要です

タイムアウト処理: 5 分間応答がない場合は自動拒否されます。Channel ごとに同時に存在できる保留中の確認リクエストは最大 5 件です。

監査ログ

セキュリティ関連のすべてのイベントは、後から追跡できるよう監査ログに記録されます。

イベント種別	説明
`firewall_block`	ExecutionFirewall によってアクセスがブロックされた
`guardian_review`	GuardianAgent のレビュー結果
`permission_granted`	ユーザーがツール実行を承認した
`permission_denied`	ユーザーがツール実行を拒否した
`permission_timeout`	確認がタイムアウトし、自動拒否された
`command_blocked`	シェルコマンドがブロックリストによってブロックされた
`injection_detected`	プロンプトインジェクションが検出された
`rate_limited`	レート制限が発動した

FAQ

問題	原因	解決策
確認プロンプトが頻繁に表示されて煩わしい	権限モードが `default` になっている	`acceptEdits` または `bypassPermissions` に設定する
Firewall が正当な操作をブロックした	操作にシステムパスまたは認証情報ファイルが含まれている	これは想定どおりの動作です。システムファイルは変更すべきではありません
GuardianAgent が安全な操作を誤ってブロックした	評価が過度に保守的	モードを `strict` から `guard` に変更する
Channel ユーザーがツールを使用できない	ユーザーロールが「Guest」になっている	ユーザーを「Member」または「Admin」に昇格させる
セッション許可リストが突然機能しなくなった	セッションが終了して再開された	セッション許可リストはセッションをまたいで保持されません。再承認してください
plan モードでファイルを編集できない	`plan` モードは読み取り専用ツールのみ許可する	`default` または `acceptEdits` モードに切り替える

権限モード​

モード概要​

モード動作の比較​

plan モードで許可されるツール​

ツールの機密度分類​

安全なツール（確認不要）​

機密ツール（確認の要否は権限モードに依存）​

確認ダイアログの流れ​

デスクトップモードの流れ​

ユーザーの選択肢​

セッション単位のツール許可リスト​

タイムアウト処理​

3 層のセキュリティ保護​

レイヤー 1: ExecutionFirewall​

レイヤー 2: GuardianAgent​

レイヤー 3: Permission Callback​

Channel 権限ゲーティング​

Channel ユーザーロール​

Channel での確認フロー​

監査ログ​

FAQ​

関連リンク​