diff options
Diffstat (limited to 'doc/Specifications.md')
| -rw-r--r-- | doc/Specifications.md | 131 |
1 files changed, 83 insertions, 48 deletions
diff --git a/doc/Specifications.md b/doc/Specifications.md index 9f6e9b8..79cb653 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -77,12 +77,22 @@ IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・ | Token CPM | TaskGraph上でexpected token costを重みとしてcritical pathを求めるモデル。 | | Token Budget Class | 1K～128KのTask単位token予算階級。Ollama `num_ctx`とは別概念。 | | Session | 会話、TaskGraph、Execution Resultをメモリ上に保持する論理単位。 | -| SandboxPolicy | Filesystem、Process、Network、Resourceの許可範囲を表すホワイトリスト型ポリシー。 | -| Sandbox | SandboxPolicyをWindows機構で強制したプロセス実行環境。 | +| User Sandbox Configuration | Workspace、Mount、Execution、Network、Resourceを利用者の意図で表すsemantic設定。 | +| Sandbox Environment Resolution | Logical Path、Executable Alias、Runtime等をHost上のResolved Pathへ解決する処理。 | +| Effective Sandbox Policy | ResolutionとExecutable Approvalの結果から生成され、Policy Engineが使用する解決済みホワイトリスト。従来のSandboxPolicyはこの意味でのみ使用する。 | +| Sandbox | Effective Sandbox PolicyをWindows機構で強制したExecution Environment。 | | Sandbox Broker | プロセス起動・許可判定・Windows強制機構の調停を担当する信頼境界。 | -| Application Profile | アプリケーション固定のAppContainer profile。Taskごとには作成・削除しない。 | +| Application Profile | アプリケーション固定のLess Privileged AppContainer (LPAC) profile。Taskごとには作成・削除しない。 | | Task Resource | Task中だけ存在するACL、WFP filter、Job Object、一時ファイル等。 | -| Approval | 実行ファイルのcanonical pathとSHA-256を信頼対象として登録する操作。 | +| Executable | Windows上でProcessとして起動可能な実行対象。Internal Toolとは区別する。 | +| Executable Alias | 利用者がHost Executableを指定する人間向け名称。Alias解決だけではApprovalにならない。 | +| Approved Entry Executable | BrokerがEntry Processとして直接起動できる、Executable Approval済みHost Executable。 | +| Executable Approval | Entry ExecutableのResolved PathとSHA-256を人間が信頼対象として登録する操作。 | +| Runtime / Runtime Root / Runtime Component | Entry Executableの動作に必要な実行環境、そのFilesystem root、その配下のExecutable/resource。 | +| Workspace Artifact | development Workspace内で生成または配置され、Host Executable ApprovalなしでSandbox Entry Processとして起動できる実行物。 | +| Shell | command interpreterとして動作するExecutable category。 | +| Sandbox Process Tree | Brokerが起動したEntry Processと、同じconfinementを継承する全Descendant Process。 | +| Logical Path / Resolved Path | 利用者が指定したpathと、reparse resolution後にPolicy評価へ使用する実体path。 | | Fixed System Prompt | 実行ファイルに組み込まれ、利用者が変更できない最上位指示。 | | User System Prompt | 設定で指定可能だがFixed System Promptを上書きできない追加指示。 | | Skill | LLMへの補助指示を記述したMarkdown。実行権限そのものを与えない。 | @@ -100,8 +110,8 @@ IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・ | UC-02 | MCP Client | Task状態を照会する | 状態と、完了時には最終回答をテキストで得る | | UC-03 | 利用者 | 画像付き依頼を送信する | Vision対応modelなら処理される | | UC-04 | 利用者 | 言語を指定して起動する | CLI/診断/MCP応答/LLM最終回答が指定言語になる | -| UC-05 | 管理者 | SandboxPolicyを設定する | 未許可能力はdenyされる | -| UC-06 | 管理者 | 実行ファイルを承認する | pathとSHA-256一致時だけ起動できる | +| UC-05 | 利用者 | User Sandbox Configurationを設定・確認する | semantic設定からEffective Sandbox Policyが可視化され、未許可能力はdenyされる | +| UC-06 | 利用者 | Entry Executableを承認する | Alias、Resolved Path、SHA-256一致時だけBrokerから直接起動できる | | UC-07 | Agent | 計画を作成・更新する | TaskGraphがDAGを維持しToken CPMを再計算する | | UC-08 | Agent | Internal Toolを呼ぶ | Policy検査後にのみ副作用が発生する | | UC-09 | システム | 異常終了から復旧する | 残留Task Resourceを除去してから受付開始する | @@ -171,9 +181,16 @@ v1のCLI surfaceは次に限定する。 ```text agent-mcp [serve] [--config <path>] [--lang <locale>] [--transport <stdio|http>] agent-mcp check [--config <path>] [--lang <locale>] +agent-mcp executable resolve <alias> [--path <path>] --config <path> +agent-mcp executable approve <alias> [--path <path>] [--runtime-root <path>|--no-runtime] [--yes] --config <path> +agent-mcp executable list --config <path> +agent-mcp executable revoke <alias> [--yes] --config <path> +agent-mcp sandbox resolve --config <path> +agent-mcp sandbox confirm [--yes] --config <path> +agent-mcp sandbox show [--format <text|json>] --config <path> ``` -command省略時、および先頭引数がoptionの場合は `serve` として扱う。CLIは起動方式と表示言語を変更するためのI/Fであり、SandboxPolicyやOllama sampling値を個別overrideするI/Fにしない。 +command省略時、および先頭引数がoptionの場合は `serve` として扱う。`resolve`、`list`、`show`、`check`はread-onlyとする。`approve`、`revoke`、`confirm`は差分表示後の対話確認を既定とし、明示的な`--yes`を許可してAuditへ記録する。MCP ClientおよびLLMからこれらの変更操作を呼び出せない。 ### 5.7 MCP 2026-07-28とTasks Extension @@ -319,22 +336,25 @@ Context要約を開始する利用率閾値は設定可能でなければなら - frontmatterなしのSkillは推測せずrejectする。malformed YAML、duplicate skill nameは起動/check時fatalとする。 - Progressive Disclosure: Stage 1 Discovery (name + descriptionのみ) → Stage 2 Selection (LLM) → Stage 3 Instructions Load (選択SKILL.md本文) → Stage 4 Resources (scripts/references/assets)。 - Skill選択はLLMにより行う。選択可能集合は設定されたSkill directoryに限定する。Runtimeは選択結果を検証し、unknown Skill名を読み込まない。 -- Skillロードは権限付与を意味しない。`allowed-tools` metadataはSandbox permissionとして解釈しない。 -- Skillに `scripts/` が含まれていても自動実行許可しない。実行には通常どおりFilesystem execute capability、Process Approval、path + SHA-256、Sandbox Brokerを必須とする。 +- Skillロードはcapability付与を意味しない。`allowed-tools` metadataはSandbox Capabilityとして解釈しない。 +- Skillに `scripts/` が含まれていても自動実行許可しない。Entry起動には通常どおりEffective Sandbox Policy上のFilesystem execute capability、Entry Process分類、必要なExecutable Approval、Sandbox Brokerを必須とする。 - Skill directory内resourceについてcanonicalization、reparse point検査、Skill root外へのescape禁止を行う。 - Skill選択・本文ロードはInternal Toolとして公開せず、Agent Runtime / Prompt Context Managementの責務として実装する。 - Internal Toolの具体的なcatalogとschemaは設計事項とする。MCP Clientへ公開せず、Internal Toolによる副作用は必ずPolicy検査を通過しなければならない。 --- -## 11. SandboxPolicy仕様 +## 11. User Sandbox Configuration・Effective Sandbox Policy仕様 ### 11.1 基本原則 -- **ホワイトリスト方式**を採用する。未指定能力はdenyする。 -- 子・孫プロセスは親より強い権限を取得できない。 -- LLMはSandboxPolicyを変更できない。 -- Policy変更は設定変更とアプリ再起動を必要とする。 +- User Sandbox Configurationは`readonly`または`development` Profile、Workspace、Mount、Execution、Network、Resourceを表す。 +- Sandbox Environment ResolutionとExecutable Approval Resolutionの成功後だけEffective Sandbox Policyを生成する。 +- Effective Sandbox PolicyはResolved Filesystem Rootのcapabilityと由来、Approved Entry Executable、Runtime Root、Artifact Root、Network endpoint、Resource limit、固定baseline capabilityを利用者が確認可能な形で保持する。 +- **ホワイトリスト方式**を採用し、未指定能力はdenyする。 +- Descendant ProcessはEntry Processと同じLPAC、Filesystem、Network、Job confinementを継承し、親より強いcapabilityを取得できない。 +- LLMとMCP ClientはUser Sandbox Configuration、Resolution Result、Executable Approval、Effective Sandbox Policyを変更できない。 +- User Sandbox Configuration変更はconfig別Resolution Resultの再確認とアプリ再起動を必要とする。 - v1で開放可能なのはFilesystem、Process、Network、Resourceとする。その他能力はdenyとする。 ### 11.2 Filesystem Policy @@ -343,37 +363,43 @@ Context要約を開始する利用率閾値は設定可能でなければなら | --- | --- | | read | ファイル内容読取、directory列挙。 | | write | create、overwrite、renameを含む。deleteは含まない。 | -| execute | 対象ファイルを実行対象として利用できる。Process approvalも別途必要。 | +| execute | 対象fileをExecutable imageとして利用できる。Entry Processの分類に応じてExecutable Approvalも必要。 | | delete | ファイルまたはdirectoryを削除できる。 | | ID | 要件 | | --- | --- | -| FS-01 | 指定粒度はdirectoryまたはfile。workspaceという特別な権限単位は持たない。 | -| FS-02 | pathはcanonicalize後にPolicy評価する。 | -| FS-03 | symlink、junction、その他reparse pointを経由した許可範囲外への脱出を禁止する。 | +| FS-01 | Workspace Root、Mount Root、Runtime Root、Artifact Root、個別Executable fileをFilesystem Rootへ変換する。 | +| FS-02 | Logical Pathはreparse chainとcycleを検査してResolved Pathへ変換した後にPolicy評価する。 | +| FS-03 | 未確認または確認後に解決先が変化したLogical Pathを使用せず、許可範囲外への脱出を禁止する。 | | FS-04 | write権限だけではdeleteできない。 | | FS-05 | ACLとAppContainerの両方で強制可能な形にする。 | | FS-06 | ディレクトリ作成 (mkdir) はwrite権限で許可する。ディレクトリ削除 (rmdir) はdelete権限で許可するが、空ディレクトリのみとする。ディレクトリ列挙 (list) はread権限で許可する。 | | FS-07 | renameはsource/destination双方にwrite権限を要求する。destination既存時は拒否する。cross-volume renameは不支持とする。 | +| FS-08 | readonly ProfileのWorkspaceはreadのみ、development ProfileのWorkspaceはread/write/deleteおよびWorkspace Artifact実行を許可する。 | +| FS-09 | Mount accessはread_only、read_write、read_write_deleteのいずれかとし、MountからのExecutable起動を許可しない。 | +| FS-10 | read Filesystem CapabilityをWindows ACL execute permissionへ暗黙変換しない。 | ### 11.3 Process Policy | ID | 要件 | | --- | --- | -| PRC-01 | 実行対象はcanonical pathとSHA-256が承認記録と一致しなければならない。 | -| PRC-02 | 実行ファイル更新でhashが変化した場合は自動許可せず再承認を要求する。 | -| PRC-03 | path変更も再承認を要求する。 | -| PRC-04 | cmd.exe、powershell.exe、pwsh.exeは機能上デフォルト許可とするが、承認照合を免除しない。 | -| PRC-05 | shell categoryは設定で禁止可能。 | -| PRC-06 | すべてのdescendant processに同等以下のSandboxPolicyを適用する。 | -| PRC-07 | 実行前判定はSandbox Brokerが行う。 | +| PRC-01 | Approved Entry ExecutableとApproved Shell ExecutableはAlias、Resolved Path、SHA-256がExecutable Approvalと一致しなければならない。 | +| PRC-02 | Entry Executable更新でhashが変化した場合は自動許可せず再承認を要求する。pathまたはreparse解決先変更も同様とする。 | +| PRC-03 | 確認済みRuntime Root内のRuntime Componentは個別hashなしでEntry Processとして起動可能とする。 | +| PRC-04 | development Workspace内のWorkspace ArtifactはHost Executable ApprovalなしでEntry Processとして起動可能とする。 | +| PRC-05 | External Unknown ExecutableをBrokerからEntry Processとして直接起動してはならない。 | +| PRC-06 | cmd.exe、powershell.exe、pwsh.exeをShellとして分類し、直接起動にはExecutable Approvalを要求する。Shellの許可は追加capabilityを付与しない。 | +| PRC-07 | Descendant Processは個別Executable Approvalを要求せず許可するが、同じLPAC token、ACL、WFP、Job Objectを継承しなければならない。 | +| PRC-08 | 全DescendantをJob chain内へ閉じ込め、breakawayを許可しない。 | +| PRC-09 | Entry Processの分類とApproval判定はSandbox Brokerが実行前に行う。 | ### 11.4 Network Policy -- Network modeは `deny` と `allow` の2値とする。 -- `deny` はlocalhostを含む全通信を拒否する。 -- `allow` はhost/port allow-listに一致するoutboundだけを許可する。 -- allow-listが空の `allow` は実質denyとして扱い、全開放を意味しない。 +- Network Access Modeは `none`、`local`、`restricted` の3値とする。 +- `none` はLoopbackを含む全通信を拒否する。 +- `local` は列挙portに対するIPv4/IPv6 Loopbackだけを許可し、LANを含めない。 +- `restricted` は列挙host/portに一致するoutboundだけを許可する。 +- endpointが空またはmodeと矛盾する設定は拒否し、全開放を意味するfallbackを持たない。 - host名はhostsファイルに近い単純な列挙思想で扱い、汎用Firewall言語は実装しない。 ### 11.5 Resource Policy @@ -385,6 +411,8 @@ Context要約を開始する利用率閾値は設定可能でなければなら | wall-clock timeout | TaskまたはProcessの停止条件として設定可能。 | | child process | 親と同等以下の制約下でのみ許可。 | +Resource Profileは`constrained = 1024 MiB/4 Process/300秒`、`normal = 4096 MiB/16 Process/1800秒`、`extended = 8192 MiB/32 Process/3600秒`とし、各正数値を個別override可能とする。 + ### 11.6 v1で明示denyする能力 - Registry write @@ -411,7 +439,9 @@ Context要約を開始する利用率閾値は設定可能でなければなら ## 13. Application Profile・Task Resource仕様 -- AppContainer profileはapplication固定とする。 +- Application Profileはapplication固定のLPACとし、`ALL APPLICATION PACKAGES`由来の既定accessを除外する。 +- 全Profileの固定baselineとしてRegistry readとSandbox Process Tree自身のinstrumentation registrationを許可し、Registry writeとCOM capabilityはdenyする。 +- Resolved `%SystemRoot%/System32`をOS Runtime RootとしてSandbox Process Treeへread/execute公開する。Brokerからの直接Entry起動は別途Executable Approvalを要求する。 - Task終了時にApplication Profileを削除しない。 - Task固有ACL、WFP filter、Job Object、一時ファイル等はTask Resourceとして管理する。 - Task Resourceは正常終了・失敗・cancelのいずれでも残留させない。 @@ -441,13 +471,15 @@ Context要約を開始する利用率閾値は設定可能でなければなら ## 15. Configuration仕様 - 主設定形式はYAML。 -- `schema_version` を必須とする。 +- `schema_version: 1` を必須とする。本改訂前の`filesystem`および`process.approvals`形式は破壊的に廃止し、移行方法付きで拒否する。 - 設定変更の反映には再起動を必須とする。 - Hot Reloadは明示的に非対応。 - CLIの `--config` で設定ファイルpathを選択可能。 - base設定と同じdirectoryに `agent.local.yaml` が存在する場合は任意overrideとして読み込む。mapは再帰mergeし、scalarと配列はlocal側で置換する。merge後の設定全体をvalidationし、相対pathはbase設定directoryを基準に解決する。 - Release Bundleは既定設定だけを配布し、利用者のlocal設定、User System Prompt、Skillをpublishで上書きしてはならない。 -- 起動時にschema、path、hash approval、locale、policyの静的validationを行う。 +- 起動時にschema、Resolution Result、Executable Approval、locale、Effective Sandbox Policyのvalidationを行う。 +- Executable Approval StoreはWindows user単位のuser-only領域へ保存し、Release Bundleへ含めない。 +- Workspace/Mountの確認済Resolution Resultはconfig別のuser-only領域へ保存し、config fingerprintまたは解決先変更時はserveをfail-closedにする。 --- @@ -457,7 +489,7 @@ Context要約を開始する利用率閾値は設定可能でなければなら | --- | --- | | Application Log | stderrに出力可能。stdio時stdoutへログを出してはならない。ファイルにも保存する。 | | LLM Log | promptとresponseを記録する。call、Session、Task、Planner Task、phase、iteration、replan、model、token usageを相関できなければならない。secretを継承しない前提でも、ログ出力先は保護する。 | -| Audit Log | 通常ログと分離する。Task lifecycle、Tool、process、args、exit code、file write、delete、denied access、network rule、recoveryをSession/Taskと相関して記録する。 | +| Audit Log | 通常ログと分離する。Task lifecycle、Internal Tool Call、Sandbox Process、秘密情報を除いたargument metadata、exit code、file write、delete、denied access、network rule、recoveryをSession/Taskと相関して記録する。argument本文、画像、Base64、credentialは記録しない。 | | Token Metrics | Task/Call単位のinput/output/total tokenを記録する。 | --- @@ -481,17 +513,18 @@ Context要約を開始する利用率閾値は設定可能でなければなら | ID | 不変条件 | | --- | --- | | SEC-INV-01 | LLMの出力だけでは権限を増加できない。 | -| SEC-INV-02 | MCP ClientはSandboxPolicyを変更できない。 | +| SEC-INV-02 | MCP ClientはUser Sandbox Configuration、Resolution Result、Executable Approval、Effective Sandbox Policyを変更できない。 | | SEC-INV-03 | descendant processは親より強い権限を持てない。 | | SEC-INV-04 | 未許可Filesystem pathへR/W/E/Deleteできない。 | -| SEC-INV-05 | 承認hashと一致しない実行ファイルを起動できない。 | -| SEC-INV-06 | Network denyではlocalhostを含め通信できない。 | -| SEC-INV-07 | Network allowでもallow-list外host/portへ通信できない。 | +| SEC-INV-05 | 承認hashと一致しないHost ExecutableをBrokerからEntry Processとして直接起動できない。 | +| SEC-INV-06 | Network noneではLoopbackを含め通信できない。 | +| SEC-INV-07 | Network local/restrictedでもEffective Network Policy外のaddress/portへ通信できない。 | | SEC-INV-08 | CredentialをSandboxへ暗黙継承しない。 | | SEC-INV-09 | Fixed System Promptは利用者入力で置換できない。 | | SEC-INV-10 | Task終了後にTask Resourceを残さない。 | | SEC-INV-11 | Recovery未完了状態でMCP受付を開始しない。 | | SEC-INV-12 | stdio stdoutにはMCP protocol以外を書かない。 | +| SEC-INV-13 | Sandbox Process TreeのどのProcessもEffective Sandbox Policy外のresourceまたはcapabilityを取得できない。 | --- @@ -505,7 +538,7 @@ Context要約を開始する利用率閾値は設定可能でなければなら | NFR-04 | Maintainability | 外部MCP Toolを2個に固定し、内部責務を分離する。 | | NFR-05 | Dependency Control | 標準ライブラリで実現可能な機能に新規依存を追加しない。 | | NFR-06 | Portability | v1はWindows 11 x64専用。Windows機構を抽象化し過ぎない。 | -| NFR-07 | Observability | Task、Tool、Process、Token、Policy denialを追跡可能にする。 | +| NFR-07 | Observability | Task、Internal Tool Call、Sandbox Process、Token、Effective Sandbox Policy denialを追跡可能にする。 | | NFR-08 | Localization | 英語・日本語を標準提供し、追加localeをコード変更なしで導入可能。 | | NFR-09 | Readability | 設定、ログ、仕様語彙を一貫させる。 | @@ -522,11 +555,13 @@ Context要約を開始する利用率閾値は設定可能でなければなら | AT-05 | MCP temperature overrideがTask scopeのみで有効。 | | AT-06 | 非Vision modelへ画像指定時、選択localeのerrorが返る。 | | AT-07 | 未許可file read/write/deleteがOSまたはBrokerで拒否されAuditに残る。 | -| AT-08 | reparse point経由で許可path外へ到達できない。 | -| AT-09 | 承認hash変更後のexe実行が拒否される。 | -| AT-10 | Network denyでloopbackを含む通信が拒否される。 | -| AT-11 | allow-list外host/portへの通信が拒否される。 | -| AT-12 | 子プロセス・孫プロセスがJobとSandbox制約から逸脱できない。 | +| AT-08 | reparse解決結果が未確認または変更されたLogical Pathは拒否される。 | +| AT-09 | Approved Entry Executableのhash変更後の直接起動が拒否される。 | +| AT-10 | Network noneでLoopbackを含む通信が拒否される。 | +| AT-11 | local/restrictedのEffective Network Policy外address/portへの通信が拒否される。 | +| AT-12 | Entry/Descendant ProcessがLPACとJob confinementを継承し、breakawayまたはPolicy外resource accessができない。 | +| AT-21 | Approved Python、Approved PowerShell、Approved .NETから通常のDescendant Processを生成できる。 | +| AT-22 | development Workspace ArtifactはApprovalなしでEntry起動でき、External Unknown Executableの直接Entry起動は拒否される。 | | AT-13 | Task crash後、次回起動RecoveryでTask Resourceが除去される。 | | AT-14 | TaskGraph cycle追加が拒否される。 | | AT-15 | completed Taskが変更されない。 | @@ -540,10 +575,10 @@ Context要約を開始する利用率閾値は設定可能でなければなら | ID | 検証条件 | | --- | --- | -| E2E-01 | ソースツリー外へ展開したRelease Bundleだけを使い、local Ollamaとstdio MCP Clientから実際のfixture修正、build、test、日本語応答、Audit追跡、Task Resource cleanupまで完走する。 | -| E2E-02 | E2E-01と同等の作業をloopback限定Streamable HTTPで完走する。 | +| E2E-01 | ソースツリー外へ展開したRelease Bundle、Python 3.14 Approval、配布既定model、stdio MCP Clientを使い、複雑なPython programとsubprocessを含むtestの作成・実行、日本語応答、Audit追跡、Task Resource cleanupまで完走する。 | +| E2E-02 | E2E-01と同等の作業をloopback限定Streamable HTTPのIPv4/IPv6で完走する。 | -v1の完了には、win-x64向けself-contained Release Bundleが単独起動でき、E2E-01とE2E-02がInternetまたはcloud modelに依存せずPASSすることを必須とする。 +v1の完了には、win-x64向けself-contained Release Bundleが単独でEnvironment Resolutionを実行でき、確認済みOperational配置でE2E-01とE2E-02が`deepseek-v4-flash:cloud`を使ってPASSすることを必須とする。rate limit、接続失敗、model unavailableをPASSへ読み替えない。 --- @@ -573,7 +608,7 @@ v1の完了には、win-x64向けself-contained Release Bundleが単独起動で ## 23. 変更管理 -- 本仕様の変更は `schema_version`、MCP Tool schema、SandboxPolicy、安全不変条件への影響を必ず確認する。 +- 本仕様の変更は `schema_version`、MCP Tool schema、Effective Sandbox Policy、安全不変条件への影響を必ず確認する。 - Design.mdが本仕様と矛盾した場合は本仕様を優先し、Design.mdを修正する。 - 実装都合で仕様を暗黙変更してはならない。必要な場合は先に仕様を変更する。 @@ -603,7 +638,7 @@ v1の完了には、win-x64向けself-contained Release Bundleが単独起動で - `temperature` overrideを永続設定へ書き戻すこと。 - Legacy HTTP+SSEを互換目的で自動有効化すること。 - Streamable HTTPをloopback外にbindすること。 -- write permissionだけでdeleteを許可すること。 +- write Filesystem Capabilityだけでdeleteを許可すること。 - reparse point解決前の文字列pathだけでallow判定すること。 - hash不一致の実行ファイルを自動再承認すること。 - Network `allow`をunrestricted outboundとして解釈すること。 |