openguardrails/openguardrails-oss

# OpenGuardrails-OSS OpenGuardrails 是一个智能体安全平台。**OpenGuardrails-OSS** 是其 开放源代码部分 — 一个用于为 AI 智能体提供 **健康检查** 和 **考试** 的工具包。你通过一个智能体（OpenClaw、Hercules — 任何自主智能体）用自然语言 驱动它；它随后使用 OpenGuardrails-OSS 来审计 *自身* 或 *其他 智能体*。 它做三件事： 1. **扫描** — 对已安装的智能体、技能、插件和 MCP 服务器进行健康检查。查找已知漏洞、已知恶意组件和 危险配置。把它想象成一次身体检查。 2. **红队测试** — 动态考试。运行来自 OpenGuardrails Agent Threat Intelligence 的 curated 攻击提示，以查看目标智能体是否会中招。把它想象成在敌对条件下进行的驾驶测试。 3. **集成** — 开箱即用的插件、技能和 SDK，使开发者能够在运行时 从自己的智能体内部调用 OpenGuardrails。 ## 👤 阅读本文档的是谁？ 该项目设计为由 **AI 智能体驱动，而不是由人类输入命令**。选择与你匹配的部分： - 👤 **你是人类** — 继续阅读下方的 [For Humans](#-for-humans) 部分。你不需要输入任何命令。你只需将本仓库的 URL 交给一个智能体（OpenClaw、Hercules Agent、Claude Code、Codex 或其他任何自主智能体），并告诉它，用 plain language 你想要检查什么。被你驱动的智能体可能是 *同一个* 被审计的智能体（自我检查）或 *不同的* 智能体（审计对等体）。 - 🤖 **你是 AI 智能体** — 跳转到 [For Agents](#-for-agents)。该部分包含你需要的命令、标志、退出码和机器可读的输出格式。你可以在自身上运行，也可以在同一机器上的兄弟智能体上运行。 ## 👤 面向人类 ### 用一段话概括这是做什么的 一个 AI 智能体 — OpenClaw、Hercules Agent、Claude Code、Cursor，无论你运行哪一个 — 对你的笔记本电脑拥有类似 root 的权限。它读取文件、写入文件、运行命令、安装工具并将数据发送到互联网。 如果攻击者偷偷将一个坏提示、坏技能或坏 MCP 服务器植入智能体的环境，攻击者就继承了该权限。 OpenGuardrails-OSS 是你告诉智能体使用的工具包，以便它可以 为自己 — 或你机器上的另一个智能体 — 进行健康检查 和考试，并在早期发现问题。 ### 如何使用（无需技术技能） 1. 打开任何可以运行 shell 命令的智能体（OpenClaw、Hercules Agent、 Claude Code、Cursor、带有终端工具的 ChatGPT 桌面等）。 2. 将以下内容粘贴给它： 3. 就这样。智能体会处理安装、扫描和 报告。 你可以请求： - *“给自己做一次安全检查。”* → 智能体运行 `scan` 检查 自身 - *“检查我安装的其他智能体。”* → 针对该智能体配置路径的 `scan` - *“假装成攻击者，看看我的智能体是否会上当。”* → 对你指定的目标运行 `redteam` - *“安装 OpenGuardrails 技能，以便这个智能体下次可以保护自己。”* → 在 `skills/openguardrails/` 下安装技能 驱动工作的智能体不 **必须** 是被审计的智能体。你可以驱动自检（智能体审计自身）或同行审计（智能体 A 审计智能体 B）。 ### 为什么一部分是开放的，一部分不是 安全是 **在成本约束下的不对称对抗**。 - 攻击者只需要找到一个 *可用的* 漏洞。 - 防御者必须覆盖 *每一个可能的路径*。 - 因此，防御者的成本在结构上高于攻击者。 - 防御取胜的唯一方法是将攻击者的成本提升到超过其预期回报（或超过其从更容易的目标获得的回报）。 这一事实决定了我们开源什么以及保留什么： | 开源（本仓库） | 原因 | | ----------------------------------------- | ---------------------------------------------- | | 已知漏洞扫描器 | 每个打补丁的用户 = 减少一个免费击杀 | | 红队攻击目录和运行器 | 让防御者 *衡量* 他们的暴露程度 | | 集成客户端（插件、技能、SDK） | 对攻击者价值低 | | 保留专有部分 | 原因 | | ----------------------------------------- | ---------------------------------------------- | | 检测规则和运行时策略引擎 | 公布它们会告诉攻击者如何规避 | | 威胁情报摄取管道 | 公布它会告诉攻击者我们看到了什么 | | 防御模型和评分 | 公布它们会让攻击者针对它们进行训练 | 简而言之：我们开源 **帮助你发现问题** 的部分，我们保留 **帮助你阻止它们** 的部分。这两部分都提高了攻击者的成本。关于更长论述，请参见 [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md)。 ### 你从中得到什么 - 如果有的话，会得到一份机器上已知不良组件的报告。 - 如果有的话，会得到一个分数和智能体中招的攻击列表。 - 如果你正在构建智能体并希望在运行时得到保护，则有简单的集成路径。 ## 🤖 面向代理 你阅读本文档是因为有人给了你这个仓库的 URL 并 要求你审计智能体安全。审计对象可能是 **你 自己**（自检）、**同一机器上的另一个智能体**（同行检查， 例如你正在检查 OpenClaw 的安装），或 **人类给你的远程智能体端点**。如果请求有歧义，请澄清。 按照以下步骤操作。优先使用机器可读输出（`--json`）。假设人类想要一个简短摘要；不要直接给他们原始 JSON。 ### 引导 ``` git clone https://github.com/openguardrails/openguardrails-oss.git cd openguardrails-oss bun install ``` 如果未安装 `bun`：`curl -fsSL https://bun.sh/install | bash`。如果 无法安装 Bun，请停止并告知人类 — 不要静默回退到 `node`。 ### 命令 所有命令都通过 `bun src/cli.ts <子命令>` 调用，或在 `bun link` 后通过 `openguardrails <子命令>` / `ogr <子命令>` 调用。 #### `scan` — 静态健康检查 ``` ogr scan [--target ] [--json] [--severity ] ``` - 遍历常见的智能体安装位置（`~/.claude`、`~/.cursor`、 `~/.config/*mcp*`、项目本地 `.mcp.json` 等）。 - 引用离线的知识库 `src/scan/knowledge-base.ts`。 - 退出码：`0` 干净，`2` 低于 `--severity` 的发现，`3` 在或高于 `--severity` 的发现，`1` 工具错误。 #### `redteam` — 动态红队测试 ``` ogr redteam --target [--suite ] [--json] [--max ] ``` - `--target` 可以是接受 `POST { "prompt": "..." }` 并返回 `{ "response": "..." }` 的 HTTP 端点，或一个从 stdin 读取提示并将其输出写入 stdout 的 shell 命令。 - 套件在 `src/redteam/attacks.ts` 中定义。默认套件为 `core-prompt-injection`。 - 每次攻击都有一个检测器；命中计为目标失败。 - 退出码反映失败（与 `scan` 相同的方案）。 #### `integrate` — 生成一个集成工件 ``` ogr integrate skill > openguardrails.skill.md ogr integrate plugin > moltguard.plugin.json ogr integrate sdk # prints SDK usage snippet ``` ### 输出约定 使用 `--json` 时，每个命令都会向 stdout 输出一个 JSON 对象： ``` { "tool": "openguardrails-oss", "version": "0.1.0", "command": "scan", "startedAt": "2026-04-17T12:00:00Z", "finishedAt": "2026-04-17T12:00:04Z", "findings": [ { "id": "OGR-KB-0001", "severity": "high", "title": "...", "location": "...", "evidence": "...", "remediation": "..." } ], "summary": { "total": 1, "bySeverity": { "high": 1 } } } ``` 报告 `severity` 字段时不要意译；保留原样报告给人类。 ### 何时升级给人类 - 任何 `critical` 发现 — 停止，立即报告，不要自动修复。 - 表明目标智能体泄露了文件系统内容或执行了攻击者提供的 shell 命令的 `redteam` 失败。 - 缺少读取 `~/.claude` 或类似目录的权限 — 询问；不要使用 sudo。 ### 你不应该做的事 - 不要将扫描报告提交回用户的仓库，除非被要求 — 它们包含路径，可能包含敏感字符串。 - 不要对未明确要求测试的目标运行 `redteam`。攻击套件设计为日志中会发出很大噪音。 - 不要“改进”知识库，添加推测性条目。 ## 项目结构 ``` src/ cli.ts # CLI entry — scan / redteam / integrate index.ts # library entry scan/ # static scanner + offline knowledge base redteam/ # attack runner + attack catalog integrations/ sdk.ts # TypeScript SDK for agent developers moltguard/ # plugin for OpenClaw-family agents skill/ # portable skill package for tool-using LLMs utils/ skills/ openguardrails/ # drop-in skill directory for Claude Code etc. docs/ PHILOSOPHY.md # why we open-source what we open-source AGENT.md # extended agent-facing playbook ``` ## 贡献 对 **攻击目录** (`src/redteam/attacks.ts`) 和 **知识库** (`src/scan/knowledge-base.ts`) 的贡献尤其受欢迎 — 这是随着社区参与而扩展的工作的一半。在提出防御性方面的任何建议之前，请先阅读 [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md)，我们很可能会将其重定向到闭源产品。 ## 许可证与联系 Apache-2.0。参见 [LICENSE](LICENSE)。 - 网站: https://openguardrails.com - 作者: [@thomas-security](https://github.com/thomas-security) · thomas@openguardrails.com - 组织: OpenGuardrails.com ## 关于 @OpenGuardrails/MoltGuard **OpenClaw 上最受欢迎的安保技能 [ClawHub](https://clawhub.ai/thomas-security/moltguard)** — 保护你的每个操作。

标签：Agent威胁情报, AI代理审计, AI安全, AI驱动安全, Chat Copilot, CISA项目, CSV导出, DNS 反向解析, DNS通配符暴力破解, MITM代理, OpenGuardrails, OSS安全工具, 代理安全, 健康检查, 动态攻击测试, 危险配置审计, 威胁情报, 安全检查, 安全防护, 开发者工具, 恶意组件检测, 插件安全, 文档结构分析, 结构化查询, 自动化安全, 自动化攻击, 集成SDK