agent-guard
Verified@mokuyoaxis/agent-guard · v0.2.9 · MIT
Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.
Install
dsh plugin add @mokuyoaxis/agent-guard Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
AGENT-GUARD
外发检查 · 可恢复删除 · Agent 验测 · English
Agent Guard 提供三大功能:Exfil-guard 检查待外发文本,Delete-guard 在受支持的破坏性操作前保留恢复数据,Guard-lab 通过受控实验测试 Agent 和宿主的实际行为。共享 Python Core 支撑命令行工具与可选宿主适配器。
负责接入本项目的 AI agent: 修改配置或编写桥接前,必须先读取 适配要求,再阅读 接入流程和对应适配器指南。 确认实际宿主/版本,查阅其官方 hook 文档,完成验证后报告实际覆盖范围。 不能仅凭 Skill 已安装或配置已复制,就告诉用户防护已生效。
目前主要维护 DSH 和 Kimi Code 的接入。其他宿主建议交给对应的官方 编码 Agent 在本地配置。
本版 0.2.9 改善清理前的盘点体验:先看目录概况, 再计量指定范围,Cleanup Copilot 和 MCP 都可使用;既有计划扫描也减少了重复的 文件属性检查和 Git 查询。这些观察不授予删除许可,执行仍需另外生成计划、审阅并确认。 使用方式见目录概况与计量。 安装前,请通过下方链接核实精确版本的 GitHub Release 与 npm 包是否可用。
| 主要功能 | 下属功能 | 对应链接 |
|---|---|---|
| Exfil-guard | 受支持的凭据与标识路径检测;脱敏计划与执行;不展示标量值的 JSON/dotenv 配置结构视图 | Skill 与 CLI · 检测规则 · 安全配置视图 |
| Delete-guard | 可恢复删除与受支持的 Git 快照;Cleanup Copilot 计划、目录概况与计量;持久预算、速率/重复限制、保护路径与批量确认;事务恢复与手动 GC;可选本地 MCP 工具及接入诊断 | Skill 与 CLI · Cleanup Copilot · 删除限制 · 恢复与 GC · MCP 工具 · MCP doctor |
| Guard-lab | 四项零模型校准对照;合成标记与声明信道观察;证据和观察器健康检查;有效基线成立后的关闭/开启防护配对比较 | Lab 流程 · 四控制示例 · 证据等级 |
Cleanup Copilot、删除限制以及当前 MCP 工具/doctor 均归属 Delete-guard。 Core 与适配器提供共享基础设施;recovery-audit 提供事故后的工作区重建与恢复审计辅助流程。
Skill 提供操作纪律,不会自行拦截工具调用。自动保护依赖宿主实际加载了 兼容 hook,且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的 OS 沙箱;实际接入证据和缺口见能力矩阵。 可选本地 MCP 适配器提供显式工具,不会拦截绕过它的操作;其 SDK 单独安装, 不改变 Core 的运行依赖。
guard-lab:用证据验测行为
guard-lab 是用户控制的实验工具。它在一次性项目中放入非秘密合成标记和 无害诱饵,只观察明确声明的信道。真正的控制器与证据保存在交给受测 Agent 的 夹具之外。
流程分别回答三个问题:
- 校准:观察器、标记、扫描和证据链是否正常?内建对照不调用模型, 不访问外网。
- 观察暴露:关闭防护的真实宿主试次是否触发了选定信道?
- 比较防护:有效基线成立后,匹配的开启防护试次是否减少或阻止了该暴露?
在安装包或源码根目录,从一项零模型对照开始:
lab_run="$(mktemp -d)"
python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json
另三项对照是 mock-positive、mock-injection 和 snapshot-positive。
真实宿主实验前应按 Lab 指南跑齐四项对照;
安装包也提供 agent-guard-lab 命令。
对照 PASS 只表示仪器校准,不表示模型安全。观察器不健康或证据缺失时为
INCONCLUSIVE;未防护基线安静,不能证明防护有效。配对比较需要匹配相关的
harness/版本/模型、任务、协议及非防护配置。结果只覆盖声明信道,不能扩展
到所有文件读取、外网传输或模型请求。已有
Kimi 与
DSH 报告保留各自的有限结论、
失败和待审状态。
自 RC3 起,包中包含蓝队研究、 去敏实验报告和 便携四控制示例,公开来源、发送授权和正常任务效用的 有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进,欢迎 fork、PR 与独立防守复现;失败和未定结果也应保留。
在包含该示例的源码或包根目录,可一次运行现有四种控制:
blue_run="$(mktemp -d)"
python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"
示例不调用模型,摘要只用于仪器校准。
安装与版本选择
Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可选采集 工具另有运行要求。 可选 MCP 适配器需要 Python 3.10+,并单独安装固定版本 SDK。
| 版本 | 状态 |
|---|---|
| 0.2.9 | 本版;安装前核实下方精确版本渠道 |
| 0.2.8 | 较早版本:MCP 接入诊断与恢复验证 |
| 0.2.7 | 历史版本,包含 Cleanup、删除限制与本地 MCP 工具 |
| 0.2.6 | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
| 0.2.5 | 更早稳定版 |
| 0.2.4 | 更早稳定版 |
| 0.2.4-hotfix.1 | 显式选择的回收站保护回补;npm hotfix |
| 0.2.5-rc3 | 已发布预发布版,包含 RC1/RC2 维护;npm rc |
安装 0.2.9 前,请通过精确版本的 GitHub Release和 npm 版本页确认可用性, checkout 或 manifest 本身不代表包已可安装。
若该版本尚不可用,请按版本说明使用经复核的 源码或本地构建 tarball。版本化测试和包核验保留各自检查点。 自 0.2.7 引入的准入限制可能拒绝此前可执行的删除, 这些限制在 0.2.9 中继续生效。
确认精确版本可用后,可安装到用户选定的长期目录:
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/[email protected]
包根目录是
/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard。
必须使用这个带作用域的包名,也可以使用源码 checkout:
git clone https://github.com/mokuyoaxis/agent-guard.git
cd agent-guard
选用已发布的预发布版时,指定 @mokuyoaxis/[email protected],对应
GitHub Release与
npm 版本页。
若只需要稳定线的回收站保护修复,可显式选择 @mokuyoaxis/[email protected]。
这两个通道均不替换稳定版 latest。
0.2.6 在 0.2.5 的基础上补充 Kimi 可选 Stop
恢复反馈、独立 Stop doctor 检查、DSH Lab 预检诊断、DSH 0.2.1-alpha.4 默认删除适配,
以及 Kimi 2.3.0 Bash profile。已有安装需要升级才能取得这些功能,Stop 还需显式配置。
接入步骤与 Agent 提示词见入门指南,
历史功能边界见0.2.6 说明。
恢复一次受支持的删除
从要保护的工作区调用你的安装包/源码路径:
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被 Git 忽略的产物可直接删除。受支持的 Git 覆盖操作先快照 tracked 状态; hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force restore 先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的 事务 ID、现场文件和状态,再决定后续动作。
0.2.5 明确提示:迁入回收站的数据仍占空间,
GC 需要显式执行,ALLOW_NOOP 不代表未识别命令没有破坏性。
本地状态查询也不能证明宿主已加载防护。见状态与清理反馈。
advisory check.py 和 safe_delete.py --dry-run 保持命令目标不变,但可能写入
隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
操作获准执行。详见策略与评估契约。
RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化 restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。 原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。 见 RC 说明。
RC2 进一步限定通用审计字段、使用不透明 session 关联, 并收口旧日志 status 展示与 GC 元信息,见审计契约及保留边界。 同时补充 observer 启动诊断与取消健康记账;最初偶发超时的具体原因仍未知, 见 RC2 范围与证据。
外发前检查文本
持有载荷的调用方主动运行扫描器,并按判决处理文本:
python3 skills/exfil-guard/scripts/check_span.py --channel file-write --json < draft.md
python3 skills/exfil-guard/scripts/sanitize.py --channel file-write < draft.md
在运行时生成完整的合成凭据示例:
python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
预期输出是 config: sk-<REDACTED>。检查器返回判决和计划,不改写载荷;
其退出码 0 表示 ALLOW/SANITIZE 评估成功,sanitizer 成功输出的 stdout 才是
允许或已改写的文本。ASK/BLOCK/错误时 sanitizer 不输出载荷。
检测覆盖文档列明的凭据形状、无需读值的秘密引用和特定本机路径。它不是通用 仓库扫描器,也不能抵抗刻意编码绕过。文本 CLI 不自动追加外发审计; 可信接入方负责实际外发和需要的审计存储。检查配置时,可用显式安全视图查看 支持的 JSON/dotenv 结构及状态;它不是可编辑副本,也不自动拦截普通读取。
接入你的编码 Agent
让对应宿主的官方编码 Agent 按适配指南,为当前 安装的版本配置 Agent Guard。优先使用能在工具执行前阻止调用的 hook。 我们主要维护 DSH 和 Kimi Code 的接入;其他宿主由 Agent 在本地配置桥接。
下表记录所测源码、宿主版本和工具路径;其他组合需要另行验证。
| 宿主 | 接入与证据 |
|---|---|
| Claude Code | 保留参考实现,暂缓新版本验收。Bash 原生 PreToolUse;2.1.270/2.1.273 的受限脚本宿主拦截记录。接入 |
| Kimi Code | Bash 原生 PreToolUse;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。0.2.6 新增 2.3.0 prompt/ACP 根代理 Bash 固定响应证据。ASK 拒绝;缺失/超时 hook 不覆盖。接入 |
| DSH | 默认删除适配覆盖 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4。可选原生 read 与 Lab 保留各自的两版边界。兼容范围 · 接入 |
| Codex | Codex 0.165.0 已通过已发布 0.2.7 的实际客户端与真实模型 MCP 试次。证据覆盖显式工具;原生 Shell/编辑器拦截仍需单独验证。MCP 证据与限制 |
| 其他宿主 | 推荐官方 Agent 按当前版本完成本地接入,并验证确实阻止执行后再声明原生拦截。没有阻塞 hook 时,Skill/CLI/MCP 仍属于协作式使用。适配指南 |
精确版本、试验与缺口统一见完整能力矩阵。
doctor.py kimi|claude --probe 只检查选定配置和本地适配路径;PASS 不证明
真实宿主已加载 hook。漂移检查也是本地预检。live sentinel 为显式操作,
可能消耗模型额度,只覆盖该次根代理 Bash 调用,见
宿主漂移指南。
决策、事故恢复与文档
共享协议是 ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK,
附带稳定 reason code 和说明。
聚合优先级为 BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW。
不透明目标和保护边界拒绝执行;受支持的可恢复修改先补偿再继续。
授权状态属于本地操作纪律,不是隔离的身份边界。
事故后,recovery-audit帮助依据尚存的 Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失;没有来源保留的字节 无法凭空恢复。
| 文档 | 用途 |
|---|---|
| 入门指南 | 包路径、Agent 接入提示词、安全验证 |
| 文档导航 | 指南、设计、Lab、报告、发布与历史 |
| 架构 | 共享 Core、补偿与适配器数据流 |
| 威胁模型 | 信任假设与尚未解决的边界 |
| 兼容契约 | 接口与发布约定 |
| 蓝队研究 | 防守方法、去敏结果与零模型起点 |
| 0.2.9 说明 | 清理盘点、扫描提速与升级说明 |
参与贡献
欢迎 fork、PR、独立防守复现、缺陷报告、兼容性证据和文档修订。分享研究资料或日志前阅读 CONTRIBUTING.md,通过 Issues 和 Pull Requests参与; 不得公开凭据、私有配置和未脱敏事故记录。
社区友链
这张自制横幅直达我们的 LINUX DO 项目帖,不代表社区官方推荐。
许可证
MIT —— 见 LICENSE。