dep-oracle

dep-oracle

予測型依存関係セキュリティエンジン

クイックスタート · 機能 · アルゴリズム · MCP · 比較

英語 | トルコ語

---

依存関係にも依存関係があります。それを見守っているのは誰ですか？

dep-oracle は、依存関係ツリー内のすべてのパッケージの信頼スコア（0～100）を算出する、予測型の依存関係セキュリティエンジンです。ゾンビ依存関係を検出し、影響範囲を測定し、タイポスクワッティングの試みを見つけ、将来のリスクを脆弱性になる前に予測します。

Claude Code Security はあなたのコードをスキャンします。dep-oracle は、あなたのコードが依存しているすべてのものをスキャンします。

なぜ必要なのか？

• サプライチェーン攻撃は2019年以降、742%増加しています（Sonatype 2024 Report）
• 平均的な 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 レジストリのリアルタイム照会で、不審な名前を検出
傾向予測	ダウンロード数、コミット数、リリース数の傾向に基づく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

信頼スコアアルゴリズム

各パッケージは、重み付けされた6つの指標に基づいて0〜100点で評価されます。

指標	重み	測定内容
セキュリティ履歴	25%	CVE件数（減衰するペナルティ）、平均修正時間、迅速な修正によるボーナス
メンテナーの健全性	25%	アクティブなメンテナー（バス係数）、問題への応答時間、PRのマージ速度
活動状況	20%	コミット頻度の傾向、リリース間隔、最終公開からの経過期間
人気度	15%	週間ダウンロード数、依存パッケージ数、GitHubスター数
資金調達	10%	GitHub Sponsors、OpenCollective、企業による支援
ライセンス	5%	MIT/Apache = 安全、GPL = リスク、Unknown = 危険信号

スコア範囲： 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. パターン照合 — レーベンシュタイン距離、接頭辞／接尾辞の変更、文字の入れ替え、文字の欠落／追加の検出

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	2 つのパッケージを並べて比較します
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	最小信頼スコアです。この値を下回るパッケージがあると警告が表示され、終了コードが 0 以外になります
ignore	[]	スキャン対象から除外するパッケージです
format	"terminal"	出力形式：terminal、json、html、sarif
offline	false	キャッシュデータのみを使用し、すべての API 呼び出しをスキップします
githubToken	null	API レート制限を引き上げるための GitHub トークン（1 時間あたり 60 回から 5000 回）
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 ツールにパストラバーサル対策を追加しました（dir/output パスを検証）
• セキュリティ: パッケージ名を検証するようにしました（npm の命名規則を適用）
• セキュリティ: HTML レポーターのメトリクス値をエスケープするようにしました（多層防御による XSS 対策）
• セキュリティ: URL パーサーで GitHub のユーザー名とリポジトリを検証するようにしました
• セキュリティ: 資金調達情報コレクターで GitHub Sponsors のユーザー名を検証するようにしました
• 機能: プログラム用 API — import { scan, checkPackage } from 'dep-oracle'
• 機能: 新しい MCP ツールを 3 つ追加しました: 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 エラーを区別するようにしました
• 修正: MCP レジストリ向けに server.json が npm パッケージに含まれるようになりました

v1.1.4 (2026-02-22)

• Package.json の修正: npm が README の内容ではなく文字列をそのまま表示する原因となっていた無効な 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 レジストリ: 正式な MCP レジストリ に io.github.ertugrulakben/dep-oracle として登録されました
• 動的なバージョン管理: MCP サーバーと SARIF レポーターが package.json からバージョンを読み取るようになりました（バージョンのハードコードを廃止）

v1.1.0 (2026-02-22)

• タイポスクワッティングの検出: 40 以上のカテゴリにわたる既知のパッケージ 1,847 件以上に拡張し、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）のパーサー
• ゾンビパッケージの検出、影響範囲の分析
• レーベンシュタイン距離によるタイポスクワッティングの検出
• トレンド予測（3 か月間のリスク予測）
• 精選された代替パッケージを提示する移行アドバイザー
• ターミナル、HTML、JSON、SARIF の出力形式
• Claude Code 統合用 MCP サーバー
• GitHub Action のサポート
• SQLite 互換のキャッシュを使用するオフラインモード
• バッジ生成ツール（SVG）

コントリビューション

開発環境のセットアップ、コーディング規約、新しいコレクター、パーサー、アナライザーの追加方法については、CONTRIBUTING.md を参照してください。

ライセンス

MIT — Ertugrul Akben