Dep Oracle

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](https://modelcontextprotocol.io/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]

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 }}

Configuration

Create .dep-oraclerc.json in your project root:

{

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

Or add to package.json:

{

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

Configuration Options

Supported Package Managers

Comparison

| Typosquat detection | No | No | Yes | No | **Yes*