dep-oracle

dep-oracle

预测性依赖项安全引擎

快速开始 · 功能 · 算法 · MCP · 对比

English | Turkce

---

你的依赖项也有自己的依赖项。谁在监视它们？

dep-oracle 是一款预测性依赖项安全引擎，可为依赖树中的每个包计算 信任分数（0-100）。它能检测僵尸依赖项、衡量影响范围、捕捉仿冒包名企图，并预测未来风险——在它们演变成漏洞之前。

Claude Code Security 扫描你的代码。dep-oracle 扫描代码所依赖的一切。

为什么？

• 自 2019 年以来，供应链攻击增加了 742%（Sonatype 2024 年报告）
• 一个 npm 项目平均会引入 数百个传递依赖项——其中任何一个都可能遭到入侵
• npm audit 只能发现 已知 CVE；dep-oracle 则能 预测未来风险
• 你会审计自己的代码。但你会审计自己的 信任对象 吗？

快速开始

# Zero install — just run it
npx dep-oracle

# Or install globally
npm install -g dep-oracle
dep-oracle scan

# Check a single package
dep-oracle check express

功能

功能	描述
信任分数	为每个包计算 0-100 的加权分数（安全性、维护者状况、活跃度、受欢迎程度、资金支持、许可证）
僵尸检测	找出无人维护但至关重要的包（12 个月以上没有提交记录）
影响范围	显示依赖项遭到入侵时会影响多少个文件
仿冒包名检测	利用 1,847+ 个已知包和实时 npm Registry 查询，捕捉可疑名称
趋势预测	根据下载量、提交记录和发布趋势预测未来 3 个月的风险
迁移建议	提供 131 个包映射，包含 192 个更安全的替代方案，可用于替换有风险的依赖项
离线模式	无需互联网即可从缓存运行（--offline）
MCP 服务	原生集成 Claude Code——用自然语言询问依赖项相关问题
多格式输出	终端（彩色树状图）、HTML、JSON 和 SARIF
GitHub Action	在 CI/CD 工作流中自动执行信任检查

用法

# Scan current project
dep-oracle scan

# Scan with specific output format
dep-oracle scan --format json
dep-oracle scan --format html
dep-oracle scan --format sarif

# Check a single package
dep-oracle check lodash
dep-oracle check [email protected]

# Offline mode (uses cached data only)
dep-oracle scan --offline

# Set minimum score threshold (exit code 1 if below)
dep-oracle scan --threshold 60

# Ignore specific packages
dep-oracle scan --ignore deprecated-but-needed,legacy-pkg

# Verbose logging
dep-oracle scan --verbose

输出示例

dep-oracle v1.2.0
Scanning package.json...
Found 47 direct dependencies, 683 transitive
Collecting data... [=============================] 100% (2.3s)

DEPENDENCY TRUST REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  CRITICAL (score < 50)

  ■ [email protected]         Score: 12  ZOMBIE
    Last commit: 2018 | 0 maintainers active
    Blast radius: 14 files | Alternative: highland

  WARNING (score 50-79)

  ■ [email protected]              Score: 58  ZOMBIE
    Maintenance mode | No new features
    Blast radius: 23 files | Alternative: dayjs, date-fns, luxon

  SAFE (score 80+): 679 packages

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SUMMARY
  Overall Trust Score: 74/100
  Critical: 2 | Warning: 3 | Safe: 679
  Zombies: 2 | Deprecated: 1

信任评分算法

每个包都会基于六项加权指标获得 0–100 分：

指标	权重	衡量内容
安全历史	25%	CVE 数量（惩罚逐渐递减）、平均修复时间、快速修复奖励
维护者健康状况	25%	活跃维护者数量（关键人员风险）、问题响应时间、PR 合并速度
活跃度	20%	提交频率趋势、发布节奏、最近一次发布时间
热度	15%	每周下载量、依赖者数量、GitHub 星标数
资金支持	10%	GitHub Sponsors、OpenCollective、企业支持
许可证	5%	MIT/Apache = 安全，GPL = 风险，未知 = 危险信号

评分范围： 80–100 安全 | 50–79 警告 | 0–49 严重

安全评分

安全指标采用递减惩罚模型——首个漏洞的影响最大，之后每增加一个漏洞，影响都会逐渐减小：

漏洞数量	安全评分
0	100
1	85
2	72
3	60
4	50
5+	max(20, 100 - n*12)

在 7 天内快速修复漏洞的包会获得 +10 奖励。在 30 天内修复的较慢补丁会获得 +5。

优雅降级

如果 API 无法访问（GitHub 宕机、没有互联网、触发速率限制），dep-oracle 不会崩溃。缺失指标的权重会重新分配给可用指标。如果有 3 项或更多指标不可用，则会显示可靠性警告。

影响范围的计算方法

影响范围指标统计有多少源文件直接导入了某个依赖项：

1. 递归收集所有 .js、.ts、.jsx、.tsx、.mjs、.mts、.cjs、.cts 文件
2. 跳过 node_modules、.git、dist、build、coverage 和其他构建目录
3. 搜索每个文件中的 import ... from 'pkg'、require('pkg') 和动态 import('pkg') 模式
4. 报告数量、文件路径，以及受影响代码库的百分比

当前限制：

• 仅扫描 JavaScript/TypeScript 导入模式
• 尚未分析 Python import 语句（仅包含 Python 的项目，其影响范围为 0）
• 不追踪重新导出或汇总文件——仅统计直接导入

权重依据

权重基于以下原则：安全漏洞和维护者弃用是供应链风险最强的预测因素，其次是开发活跃度信号。权重可通过 .dep-oraclerc.json 完全配置——企业团队可根据自身的风险容忍度进行调整。

当某项指标的数据不可用时，评分会根据缺失权重的比例向中点（50）靠拢，以防因数据缺失而人为抬高评分。

拼写仿冒检测

dep-oracle 采用多层方法来检测拼写仿冒：

1. 静态注册表——包含 40 多个类别（React、Vue、Angular、Express、测试、CLI 工具等）中 1,847 个以上的知名包名
2. 动态 npm 查询——从 npm 获取下载量最高的 5,000 个包，并缓存 7 天
3. 模式匹配——Levenshtein 距离、前缀/后缀篡改、字符交换、缺失/多余字母检测

dep-oracle check expresss    # Catches: similar to "express" (distance: 1)
dep-oracle check lodashe     # Catches: similar to "lodash" (distance: 1)
dep-oracle check react-js    # Catches: suffix pattern of "react"

迁移顾问

当某个包评分较低或被标记为僵尸包时，dep-oracle 会从精选数据库中推荐更安全的替代方案。该数据库包含 131 个包映射和 192 个替代方案：

moment     → dayjs, date-fns, luxon
request    → axios, got, node-fetch, undici
lodash     → lodash-es, radash, just (native alternatives)
express    → fastify, koa, hono
gulp       → esbuild, tsup, vite
mocha      → vitest, jest, node:test
...and 125 more

每条建议都包含难度评级（简单/中等/困难）和迁移背景说明。

Claude Code 集成（MCP）

dep-oracle 已列入官方 MCP Registry，并可作为 Claude Code 的 MCP 服务运行：

// .claude/settings.json
{
  "mcpServers": {
    "dep-oracle": {
      "command": "npx",
      "args": ["dep-oracle", "mcp"]
    }
  }
}

然后在 Claude Code 中，只需询问：

• “这个项目中风险最高的依赖是什么？”
• “lodash 是否可以安全使用？”
• “显示僵尸依赖”
• “为 moment.js 推荐替代方案”

可用的 MCP 工具：

工具	描述
dep_oracle_scan	扫描项目的所有依赖
dep_oracle_trust_score	单个包的信任评分
dep_oracle_blast_radius	分析某个包的影响范围
dep_oracle_zombies	列出所有僵尸依赖
dep_oracle_suggest_migration	获取替代包建议
dep_oracle_typosquat_check	检查包名的拼写抢注风险
dep_oracle_compare	并排比较两个包
dep_oracle_report	生成 JSON 报告，可选择写入文件

GitHub Action

name: Dependency Trust Check
on: [pull_request]

jobs:
  dep-oracle:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Run dep-oracle
        run: npx dep-oracle scan --format sarif --min-score 60
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

配置

在项目根目录创建 .dep-oraclerc.json：

{
  "threshold": 60,
  "ignore": ["known-risky-but-needed"],
  "format": "terminal",
  "offline": false,
  "githubToken": "$GITHUB_TOKEN",
  "cacheTtl": 86400
}

或添加到 package.json：

{
  "dep-oracle": {
    "threshold": 60,
    "ignore": []
  }
}

配置选项

选项	默认值	描述
threshold	60	最低信任评分。低于此分数的包会触发警告，并返回非零退出码
ignore	[]	扫描时跳过的包
format	"terminal"	输出格式：terminal、json、html、sarif
offline	false	仅使用缓存数据，跳过所有 API 调用
githubToken	null	用于提高 API 速率限制的 GitHub 令牌（每小时 5000 次，而非 60 次）
cacheTtl	86400	缓存 TTL（秒），默认：24 小时

支持的包管理器

管理器	清单文件	锁定文件	状态
npm	package.json	package-lock.json	支持
yarn	package.json	yarn.lock	支持
pnpm	package.json	pnpm-lock.yaml	支持
pip	requirements.txt	Pipfile.lock	支持
poetry	pyproject.toml	poetry.lock	支持

对比

功能	npm audit	Dependabot	Socket.dev	Snyk	dep-oracle
已知 CVE 扫描	是	是	是	是	是
预测性风险	否	否	部分支持	部分支持	是
信任评分（0-100）	否	否	否	否	是
僵尸检测	否	否	否	否	是
影响范围	否	部分支持	否	否	是
拼写抢注检测	否	否	是	否	是
趋势预测	否	否	否	否	是
迁移顾问	否	部分支持	否	部分支持	是（131 个包）
MCP 集成	否	否	否	否	是
零安装（npx）	是	否	否	否	是
免费且开源	是	是	免费增值	免费增值	是

注意：在企业环境中，dep-oracle 不能替代 Snyk 或 Socket.dev。它们拥有专门的安全研究团队和 CVE 数据库。dep-oracle 专注于预测性信号（信任评分、维护状况、资金支持、僵尸检测），可与现有工具互补。

编程 API

import { scan, checkPackage } from 'dep-oracle';

// Scan a project
const report = await scan({ dir: './my-project', format: 'json' });

// Check a single package
const result = await checkPackage('express');
console.log(result.trustScore); // 74
console.log(result.isZombie);   // false

测试套件

dep-oracle 拥有全面的测试覆盖：

10 test files | 144 tests | 100% passing

  trust-score.test.ts     34 tests   Scoring engine, metrics, edge cases
  zombie-detector.test.ts 10 tests   Zombie detection logic
  typosquat.test.ts       15 tests   Typosquat pattern matching
  migration-advisor.test.ts 12 tests Migration suggestions
  trend-predictor.test.ts 10 tests   Trend prediction engine
  parsers.test.ts         17 tests   npm + Python parsers
  cache.test.ts           15 tests   Cache store operations
  logger.test.ts          17 tests   Logger utility
  rate-limiter.test.ts    6 tests    Rate limiter
  schema.test.ts          8 tests    Zod schema validation

npm test          # Run all tests
npm run lint      # TypeScript type checking

更新日志

v1.2.0（2026-02-22）

• 安全性：MCP 工具中的路径遍历防护（验证目录／输出路径）
• 安全性：包名验证（强制遵循 npm 命名规则）
• 安全性：转义 HTML 报告器的指标值（纵深防御 XSS）
• 安全性：在 URL 解析器中验证 GitHub 用户名／仓库名
• 安全性：在资助信息收集器中验证 GitHub Sponsors 用户名
• 功能：程序化 API — import { scan, checkPackage } from 'dep-oracle'
• 功能：新增 3 个 MCP 工具：dep_oracle_typosquat_check、dep_oracle_compare、dep_oracle_report（共 8 个）
• 功能：GitHub Action 现可正常构建（独立打包）
• 修复：收集器超时（30s），防止因 API 缓慢而卡住
• 修复：信任评分权重验证（总和必须为 1.0）
• 修复：仅在存在漏洞时应用补丁加分
• 修复：Python 解析器会保留 Git URL 中的 #egg= 片段
• 修复：拼写相似包检测现可捕获 2 个字符的替换
• 修复：缓存错误处理会区分 JSON 损坏和 I/O 错误
• 修复：现已将 server.json 纳入 npm 包，供 MCP 注册表使用

v1.1.4（2026-02-22）

• Package.json 修复：移除无效的 readme 字段，该字段会导致 npm 显示字面字符串而非 README 内容

v1.1.3（2026-02-22）

• npm README 修复：npmjs.com 现可正确显示英文 README（通过 prepack/postpack 生命周期钩子，将土耳其语 README 排除在 npm 包之外）

v1.1.2（2026-02-22）

• MCP 注册表链接：更新为官方文档 URL

v1.1.1（2026-02-22）

• MCP 注册表：已作为 io.github.ertugrulakben/dep-oracle 列入官方 MCP 注册表
• 动态版本管理：MCP 服务和 SARIF 报告器现从 package.json 读取版本（不再硬编码版本）

v1.1.0（2026-02-22）

• 拼写相似包检测：扩展至 1,847+ 个已知包，涵盖 40+ 个类别，并支持动态获取 npm 注册表数据（前 5,000 个包，缓存 7 天）
• 迁移建议器：扩展至 131 个包映射，提供 192 个更安全的替代方案
• 信任评分校准：采用递减式漏洞惩罚（首个 CVE 影响最大），快速修复加分（<=7 天加 10 分）
• Poetry.lock 支持：全面支持解析 Python 项目的 poetry.lock
• 全面测试套件：10 个测试文件，144 项测试，覆盖所有分析器、解析器、缓存和实用工具
• 土耳其语 README：提供完整的土耳其语文档（README.tr.md）
• 动态 CLI 版本：版本会自动与 package.json 同步

v1.0.0（2026-02-22）

• 首次发布
• 信任评分引擎，包含 6 项加权指标
• npm + Python（pip、poetry、pyproject.toml）解析器
• 僵尸包检测、影响范围分析
• 基于 Levenshtein 距离的拼写相似包检测
• 趋势预测（3 个月风险预测）
• 提供精选替代方案的迁移建议器
• 终端、HTML、JSON、SARIF 输出格式
• 用于集成 Claude Code 的 MCP 服务
• 支持 GitHub Action
• 支持离线模式，使用兼容 SQLite 的缓存
• 徽章生成器（SVG）

贡献

请参阅 CONTRIBUTING.md，了解开发环境设置、编码标准，以及如何添加新的收集器、解析器或分析器。

许可证

MIT — Ertugrul Akben