agent-safety-kit

English | 中文

为 AI Agent 工具调用提供的轻量安全闸门。

Agent 想要执行: rm -rf /
agent-safety-kit:   ❌ 拒绝 — 工作区外的破坏性命令

它做什么

当 AI Agent（Claude、Codex、Cursor 等）尝试执行工具调用时， agent-safety-kit 会拦截并做出判断：

• allow（放行） — 安全，正常执行
• ask（询问） — 需要人工确认
• deny（拒绝） — 阻止，永不执行

默认防护

开箱即用，零配置：

• 工作区外的文件 → 询问
• .ssh/、.env、凭证文件 → 拒绝
• rm -rf、curl | bash、编码命令 → 拒绝
• 云端元数据端点（169.254.x.x）→ 拒绝
• Git 身份探测（git config user.email）→ 询问/拒绝
• 未知工具类型 → 询问（fail-closed）

安装

npm install -g @glos/agent-safety-kit

需要 Node.js 18+。

2 分钟上手

# 初始化（创建审计目录 + HMAC 密钥）
agent-safety init --mode hardened --write

# 验证安装
agent-safety doctor

也可以选择更轻量的模式：

agent-safety init --mode basic --write     # 仅创建工作区配置
agent-safety init --mode audit --write     # 加上审计目录（无 HMAC）
agent-safety init --mode hardened --write  # 完整：审计 + HMAC + 文件锁定

两种使用方式

1. MCP 代理 — 保护任何 MCP 服务器（推荐）

夹在你的 MCP 宿主（Claude Desktop、Cursor 等）和上游 MCP 服务器之间。 每次 tools/call 在转发前都会经过策略检查：

agent-safety proxy \
  --workspace-root ~/my-project \
  --upstream "npx -y @modelcontextprotocol/server-filesystem ~/my-project"

在 Claude Desktop 的 claude_desktop_config.json 中加入：

{
  "mcpServers": {
    "safe-filesystem": {
      "command": "agent-safety",
      "args": [
        "proxy",
        "--workspace-root", "/home/user/project",
        "--upstream", "npx",
        "--", "-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"
      ]
    }
  }
}

2. 作为库嵌入你自己的工具

import { evaluateAndDecide } from '@glos/agent-safety-kit';

const result = await evaluateAndDecide({
  agent: 'my-agent',
  workspaceRoot: '/home/user/project',
  tool: { kind: 'shell', command: 'git', args: ['config', 'user.email'] },
});

if (result.decision === 'allow') {
  // 安全，可以执行
} else {
  console.log(`已拦截: ${result.reasons.join(', ')}`);
}

策略档位

| 档位 | 适用场景 | | --- | --- | | default / balanced（默认） | 个人开发 — 拦截危险操作，边缘情况询问 | | hardened / strict | CI / 共享环境 — 更多拒绝，更少询问 | | minimal / permissive | 受信任的本地开发 — 保留硬性拒绝，放宽询问 |

agent-safety proxy --policy-profile hardened --upstream ...

高级功能（可选启用）

需要时再开，基础使用不必关心：

| 功能 | 作用 | 文档 | | --- | --- | --- | | HMAC 审计日志 | 防篡改的决策历史 | docs/mcp-proxy.md | | 内容扫描 | 检测文件写入中的后门 | docs/content-scan.md | | 秘密检测 | 拦截硬编码 API 密钥 | docs/content-scan.md | | 实时仪表盘 | 决策实时查看器 | docs/dashboard.md | | SARIF 导出 | 标准安全报告格式 | docs/extends-explain-doctor.md | | Webhook 告警 | deny 决策实时通知 | docs/mcp-proxy.md | | 策略 extends | 组合自定义策略链 | docs/extends-explain-doctor.md | | 插件系统 | 自定义工具评估器 | 见下文 | | 决策回放 | 用历史事件测试新策略 | docs/capture-strategy.md |

插件

为自定义工具类型注册评估器：

import { registerEvaluator } from '@glos/agent-safety-kit';

registerEvaluator('database_query', (tool) => {
  if (/DROP\s+TABLE/i.test(tool.statement || '')) {
    return [{ id: 'sql-drop', action: 'deny', reason: '检测到 DROP TABLE' }];
  }
  return [];
});

开发

npm install
npm test            # 核心测试
npm run test:all    # 全量 550+ 测试
npm run lint
npm run typecheck

参考适配器

adapters/ 目录提供 Claude、Codex、OpenCode、Gemini 的参考集成。 这些是示例，演示如何将各 runtime 的工具事件归一化为标准格式 —— 不是长期维护承诺。

文档

• 事件契约 — 输入输出 JSON 形态
• MCP 代理参考 — 全部代理选项
• 内容扫描 — 写入/网络内容检查
• 集成手册 — 各 runtime 配置
• 完整 CLI 参考 — 全部命令与选项

License

MIT

感谢 LINUX DO 社区的支持与分享