一个默认只读的 AI Agent CLI 安全审计工具，用于发现隐藏的全局 Skill 路由、跨 Agent 技能传播、环境凭据继承、Bridge 环境快照和过宽执行权限。它能帮助你解释“为什么 Codex 把开发任务交给 Coze”“一个全局 Skill 为什么同时影响多个编辑器”以及“子 Agent 为什么能读到无关 API Key”。
当前内置检测覆盖 Windows/Linux 上常见的 .agents、.codex、.trae、.coze 配置形态，规则模型可扩展到其他 AI coding agent 和 vendor CLI。工具不会读取或输出密钥值，也不会自动删除 Skill、停止进程或修改权限。
| 场景 | 典型信号 | 你能得到什么 |
|---|---|---|
| 安装或升级 Agent CLI 前后 | 安装器可能写入全局 Skill、hook 或桥接配置 | 升级前后差异基线 |
| 开发任务被意外转交外部平台 | 没有点名 Coze/Figma，任务却由外部平台执行 | 隐式路由规则和物理来源 |
| 多个 Agent 同时出现相同行为 | Codex、Trae 等宿主加载同一套规则 | Junction、符号链接或共享 Skill 池证据 |
| API Key 作用域异常 | 无关子 Agent 也能访问公众号、云服务或模型凭据 | 敏感变量名称、Bridge 快照和 ACL 风险 |
| 外部项目、草稿或部署重复创建 | 超时后自动重试，多个 Agent 都具有写权限 | 幂等键、唯一写入者和先查后重试方案 |
| 开发者工作站安全体检 | 可信项目多、完全访问、免审批长期启用 | 权限与信任面清单 |
| 企业镜像或 DevSecOps 门禁 | 需要阻止高风险 Agent 配置进入标准镜像 | JSON 报告和 --fail-on CI 门禁 |
| Skill/插件发布前自检 | 新规则可能过度触发或跨项目生效 | 路由边界与误报检查 |
每个场景的触发条件、命令和验收标准见完整使用场景。
安装一个 Agent CLI 后，影响范围可能远大于“多了一个命令”。常见失效链是：
- npm、安装器或升级脚本把 Skill 写入用户级共享目录。
- Skill 使用“无需显式点名”“所有开发任务均触发”等宽泛规则。
- 共享目录、符号链接或 Windows Junction 把规则传播到多个 Agent 宿主。
- Bridge 把父进程完整环境复制到子 Agent，令无关任务也能读取密钥。
danger-full-access与免审批策略放大误路由的影响。- 多 Agent 并行调用外部平台，却没有幂等键或唯一写入锁，产生重复项目、草稿或部署。
这不是“哪个模型更强”的问题，而是谁控制路由、凭据和副作用边界的问题。
flowchart LR
U["User request"] --> H["Host model"]
H --> G["Global skill or rule"]
G --> V["External vendor CLI"]
V --> B["Bridge or child agent"]
E["Ambient credentials"] --> B
P["Full access and no approval"] --> B
B --> W["External writes"]
需要 Python 3.11 或更高版本，无第三方运行时依赖。
git clone https://github.com/xiaoqi-AI/agent-cli-scope-guard.git
cd agent-cli-scope-guard
python -m pip install -e .
agent-scope-guard输出 JSON，并在发现高风险项时返回退出码 2：
agent-scope-guard --json --fail-on high审计另一个用户目录：
agent-scope-guard --home /path/to/home --skip-user-env默认只向终端输出。只有显式传入 --output 时才会写报告文件。
| ID | 风险 | 检测内容 |
|---|---|---|
ROUTE-001 |
高 | 全局 Skill 中的隐式、强制或宽泛平台路由 |
ROUTE-002 |
高 | 同一物理 Skill 被多个 Agent 宿主共享 |
SYNC-001 |
高 | 全局 CLI 在安装或升级阶段同步 Agent Skill |
SECRET-001 |
高 | 进程级或 Windows 用户级敏感环境变量名称 |
SECRET-002 |
严重 | Bridge 环境快照含敏感字段，且可能仍在运行 |
SECRET-003 |
高 | 凭据文件对无关本地用户组或 Agent 身份可读 |
PERM-001 |
严重 | danger-full-access 等不受限执行上下文 |
PERM-002 |
高/严重 | never 等免审批策略 |
TRUST-001 |
中 | 大量项目被设置为可信并可加载本地指令 |
AUTO-001 |
中 | 用户级 hooks、rules 或 requirements |
UX-001 |
中 | Agent 编辑器关闭文件删除确认 |
宽泛自然语言规则采用启发式检测，结果需要人工复核。匹配结果不等于恶意行为、远程泄漏或已确认漏洞。
- 显式路由：只有用户点名平台或使用明确命令前缀时，才允许委托外部 CLI。
- 最小作用域：业务专用 Skill 放在所属项目内，不放用户级共享目录。
- 密钥隔离：凭据按任务注入，禁止 Bridge 复制完整父进程环境。
- 最小权限：默认工作区范围写入；发布、部署、删除和账号修改必须逐次确认。
- 副作用幂等：外部创建操作使用幂等键、唯一写入者和结果核对，超时后先查后重试。
- 升级后对账：每次 CLI 升级后重新审计 Skill、链接、启动项、环境快照和权限。
通常不是模型能力选择，而是用户级 SKILL.md 使用了“无需显式点名”或“开发任务均触发”之类的宽泛路由。若该 Skill 来自全局 npm 包，它还可能在升级后被重新同步。
先解析两个宿主的 Skill 路径，再比较它们是否指向同一个物理目录。ROUTE-002 会识别共享池、符号链接和 Windows Junction 造成的跨宿主传播。
不会。审计器只识别敏感变量和 JSON 字段的名称，从不收集或输出对应值。测试套件包含防止密钥值进入文本或 JSON 报告的回归用例。
不意味着。快照证明本地凭据暴露面扩大，但不能证明已经远程传输。报告会区分“观察到的本地状态”“有边界的推断”和“已确认事件”。
当前版本坚持只读审计。停止 Bridge、收紧 ACL、删除全局 Skill 和轮换密钥都需要在确认影响范围后人工执行，避免把安全工具本身变成新的高权限修改器。
- 不读取或输出环境变量值。
- 对 JSON 快照只识别敏感字段名称，不输出对应值。
- 本机路径在报告中折叠为
~/...。 - 默认不删除 Skill、不停止进程、不更改 ACL、不撤销 token。
- 发现快照不等于发现远程泄漏；工具会明确区分本地暴露与已证实外传。
请不要把真实凭据、完整环境快照或未脱敏审计报告提交到公开 Issue。详见 SECURITY.md。
python -m unittest discover -s tests -v
agent-scope-guard --help欢迎提交新的 Agent CLI 检测器，但每条规则都必须说明证据边界、误报可能和安全修复路径。