tiagosilva07/zyrax-guard

# Zyrax Guard [](https://github.com/tiagosilva07/zyrax-guard/actions/workflows/ci.yml) [](LICENSE) [](https://goreportcard.com/report/github.com/tiagosilva07/zyrax-guard) [](https://zyrax.io) **在安装前先检查依赖。** Zyrax Guard 会对包进行审查，排查拼写错误 (typosquats)、已知的恶意名称、幻觉包名以及供应链异常——这一切都在几毫秒内完成，即在实际执行安装之前。**支持 npm, PyPI 和 crates.io**（由一个与生态系统无关的引擎驱动）。 ``` $ zyrax-guard check lodahs ✗ lodahs@0.0.1-security — BLOCK - name is similar to "lodash" — double-check you meant this package - MAL-2025-25502: Malicious code in lodahs (npm) did you mean: lodash to override: zyrax-guard allow lodahs $ zyrax-guard check lodash ✓ lodash@4.18.1 — SAFE ``` 支持在本地、CI 中运行，并可作为 AI 编程代理的门禁。无需账号。除了你查询的公开包名外，没有任何数据会被发送到外部。 🌐 **主页:** [zyrax.io](https://zyrax.io) ## 安装 ### 快速安装 (Linux / macOS) ``` curl -fsSL https://raw.githubusercontent.com/tiagosilva07/zyrax-guard/main/scripts/install.sh | sh ``` 为你操作系统的架构下载已签名的发布二进制文件，根据发布版本的校验和验证其 SHA-256，并安装它（安装到 `/usr/local/bin`，如果该路径不可写，则安装到 `~/.local/bin`）。可以通过 `VERSION=v0.5.0` 来固定版本，或者设置 `BINDIR` 来选择安装位置。如果你的 `PATH` 中包含 `cosign`，它也会验证 cosign 签名。 ### `go install` (Go 1.23+) ``` go install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest ``` ### 已签名的发布二进制文件 从 [Releases](https://github.com/tiagosilva07/zyrax-guard/releases) 下载。 每个发布版本包含： - 针对 linux/darwin/windows × amd64/arm64 的预编译二进制文件 - `checksums.txt` (SHA-256) - SLSA L3 构建来源证明（每个构件包含 `.cosign.bundle`） - SBOM (`zyrax-guard.spdx.json`) 验证二进制文件： ``` cosign verify-blob \ --bundle zyrax-guard-linux-amd64.cosign.bundle \ zyrax-guard-linux-amd64 ``` ### 从源码构建 ``` git clone https://github.com/tiagosilva07/zyrax-guard cd zyrax-guard go build -o zyrax-guard ./cmd/zyrax-guard ``` ## 快速开始 ### 检查单个包 ``` zyrax-guard check lodash # npm (default) zyrax-guard check requests --ecosystem pypi # PyPI zyrax-guard check serde --ecosystem crates # crates.io ``` ### 先检查再安装 ``` zyrax-guard install lodash axios # vets, then runs npm install zyrax-guard install flask --ecosystem pypi # vets, then runs pip install zyrax-guard install serde --ecosystem crates # vets, then runs cargo add ``` ### 允许包 (添加至本地策略) ``` zyrax-guard allow my-internal-pkg # 已允许 "my-internal-pkg"（记录在 .zyrax/policy.json 中） ``` 提交 `.zyrax/policy.json` —— 这是针对你项目的可审查白名单。 ### 扫描 PR 的 lockfile 差异 ``` zyrax-guard scan --base /tmp/base-lock.json --head package-lock.json --sarif ``` 向 stdout 输出 SARIF 2.1.0。如果没有 BLOCK，则退出码为 0；否则为非零值。 添加 `--strict` 可将 WARN 视为失败。 ## GitHub Action 对每个 pull request 设置门禁：Zyrax Guard 会检查 PR 中新增的依赖，如果有任何依赖被拦截，则使检查失败。添加 `.github/workflows/zyrax-guard.yml`： ``` name: Zyrax Guard on: pull_request jobs: guard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # lets Guard diff against the PR base (added deps only) - uses: tiagosilva07/zyrax-guard@v0 with: ecosystem: npm # npm | pypi | crates ``` 在 pull request 中，它仅扫描相对于基础分支新增的依赖；否则它将扫描整个 lockfile。当依赖被拦截时，作业将失败。`@v0` 会跟踪最新的 0.x 发布版本；固定一个确切的版本（例如 `@v0.6.0`）可实现完全可复现的 CI。 **输入参数**（均为可选）：`ecosystem`（默认为 `npm`），`lockfile`（根据生态系统默认），`base`（显式的基础 lockfile），`strict`（将 WARN 视为失败），`deep`（检查安装脚本），`version`（Guard 发布版本，默认为 `latest`），`fail-on-block`（默认为 `true`），`sarif-file`（写入用于 Code Scanning 的 SARIF），`args`（额外的原始标志）。 将结果上传至 **GitHub Code Scanning**，以便发现的问题能直接在 PR 中内联显示： ``` - uses: tiagosilva07/zyrax-guard@v0 with: sarif-file: zyrax-guard.sarif fail-on-block: "false" # let Code Scanning surface findings; don't hard-fail - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: zyrax-guard.sarif ``` （该作业需要 `permissions: { security-events: write }`。） ## 生态系统 Guard 支持 **npm, PyPI 和 crates.io**。使用 `--ecosystem` 进行选择（默认为 `npm`）： ``` zyrax-guard check --ecosystem pypi requests zyrax-guard check --ecosystem crates serde zyrax-guard scan --ecosystem crates # PR gate over Cargo.lock zyrax-guard scan --ecosystem pypi # PR gate over poetry.lock / requirements.txt ``` ## 检查工作原理 Guard 仅针对公开的注册表元数据运行 —— 不进行本地执行，不进行安装，不使用沙箱： | 检查项 | 判定触发条件 | |---|---| | **存在性** | 在注册表中找不到包 → **BLOCK**（幻觉包名或陷阱名称） | | **Typosquat (域名/包名误植)** | 包名与一个受欢迎得多的包仅相差一次编辑 且 下载量接近于零 → **BLOCK** 并附带“你是不是指”提示 | | **已知恶意** | 匹配到 OSV 公告 → 恶意软件 / 高危漏洞 → **BLOCK**；低危漏洞 → **WARN** | | **年龄与热度** | 发布时间 < 30 天 且 每周下载量 < 50 → **WARN** | | **Lockfile 完整性** | *(仅扫描)* 解析的 URL 或完整性哈希发生改变 → **BLOCK** | | **维护者变更** | *(仅扫描)* 由此前未见的维护者发布的新版本 → **WARN** | ## 深度检查 (`--deep`) 默认情况下，检查仅涉及元数据（几毫秒内完成）。添加 `--deep` 参数，也会下载包的分发制品，并**静态检查其在安装/构建时运行的代码** —— 包括 npm 的 `preinstall`/`install`/`postinstall` 脚本，PyPI 的 `setup.py`，以及 crates 的 `build.rs`： ``` zyrax-guard check --deep some-pkg zyrax-guard scan --deep # PR gate, deep mode ``` 它会标记可疑模式 —— 例如网络调用、进程生成、base64/混淆的 `eval` —— 并对危险的组合（例如“下载并运行脚本”）进行 **BLOCK**。它**不会执行任何代码**（纯静态分析），并尽**最大努力**进行检查：如果无法获取制品，你只会收到一条信息提示，绝不会发生误报拦截。 零额外依赖 —— 提取器仅使用标准库中的 `archive/tar` 和 `compress/gzip`。 ## 三种判定结果 | 判定 | 含义 | 默认退出码 | |---|---|---| | **SAFE** | 无值得关注的异常信号 | `0` | | **WARN** | 存在可疑之处 —— 继续操作前请进行审查 | `0` (使用 `--strict` 可使其变为 `1`) | | **BLOCK** | 强烈指示为恶意包或幻觉包 | `1` | ## 使其自动化 —— Shell 钩子 Shell 钩子会透明地拦截 `npm install` / `pip install` / `cargo add`。 每个新包都会在实际的安装程序运行前进行检查；已安装的包和非安装命令则会原样放行。 ### macOS / Linux (bash 或 zsh) 添加到 `~/.bashrc`、`~/.zshrc` 或 `~/.bash_profile`： ``` # 拦截 npm 安装（默认） eval "$(zyrax-guard init bash)" # 拦截 pip 安装 eval "$(zyrax-guard init bash pip)" # 拦截 cargo add eval "$(zyrax-guard init bash cargo)" ``` 无需重启终端即可立即应用： ``` source ~/.zshrc # or ~/.bashrc ``` ### Windows (PowerShell) 添加到你的 PowerShell 配置文件 (`$PROFILE`) 中。查找并打开它： ``` notepad $PROFILE # creates the file if it doesn't exist ``` 添加以下行并保存： ``` Invoke-Expression (zyrax-guard init powershell | Out-String) ``` 立即应用： ``` . $PROFILE ``` 从现在起，在 PowerShell 窗口中执行的每个 `npm install`、`pip install` 或 `cargo add`，都会在实际安装任何内容之前自动进行检查。 ## 与 AI 编程代理配合使用 AI 代理有时会产生幻觉并虚构包名。攻击者会预先注册这些名称并植入恶意软件。Guard 会在代理执行任何安装之前检查每个包，从而切断这种攻击链。 ### Claude Code CLI 将 Guard 注册为持久化的 MCP 工具，以便 Claude 自动检查包： ``` claude mcp add zyrax-guard -- zyrax-guard mcp ``` 就是这样。Claude Code 现在拥有一个 `check_package` 工具，它会在建议执行 `npm install` / `pip install` / `cargo add` 之前调用该工具。要启用深度安装脚本检查： ``` claude mcp add zyrax-guard -- zyrax-guard mcp ``` 然后在 Claude Code 会话中，Guard 的 `check_package` 工具可接受一个 `deep` 布尔值： ``` check_package(name="some-pkg", ecosystem="npm", deep=true) ``` 你也可以在 `CLAUDE.md` 中添加一条规则： ``` ## 依赖策略 Before installing any package, use the zyrax-guard MCP tool to check it. Never install a BLOCK result. Treat WARN as a prompt to confirm with the user. ``` ### Cursor 添加到项目根目录的 `.cursor/mcp.json` 中（或全局配置 `~/.cursor/mcp.json`）： ``` { "mcpServers": { "zyrax-guard": { "command": "zyrax-guard", "args": ["mcp"] } } } ``` 重启 Cursor。代理现在可以在安装任何内容之前访问并使用 `check_package`。 ### Windsurf 添加到 `.codeium/windsurf/mcp_config.json`： ``` { "mcpServers": { "zyrax-guard": { "command": "zyrax-guard", "args": ["mcp"], "description": "Check npm/PyPI/crates packages for malware and typosquats before installing" } } } ``` ### VS Code (GitHub Copilot / Copilot Chat) 添加到你的 VS Code `settings.json` 中： ``` { "github.copilot.chat.mcp.servers": { "zyrax-guard": { "command": "zyrax-guard", "args": ["mcp"] } } } ``` 或者添加到项目的 `.vscode/mcp.json` 中： ``` { "servers": { "zyrax-guard": { "type": "stdio", "command": "zyrax-guard", "args": ["mcp"] } } } ``` ### Continue.dev 添加到 `~/.continue/config.json`： ``` { "mcpServers": [ { "name": "zyrax-guard", "command": "zyrax-guard", "args": ["mcp"] } ] } ``` ### MCP 工具的工作原理 注册后，代理即可访问 `check_package`： ``` { "name": "check_package", "arguments": { "name": "lodahs", "ecosystem": "npm", "deep": false } } ``` 返回： ``` { "verdict": "BLOCK", "reasons": ["MAL-2025-25502: Malicious code in lodahs (npm)"], "didYouMean": "lodash" } ``` `BLOCK` 属于正常结果（而非 MCP 错误）—— 代理应当停止操作并告知用户，而不是继续执行安装。 ## 在 CI 中使用 ### GitHub Actions (PR 门禁) ``` # .github/workflows/guard.yml name: Dependency guard on: [pull_request] jobs: guard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } - uses: actions/setup-go@v5 with: { go-version: "1.26" } - run: go install github.com/tiagosilva07/zyrax-guard/cmd/zyrax-guard@latest - name: Guard new dependencies run: | git show "origin/${{ github.base_ref }}:package-lock.json" > /tmp/base-lock.json 2>/dev/null || echo '{"packages":{}}' > /tmp/base-lock.json zyrax-guard scan \ --base /tmp/base-lock.json \ --head package-lock.json \ --strict \ --sarif > guard.sarif - uses: github/codeql-action/upload-sarif@v3 if: always() with: { sarif_file: guard.sarif } ``` 它仅检查**新增或更改的**依赖（速度快，不会重复标记整个依赖树），如果出现任何 BLOCK 将使 PR 失败，并将结果上传至 GitHub Code Scanning。 ### 在 CI 中使用 PyPI ``` git show "origin/$BASE_REF:poetry.lock" > /tmp/base-lock.txt 2>/dev/null || echo "" > /tmp/base-lock.txt zyrax-guard scan --ecosystem pypi \ --base /tmp/base-lock.txt \ --head poetry.lock \ --sarif --strict > guard.sarif ``` ### 在 CI 中使用 crates.io ``` git show "origin/$BASE_REF:Cargo.lock" > /tmp/base-lock.txt 2>/dev/null || echo "" > /tmp/base-lock.txt zyrax-guard scan --ecosystem crates \ --base /tmp/base-lock.txt \ --head Cargo.lock \ --sarif --strict > guard.sarif ``` ## 隐私承诺 只有**你查询的公开包名**会离开你的机器，这是针对公开注册表 API 的只读查询： - `registry.npmjs.org` — 检查存在性和元数据 - `api.npmjs.org` — 查询下载量 - `api.osv.dev` — 查询已知的安全公告 没有遥测。无需账号。不会向任何地方发送密钥。二进制文件是可复现的 (`-trimpath`)，并且每个发布版本都提供 SLSA L3 来源证明，因此你可以自行验证构建链。 ## 免费且开源 Zyrax Guard 采用 **MIT 许可证且完全免费** —— 涵盖所有检查功能、PR 门禁、MCP server、Shell 钩子以及 JSON/SARIF 输出。你可以阅读源码并自行验证二进制文件。 面向团队的 **Zyrax 平台**（包含组织级策略、持续监控、仪表板和审计/合规报告）正在开发中。了解更多信息并加入抢先体验候补名单，请访问 **[zyrax.io](https://zyrax.io)**。 ## 路线图 | 阶段 | 项目 | |---|---| | **v1** | npm CLI + PR 门禁 + JSON/SARIF + 自我强化 — 已发布 | | **v1.1** | MCP server (`check_package`) + shell-hook (`zyrax-guard init`) — 已发布 | | **v1.2** | 跨越检查/安装/钩子/MCP/扫描的 PyPI + crates.io 支持 — 已发布 | | **v1.3** | 深度检查 (`--deep`)：静态安装/构建脚本分析 — 已发布 | | **v0.5.0** | 品牌重塑为 Zyrax；公开发布 — 已发布 | 路线图项目将通过现有的 `Ecosystem`、`ThreatIntel`、`Policy` 和 `Reporter` 拼接接口逐步加入 —— 无需重新设计架构。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：EVTX分析, Go, Google Gemini, Ruby工具, 依赖审查, 日志审计