dep-oracle

Predictive Dependency Security Engine

Quick Start · Features · Algorithm · MCP · Comparison

English | Turkce

Your dependencies have dependencies. Who's watching them?

dep-oracle is a predictive dependency security engine that calculates Trust Scores (0-100) for every package in your dependency tree. It detects zombie dependencies, measures blast radius, catches typosquatting attempts, and predicts future risks — before they become vulnerabilities.

Claude Code Security scans YOUR code. dep-oracle scans everything your code depends on.

Why?

• Supply chain attacks increased 742% since 2019 (Sonatype 2024 Report)
• The average npm project pulls in hundreds of transitive dependencies — any one could be compromised
• npm audit only catches known CVEs — dep-oracle predicts future risks
• You audit your code. But do you audit your trust?

Quick Start

# 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

Features

Usage

# 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 express@4.18.2

# 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

Output Example

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)

  ■ event-stream@3.3.6         Score: 12  ZOMBIE
    Last commit: 2018 | 0 maintainers active
    Blast radius: 14 files | Alternative: highland

  WARNING (score 50-79)

  ■ moment@2.29.4              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

Trust Score Algorithm

Each package is scored 0-100 based on six weighted metrics:

Score Ranges: 80-100 Safe | 50-79 Warning | 0-49 Critical

Security Scoring

The security metric uses a diminishing penalty model — the first vulnerability has the highest impact, and each additional one has progressively less effect:

Packages that patch vulnerabilities quickly (within 7 days) receive a +10 bonus. Slower patches (within 30 days) receive +5.

Graceful Degradation

If an API is unreachable (GitHub down, no internet, rate limited), dep-oracle doesn't crash. The missing metric weight is redistributed across available metrics. If 3+ metrics are unavailable, a reliability warning is shown.

Blast Radius Methodology

The blast radius metric counts how many of your source files directly import a given dependency:

1. Recursively collects all .js, .ts, .jsx, .tsx, .mjs, .mts, .cjs, .cts files
2. Skips node_modules, .git, dist, build, coverage, and other build directories
3. Searches each file for import ... from 'pkg', require('pkg'), and dynamic import('pkg') patterns
4. Reports the count, file paths, and percentage of codebase affected

Current limitations:

• Only scans JavaScript/TypeScript import patterns
• Python import statements are not yet analyzed (blast radius returns 0 for Python-only projects)
• Does not trace re-exports or barrel files — counts direct imports only

Weight Rationale

Weights are based on the principle that security vulnerabilities and maintainer abandonment are the strongest predictors of supply chain risk, followed by development activity signals. Weights are fully configurable via .dep-oraclerc.json — enterprise teams can adjust to match their specific risk tolerance.

When data is unavailable for a metric, the score is pulled toward the midpoint (50) proportionally to the fraction of missing weight, preventing artificial inflation from missing data.

Typosquat Detection

dep-oracle uses a multi-layer approach to catch typosquatting:

1. Static registry — 1,847+ known popular package names across 40+ categories (React, Vue, Angular, Express, testing, CLI tools, etc.)
2. Dynamic npm lookup — Fetches the top 5,000 most-downloaded packages from npm and caches them for 7 days
3. Pattern matching — Levenshtein distance, prefix/suffix manipulation, character swap, missing/extra letter detection

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"

Migration Advisor

When a package scores low or is flagged as a zombie, dep-oracle suggests safer alternatives from a curated database of 131 package mappings with 192 alternatives:

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

Each suggestion includes difficulty rating (easy/moderate/hard) and migration context.

Claude Code Integration (MCP)

dep-oracle is listed on the official MCP Registry and works as an MCP server for Claude Code:

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

Then in Claude Code, just ask:

• "What's the riskiest dependency in this project?"
• "Is lodash safe to use?"
• "Show me zombie dependencies"
• "Suggest alternatives for moment.js"

Available MCP Tools:

GitHub Action

name: Dependency Trust Check
on: [pull_request]