AgentGuard

AI Agent 防火墙与沙盒
在强制权限、实时监控和真正有效的紧急开关下运行任何 AI Agent。

``` $ agentguard run "openclaw start --task 'organize my inbox'" ╔══════════════════════════════════════════════════════════╗ ║ AgentGuard v1.0.0 — AI Agent Firewall Active ║ ╚══════════════════════════════════════════════════════════╝ ▸ Container: agentguard-a7f3x (isolated) ▸ Permissions: ~/projects (read-write) · ~/docs (read-only) ▸ Network: api.openai.com only ▸ Secrets: 12 env vars stripped ▸ Kill switch: Ctrl+C → instant container kill 14:32:01 ✓ Read file: ~/projects/todo.md 14:32:03 ✓ Write file: ~/projects/todo.md 14:32:05 ✓ Network: POST api.openai.com/v1/chat 14:32:08 ✗ BLOCKED — Write attempt: ~/.ssh/id_rsa 14:32:08 ✗ BLOCKED — Network: smtp.gmail.com:587 14:32:09 ✗ POLICY VIOLATION — 2 blocked actions in 1s Agent terminated. Audit log saved to ~/.agentguard/logs/a7f3x.json ``` ## 为什么选择 AgentGuard？ 2026 年 2 月 10 日，Meta 的 AI 安全主管 Jill 运行 OpenClaw 来整理她的收件箱。该 Agent **删除了 200 多封邮件**，开始代表她发送消息，并**忽略了她的 STOP 命令**超过一分钟。她不得不物理拔掉机器电源。 这不是一个边缘工具。OpenClaw 拥有 **430,000 行代码**。没有人——甚至 Meta 自己的安全团队——能在运行前对它进行审计。 以下是 2026 年关于 AI Agent 的一些令人不安的事实： - **它们使用你的权限运行。** 每个文件、每个 SSH key、每个 API token——都可被访问。 - **它们的行动速度比你反应快。** 当你看到损害时，一切都已经发生了。 - **“STOP”只是建议，不是命令。** Agent 异步处理指令。你的中断请求只是进入了队列。 - **当前的“安全性”依赖于 AI 选择表现良好。** 这就像是要求囚犯自己看守自己。 AgentGuard 采用了一种根本不同的方法。它不要求 AI 遵守规则，而是在 **OS 和容器级别强制执行规则**。Agent 在一个锁定的 Docker 容器内运行，只有你明确授予的权限。它**根本无法**读取你的 SSH key、删除你的邮件或访问网络，除非你允许。 AI 没有选择权。 ## 功能 🐳 **Docker 隔离** — 每个 Agent 都在其自己的临时容器中运行。除了你明确允许的内容外，无法访问你的主机系统。 🔒 **权限防火墙** — 对文件读/写、网络访问和命令执行进行精细控制。单独允许列表路径、域名和命令。 ⚡ **紧急开关 (Kill Switch)** — `Ctrl+C` 立即杀死容器。不是礼貌的请求——而是向容器 runtime 发送 `SIGKILL`。Agent 无法拦截、延迟或忽略它。 📊 **实时仪表板** — 实时监控每个文件访问、网络调用和命令执行。准确了解 Agent 正在做什么。 📋 **审计日志** — 完整的结构化记录，包含 Agent 采取的每个动作、访问的每个资源以及每次策略违规。JSON 格式，便于审查或合规。 🛡️ **Secret 保护** — 在 Agent 看到之前，自动检测并清除 API key、token、凭据和敏感环境变量。支持 `.env`、AWS 凭据、SSH key 等。 ⏱️ **资源限制** — 设置 CPU、内存和挂钟时间上限。没有失控的 Agent 能挖掘加密货币或导致你的机器 OOM。 🔧 **零配置** — 开箱即用，具有合理的默认设置。安装，运行，完成。仅在需要时进行自定义。 ## 快速开始 **前置条件：** [Node.js 18+](https://nodejs.org/) 和 [Docker](https://docs.docker.com/get-docker/) ``` # 安装 npm install -g agentguard # 安全运行任何 AI agent agentguard run "your-ai-agent command here" ``` 就是这样。AgentGuard 创建一个隔离的容器，应用默认安全策略，并将 Agent 的输出流式传输到你的终端。`Ctrl+C` 随时终止。 ## 使用示例 ### 安全运行 OpenClaw ``` agentguard run "openclaw start --task 'summarize my documents'" \ --allow-read ~/documents \ --allow-write ~/documents/summaries \ --allow-net api.openai.com ``` ### 安全运行编程 Agent ``` agentguard run "coding-agent --auto" \ --allow-read ~/projects/myapp \ --allow-write ~/projects/myapp \ --allow-net github.com,registry.npmjs.org ``` ### 在沙盒中运行任意命令 ``` agentguard run "python3 untrusted_script.py" \ --allow-read /tmp/input \ --allow-write /tmp/output \ --no-network ``` ### 使用配置文件 ``` agentguard run "openclaw start" --config agentguard.yml ``` ### 网络隔离模式（完全没有互联网） ``` agentguard run "agent-cli process ./data" --no-network ``` ### 只读模式（Agent 可读但永远不能写） ``` agentguard run "agent-cli analyze ~/codebase" --read-only ``` ### 设置资源限制 ``` agentguard run "openclaw start" \ --memory 2g \ --cpus 2 \ --timeout 30m ``` ## 配置 在你的项目根目录下创建一个 `agentguard.yml` 以使用可复用的策略： ``` # agentguard.yml # agent 可读取的路径 allow_read: - ~/projects/myapp - ~/documents/specs # agent 可写入的路径（意味着可读） allow_write: - ~/projects/myapp/src - ~/projects/myapp/tests # 始终被阻止的路径，即使父路径被允许 deny: - ~/.ssh - ~/.aws - ~/.gnupg - ~/.agentguard - "**/.env" - "**/credentials*" # Network allowlist（阻止所有其他域名） allow_network: - api.openai.com - registry.npmjs.org - pypi.org # 资源限制 resources: memory: 4g # Max memory cpus: 4 # Max CPU cores timeout: 60m # Max wall-clock time max_file_size: 50m # Max single file write size # 违反策略时的操作 on_violation: kill # kill | warn | log # kill — terminate immediately (recommended) # warn — alert + continue # log — silent log only # 从 agent 环境中剥离的 Secrets strip_secrets: true # Auto-detect and remove sensitive env vars strip_patterns: # Additional patterns to strip - "*_TOKEN" - "*_SECRET" - "*_KEY" - "*_PASSWORD" ``` ## 工作原理 ``` ┌─────────────────────────────────────────────────────────────┐ │ YOUR MACHINE │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ AgentGuard Process │ │ │ │ │ │ │ │ ┌─────────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ │ │ Policy │ │ Monitor │ │ Kill Switch │ │ │ │ │ │ Engine │ │ (live) │ │ (Ctrl+C) │ │ │ │ │ └──────┬──────┘ └────┬─────┘ └──────┬────────┘ │ │ │ │ │ │ │ │ │ │ │ ┌──────┴──────────────┴───────────────┴─────────┐ │ │ │ │ │ Docker Container │ │ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ │ │ │ │ AI Agent (sandboxed) │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ • Only sees allowed paths │ │ │ │ │ │ │ │ • Only reaches allowed domains │ │ │ │ │ │ │ │ • No access to host secrets │ │ │ │ │ │ │ │ • Resource-capped │ │ │ │ │ │ │ └──────────────────────────────────────────┘ │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` 1. **创建一个最小化的 Docker 容器** — 基于一个精简的基础镜像，仅包含你的 Agent 所需的 runtime。没有工具，没有包管理器，没有额外的组件。 2. **仅挂载允许的路径** — 除了你明确允许的目录外，Agent 无法感知你的文件系统。写入权限与读取权限是分开的。 3. **默认阻止所有网络** — DNS 和 IP 级别的防火墙规则确保 Agent 只能访问你白名单中的域名。其他所有内容都会被静默丢弃。 4. **实时监控所有活动** — 文件操作、网络调用、进程生成和资源使用被跟踪并流式传输到你的终端。 5. **违反策略即终止** — 当设置了 `on_violation: kill` 时，单个未授权操作会通过 `SIGKILL` 立即终止容器。没有宽限期。没有协商余地。 6. **保存完整的审计日志** — 每个动作，无论允许还是阻止，都记录在 `~/.agentguard/logs/` 下的结构化 JSON 日志中。 ## AgentGuard vs. 直接运行 Agent | | 直接运行 Agent | AgentGuard | |---|---|---| | **文件访问** | 无限制 —— 读取你能读取的任何内容 | 沙盒化 —— 仅限允许的路径 | | **网络** | 无限制 —— 可以访问任何服务器 | 防火墙保护 —— 仅限允许列表中的域名 | | **紧急开关** | 寄希望于 AI 处理你的中断 | 容器终止 —— 即时，不可阻挡 | | **你的 secret** | 完全暴露（SSH key、token 等） | Agent 启动前自动清除 | | **审计追踪** | 无 —— 你不知道它做了什么 | 每个动作的完整结构化日志 | | **资源限制** | 无 —— 可以使用所有 CPU/RAM | 强制执行 CPU、内存和时间上限 | | **损害半径** | 你的整个系统 | 一个可丢弃的容器 | ## CLI 参考 ``` agentguard [options] Commands: run Run an AI agent inside a secure container logs [session-id] View audit logs from a previous session config init Generate a default agentguard.yml config validate Validate an existing config file ps List running AgentGuard sessions kill Kill a running session Run Options: --config, -c Path to config file [default: ./agentguard.yml] --allow-read Paths the agent can read [array] --allow-write Paths the agent can write [array] --allow-net Domains the agent can reach [array] --no-network Block all network access [boolean] --read-only Block all write operations [boolean] --memory Memory limit (e.g., 2g, 512m) [default: 4g] --cpus CPU limit [default: 4] --timeout Max runtime (e.g., 30m, 2h) [default: 60m] --on-violation Action on policy violation [default: kill] --verbose, -v Show all agent activity in real-time [boolean] --dry-run Show what would happen without running[boolean] Examples: agentguard run "openclaw start" --no-network agentguard run "my-agent" --allow-write ~/project -c policy.yml agentguard logs --last agentguard kill a7f3x ``` ## 贡献 AgentGuard 是开源的，欢迎贡献。 ``` # Clone repo git clone https://github.com/A386official/agentguard.git cd agentguard # Install dependencies npm install # 运行测试 npm test # 在开发环境中运行 npm run dev ``` **我们特别希望能得到帮助的领域：** - 额外的 runtime 支持（Python Agent、Go Agent 等） - Windows 容器支持 - 针对边缘情况逃逸场景的集成测试 - 流行 AI Agent 的策略模板 - Dashboard UI 改进 请在提交 PR 之前阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT © 2026 [AgentGuard 贡献者](https://github.com/A386official/agentguard/graphs/contributors)

_{构建理由：AI Agent 不应拥有超过其所需的访问权限。}

标签：AISec, AI安全治理, DNS 解析, Docker, GNU通用公共许可证, Kill Switch, MITM代理, Node.js, Streamlit, Web截图, WSL, 安全防御评估, 安全隔离, 容器安全, 开源安全工具, 敏感信息保护, 文档结构分析, 权限管理, 模型越狱, 沙盒, 沙箱, 熔断机制, 环境隔离, 网络安全, 网络安全审计, 自动化攻击, 自动化攻击, 自动化攻击, 访问控制, 请求拦截, 资源限制, 逆向工程平台, 防火墙, 隐私保护