summaryrefslogtreecommitdiff
path: root/doc/Design.md
diff options
context:
space:
mode:
authortanaka takashi <isazaka@gmail.com>2026-08-13 19:15:01 +0900
committertanaka takashi <isazaka@gmail.com>2026-08-13 19:15:01 +0900
commit36ae1a4cba791ec633a81b38b1d8345af8487276 (patch)
tree91cef96efac7eb8c2754658ce5af5181b1a15898 /doc/Design.md
parent76fdcb43585a4c4d288c1026d318a0ddbe3e26ab (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.md55
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 |