From 36ae1a4cba791ec633a81b38b1d8345af8487276 Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Thu, 13 Aug 2026 19:15:01 +0900 Subject: feat!: unify sandbox configuration and permission application Replace the split executable approval and sandbox resolution workflows with schema_version 2 and a YAML-driven execution.entries model. Resolve workspace, mount, executable, runtime, network, and resource settings into one config-scoped Applied Configuration snapshot protected by a user-only DACL and written with atomic replacement. Reduce the public CLI to implicit server startup, show, and apply. Remove serve/check, executable and sandbox subcommands, and configuration override flags including --config, --lang, --transport, --path, and --runtime-root. Add migration diagnostics for every removed schema and command surface, and keep server preflight mandatory for both stdio and HTTP. Update effective-policy compilation to validate the applied fingerprint, resolved paths, and executable hashes before startup. Preserve fail-closed behavior while allowing execution entries and runtime roots inside a development workspace to inherit that workspace capability without creating an impossible narrower ACL boundary. Rewrite the README around the consolidated permission matrix and document configuration, application, store location, startup, transport-specific elevation, Python 3.14, PowerShell, and cmd usage. Align specifications, design, implementation plan, traceability, audit report, localization, publish scripts, and operational verification with the breaking schema. Verification: Release build completed with zero warnings and errors; Agent.Core.Tests 104/104 and Agent.Planner.Tests 10/10 passed; administrator Windows Security/Recovery 56/56 and README operational 19/19 passed with no skips; published HTTP MCP completed a cmd/curl/venv-Python task with network deny and zero ACL, WFP, journal, backup, or process residue. --- doc/AuditReport.md | 2 ++ doc/Design.md | 55 ++++++++++++++++++++++++++++----------------------- doc/Specifications.md | 43 ++++++++++++++++++++-------------------- 3 files changed, 54 insertions(+), 46 deletions(-) (limited to 'doc') diff --git a/doc/AuditReport.md b/doc/AuditReport.md index b176260..3cbed19 100644 --- a/doc/AuditReport.md +++ b/doc/AuditReport.md @@ -1,5 +1,7 @@ # v1再監査報告とSandbox Usability Revision状況 +> 2026-08-13 schema version 2追補: YAMLを唯一のSandbox desired stateとし、個別のExecutable Approval／Sandbox Resolution操作を廃止した。CLIはcommand省略のServer起動、`apply`、`show`に限定し、確認結果はconfig別Applied Configuration Storeへ一括保存する。本追補より前の管理者・publish証跡は旧schemaの履歴であり、schema version 2のPASS根拠ではない。最終検証はRelease build warning/error 0、Core 104件、Planner 10件、Windows Security/Recovery 56件、README operational 19件がfail/skip 0。publish HTTP MCPも`deepseek-v4-flash:cloud`でcompleted 3/3となり、cmd→cmd/curl/venv Python、Network none、終了後残留0を確認した。 + ## 基準 commit `37386b8`に対する2026-08-11の再監査結果は履歴として以下に保持する。2026-08-12に開始したSandbox Usability RevisionはUser Sandbox Configuration、Resolution、Executable Approval、Effective Sandbox Policy、LPAC Process Treeへ安全境界を改定する破壊的変更であり、旧commitのPASSを現行実装へ流用しない。 diff --git a/doc/Design.md b/doc/Design.md index d4920a0..80b5acc 100644 --- a/doc/Design.md +++ b/doc/Design.md @@ -444,7 +444,7 @@ raw chain-of-thoughtは保存・要約対象としない。 ## 10. User Sandbox Configuration・Resolution・Effective Policy設計 ### 10.1 schema概要 ```yaml -schema_version: 1 +schema_version: 2 application: language: en mcp: @@ -476,8 +476,7 @@ sandbox: workspaces: [] mounts: [] execution: - executables: [] - shells: [] + entries: [] network: access: none local_endpoints: [] @@ -507,18 +506,23 @@ base YAMLと同じdirectoryに`agent.local.yaml`が存在する場合、YAML nod - `workspaces`はLogical Path文字列のsequenceとする。`readonly`はreadのみ、`development`はread/write/delete/Artifact executeへcompileする。 - `mounts`は`path`と`access: read_only|read_write|read_write_delete`を持つ。readonly Profileではread_onlyだけを許可し、Mountにexecuteを付与しない。 - relative Logical Pathはbase YAML directory基準。実在するlocal directoryだけを許可する。 -- 同一Resolved Rootはcapabilityを統合する。親の継承capabilityより狭いnested rootは拒否する。 -### 10.3 Executable Alias・Approval Store +- 同一Resolved Rootはcapabilityを統合する。利用者が宣言したWorkspace/Mountについて、親の継承capabilityより狭いnested rootは拒否する。Execution EntryまたはRuntime Rootがdevelopment Workspace内にある場合、その派生rootは親Workspaceのcapabilityを継承するため別の制限境界とは扱わず、Alias/Resolved Path/SHA-256によるEntry identity検査は維持する。 +### 10.3 Execution Entry・Applied Configuration Store ```yaml execution: - executables: [python, git] - shells: [powershell] + entries: + - alias: python + path: C:/runtime/python.exe + runtime_root: C:/runtime + - alias: cmd + path: C:/Windows/System32/cmd.exe ``` -- AliasはApprovalではない。CLIが候補を提示し、人間が選択したResolved Executable PathとSHA-256をWindows user単位Storeへ固定する。 -- Store pathは`%LOCALAPPDATA%/AgentSandboxMcp/executable-approvals.json`。user-only DACL、WriteThrough、atomic replace、schema versionを持つ。 -- recordはAlias、Approved Entry Executable/Approved Shell Executable分類、Logical Path、Resolved Path、SHA-256、optional Runtime Root、承認日時を持つ。 -- Runtime RootはCLI提案後の明示確認対象とし、その配下のRuntime Componentは個別hashなしでEntry起動できる。 -- Aliasはcase-insensitiveに一意とし、Executable/Shell双方への重複指定を拒否する。ShellのResolved file nameは`cmd.exe|powershell.exe|pwsh.exe`だけを許可する。 +- EntryはAlias、Logical Executable Path、optional Logical Runtime RootをYAML内で一体として宣言する。Runtime Root省略はRuntime Rootなしを意味する。 +- apply時にExecutableをResolved Pathへ固定しSHA-256を計算する。Resolved file nameが`cmd.exe|powershell.exe|pwsh.exe`ならApproved Shell Executable、それ以外はApproved Entry Executableへ分類する。 +- Aliasはcase-insensitiveに一意とする。Executableは実在file、Runtime Rootは実在directoryでなければならない。 +- Store pathは`%LOCALAPPDATA%/AgentSandboxMcp/applied-configurations/.json`。user-only DACL、WriteThrough、atomic replace、schema versionを持つ。 +- Storeはconfig path、YAML fingerprint、Workspace/Mount Resolution、全Execution EntryのAlias、分類、Logical/Resolved Path、SHA-256、Runtime Root、Network/Resourceを含む一つのsnapshotとする。個別Approval StoreとResolution Storeは持たない。 +- applyは全項目を先に解決・検証して差分を一度表示し、承認後にsnapshot全体をatomic replaceする。YAMLから削除されたEntryは同じtransactionで適用状態から除去する。 ### 10.4 Network entry ```yaml network: @@ -531,14 +535,16 @@ network: `none`は全deny、`local`は列挙portを`127.0.0.1`/`::1`へ展開、`restricted`はhostをTask開始時にIP snapshot化する。mode不一致または空endpointを拒否する。 ### 10.5 Resource Profile `constrained=1024 MiB/4/300秒`、`normal=4096 MiB/16/1800秒`、`extended=8192 MiB/32/3600秒`とする。`memory_mb`、`process_limit`、`execution_timeout_seconds`の正数overrideはpreset値を置換する。 -### 10.6 Resolution Result -- Workspace/MountのLogical→Resolved mapping、config絶対path、semantic sandbox fingerprint、確認日時を`%LOCALAPPDATA%/AgentSandboxMcp/environment-resolutions/.json`へ保存する。 -- reparse chainを最終targetまで解決しcycle、missing target、非local filesystemを拒否する。確認後のfingerprintまたはResolved Path変化はserve/checkをfail-closedにする。 -- `sandbox resolve`はpreview、`sandbox confirm`だけがStoreを更新し、`sandbox show`はEffective Sandbox Policyをtext/JSON表示する。 +### 10.6 Apply・起動・表示 +- reparse chainを最終targetまで解決しcycle、missing target、非local filesystemを拒否する。 +- `agent-mcp apply [config] [--yes]`だけがApplied Configuration Storeを更新する。全解決・validation完了前、または確認前にStoreを変更しない。 +- `agent-mcp [config]`は現在のYAMLを再解決・再hashし、Applied Configuration snapshotとの完全一致とWindows preflightを検証してからMCP受付を開始する。個別の`serve`と`check`commandは持たない。 +- `agent-mcp show [config]`はdesired/resolved/appliedの権限matrixをtext表示し、StoreやACL/WFPを変更しない。管理者権限、BFE、WFP add/deleteを伴う完全なWindows preflightはServer起動時だけ実行する。 +- languageとtransportはYAMLだけから取得し、CLI overrideを持たない。 ### 10.7 Effective Sandbox Policy -確認済みResolution Resultと現在のApproval Storeをcompileし、次を由来付きで保持する。 +現在のYAMLと一致するApplied Configuration snapshotをcompileし、次を由来付きで保持する。 - Filesystem Root: `workspace`、`mount`、`approved_entry_executable`、`approved_shell_executable`、`runtime_root`、`os_runtime_root`の由来、Resolved Path、Filesystem Capability。 - Entry Executable: Alias、分類、Resolved Path、SHA-256、optional Runtime Root。 @@ -547,7 +553,7 @@ network: - Resource: Resource Profile名、override適用後のmemory/process/timeout。 - baseline capability: 固定された`registryRead`と`lpacInstrumentation`。 -同じResolved RootのFilesystem Capabilityは和集合にし、由来も併記する。親rootから継承するCapabilityより狭いnested rootは表現不能としてcompileを拒否する。`sandbox show`はこのcompile結果をtextまたはJSONで表示するが、Storeや設定を変更しない。 +同じResolved RootのFilesystem Capabilityは和集合にし、由来も併記する。親rootから継承するCapabilityより狭いnested rootは表現不能としてcompileを拒否する。`show`は現在の希望状態、解決結果、hash、適用状態をtextで表示するが、Storeや設定を変更しない。 --- ## 11. Windows強制設計 ### 11.1 Less Privileged AppContainer @@ -589,7 +595,7 @@ network: - process count / memory limitをJobへ設定する。 - `KILL_ON_JOB_CLOSE`相当を利用し、application終了時にprocess treeを残さない。 ### 11.4 Entry Process分類・Executable Approval -- AliasはApproval StoreのApproved Entry Executable/Shellへ解決し、起動直前とsuspended生成後・resume前にResolved PathとSHA-256を再検証する。 +- Aliasは現在のApplied Configuration snapshotのApproved Entry Executable/Shellへ解決し、起動直前とsuspended生成後・resume前にResolved PathとSHA-256を再検証する。 - Runtime Componentは確認済みRuntime Root containment、Workspace Artifactはdevelopment Artifact Root containmentで分類する。MountおよびExternal Unknown Executableからの直接Entry起動は拒否する。 - Descendant Processは個別分類・Approvalを行わず、LPAC/ACL/WFP/Job confinementをSecurity Boundaryとする。`PROCESS_CREATION_CHILD_PROCESS_RESTRICTED`は使用しない。 ### 11.5 WFP方針 @@ -736,7 +742,7 @@ closed Sessionは再利用しない。プロセス再起動後に以前のSessio - locale baseline/placeholder - Ollama endpoint URI - Sandbox path canonicalization -- Executable Approval StoreのAlias/Logical Path/Resolved Path/hash format +- Applied Configuration Storeのconfig path/fingerprint、Filesystem Resolution、Execution EntryのAlias/Logical Path/Resolved Path/hash format - network host/port syntax - resource limit range - Fixed/User prompt file state @@ -748,7 +754,7 @@ closed Sessionは再利用しない。プロセス再起動後に以前のSessio | TokenPERT | O<=M<=P<=budget、式のunit test | | TokenCPM | 既知DAGに対するcritical path unit test | | Filesystem | allow/deny/reparse point integration test | -| Process | Alias不明、Approval不足、hash/Resolved Path変更、Entry分類拒否、LPAC不一致 | +| Process | Alias不明、未適用、hash/Resolved Path変更、Entry分類拒否、LPAC不一致 | | Network | noneのLoopback、local/restrictedのPolicy外address/port | | Recovery | 各transaction stateで強制crashして再起動cleanup | | MCP | stdio purity、Streamable HTTP loopback、GET 405 | @@ -779,8 +785,8 @@ closed Sessionは再利用しない。プロセス再起動後に以前のSessio | ST-20 | External Unknown/System32 Executableの直接Entry | Approvalなしでは拒否 | | ST-21 | malformed locale | 起動失敗 | | ST-22 | non-loopback HTTP bind | 起動失敗 | -| ST-23 | Approval/Resolution Store | user-only DACL、atomic replace、破損record拒否 | -| ST-24 | config fingerprint/Resolved Path/hash変更 | 再確認または再承認までfail-closed | +| ST-23 | Applied Configuration Store | user-only DACL、snapshot全体のatomic replace、破損record拒否 | +| ST-24 | config fingerprint/Resolved Path/hash変更 | 全体を再applyするまでfail-closed | | ST-25 | Entry (`PowerShell`/Python/.NET/`cmd`) × Descendant (`cmd`/PowerShell/Python/.NET/System32 utility) | 個別Approvalなしで起動し、Descendantが同じLPAC SID/Jobに残る。cmd内からはPATH解決名またはWorkspace相対pathを使用する | | ST-26 | protected DACL root/descendantと通常DACL rootのread/write/execute | protected bitを解除せず、許可ケースだけ成功。適用不能ケースは拒否し、cleanup後Security Descriptorが完全一致 | | ST-27 | baseline/Network capabilityの追加前後 | 必要な正方向ケースに加えFilesystem、Registry write、COM、Policy外Network、Job breakawayの負方向集合をすべて検証 | @@ -894,8 +900,7 @@ errorは内部codeとlocalized messageを分離し、ログ/auditにはcode、MC | sandbox.profile | readonly/development Workspace preset | | sandbox.workspaces | Workspace Logical Path list | | sandbox.mounts | Mount Logical Path + semantic access | -| sandbox.execution.executables | Approved Entry Executable Alias list | -| sandbox.execution.shells | Approved Shell Executable Alias list | +| sandbox.execution.entries | Alias、Executable Logical Path、optional Runtime Rootのlist。Shell分類はResolved file nameから導出 | | sandbox.network.access | none/local/restricted | | sandbox.network.local_endpoints | Loopback port list | | sandbox.network.restricted_endpoints | host/port list | diff --git a/doc/Specifications.md b/doc/Specifications.md index 79cb653..fb1de12 100644 --- a/doc/Specifications.md +++ b/doc/Specifications.md @@ -110,8 +110,8 @@ IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・ | UC-02 | MCP Client | Task状態を照会する | 状態と、完了時には最終回答をテキストで得る | | UC-03 | 利用者 | 画像付き依頼を送信する | Vision対応modelなら処理される | | UC-04 | 利用者 | 言語を指定して起動する | CLI/診断/MCP応答/LLM最終回答が指定言語になる | -| UC-05 | 利用者 | User Sandbox Configurationを設定・確認する | semantic設定からEffective Sandbox Policyが可視化され、未許可能力はdenyされる | -| UC-06 | 利用者 | Entry Executableを承認する | Alias、Resolved Path、SHA-256一致時だけBrokerから直接起動できる | +| UC-05 | 利用者 | User Sandbox Configurationを適用する | YAML全体の解決・Executable identity・権限差分を一度確認し、原子的に適用できる | +| UC-06 | 利用者 | 適用状態を確認する | YAML、Resolved Path、Executable hash、Effective Sandbox Policy、Platform状態を一つの表で確認できる | | UC-07 | Agent | 計画を作成・更新する | TaskGraphがDAGを維持しToken CPMを再計算する | | UC-08 | Agent | Internal Toolを呼ぶ | Policy検査後にのみ副作用が発生する | | UC-09 | システム | 異常終了から復旧する | 残留Task Resourceを除去してから受付開始する | @@ -176,21 +176,21 @@ IPA「厳密な仕様記述入門」の考え方に従い、課題・仕様・ ### 5.6 CLI -v1のCLI surfaceは次に限定する。 +schema version 2のCLI surfaceは次に限定する。 ```text -agent-mcp [serve] [--config ] [--lang ] [--transport ] -agent-mcp check [--config ] [--lang ] -agent-mcp executable resolve [--path ] --config -agent-mcp executable approve [--path ] [--runtime-root |--no-runtime] [--yes] --config -agent-mcp executable list --config -agent-mcp executable revoke [--yes] --config -agent-mcp sandbox resolve --config -agent-mcp sandbox confirm [--yes] --config -agent-mcp sandbox show [--format ] --config +agent-mcp [] +agent-mcp apply [] [--yes] +agent-mcp show [] ``` -command省略時、および先頭引数がoptionの場合は `serve` として扱う。`resolve`、`list`、`show`、`check`はread-onlyとする。`approve`、`revoke`、`confirm`は差分表示後の対話確認を既定とし、明示的な`--yes`を許可してAuditへ記録する。MCP ClientおよびLLMからこれらの変更操作を呼び出せない。 +command省略時はYAMLの`mcp.transport`と`application.language`を使用してMCP Serverを起動する。config path省略時は実行ファイルと同じdirectoryの`agent.yaml`を使用する。CLIからYAML値を上書きしてはならない。 + +`apply`はbase/local merge後のYAML全体、Workspace、Mount、Execution Entry、Network、Resourceを解決し、ExecutableのResolved PathとSHA-256を含む権限差分を一度だけ表示する。全検証成功後、利用者が承認した場合だけconfig別Applied Configuration Storeをatomic replaceする。途中失敗時は以前の適用状態を維持する。`--yes`は非対話適用だけに使用でき、Auditへ記録する。 + +`show`はread-onlyとし、desired/resolved/applied/effectiveの状態とFilesystem/Execution/Network/Resource権限マトリックスを一つのtext表示で返す。WFP filter追加削除を伴う完全なPlatform preflightは起動時に必ず実施する。MCP ClientおよびLLMから`apply`を呼び出せない。 + +旧`serve`、`check`、`executable *`、`sandbox *`、`--config`、`--lang`、`--transport`、`--path`、`--runtime-root`、`--no-runtime`、`--format`は受け付けず、schema version 2の移行診断を返す。 ### 5.7 MCP 2026-07-28とTasks Extension @@ -206,7 +206,7 @@ command省略時、および先頭引数がoptionの場合は `serve` として ### 5.8 起動・HTTP観測性 -- `serve`はbind前に管理者権限、BFE、WFP transaction、filter add/deleteを検査し、不足時は具体的なerrorと対処をstderrへ出してexit code 2で終了しなければならない。 +- command省略のServer起動はbind前に管理者権限、BFE、WFP transaction、filter add/deleteを検査し、不足時は具体的なerrorと対処をstderrへ出してexit code 2で終了しなければならない。 - ready messageは実際のtransport開始後だけ出力し、HTTPではendpoint/protocol/stateless/PID/log path、stdioではprotocol/PID/log pathを含める。 - HTTP request logは実socketのremote/local endpoint、method、path、status、duration、標準MCP routing headerを記録可能とする。 - `Authorization`、`Cookie`、query、body、prompt、画像、Base64をrequest logへ記録してはならず、`X-Forwarded-For`を接続元として信用してはならない。 @@ -458,8 +458,8 @@ Resource Profileは`constrained = 1024 MiB/4 Process/300秒`、`normal = 4096 Mi | I18N-02 | 標準localeとして `locales/en.json` と `locales/ja.json` を配布する。 | | I18N-03 | ユーザーは `zh-CN.json` 等を追加し、アプリ変更なしでlocaleを追加できる。 | | I18N-04 | locale識別子はBCP 47形式を推奨する。 | -| I18N-05 | `--lang ` で起動時に選択可能。 | -| I18N-06 | 優先順位は CLI > config > built-in default(en)。 | +| I18N-05 | 起動時のlocaleは`application.language`で選択する。 | +| I18N-06 | 優先順位はconfig > built-in default(en)とし、CLI overrideを持たない。 | | I18N-07 | 選択言語はCLI、診断、MCPテキスト応答、LLM最終回答へ適用する。 | | I18N-08 | 入力言語の自動検出による切替は行わない。 | | I18N-09 | placeholderは `{task}` のようなnamed placeholderを使う。 | @@ -471,15 +471,16 @@ Resource Profileは`constrained = 1024 MiB/4 Process/300秒`、`normal = 4096 Mi ## 15. Configuration仕様 - 主設定形式はYAML。 -- `schema_version: 1` を必須とする。本改訂前の`filesystem`および`process.approvals`形式は破壊的に廃止し、移行方法付きで拒否する。 +- `schema_version: 2` を必須とする。version 1の`execution.executables`／`execution.shells`と、それ以前の`filesystem`／`process.approvals`形式は破壊的に廃止し、移行方法付きで拒否する。 - 設定変更の反映には再起動を必須とする。 - Hot Reloadは明示的に非対応。 -- CLIの `--config` で設定ファイルpathを選択可能。 +- config pathはCLIの任意の位置引数で選択可能とし、optionによる設定上書きを持たない。 - base設定と同じdirectoryに `agent.local.yaml` が存在する場合は任意overrideとして読み込む。mapは再帰mergeし、scalarと配列はlocal側で置換する。merge後の設定全体をvalidationし、相対pathはbase設定directoryを基準に解決する。 - Release Bundleは既定設定だけを配布し、利用者のlocal設定、User System Prompt、Skillをpublishで上書きしてはならない。 -- 起動時に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にする。 +- `sandbox.execution.entries`はAlias、Executable Logical Path、optional Runtime Rootを一つのrecordとして持つ。Shell分類はResolved file nameから内部で決定する。 +- 起動時にschema、Applied Configuration、locale、Effective Sandbox Policyのvalidationを行う。 +- Workspace/Mount ResolutionとExecutable identity/Approvalを分離保存せず、config別Applied Configuration Storeへ一つのsnapshotとして保存する。StoreはWindows user単位のuser-only領域に置き、Release Bundleへ含めない。 +- YAML fingerprint、Resolved Path、Executable SHA-256、Runtime Rootのいずれかが適用済みsnapshotと異なる場合、起動はfail-closedにして`agent-mcp apply`を案内する。 --- -- cgit v1.2.3