From b07b41cd435991cd254957af79055080c85b346e Mon Sep 17 00:00:00 2001 From: tanaka takashi Date: Sun, 9 Aug 2026 21:08:20 +0900 Subject: feat: AI Agent Sandbox MCP Server v1を実装 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Specifications、Design、ImplementationPlanの優先順位を整理し、単一Task実行モデル、typed option優先、設定可能なresource上限、local Ollamaを必須とするRelease Gateを文書化。 .NET 10/C# 14の5 production project、3 test project、E2E Clientを構築。typed YAML、en/ja locale、fixed/user prompt、stdioおよびloopback限定Streamable HTTP、agent_run/agent_status、Session、Ollama text/tool/Vision、TaskGraphとtoken accountingを実装。 Windows sandboxとしてfixed AppContainer、canonical/reparse検査、能力別ACL、path+SHA-256 executable approval、child-process restriction、Job Object、task journal、atomic file transaction、crash recoveryを実装。WFPのIPv4/IPv6 default denyとexact allow、dynamic session、temporary loopback exemption、管理者/BFE診断を追加。 Security/Recovery test、MCP/Ollama integration test、stdio/HTTP Operational E2E、Release Bundle生成・checksum・manifest・fresh extraction検査を追加。Requirement TraceabilityとPhase 0〜11の進捗、初回セットアップ可能なREADMEを整備。 Debug/Release/publish/objをrepository rootのbuild/へ集約し、旧project-local bin/objへの依存を除去。artifacts/とbuild/をGit管理外に設定し、clean checkoutでもsolution buildからE2E Clientまで生成可能にした。 --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..e2a350c --- /dev/null +++ b/README.md @@ -0,0 +1,141 @@ +# AI Agent Sandbox MCP Server v1 + +Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、Process、Network操作だけをAppContainer内で実行するMCP Serverです。MCP公開Toolは `agent_run` と `agent_status` の2つです。 + +## 動作要件 + +- Windows 11 x64 +- 管理者権限（TaskごとのWFP filter追加・削除に必要） +- Base Filtering Engine (BFE)が実行中 +- Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。 +- 必須local model: `hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL` + +サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。 + +## 初回セットアップ + +管理者としてPowerShellを起動し、Release Bundleへ移動します。 + +```powershell +ollama --version +ollama pull hf.co/unsloth/gemma-4-E2B-it-qat-GGUF:UD-Q4_K_XL +ollama serve +``` + +別の管理者PowerShellで診断します。 + +```powershell +.\agent-mcp.exe check --config .\agent.yaml --lang ja +``` + +`administrator=true`、`bfe_engine_open=true`、`wfp_write_transaction=true`、`wfp_filter_add_delete=true` が必要です。probeはdynamic WFP filterを追加後すぐ削除し、残留させません。 + +## agent.yaml + +Filesystem pathは能力ごとに指定します。未指定能力はdenyです。 + +```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許可とは独立です。 + +## stdio + +WFP操作のため、stdioではMCP Client自体を管理者PowerShellから起動します。Client設定例: + +```json +{ + "mcpServers": { + "agent-sandbox": { + "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe", + "args": ["serve", "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml", "--lang", "ja", "--transport", "stdio"] + } + } +} +``` + +`agent_run`へ自然言語の依頼を送り、返却されたUUIDを `agent_status` でterminal stateまでpollします。複数Taskはqueuedで受理しますが、planning/runningおよびTask Resource適用は全体で1件です。 + +## Streamable HTTP + +管理者PowerShellでserverを起動します。 + +```powershell +.\agent-mcp.exe serve --config .\agent.yaml --lang ja --transport http +``` + +Client endpointは `http://127.0.0.1:8080/mcp` です。設定できるbindは `127.0.0.1` または `::1` だけです。Streamable HTTP POSTだけを使用し、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。 + +## LogとRecovery + +- `logs/application.log`: 起動・診断・管理event +- `logs/llm.jsonl`: LLM request/response、token usage、tool result +- `logs/audit.jsonl`: Task ID付きfile/process/policy/ACL/WFP/recovery event +- `state/journals/`: crash recovery journal。正常終了後は空 +- `state/backups/`: 大容量file transaction backup。正常終了後は空 + +log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。 + +正常停止後、`agent-mcp.exe` descendant、追加ACL、WFP filter、loopback exemption、`state/backups`、`state/journals` が残っていないことを確認してください。loopback exemptionは `CheckNetIsolation.exe LoopbackExempt -s` で確認できます。 + +## よくあるエラー + +- `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能力へ追加し、再起動してください。 +- rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。 + +## ソースからのbuild／release + +```powershell +dotnet restore AgentSandboxMcp.slnx +dotnet build AgentSandboxMcp.slnx -c Release --no-restore +dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore +.\scripts\Publish-Release.ps1 +``` + +生成物はすべてrepository rootの `build/` に集約されます。 + +- `build/Debug//`: Debug build +- `build/Release//`: Release build +- `build/obj//`: restoreおよびcompiler中間生成物 +- `build/Release/publish/`: win-x64 self-contained Bundle、version付きZIP、checksum + +`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で実行してください。 -- cgit v1.2.3