barestripehq/primer

# primer 为包管理器提供预安装安全拦截器。在软件包进入你的系统之前，针对 [OSV 漏洞数据库](https://osv.dev/) 对其进行扫描——支持可选的本地 AI 摘要、git hook 集成以及 CI 模式。 ## 工作原理 primer 会在 `$PATH` 中你的包管理器之前放置轻量级的 shim。当你运行 `pip install requests` 时，该 shim 会拦截命令，查询 OSV，然后要么静默放行（结果安全），要么在执行前提示你。 ``` pip install pillow → primer shim intercepts → queries OSV → found 3 vulnerabilities (1 CRITICAL, 2 HIGH) pillow 9.0.0 — GHSA-56pw-mpj4-fxjw [CRITICAL] Summary: Heap buffer overflow in TIFF image parser Fixed in: 9.0.1 → [prompt] View full details? (y/N) → [prompt] Continue install anyway? (y/N) → exits 1 on "N" ``` ✓ requests: 发现 0 个漏洞 — 静默放行（在首次缓存查询之后）。 ## 支持的生态系统 | 生态系统 | 拦截的命令 | 清单 / Lockfile | |-----------|---------------------|---------------------| | Python | `pip`, `uv`, `poetry` | `requirements.txt`, `pyproject.toml`, `uv.lock`, `poetry.lock` | | Node.js | `npm`, `yarn`, `pnpm` | `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` | | Go | `go get`, `go mod` | `go.mod`, `go.sum` | | Rust | `cargo add`, `cargo build`, `cargo fetch`, `cargo check` | `Cargo.toml`, `Cargo.lock` | ## 安装 **macOS / Linux** ``` curl --proto '=https' --tlsv1.2 -fsSL https://github.com/barestripehq/primer/releases/latest/download/primer-installer.sh | sh primer init ``` `primer init` 会在 `~/.primer/bin` 中创建 shim，并将其添加到你的 shell 配置文件（zsh 对应 `.zshenv`，bash 对应 `.bashrc`，fish 对应 fish 函数）的顶部。重启你的 shell 或 `source` 该配置文件。 **Windows** 从 [最新发布版本](https://github.com/barestripehq/primer/releases/latest) 下载 MSI 安装程序，然后在一个新终端中运行： ``` primer init ``` `primer init` 会在 `%USERPROFILE%\.primer\bin` 中创建 `.cmd` 包装器，通过 `SETX` 更新用户 PATH，并注入到你的 PowerShell 7 配置文件中。打开一个新终端以使更改生效。 **从源码构建：** ``` cargo install --git https://github.com/barestripehq/primer primer init ``` ## 命令 ### 扫描 ``` # 手动扫描任意 package primer scan requests --ecosystem pypi primer scan express --ecosystem npm primer scan github.com/gin-gonic/gin --ecosystem go primer scan serde --ecosystem cargo # 固定 version primer scan pillow --ecosystem pypi --version 9.0.0 # 跳过提示（无论如何都继续） primer scan pillow --ecosystem pypi --force # 显示 cache 命中/未命中 primer scan requests --ecosystem pypi --verbose # 包含 AI 生成的摘要（需要 primer model add） primer scan pillow --ecosystem pypi --ai # 扫描 manifest 文件中声明的所有 package（不安装） primer scan --file requirements.txt primer scan --file package.json primer scan --file go.mod primer scan --file Cargo.toml # 直接扫描 lockfile — 解析每个 transitive dep 的确切固定 version primer scan --file package-lock.json primer scan --file yarn.lock primer scan --file Cargo.lock # 跳过 transitive dependencies（仅限直接 package） primer scan --file package.json --direct-only # 输出 SARIF 2.1.0 用于 GitHub Security 标签页上传 primer scan --file requirements.txt --format sarif primer scan --file package-lock.json --format sarif --output results.sarif ``` 当 OSV 提供修补版本时，每条发现结果都会显示该版本： ``` pillow 9.0.0 — GHSA-56pw-mpj4-fxjw [CRITICAL] Summary: Heap buffer overflow in TIFF image parser Fixed in: 9.0.1 ``` ### 传递依赖扫描 默认情况下，primer 会扫描整个依赖树——不仅是你指定的包，还包括它拉取的所有内容。 **显式安装**（`npm install express`、`cargo add serde`）：primer 会首先扫描指定的包（安装前），然后在 PM 运行后对 lockfile 进行 diff 操作，并扫描任何新添加的传递依赖包。安装后的发现结果包含移除提示，因为该包已经在磁盘上了。 **纯还原**（`npm install`、`go mod download`）：当启用了 `intercept-restore` 且清单旁边存在 lockfile 时，primer 会在 PM 运行之前加载它，以解析直接包和传递包的确切版本。标题中会显示划分情况： ``` primer: scanning package.json — 3 direct + 47 transitive packages ``` **选择退出** —— 当你需要低噪音的结果时，跳过传递扫描： ``` # 按命令 primer scan --file package.json --direct-only # 全局（写入 ~/.primer/config.toml） primer config set direct-only true ``` 传递扫描始终以状态行结束： ``` primer: scanning 4 new transitive packages … ✓ transitive scan complete — found 0 vulnerabilities. ``` ### 审计现有漏洞 shim 会拦截新的安装。要揭示项目中已有的漏洞，请直接扫描清单或 lockfile： ``` primer scan --file package-lock.json # full resolved tree (recommended) primer scan --file package.json # declared dependencies only primer scan --file requirements.txt primer scan --file Cargo.toml ``` 对于每个易受攻击的包，primer 会显示 CVE 详细信息和一条可直接运行的修复命令： ``` ⚠ lodash 4.17.15 (npm) — 6 vulnerabilities [HIGH] GHSA-35jh-r3h4-6jhm — Command Injection Fixed in: 4.17.21 Fix: npm install lodash@4.17.21 … ``` Primer 会打印修复命令，但不会修改你的清单——由你来运行它，而 shim 会在新版本进入时进行拦截控制。 ### 目录监视器 每当清单文件发生更改时自动扫描——对于长时间运行的开发会话非常有用： ``` primer watch # watch current directory primer watch --directory /project # watch a specific path primer watch --scan # also scan immediately on startup ``` 监视：`requirements.txt`、`pyproject.toml`、`package.json`、`go.mod`、`Cargo.toml`。防抖延迟为 500 毫秒。使用 `Ctrl+C` 退出。 ### 策略文件 `.primer/policy.toml` 会提交到仓库中，并在每台开发机器和 CI 中自动执行——无需任何标志。它与 `~/.primer/config.toml`（机器范围设置）是分开的。 ``` # .primer/policy.toml [policy] threshold = "high" # optional global override for this repo [[deny]] package = "event-stream" # hard block by name regardless of CVE status reason = "supply chain compromise" [[ignore]] cve = "CVE-2023-1234" package = "pillow" # optional: scope to one package expires = "2026-12-31" # YYYY-MM-DD; finding re-activates after this date reason = "Mitigated by WAF" [[override]] package = "requests" threshold = "critical" # per-package threshold ``` 评估顺序：`[[deny]]` → `[[ignore]]`（检查过期时间）→ `[[override]]` → `[policy].threshold`。 ``` primer policy list # show all rules and expiry status primer policy check # validate syntax without scanning ``` ### 严重性阈值 控制哪个严重级别触发提示或 CI 拦截： ``` primer config set prompt-threshold medium # block MEDIUM, HIGH, CRITICAL primer config set prompt-threshold critical # block CRITICAL only primer config set prompt-threshold high # default ``` ### SBOM 生成 为任何清单或 lockfile 生成软件物料清单 (SBOM)： ``` primer sbom --file requirements.txt # CycloneDX JSON to stdout primer sbom --file package-lock.json # from lockfile (exact versions) primer sbom --file Cargo.toml --output sbom.json # write to file primer sbom --file package.json --format spdx # SPDX 2.3 JSON primer sbom --file go.mod --no-scan # inventory only, no OSV queries ``` ### AI 智能体集成 (MCP) `primer mcp` 通过 stdio 启动一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，暴露出一个 `scan_package` 工具，任何支持 MCP 的智能体（Claude Code、Cursor、Cline 等）都可以在决定安装包之前调用它。 在你的项目根目录添加一个 `.mcp.json`（对于 Claude Code 则为 `~/.claude/mcp.json`）： ``` { "mcpServers": { "primer": { "command": "primer", "args": ["mcp"] } } } ``` 然后该智能体可以调用： ``` scan_package("pillow", "PyPI", "9.0.0") → ⚠ pillow 9.0.0 (PyPI) — found 2 vulnerabilities: [HIGH] GHSA-xxxx-yyyy-zzzz — Buffer overflow in TIFF decoder (Fixed in: 9.1.0) [MEDIUM] GHSA-aaaa-bbbb-cccc — … ``` 该工具会返回结构化的 JSON（`vulnerabilities[]`、`summary.blocking`），以便智能体决定是否继续。OSV 缓存同样适用——重复查找是即时的。 ### 安装与卸载 ``` primer init # create shims, update PATH primer uninit # remove shims, strip PATH entry primer uninit --purge # also delete cache and model files primer doctor # check PATH order, shim health, cache state, model state primer migrate # move .primer-ignore / .primer-policy.toml into .primer/ ``` ### 白名单 将包添加到 `.primer/ignore`（或针对旧仓库的 `.primer-ignore`）以跳过扫描，而无需使用 `--force`： ``` primer allow add pillow primer allow add pillow --ecosystem pypi # scope to one ecosystem ``` ### 缓存 ``` primer cache clear # remove all cached OSV results ``` 结果会缓存在 `~/.primer/cache/` 中，TTL 为 24 小时。在网络失败时，将使用最近一次缓存的结果（错误时回退旧数据机制）。 ### AI 模型 ``` # 下载默认 model（约 80 MB，无需账号） primer model add # 导入本地 GGUF 文件 primer model add --from /path/to/model.gguf --tokenizer /path/to/tokenizer.json # 从 HuggingFace Hub 下载特定 model primer model add --repo --file # 列出已注册的 model（* = 激活） primer model list # 设置激活的推理目标 primer model set ~/.primer/models/smollm2.gguf # local candle inference primer model set ollama:llama3.2 # route to local Ollama instance # 移除 model primer model remove # interactive select primer model remove smollm2.gguf ollama:llama3.2 # remove by name (no prompt) primer model remove --all # remove all, clear config ``` 一旦配置了模型，在任意 `scan` 命令中传入 `--ai`，即可在决策提示之前获取一份通俗易懂的英文 CVE 摘要。 设置 `PRIMER_AI=0` 可完全禁用 AI（在 CI 流水线中非常有用）。 ### Git hook 阻止那些向清单中添加易受攻击包的提交： ``` # 在当前 repo 中安装 pre-commit hook primer hook install # 手动运行检查而不提交 primer hook check ``` 监视的清单：`requirements.txt`、`pyproject.toml`、`package.json`、`go.mod`、`Cargo.toml`。 ### 拦截纯还原命令 默认情况下，纯还原命令（不带包参数的 `npm install`、`go mod download` 等）会直接放行。启用拦截以在安装依赖项之前扫描清单： ``` primer config set intercept-restore true ``` 启用后，primer 会在放行之前，针对每个 PM 的“安装全部”形式扫描相关清单。如果存在 lockfile，primer 会加载它以包含确切锁定版本的传递包： | 命令 | 扫描的清单 | Lockfile（如存在） | |---------|-----------------|----------------------| | `npm install` / `pnpm install` / `yarn` | `package.json` | `package-lock.json`, `yarn.lock`, 或 `pnpm-lock.yaml` | | `pip install`（无包参数） / `uv sync` | `requirements.txt` → `pyproject.toml` | `uv.lock`, `poetry.lock` | | `poetry install` | `pyproject.toml` | `poetry.lock`, `uv.lock` | | `go mod download` | `go.mod` | `go.sum` | | `cargo build` / `cargo fetch` / `cargo check` | `Cargo.toml` | `Cargo.lock` | 默认禁用 —— 大型项目可能会有很多依赖项。缓存使得重复扫描瞬间完成。使用 `--direct-only`（或 `primer config set direct-only true`）以跳过传递包。 ## CI / 非交互模式 当设置了 `CI=true`（在 GitHub Actions、CircleCI 等平台上的标准做法）或 stdin 不是 TTY 时，primer 会自动切换到非交互模式： - 无提示 —— 将合并后的发现结果表打印到 stderr - 遇到严重和高危发现结果时拦截（退出代码 `1`） - 将所有发现结果写入工作目录下的 `primer-report.json` 中 使用 `PRIMER_CI_MODE=allow-all` 覆盖该设置以禁用拦截（仅用于审计的流水线）。 ### GitHub Actions 使用 `barestripehq/primer-action@v1` —— 它会安装 primer，扫描清单，将 SARIF 上传到 GitHub Security 选项卡，并仅需一步即可发布 PR 评论： ``` permissions: security-events: write # SARIF upload pull-requests: write # PR comments actions: read contents: read steps: - uses: actions/checkout@v6 - uses: barestripehq/primer-action@v1 with: file: package-lock.json ``` 有关所有输入和示例，请参阅 [集成文档](https://primer.barestripe.com/integrations/)。 ### 其他 CI 系统 (CircleCI, GitLab CI, Jenkins) 通过安装脚本安装 primer，并调用 `--format sarif` 来输出 SARIF 2.1.0： ``` - name: Install primer run: curl --proto '=https' --tlsv1.2 -fsSL https://github.com/barestripehq/primer/releases/latest/download/primer-installer.sh | sh - name: Scan dependencies run: primer scan --file package-lock.json --format sarif --output results.sarif ``` ## 诊断 ``` primer doctor ``` 报告内容： - `~/.primer/bin` 是否在 `$PATH` 中正确地排列在版本管理器（`nvm`、`pyenv`、`asdf`、`volta`）之前 - 每个 shim 及其真实二进制文件的解析路径 - 缓存条目数量和总大小 - `intercept-restore` 配置状态及启用提示 - 激活的 AI 模型路径及文件大小 ## 卸载 ``` primer uninit --purge ``` 移除 shim，从你的 shell 配置中剔除 `$PATH` 条目，并删除 `~/.primer/`（缓存、模型、配置）。 ## 许可证 MIT

标签：DevSecOps, LLM防护, 上游代理, 依赖扫描, 包管理器, 可视化界面, 实时告警, 开发安全, 模型提供商, 统一API, 通知系统