gateway/guardian

# Guardian **面向 AI 编程代理的本地优先依赖安全工具。** Guardian 为 Codex 和 Claude Code 提供了一种针对 npm、Python、Go、Rust 和 Composer 项目的只读安全工作流：它会在安装 npm 和 Python 包*之前*进行检查，针对所有五个生态系统进行安全公告和恶意包情报扫描，长期监控可疑的依赖行为，并解释真正重要的内容，而不会建议进行毫无意义的依赖变更。请参阅 [生态系统覆盖](#ecosystem-coverage) 以了解具体适用的功能。 [](https://github.com/gateway/guardian/actions/workflows/release-check.yml) [](LICENSE) [](docs/TRUST_MODEL.md) [](#install-in-claude-code) [](#install-in-codex) ## 运行效果 你的代理输入 `npm install lodahs`（注意拼写错误）。Guardian 的预安装 hook 会在获取任何内容之前阻止它： ``` Guardian paused this install for package-risk review. - lodahs: Package name is unusually similar to popular npm package 'lodash' (rank 145). Verify the spelling and publisher before installation. ``` 同样的检查也可以作为 skill 或 CLI 判定结果提供（截断的实际输出）： ``` { "verdict": "block", "name": "lodahs", "resolved_version": "0.0.1-security", "explanation": "Blocked by OSV/OpenSSF malicious-package evidence for this exact version.", "signals": [ {"signal_type": "typosquat-suspected", "signal_grade": "behavioral-high", "similar_package": "lodash", "edit_distance": 1}, {"signal_type": "malicious-package-match", "signal_grade": "catalog-match", "id": "MAL-2025-25502", "source": "osv-malicious"} ] } ``` 合法的安装会不受影响地通过。网络故障会以显式的覆盖警告进行 fail-open（失败放行）—— Guardian 绝不会让你无法进行安装。 ## 目录 - [Guardian 的功能](#what-guardian-does) - [生态系统覆盖](#ecosystem-coverage) - [Guardian 的对比](#how-guardian-compares) - [在 Codex 中安装](#install-in-codex) - [在 Claude Code 中安装](#install-in-claude-code) - [测试你的第一个仓库](#test-your-first-repo) - [安装前检查](#check-before-installing) - [Skills 及其使用时机](#skills-and-when-to-use-them) - [自动化](#automation) - [情报来源](#intelligence-sources) - [默认高效](#efficient-by-default) - [更多文档](#more-documentation) - [Guardian 不会做什么](#what-guardian-does-not-do) ## Guardian 的功能 - 在安装前检查拟引入的包，包括潜在的 typosquat（拼写错误抢注）、已发布的 advisories（安全公告）、安装行为以及精确的恶意目录匹配。 - 从清单、lockfile 和可选的已安装元数据中盘点 npm、Python、Go、Rust 和 Composer 的依赖证据。 - 将确切的包版本与漏洞、漏洞利用情报和恶意包来源进行匹配。 - 检测依赖何时新增了安装时的行为，包括 npm 生命周期脚本和特定的 Python 源码安装证据。 - 在无需网络访问的情况下，检测未经批准的 npm lockfile 主机、相同版本的完整性漂移、直接依赖 URL 以及不完善的 Python 版本锁定/hash 规范。 - 审查新采用的 registry 版本是否存在近期发布、维护者变更、来源证明消失、废弃/撤销以及仓库更改等情况。 - 将直接的运行时风险与传递性、vendored 元数据、仅用于测试、仅用于工具以及隔离环境的干扰项区分开来。 - 随时间跟踪扫描结果，以便你可以查看新增、已解决、已更改和未更改的发现。 - 为代理、维护者和审查者生成紧凑的操作员 JSON 和可选的 Markdown 交接报告。 - 包含一个针对未使用、可替换或许可安全的 Vendor Candidate（候选供应商）依赖的 package-diet（包瘦身）工作流，该工作流利用 lockfile 占用空间和缓存的维护证据。 - 仅在证据支持真正的修复时，协助准备对维护者友好的 advisory PR。 Guardian 不会编辑依赖文件、安装项目依赖，或在正常扫描期间执行任意的项目代码。 ``` Project evidence -> read-only inventory -> normalized package versions -> advisory and exploit-intelligence matching -> behavioral drift detection (install scripts, lockfile tamper, registry metadata) -> project-context corroboration -> prioritized findings -> operator summary, handoff report, and snapshot comparison ``` ## 生态系统覆盖 并非每个功能都适用于所有生态系统。Guardian 的原则是准确说明它检查了什么，因此这是当前的矩阵： | 功能 | npm | PyPI | Go | Rust (crates.io) | Composer | |---|:---:|:---:|:---:|:---:|:---:| | 盘点 + advisory/恶意包匹配 | ✅ | ✅ | ✅ | ✅ | ✅ | | 预安装拦截 + `guardian-check-package` | ✅ | ✅ | — | — | — | | Typosquat / slopsquat 检测 | ✅ | ✅ | — | — | — | | 安装时行为信号 | ✅ 生命周期脚本 | ✅ sdist / direct-URL | n/a¹ | — | — | | 相同版本 lockfile 完整性漂移 | ✅ | hash/pin 规范 | ✅ | ✅ | ✅ | | 未经批准的 lockfile registry 主机 | ✅ | — | — | — | — | | Registry 行为元数据（发布时长、维护者、来源证明） | ✅ | ✅ | — | — | — | | Package diet / 供应商审查 | ✅ | — | — | — | — | ¹ Go module 的获取不会在安装时执行代码，因此没有需要监控的安装脚本暴露面。 简而言之：Go、Rust 和 Composer 可获得只读盘点、精确版本的 advisory 和恶意包匹配（通过 OSV）、直接依赖与传递性依赖的上下文，以及 lockfile 校验和漂移检测。预安装拦截、typosquat 检查和 registry 行为情报目前仅覆盖 npm 和 PyPI 包的新增 —— `go get` 和 `cargo add` 尚未被拦截。Rust 是拦截扩展的优先对象，因为 `build.rs` 和 proc-macros 会在构建时执行任意代码，这正是 npm 生命周期脚本的直接类比。 ## Guardian 的对比 Guardian 与现有工具存在重叠，但它所处的位置不同：它是为 AI 代理即将更改你的依赖关系图的那个时刻而构建的。 - **`npm audit` / `pip-audit`**：单一生态系统、仅包含 advisory、无状态。Guardian 是跨生态系统的，增加了恶意包目录和漏洞利用情报（KEV/EPSS），会记住之前的扫描结果，因此无需重新解释未更改的发现，并能检测 advisory 尚未捕获的行为漂移。 - **Dependabot / Renovate**：托管在代码仓库中且由 PR 驱动，在依赖发生更改后做出反应。Guardian 在本地运行，在安装*发生之前*进行拦截，并将可信的暴露风险与 vendored 元数据和仅用于测试的干扰项区分开来，而不是为每个 advisory 都创建一个 PR。 - **托管供应链服务**：功能强大，但它们是服务 —— 你的依赖关系图会被发送到别人的云上。Guardian 是本地优先的，没有遥测，其扫描器 runtime 仅使用 Python 标准库，其状态保存在你拥有的 SQLite 文件中。唯一的出站流量是前往公开文档注明的 advisory 和 registry 来源。 如果你已经在使用这些工具，Guardian 可以作为它们的补充：它是位于你的编程代理内部的那一层。 ## 在 Codex 中安装 ### Codex 桌面版 在 Codex 应用中打开 **Plugins**。如果你的应用暴露了添加应用市场或添加仓库的流程，请使用以下信息添加 Guardian： - 应用市场或 GitHub 仓库：`gateway/guardian` - 要安装的插件：`guardian-security-scan` 如果应用没有暴露该源流程，请在终端中使用以下 Codex CLI 命令一次，然后重启 Codex 或开启新对话，以便加载 Guardian skills。 ### Codex CLI 在终端中运行这些命令。安装分为两步，因为 Codex 首先会添加 Guardian 应用市场源，然后从该市场安装插件。 1. 添加 Guardian 应用市场： ``` codex plugin marketplace add gateway/guardian --ref main ``` 2. 安装 Guardian 插件： ``` codex plugin add guardian-security-scan@guardian ``` 如需从本地检出的代码进行开发，请使用本地路径代替 GitHub 应用市场： ``` git clone https://github.com/gateway/guardian.git codex plugin marketplace add ./guardian codex plugin add guardian-security-scan@guardian ``` ## 在 Claude Code 中安装 ### Claude 桌面版 / Claude Code UI 在 Claude Code 中，在提示框中输入 `/plugin` 以打开插件管理器。前往 **Marketplaces**，添加 Guardian，然后安装该插件： - 插件来源或 GitHub 仓库：`https://github.com/gateway/guardian` - 要安装的插件：`guardian-security-scan` Claude skills 在安装后会有命名空间，例如 `guardian-security-scan:guardian-project-scan`。 ### Claude Code 提示命令 这些是 Claude Code 的斜杠命令。请将它们粘贴到 Claude Code 提示中，而不是你的 shell 中。安装分为两步：添加 Guardian 应用市场，然后安装插件。 1. 添加 Guardian 应用市场： ``` /plugin marketplace add gateway/guardian ``` 2. 安装 Guardian 插件： ``` /plugin install guardian-security-scan@guardian ``` 安装后，请运行 `/reload-plugins` 或开启一个新的 Claude Code 会话。 Guardian 的 Claude skills 使用了命名空间： - `guardian-security-scan:guardian-check-package` - `guardian-security-scan:guardian-project-scan` - `guardian-security-scan:guardian-daily-watch` - `guardian-security-scan:guardian-repo-scout` - `guardian-security-scan:guardian-package-diet` - `guardian-security-scan:guardian-advisory-pr` 有关 Claude 特定的安装和验证说明，请参阅 [`docs/CLAUDE_CODE.md`](docs/CLAUDE_CODE.md)。 ## 测试你的第一个仓库 安装完成后，在你想要扫描的项目中打开 Codex 或 Claude，并使用以下提示之一： Codex: Claude Code: 一次良好的初步扫描应报告： - 当前状态，例如 `0 act now`、`1 fix this week` 或 `watch`。 - 发现的问题是关联到 runtime、传递性的、vendored 元数据、仅用于测试，还是隔离环境。 - 当包与已知问题匹配时，提供 advisory 链接和严重程度。 - 如果之前扫描过此仓库，报告与上次扫描相比的变化。 - 任何操作员 JSON 或 Markdown 交接产物的路径。 如果你是从 Guardian 检出代码而不是已安装的插件进行测试，请运行： ``` ./plugins/guardian-security-scan/scripts/guardian scan /path/to/repo --mode daily --output compact --json ``` 对于常规的扫描总结，请使用 Sonnet 并设置较低或正常的计算量。Guardian 在本地进行依赖扫描；在验证安装时通常不需要使用更高推理能力的模型。 ## 安装前检查 预安装拦截涵盖了 npm 和 PyPI 包的新增（[其他生态系统](#ecosystem-coverage) 由扫描和 advisory 匹配涵盖，但不拦截安装）。Guardian 注册了一个受限的 `PreToolUse` hook，可识别常见的 npm、pnpm、Yarn、Bun、pip、Pipenv、uv 和 Poetry 安装形式 —— 包括子命令之前的包管理器标志、带版本号的 Python 可执行文件、npm 别名、包执行命令（`npx`、`npm exec`、`pnpx`、`pnpm dlx`、`yarn dlx`、`bunx`、`bun x`）、单条命令包含多个包，以及受限的 `sh`/`bash`/`zsh -c` 包装器。 你也可以在安装前明确要求进行检查： Codex: Claude Code: 判定结果的行为： - 精确的恶意目录匹配将**阻止**。 - 潜在的 typosquat、已知的漏洞版本和不透明的远程源安装将**暂停以供审查**。 - 本地文件系统依赖（例如 `pip install -e .`）在附加说明信息后会被**允许**。 - 网络故障依然保持**fail-open**，并带有显式的覆盖范围警告。 如果 Guardian 暂停了一个合法的相似包名，请使用 `guardian policy accept-name ` 将其永久静音。要禁用或调整拦截（包括哪个信号级别会被强制阻止），请编辑 `~/.guardian-security-scan/config.json` 中的 `preinstall_gate_enabled` 和 `preinstall_gate_block_grades`。完整详情、误报指南和判定语义见：[`docs/PREINSTALL_GATE.md`](docs/PREINSTALL_GATE.md)。 ## Skills 及其使用时机 Skill 调用因运行环境而略有不同： - Codex：使用 `$guardian-security-scan:skill-name`。 - Claude Code：使用 `/guardian-security-scan:skill-name`。 - 通常自然语言也有效，但带有前缀的形式是最清晰的复制/粘贴选项。 独立的个人 skill 可能会有更短的名称，如 `$guarded-code`；Guardian skills 是插件 skill，因此它们使用插件命名空间，以避免与其他已安装的 skill 发生冲突。 ### `guardian-check-package` 在添加 npm 或 Python 依赖之前使用此 skill。它会在不安装包的情况下返回受限且缓存的允许/警告/阻止判定。 Codex: Claude Code: ### `guardian-project-scan` 用于常规项目安全扫描、重复扫描、修复验证和交接报告。 Codex: Claude Code: ### `guardian-daily-watch` 用于跨已知本地仓库的轻量级晨间自动化。它会对依赖文件进行指纹识别，跳过未更改的清单，并能为已知的包清单刷新 advisory 数据。 Codex: Claude Code: 有关计划扫描策略，请参阅 [`docs/AUTOMATION.md`]()。 ### `guardian-repo-scout` 用于对你不拥有的公共 GitHub 仓库进行临时扫描。Repo Scout 默认使用一次性克隆和临时的 Guardian 状态，然后报告高价值的发现及建议的报告路径。 Codex: Claude Code: 有关公共仓库探测工作流，请参阅 [`docs/REPO_SCOUT.md`](docs/REPO_SCOUT.md)。 ### `guardian-package-diet` 用于处理依赖臃肿、未使用的包，以及审查“是否可以用简单的本地代码替换此依赖？”。这与漏洞扫描是分开的。 Codex: Claude Code: ### `guardian-advisory-pr` 在 Guardian 确认了一个可操作的发现后，如果你想要一个包含 advisory 链接、依赖证据、修复理由和验证说明的对维护者友好的 PR，请使用此 skill。 Codex: Claude Code: ## 自动化 默认情况下，Guardian 会将本地扫描状态存储在插件外部的 SQLite 中： ``` ~/.guardian-security-scan/guardian.db ``` 该状态允许 Guardian 跨时间比较扫描结果并回答实际问题： - 新的 advisory 是否影响了我们已有的包？ - 依赖项的更改是否引入了新的发现？ - 修复是否真正解决了之前的问题？ - 这是否属于不应在每天早上重新解释的、未更改的元数据干扰？ 对于晨间检查，请使用 `guardian-daily-watch`。它首先会对依赖清单和 lockfile 进行哈希计算，以此保持低廉的扫描成本，然后仅对依赖文件发生更改的仓库进行重新盘点。当你想根据最新发布的数据检查已知包时，可以添加实时的 advisory 刷新。 要每天早上自动运行它，请将 daily-watch 提示放入你运行环境的调度程序中（Claude Code 的 `/schedule` 例程或 Codex 的等效功能）—— [`docs/AUTOMATION.md`](docs/AUTOMATION.md) 提供了可直接复制的提示和无头 cron 替代方案。扫描工作在本地进行，模型仅总结紧凑的差异，因此计划运行的 token 成本很低，在小型模型上运行也完全没问题。 ## 情报来源 Guardian 使用多种来源，因为没有单一的订阅源是完整的： - OSV - GitHub Security Advisories - CISA Known Exploited Vulnerabilities - FIRST EPSS - NVD enrichment - GitLab Advisory Database ingest - OpenSSF Malicious Packages（通过模式控制的稀疏摄取） - 针对新采用版本的 npm 和 PyPI registry 行为元数据 - 内置的精确匹配公开恶意包活动目录 Guardian 也会验证自身的情报：`guardian catalog verify` 会将每个内置目录条目与 OSV 的恶意包记录进行交叉核对，并报告哪些条目得到了独立证实；远程目录刷新通过插件中固定的 SHA-256 manifest 执行 fail-closed（失败拒绝）策略。 Guardian 报告的是已配置来源目前对其能看到的包版本的了解情况。它无法证明项目免受未知的 zero-day 攻击。 有关来源行为、信任边界和已知限制，请参阅 [`docs/TRUST_MODEL.md`](docs/TRUST_MODEL.md)。 ## 默认高效 Guardian 专为本地代理工作流和计划扫描而设计，力求轻量化： - 扫描器 runtime 仅使用 Python 标准库（没有 pip 依赖）。源码使用情况分析会调用 ripgrep (`rg`)；如果缺少该工具，Guardian 会明确指出，并降低基于使用情况的结论的可信度，而不是进行猜测。 - 常规报告非常紧凑，以便代理阅读摘要而不是原始 lockfile。 - Daily watch 会跳过未更改的依赖清单。 - 未更改的 daily-watch 根目录不会发起任何 registry 情报调用；标准扫描会在首次基线建立时跳过 registry 枚举。 - 实时源请求共享受限的重试、配速和条件磁盘缓存，因此不会在数据有效期内重复下载大型订阅源。 - 精确版本的预安装判定结果默认在 SQLite 中缓存 24 小时；无版本号检查始终会刷新 registry 当前的 `latest` 版本。 - 实时 advisory 刷新和已安装目录树印证是明确的可选项目。 - Repo Scout 对大型公共仓库使用受限且带有配速的扫描。 - 快照对比可防止重复扫描反复解释未更改的发现。 - Package-diet 审查是独立的，因此臃肿分析不会导致安全输出膨胀。 默认扫描是保守的。当情况确有需要时，可进行更深度的实时源检查、已安装目录树印证和包使用情况扫描。 ## 更多文档 - [`docs/AUTOMATION.md`](docs/AUTOMATION.md)：daily watch、新鲜度和扫描状态行为。 - [`docs/CLI.md`](docs/CLI.md)：直接使用 CLI、扫描模式、token 和本地状态。 - [`docs/PREINSTALL_GATE.md`](docs/PREINSTALL_GATE.md)：包检查、hooks、判定、误报和 fail-open 行为。 - [`plugins/guardian-security-scan/docs/SOURCES.md`](plugins/guardian-security-scan/docs/SOURCES.md)：来源矩阵、新鲜度、身份验证、registry 隐私和目录完整性。 - [`docs/CLAUDE_CODE.md`](docs/CLAUDE_CODE.md)：Claude Code 安装、验证和冒烟测试。 - [`docs/REPO_SCOUT.md`](docs/REPO_SCOUT.md)：临时的公共 GitHub 仓库探测。 - [`docs/TRUST_MODEL.md`](docs/TRUST_MODEL.md)：安全边界、来源模型和已知限制。 - [`SECURITY.md`](SECURITY.md)：漏洞报告和密钥处理指南。 ## Guardian 不会做什么 - 它不证明项目没有未知的 zero-day。 - 它在正常扫描期间不执行任意的项目代码。 - 它不自动编辑或升级依赖。 - 它不把每一个传递性或 vendored 元数据的发现都当作生产事故。 - 它不能取代针对高影响安全修复的人工审查。

标签：AI编程助手插件, 云安全监控, 依赖安全, 逆向工具, 静态分析