hermes-labs-ai/agent-gorgon

# agent-gorgon agent-gorgon（前身为 agent-warden）是一个面向自主 AI agent 的用户态 runtime 策略守卫。它轮询实时的进程树，将确定性策略应用于带有归属的观测结果，并记录控制尝试和取证证据。 **检测高风险 runtime 观测并尝试进行 SIGSTOP 或 SIGKILL 控制。** Agent Warden 是一个轮询监视器，而不是执行前的插入：在被观测到之前，某个动作可能已经启动或完成。 [](LICENSE) [](https://github.com/hermes-labs-ai/agent-gorgon/actions/workflows/ci.yml) 如果在两次快照之间有 40 个文件消失，Agent Warden 会记录 40 条未确认归属的删除观测。它不会仅凭这些观测就挂起受监视的进程，因为目录差异无法确定是哪个进程执行了删除操作。 ## 痛点 - 仅靠日志无法在高风险观测发生后暂停进程。 - 内联 LLM 裁决器不提供进程树、文件或网络可见性，并且在这里没有停止权限。 - 基于名称的定位可能会选中错误的进程；精确的 PID 定位是更安全的边界。 - 策略文件需要主动观察者和明确的控制结果，才能成为操作性证据，而不仅仅是文档。 ## 安装 从 PyPI 安装标准发行版（发布为 `agent-gorgon` —— PyPI 上的 `agent-warden` 名称不可用）： ``` pip install agent-gorgon==0.1.5 ``` 现有的 `suy-sideguy` 用户可以通过 0.1.5 兼容版本进行升级： ``` pip install --upgrade suy-sideguy==0.1.5 ``` 0.1.5 兼容版本会安装匹配的 `agent-warden` 发行版，并临时转发旧的 `suy_sideguy` 导入和 `suy-*` 命令，同时发出弃用警告。 需要 Python 3.9+。 ## 快速开始 ``` agent-warden --scope examples/scope.generic.yaml --agent-pid 12345 --poll 0.5 --no-llm ``` `examples/` 是代码仓库的一部分，而不是已安装 wheel 的一部分。如果是通过 wheel 安装的，请在运行命令之前从代码仓库中复制并查看示例 scope，或者提供您自己的 scope 文件。 agent 运行时的代表性本地日志行（SAFE 行需要使用 `--verbose`）： ``` 🛡️ Agent Warden active ⚠️ FLAG [1/12]: process_exec: unknown-command 🟡 HALT: Suspicious process spawned: curl ``` 运行结束后： ``` agent-warden-forensic --last-hours 24 ``` ## 何时使用 当您运行自主或半自主 agent，并且需要尽力而为的用户态 runtime 观察、被动式进程控制以及作为纵深防御中一层的取证证据时，请使用 `agent-warden`。 ## 何时不使用 - 这不是内核级别的 sandbox。如果您的威胁模型需要内核隔离，请使用内核 sandbox。 - 不能替代输入侧的 prompt 注入防御。 - 不能证明任何单一的策略文件都能安全地覆盖所有工作负载。策略需要针对每个工作负载进行校准。  ## 这个工具是什么（以及不是什么） ### ✅ 它能做什么 - 轮询 agent 进程树可用的进程、文件和网络信号 - 应用确定性策略规则；可选的本地 Ollama 裁决器只能建议 SAFE 或 FLAG - 在基于确定性的、有归属的触发条件上尝试 **HALT**（SIGSTOP，一种可逆的暂停，以及本地日志/报告） - 对于确定性的严重违规尝试使用 `SIGKILL` 进行 **KILL** - 存储证据并能生成可直接用于事件的取证报告 ### ⚠️ 它不能做什么 - 它**不是内核级别的强制执行**（它在用户态运行） - 它是被动轮询，不是系统调用拦截，也不能保证危险动作在生效前被停止 - 通过 `psutil.open_files()` 实现的文件可见性是尽力而为的，且依赖于操作系统 - 短暂存在的子进程和轮询期间发生的动作可能会被遗漏；这并不是完整的进程或系统调用可见性 - 快照差异对比的创建/删除观测没有归属，绝不会挂起或杀死受监视的进程 - 网络观测是远程 IP/端口对；主机名允许列表不会对观测到的 IP 进行身份验证 - 信号尝试可能会失败，或者只能部分覆盖不断变化的进程树；报告会记录观测到的结果。失败的 HALT/KILL 尝试保持可重试状态；重试会核对实际进程状态，并更新一份事件报告，而不会重复回滚带来的副作用 ## 安装 从 PyPI 安装： ``` pip install agent-gorgon==0.1.5 ``` 对于从源码检出进行贡献开发的用户： ``` git clone https://github.com/hermes-labs-ai/agent-gorgon.git cd agent-gorgon pip install -e ".[dev]" ``` 需要 Python 3.9+。 ## 5 分钟快速开始 ### 1) 选择目标进程 使用以下方式之一： - `--agent-pid`（推荐用于生产环境） - `--agent-name`（方便，但可能会匹配到非预期的进程） ### 2) 从示例策略 scope 开始 - 打开 `examples/scope.openclaw.yaml` - 对于分阶段推行，请从 `examples/scope.low-disruption.yaml` 开始 - 将允许列表缩小到您的工作负载真正需要的范围 - 对于通用基准，请从 `examples/scope.generic.yaml` 开始 ### 3) 运行 warden ``` # 更安全的靶向方式：PID agent-warden --scope examples/scope.generic.yaml --agent-pid 12345 --poll 0.5 --no-llm # 便捷的靶向方式：进程名 agent-warden --scope examples/scope.generic.yaml --agent-name my-agent --poll 0.5 --no-llm ``` ### 4) 运行后生成报告 ``` agent-warden-forensic --last-hours 24 ``` ## 日志和证据的存放位置 默认路径： - `~/.local/share/sysmond/warden.log` - `~/.local/share/sysmond/logs/actions_*.jsonl` - `~/.local/share/sysmond/logs/incidents/*.json` 提示：请将这些视为安全制品。保护访问权限并定义保留/轮换策略。 ## 隐私和网络行为 - Agent Warden 没有遥测或外部报告客户端。 - 默认情况下，它会探测 `http://localhost:11434`，当 Ollama 可用时，会将当前动作、scope 摘要以及最多 20 个最近的动作发送到该本地服务，进行非强制性的咨询分析。使用 `--no-llm` 可禁用探测和咨询调用。 - 远程 IP 策略检查不执行反向 DNS。必须显式地允许或禁止原始 IP；主机名允许列表仅在集成提供主机名时适用。 - 本地 JSONL 证据包含完整观测到的路径、命令和远程 IP/端口值。请将其作为敏感操作数据加以保护，并配置保留策略。 ## 推荐的推行策略 Agent Warden 0.1.5 没有仅审计或确认模式。当 warden 运行时，确定性的 HALT/KILL 规则即被激活。请先针对一次性的进程和已审查的低干扰 scope 开始，使用 `--no-llm` 进行无咨询的确定性试验，只有在验证了硬性不变量和操作系统可见性之后，才将其部署到重要的工作负载上。 ## 重要的安全注意事项 - `SIGKILL` 是立即执行的，如果策略范围太广，可能会中断合法的工作。 - 名称匹配 (`--agent-name`) 可能会发生过度匹配；在生产环境中优先使用 PID 定位。 - 本项目应成为分层防御策略的一部分。 ## 判定级别 | 判定 | 含义 | 响应 | |---------|---------|----------| | `SAFE` | 动作符合策略 | 继续 | | `FLAG` | 可疑，低于阈值 | 记录，继续 | | `HALT` | 检测到危险模式 | 尝试对进程树进行 SIGSTOP（可逆）；写入本地证据 | | `KILL` | 严重违规 | 尝试对进程树进行 SIGKILL；写入本地证据 | ### HALT 触发器（尝试 SIGSTOP，一种可逆的暂停；不会故意杀死 agent） - **观测到 curl 或 wget 子进程** —— 非预期的向外交付数据的进程 - **60 秒内观测到 50+ 个不同且带有归属的网络连接** —— 批量流出信号 - **带有归属的写入操作发生在允许的工作区之外** —— 非预期的文件系统访问（当操作系统暴露写入模式时） - **10 秒内发生 3 次及以上带有归属的 `FILE_DELETE` 事件** —— 适用于能提供归属信息的集成；内置的快照差异不会激活此触发器 - **没有观测到子进程 cwd 的相对递归删除** —— 无法安全解析目标，因此 Warden 选择暂停，而不是猜测为 SAFE 或赋予不可逆的 KILL 权限 - **在允许的文件系统 scope 之外进行递归删除** —— 任意的字面目标不会仅仅因为它们的 `sh`/`bash` 包装器被允许就变为 SAFE；只要观测到的 cwd 解析在 `filesystem.allowed_paths` 内，常规的相对项目清理依然保持低噪音 - **具有未解析的包装器、命令、选项或目标语义的递归删除** —— 当无法进行精确规约时，Warden 会选择暂停，而不是猜测为 SAFE 或赋予 KILL 权限 - **在可执行的 shell 命令替换内的递归删除** —— 未加引号/双引号的 `` `...` `` 和 `$(...)` 形式会可逆地暂停；单引号替换文本仍被视为数据 ### KILL 触发器（观测后尝试对进程树执行 SIGKILL） - **带有归属的 SSH 密钥访问** —— 观测到对 `~/.ssh/` 或 `*id_rsa*`, `*id_ed25519*` 的读/写 - **带有归属的配置文件写入** —— 观测到对 `~/.openclaw/openclaw.json` 的写入 - **观测到子进程执行 `rm -rf` 命令针对受保护的根目录** —— 文件系统根目录、家目录或配置的禁用根目录；相对操作数会根据观测到的子进程 cwd 进行解析，且支持的 `env` 包装器以及根/主目录的通配符和祖先形式会在分类前进行规约；直接子进程的 argv 会被保留，因此字面量 `~`、`$HOME` 和通配符字节不会被重新展开 - **带有归属的凭证读取，且伴随活跃或新观测到的非本地网络流出** —— 读取时已建立的外部 socket，或配置短时间窗口内的新外部连接，会激活此关联；IP 环回 IPC 被豁免，不会解除此触发 - **带有归属的禁止路径或禁止扩展名访问** —— 位于 `filesystem.forbidden_paths` 中的路径或位于 `filesystem.forbidden_extensions` 中的扩展名 ## 预期的 FLAG 噪音（早期推行阶段） 在对真实工作负载进行策略校准期间，早期的 FLAG 噪音是正常现象。 - 将早期的 `FLAG` 事件视为校准数据，而不是即时缺陷。 - 默认情况下，Flags 不会自动执行杀死操作。`WARDEN_KILL_ON_FLAGS=1` 会显式启用使用 `flag_threshold` 和 `flag_window` 进行累积杀死。 - 将**硬性不变量**（例如，禁止的机密路径 / 破坏性命令）作为立即停止的决策依据。 - 在 0.1.5 版本中没有仅审计开关；在验证其确定性控制之前，仅针对一次性目标试用 warden。 ## 发布质量状态 _当前状态基于代码仓库检查和 CI 配置；并非正式的安全认证。_ - ✅ 仓库中包含测试 (`pytest`) - ✅ 可构建包 (`python -m build`) - ✅ CI 工作流 (`.github/workflows/ci.yml`) - ✅ 发布工作流 (`.github/workflows/publish.yml`) - ✅ 安全披露策略 (`SECURITY.md`) ## 关于 Hermes Labs Hermes Labs 是一个独立的 AI 可靠性实验室，致力于构建能够捕获生产环境中 AI 静默失败模式的开源工具。我们将这门学科称为 **Epistemic Engineering**。Hermes Labs 的立场是：**模型是底层基石** —— 即训练好的系统、能力上限 —— 但 **语言是操作层**：提示词、脚手架、评估、记忆层和审计表面，部署的可靠性正是在这里决定成败的。agent-gorgon 是这种**语言基础设施**的一部分 —— 即技术栈中的 runtime 强制执行层。更多信息请访问 [hermes-labs.ai](https://hermes-labs.ai)。 ## 开发 ``` pip install -e .[dev] pytest ``` 另请参见： - `CONTRIBUTING.md` - `SECURITY.md` - `PUBLISH_CHECKLIST.md` - `AGENTS.md` - `CODE_OF_CONDUCT.md` - 审计清单：`docs/AUDIT_CHECKLIST.md` - 分层计划：`docs/IMPLEMENTATION_PLAN_LAYERED.md` ## 相关的 Hermes Labs 工具 - [te-drift-detector](https://github.com/hermes-labs-ai/te-drift-detector) — 针对 agent 会话的零 LLM 漂移检测（在 warden 不得不采取行动之前将其捕获） - [hermes-blind](https://github.com/hermes-labs-ai/hermes-blind) — 能够使发生漂移的会话恢复正常的恢复脚手架 - [lintlang](https://github.com/hermes-labs-ai/lintlang) — 用于 agent 配置和提示词的静态检查工具（在 runtime 之前将其捕获）

标签：AI代理, AI风险缓解, Python, 安全规则引擎, 无后门, 策略引擎, 系统运维, 网络安全挑战, 运行时防护, 逆向工具