CXP-shawn/sandbox-tools-inventory

# TTWWIINN Sandbox — Tools Inventory & Technical Documentation 一份对 TTWWIINN 沙箱系统（一个用 Nix + bwrap 构建的 AI Agent 执行沙箱系统）的实测调研与技术实现方案文档集。 ## 📚 文档导航 | 文档 | 内容 | 适合读者 | |---|---|---| | [📘 TECHNICAL_SPEC.md](./TECHNICAL_SPEC.md) | TTWWIINN 沙箱系统技术实现方案（主文档，10 章 + 5 附录） | 内部工程团队 | | [📕 sandbox_tools_inventory.md](./sandbox_tools_inventory.md) | 219 个内置工具的完整清单（13 分类） | 所有读者 | | [📗 sandbox_startup_forensics.md](./sandbox_startup_forensics.md) | 沙箱启动机制取证报告（4 次独立探针） | 工程/安全 | | [📙 agent_generated_persistence.md](./agent_generated_persistence.md) | `/agent/generated` 跨调用持久化行为（5 次探针） | Agent 开发者 | | [📒 behavior_table_verification.md](./behavior_table_verification.md) | Session 级行为对比表逐项验证（7 次探针） | Agent 开发者 | | [📓 gap_analysis.md](./gap_analysis.md) | 送审方案 vs 现状 gap 分析（含改造路线） | 产品/工程 | ## 🎯 核心结论（3 条） 1. **TTWWIINN 沙箱是双层架构**：Agent Run 层有 session 语义（靠 `/agent/generated` 文件系统持久化），Shell Tool API 层是 per-call stateless（每次 `bwrap + sh -c` 全新进程）。 2. **每次 shell 调用之间唯一保留的**是 `/agent/generated` 下的普通文件内容。env / cwd / `/tmp` / 后台进程 / alias / symlink / exec bit / 空目录 / 文件删除 全部丢失。 3. **如果需要跨调用的"session 行为"**，用 `source /agent/generated/profile.sh` 约定即可，**零平台改动**。 ## 🔬 调研方法 所有结论均来自在沙箱内运行的 shell 探针，共 **4 轮 16 次** 独立 `shell` 调用： - **Round 1**：219 工具清单实测 → [`sandbox_tools_inventory.md`](./sandbox_tools_inventory.md) - **Round 2**：4 次启动机制探针（`probe_call_1..4.txt`）→ [`sandbox_startup_forensics.md`](./sandbox_startup_forensics.md) - **Round 3**：5 次持久化行为探针（`persist_call_1..5.txt`）→ [`agent_generated_persistence.md`](./agent_generated_persistence.md) - **Round 4**：7 次 session 行为探针（`behavior_probe_A..G.txt`）→ [`behavior_table_verification.md`](./behavior_table_verification.md) 原始 probe 文件都保留在仓库外部的沙箱工作目录 `/agent/generated/` 下；每条结论都可追溯到具体文件与行号。 ## 🙋 如何用这个仓库 - 想了解 TTWWIINN 沙箱到底是什么 → 读 [TECHNICAL_SPEC.md](./TECHNICAL_SPEC.md) - 想知道 sandbox 里有哪些工具 → 读 [sandbox_tools_inventory.md](./sandbox_tools_inventory.md) - 写 TTWWIINN agent 想避免踩坑 → 读 [TECHNICAL_SPEC §7 行为契约](./TECHNICAL_SPEC.md#7-行为契约面向-agent--tool-作者) - 设计新沙箱方案想借鉴 → 读 [gap_analysis.md](./gap_analysis.md) + [TECHNICAL_SPEC §10 业界对比](./TECHNICAL_SPEC.md#10-与业界方案对比) - 想快速验证某个行为 → 读 [TECHNICAL_SPEC §9.1 自测模板](./TECHNICAL_SPEC.md#91-自测模板) ## ⚖️ 文档版本 - **v2.0**（2026-04-17）：整体修订，统一 TL;DR 卡片 + 交叉链接 + 文档状态 banner；新增 `TECHNICAL_SPEC.md` 主文档与本 README。 - v1.x：原始取证报告系列（单篇发布）。 ## 📬 贡献与反馈 如果发现文档与实测行为不一致，欢迎提 issue，附上探针原始输出（`env | sort`、`cat /proc/self/mountinfo`、`readlink /proc/self/ns/*` 等）。所有结论都应该可重现——重跑一组探针即可确认。

标签：bwrap, Cutter, NIDS, Nix, Session 语义, Shell 探针, source profile, stateless, 产品工程, 双层架构, 启动机制取证, 安全测试, 实测调研, 容器化, 工具清单, 执行沙箱, 技术实现, 攻击性安全, 文件系统持久化, 文档集, 沙箱, 系统架构, 行为对比验证, 跨调用, 送审方案