diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 120 |
1 files changed, 73 insertions, 47 deletions
@@ -1,6 +1,6 @@ # AI Agent Sandbox MCP Server v1 -Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、Process、Network操作だけをAppContainer内で実行するMCP Serverです。MCP `2026-07-28`のstateless HTTPと公式Tasks Extensionに対応し、MCP公開Toolは `agent_run` と `agent_status` の2つです。 +Windows 11上でOllamaを利用し、利用者が確認したWorkspace、Mount、Executable、Network、Resourceの範囲だけをLPAC内で実行するMCP Serverです。MCP `2026-07-28`のstateless HTTPと公式Tasks Extensionに対応し、MCP公開Toolは `agent_run` と `agent_status` の2つです。 ## 動作要件 @@ -8,7 +8,7 @@ Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、 - 管理者権限（TaskごとのWFP filter追加・削除に必要） - Base Filtering Engine (BFE)が実行中 - Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。 -- Release既定model: `deepseek-v4-flash:cloud`（native Tool calling対応） +- Release既定model: `deepseek-v4-flash:cloud`（native Internal Tool calling対応） サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。 @@ -22,9 +22,14 @@ ollama pull deepseek-v4-flash:cloud ollama serve ``` -別の管理者PowerShellで診断します。 +初回はUser Sandbox ConfigurationのLogical Pathを確認してから、別の管理者PowerShellで診断します。 ```powershell +.\agent-mcp.exe sandbox resolve --config .\agent.yaml +.\agent-mcp.exe executable resolve python --config .\agent.yaml +.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml +.\agent-mcp.exe sandbox confirm --config .\agent.yaml +.\agent-mcp.exe sandbox show --format text --config .\agent.yaml .\agent-mcp.exe check --config .\agent.yaml --lang ja ``` @@ -32,9 +37,67 @@ ollama serve `serve`も待受開始前に同じprobeを必ず実行します。失敗時はendpointをbindせず、失敗項目・Win32 error・対処方法をstderrと`logs/application.log`へ出してexit code 2で終了します。 -## agent.yaml +## User Sandbox Configuration -Filesystem pathは能力ごとに指定します。未指定能力はdenyです。 +`schema_version: 1`のSandbox設定は利用者が理解できるsemantic単位で記述します。未指定capabilityはdenyです。 + +```yaml +sandbox: + profile: development + workspaces: + - C:/work/project + mounts: + - path: C:/data/reference + access: read_only + execution: + executables: [python, git] + shells: [powershell] + network: + access: local + local_endpoints: + - port: 11434 + restricted_endpoints: [] + resources: + profile: normal + # memory_mb: 4096 + # process_limit: 16 + # execution_timeout_seconds: 1800 +``` + +`readonly` ProfileはWorkspaceをread-onlyにし、Workspace ArtifactのEntry起動を禁止します。`development`はWorkspaceのread/write/deleteとArtifact起動を許可します。Mountは`read_only`、`read_write`、`read_write_delete`から選び、Mount上のExecutableをEntry Processとして起動することはできません。 + +Resource Profileは`constrained`（1024 MiB/4 Process/300秒）、`normal`（4096 MiB/16 Process/1800秒）、`extended`（8192 MiB/32 Process/3600秒）です。正数overrideを指定できます。 + +Network accessは`none`、`local`、`restricted`です。`none`はLoopbackを含め全deny、`local`は列挙portの`127.0.0.1`と`::1`だけ、`restricted`はTask開始時にIP snapshot化したhost/portだけを許可します。Ollama通信はBroker側から行うため、Sandbox Process TreeのNetwork設定とは独立です。 + +Workspace/Mountはreparse chainをResolved Pathへ解決します。`sandbox resolve`で差分を確認し、`sandbox confirm`でconfig別のResolution Storeへ保存してください。config fingerprintまたはResolved Pathが変わると`serve`は再確認までfail-closedになります。 + +```powershell +.\agent-mcp.exe sandbox resolve --config .\agent.yaml +.\agent-mcp.exe sandbox confirm --config .\agent.yaml +.\agent-mcp.exe sandbox show --format json --config .\agent.yaml +``` + +## Executable Approval + +`sandbox.execution`には人間向けAliasを記載します。PATH候補は提示だけで自動選択されません。選んだResolved PathとSHA-256をuser-local Approval Storeへ固定します。 + +```powershell +.\agent-mcp.exe executable resolve python --config .\agent.yaml +.\agent-mcp.exe executable approve python --path C:\Python314\python.exe --runtime-root C:\Python314 --config .\agent.yaml +.\agent-mcp.exe executable list --config .\agent.yaml +.\agent-mcp.exe executable revoke python --config .\agent.yaml +``` + +Approved Entry Executable／Approved Shell ExecutableはAlias、Resolved Path、SHA-256一致が必要です。確認済みRuntime Root内のRuntime Componentと、development Workspace内のWorkspace ArtifactもEntry Processにできます。その他のExternal Unknown ExecutableをBrokerから直接起動することはできません。 + +ApprovalはEntry Processにだけ適用されます。Descendant Processは個別Approvalを要求せず、Entry Processと同じLPAC token、Filesystem ACL、WFP、Job Objectを継承します。Jobからのbreakawayは禁止され、Process数・memory・timeout・`KILL_ON_JOB_CLOSE`はProcess Tree全体へ適用されます。 + +Sandbox Process Treeへは最小限のWindows/runtime環境変数だけを渡し、Brokerの任意token、password、SSH/API credential環境変数は継承しません。User profile等のpathが環境に含まれても、そのpathへFilesystem Capabilityは付与されません。 + +Executable Approval StoreとResolution Storeは`%LOCALAPPDATA%\AgentSandboxMcp`にuser-only DACL、WriteThrough、atomic replaceで保存されます。publishやupgradeはこれらのStoreを上書きしません。 + +## その他のagent.yaml設定 MCP Taskの保持とlog出力は次のtyped settingで変更できます。 @@ -62,47 +125,9 @@ logging: Task状態は`state/mcp-tasks/`へatomic保存されます。再起動時の未完了Taskは`failed/server_restarted`となり、自動再実行されません。 -```yaml -sandbox: - filesystem: - read: [C:/work/fixture] - write: [C:/work/fixture] - execute: - - C:/Program Files/dotnet/dotnet.exe - delete: [C:/work/fixture] -``` - -実行ファイルはcanonical absolute pathとSHA-256の両方を承認します。 - -```powershell -(Get-FileHash -Algorithm SHA256 -LiteralPath 'C:\Program Files\dotnet\dotnet.exe').Hash -``` - -```yaml -sandbox: - process: - allow_shell: false - approvals: - - path: C:/Program Files/dotnet/dotnet.exe - sha256: <64桁の実測値> -``` - -Sandbox processからの子process生成は、承認済みpathであってもOSのchild-process restrictionで拒否されます。build/testで必要な各実行ファイルは事前にpath/hash承認し、個別の `process_run` としてBrokerから起動してください。E2Eではbuild server、node reuse、shared compilationを無効化し、in-process buildまたはBrokerから直接起動できるself-testを使用します。Networkは既定でlocalhostを含めdenyです。allow時はTask開始時にhostをIPへsnapshot化します。 - -```yaml -sandbox: - network: - mode: allow - allow: - - host: 127.0.0.1 - ports: [11434] -``` - -Ollama通信は管理Broker側から行うため、Sandbox processのnetwork許可とは独立です。 - ## Agent Skills -`skills/<skill-name>/SKILL.md`形式だけを読み込みます。legacyの`skills/*.md`は読み込みません。SkillはLLMへの補助指示であり、Filesystem/Process/Network権限は付与しません。Skillが使用する実行ファイルは、別途`agent.yaml`でabsolute pathとSHA-256を承認してください。 +`skills/<skill-name>/SKILL.md`形式だけを読み込みます。legacyの`skills/*.md`は読み込みません。SkillはLLMへの補助指示であり、Sandbox capabilityは付与しません。Skillが使うHost ExecutableはAliasを設定し、Entry起動前に承認してください。 ## stdio @@ -162,8 +187,9 @@ LLM/Audit JSONLはtask、session、event、call単位で絞り込めます。 - `error 5` / administrator=false: 管理者PowerShellから起動してください。 - BFE open失敗: `Get-Service BFE` でBase Filtering Engineを確認してください。 - Ollama接続失敗: `ollama list`、endpoint、model名を確認してください。 -- executable deny: pathをabsolute/canonicalにし、更新後のSHA-256を再取得してください。 -- file deny: 対象pathを必要なread/write/execute/delete能力へ追加し、再起動してください。 +- resolution未確認／変更: `sandbox resolve`のLogical/Resolved Path差分を確認し、`sandbox confirm`を実行してください。 +- Alias不明／Approval不足／hash変更: `executable resolve`で候補を確認し、明示したpathを`executable approve`で再承認してください。 +- Filesystem deny: 対象を適切なWorkspaceまたはMountとして設定し、Resolutionを再確認してください。 - rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。 ## ソースからのbuild／release @@ -187,4 +213,4 @@ dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore `artifacts/` はローカルの試験証跡・デバッグログ用です。`artifacts/` と `build/` はどちらもGit管理外です。 -Release scriptはwin-x64 self-contained directory、version付きZIP、ZIP checksum、publish manifestを生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。完全な `agent-mcp check` は管理者PowerShellで実行してください。 +Release scriptは再現可能な既定値だけを含むwin-x64 self-contained ZIP、checksum、publish manifestをstagingから生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。deployment directory更新時は`agent.local.yaml`、`local/`、`logs/`、`state/`を削除・上書きしません。完全な `agent-mcp check` はResolution確認とExecutable Approval後に管理者PowerShellで実行してください。 |