diff options
| author | tanaka takashi <isazaka@gmail.com> | 2026-08-13 19:15:01 +0900 |
|---|---|---|
| committer | tanaka takashi <isazaka@gmail.com> | 2026-08-13 19:15:01 +0900 |
| commit | 36ae1a4cba791ec633a81b38b1d8345af8487276 (patch) | |
| tree | 91cef96efac7eb8c2754658ce5af5181b1a15898 /doc/Design.md | |
| parent | 76fdcb43585a4c4d288c1026d318a0ddbe3e26ab (diff) | |
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.
Diffstat (limited to 'doc/Design.md')
| -rw-r--r-- | doc/Design.md | 55 |
1 files changed, 30 insertions, 25 deletions
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/<config-path-hash>.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/<config-path-hash>.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 | |
