MiGoller/ai-agent-sandbox

# AI Agent 沙盒 🛡️ **安全、隔离且 rootless 的环境，用于运行自主 AI CLI Agent（`Hermes`、`Aider`、`Claude Code`），避免暴露您的主机系统。** ## 问题所在 现代 AI 编码 Agent 功能极其强大，但它们需要您的终端具备执行能力。如果 Agent 遭到 **Indirect Prompt Injection**（间接提示词注入）的攻击（例如，通过读取公共代码仓库或网站上的恶意文件），它可能会被指示执行以下操作： - 🔐 **窃取私有 SSH 密钥** (`~/.ssh`) 或凭据。 - 💥 由于幻觉或恶意输入而**运行破坏性命令** (`rm -rf /`)。 - 🌐 **访问敏感的主机进程**。 简单的 `.gitignore` 样式文件只能帮助减少 token 混乱——**它并不是安全边界。** ## 解决方案 `ai-agent-sandbox` 使用 Podman 和多层安全验证机制，将您的 AI Agent 锁定在经过强化的 **rootless 容器牢笼**中。 - 🔒 **完全隔离：** Agent 只能看到您授予其访问权限的特定项目文件夹。它无法查看您的主目录或未经批准的进程。 - 🌐 **网络锁定（可选/默认）：** 除非通过 `--online` 明确启用，否则禁用网络访问以防止数据泄露。 - 🛡️ **阶段一预检验证：** 启动器会自动检查主机依赖项、验证输入路径，并在执行前拦截潜在的危险命令。 - 🧹 **干净的工作区策略：** 特定于工具的数据、聊天历史记录和配置会映射到集中的主机目录，让您的项目文件夹保持完全整洁。 ## 目录结构与内存映射 主机系统提供了一个集中的配置目录，该目录会动态映射到容器内每个工具期望的原生标准目录： ``` Host System Container (Guest) └── ~/.config/ai-agent-sandbox/ ├── hermes/ ───────────────► /root/.hermes/ ├── aider/ ───────────────► /root/.aider/ └── claude-code/ ───────────────► /root/.claude-code/ ``` ### 仓库布局 ``` . ├── run.sh # Universal secure launcher (with Phase 1 validation) └── flavors/ ├── base/ # Common core layer (Ubuntu 24.04 + core utilities) ├── hermes/ # Hermes Agent flavor layer ├── aider/ # Aider flavor layer └── claude-code/ # Claude Code flavor layer ``` ## 支持的版本 | 版本 | 目标 AI Agent | 默认容器命令 | 网络要求 | | --- | --- | --- | --- | | `hermes` | 开源多 Agent 路由器 | `hermes chat --tui` | 支持离线 | | `aider` | CLI 结对编程工具 | `aider` | 支持离线（配合本地 LLM） | | `claude-code` | Anthropic 官方 CLI Agent | `claude` | 需要 `--online` | | `base` | 沙盒核心环境 | `bash` | 支持离线 | ## 前置条件与安装 要使用此沙盒，您需要在主机系统上安装 **Podman**。之所以需要 Podman，是因为它默认以 rootless 方式运行，与标准的 Docker 设置相比提供了更出色的安全性。 ### 🐧 Linux / WSL2 (Ubuntu / Debian) ``` sudo apt update && sudo apt install -y podman ``` ### 🍏 macOS (Homebrew) ``` brew install podman podman machine init podman machine start ``` ## 快速开始 1. **使启动器脚本可执行**： ``` chmod +x run.sh ``` 2. **在严格隔离模式下启动默认 Agent（Hermes）**： ``` ./run.sh ``` 3. **启动一个在线 Agent（例如 Claude Code）**： ``` ./run.sh claude-code --online ``` ## 用法与 CLI 标志 通用启动脚本（`run.sh`）充当容器执行的安全包装器。 ### 核心标志 * `./run.sh` ➔ 在 **严格隔离模式**（无网络）下启动默认版本（`hermes`）。 * `./run.sh --online` ➔ 启用主机网络模式（外部 API 调用或诸如 LiteLLM 之类的本地 LLM 代理需要此模式）。 * `./run.sh --build` ➔ 强制 Podman 重新构建所选版本的容器层。 * `./run.sh --local` ➔ 将 Agent 内存从全局回退目录（`~/.config/ai-agent-sandbox`）切换到当前目录中特定于项目的隐藏文件夹（`.ai_agent_sandbox_data`）。 ### 自定义命令与 Shell 访问 要绕过默认的启动命令或进入交互式调试 shell，只需将您的命令附加到脚本的末尾： ``` # 在 Aider sandbox 内获取标准的交互式 bash shell ./run.sh aider bash # 执行一次性命令并立即退出 ./run.sh --online hermes profile list ``` ## 许可证 本项目基于 **MIT License** 授权。

标签：AI代理, Cutter, Docker, Podman, SOC Prime, 安全防御评估, 安全防护, 容器沙箱, 开发工具, 环境隔离, 请求拦截