CodeAbbas/osv-depguard

# OSV-DepGuard 🛡️ [](https://www.npmjs.com/package/osv-depguard) [](https://www.npmjs.com/package/osv-depguard) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) **OSV-DepGuard** 是一个 CLI 工具，它将你的 `package-lock.json` 与 [OSV.dev](https://osv.dev)（谷歌的开源漏洞数据库）进行比对，以查找你确切安装版本中的已知 CVE。找到的任何漏洞随后将传递给 Claude AI，它会为每个漏洞生成一份平实的英文摘要和具体的修复命令——没有幻觉，没有虚构数据。 ``` npm install -g osv-depguard ``` ## 工作原理 | 层级 | 工具 | 角色 | |---|---|---| | **扫描器** | OSV.dev (谷歌) | 100% 确定性 CVE 查找 — 没有幻觉 | | **源** | `package-lock.json` | 确切的安装版本，不是 semver 范围 | | **AI** | Claude (Anthropic) | 将 OSV 数据解释为平实的英文 + 修复命令 | | **UI** | chalk + cli-table3 | 带颜色的终端表格 | ``` package-lock.json │ ▼ exact installed versions OSV.dev /v1/querybatch ──► real CVE data, zero hallucination │ ▼ (if vulns found) Anthropic API ──────────► plain English summary + remediation (no web search — interprets OSV data only, cannot fabricate vulns) │ ▼ cli-table3 + chalk ─────► colour-coded terminal table ``` ## 要求 - Node.js >= 18.0.0 - npm >= 7（用于 lockfileVersion 2/3 支持） - 一个 Anthropic API 密钥 — [在此获取一个](https://console.anthropic.com/) ## 安装 ### 全局安装（推荐 — 在任何项目中作为 CLI 使用） ``` npm install -g osv-depguard ``` 验证是否正确安装： ``` osv-depguard --version ``` ### 本地安装（每个项目，或通过 npx 运行） ``` # 在您的项目中安装为开发依赖 npm install --save-dev osv-depguard # 通过 npx 运行，无需安装 npx osv-depguard ``` ### 本地开发（克隆并从源运行） ``` # 1. 克隆仓库 git clone https://github.com/CodeAbbas/osv-depguard.git cd osv-depguard # 2. 安装依赖 npm install # 3. 设置您的 API 密钥（见下文设置部分） # 4. 直接从源运行 node depguard.js # 5. 或将其链接到全局，使 osv-depguard 命令在任何地方都能使用 npm link osv-depguard ``` ## 设置 ### 1. 获取一个 Anthropic API 密钥 在 [console.anthropic.com](https://console.anthropic.com/) 上注册并创建一个 API 密钥。 ### 2. 将其添加到项目根目录下的 `.env` 文件中 ``` echo "ANTHROPIC_API_KEY=sk-ant-..." > .env ``` 或手动创建文件： ``` ANTHROPIC_API_KEY=sk-ant-... ``` ### 3. 立即将其添加到 `.gitignore` 中 ``` echo ".env" >> .gitignore ``` 仓库中包含一个安全的 `.env.example` 模板 — 将其复制作为起点： ``` cp .env.example .env # 然后填写您的真实密钥 ``` ## 使用 从包含 `package-lock.json` 的任何目录运行： ``` # 扫描当前目录 osv-depguard # 扫描特定项目目录 osv-depguard ~/projects/my-app # 跳过 devDependencies osv-depguard --no-dev # 仅显示 HIGH 和 CRITICAL 漏洞 osv-depguard --min-severity high # 仅显示 CRITICAL 漏洞 osv-depguard --min-severity critical # 输出原始 JSON（适用于 CI 管道和脚本） osv-depguard --json # 显示版本 osv-depguard --version # 显示帮助 osv-depguard --help ``` ### 严重程度级别 | 级别 | 颜色 | 描述 | |---|---|---| | `CRITICAL` | 红色背景 | 立即采取行动 | | `HIGH` | 红色 | 尽快升级 | | `MEDIUM` | 黄色 | 规划升级 | | `LOW` | 蓝色 | 监控并在常规更新中修补 | ## CI 集成 使用 `--json` 标志将 OSV-DepGuard 集成到 CI 管道中： ``` # 列出所有易受攻击的包名 osv-depguard --json | jq '.[].package' # 按严重程度分组获取计数 osv-depguard --json | jq 'group_by(.severity) | map({severity: .[0].severity, count: length})' ``` ### 退出代码 | 代码 | 含义 | |---|---| | `0` | 扫描成功完成（检查 JSON 输出以获取漏洞） | | `1` | 扫描失败 — 缺少锁文件、API 错误或无效配置 | ## 安全注意事项 - 永远不要将 API 密钥硬编码 — 总是使用 `.env` 通过 dotenv。 - 在第一次提交之前，始终将 `.env` 添加到 `.gitignore` 中。 - OSV.dev 是一个公共 API — 无需密钥。仅发送包名和确切版本。 - AI 没有网络搜索权限 — 它只解释经过验证的 OSV 数据，因此它不能虚构漏洞。 ## 项目结构 ``` depguard.js # thin executable entry point src/ cli.js # argument parsing + pipeline orchestration lockfile.js # package-lock.json discovery, loading, extraction osv.js # OSV.dev querying + vulnerability list building severity.js # severity extraction, ranking, colouring ai.js # Anthropic enrichment + merge renderer.js # table, summary, advisory-link rendering gitignore.js # .env safety check constants.js # shared constants utils.js # safe JSON parsing + validation helpers logger.js # standardized logging tests/ # vitest unit tests ``` ## 开发 ``` npm test # run the test suite npm run test:watch # watch mode npm run coverage # run with a coverage report (≥80% enforced) ``` 网络和 AI 调用接受可注入的 `fetch`，因此 `osv.js` 和 `ai.js` 可以在不接触真实端点的情况下进行单元测试。 ## 贡献 欢迎贡献、问题和功能请求。 1. 分叉仓库 2. 创建一个功能分支：`git checkout -b feat/your-feature` 3. 提交你的更改：`git commit -m 'feat: add your feature'` 4. 推送到分支：`git push origin feat/your-feature` 5. 提交一个 Pull Request ## 许可证 [MIT](https://opensource.org/licenses/MIT) © [Abbas Uddin](https://github.com/CodeAbbas)

标签：AI安全, AI辅助安全, Anthropic API, Chat Copilot, Claude, CVE检测, MITM代理, Node.js安全, npm漏洞扫描, OSV.dev, 安全漏洞数据库, 开源漏洞数据库, 漏洞修复, 终端用户界面, 网络安全培训, 自定义脚本, 软件依赖管理