io.github.ertugrulakben/dep-oracle

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]

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

Note: dep-oracle is not a replacement for Snyk or Socket.dev in enterprise environments. They have dedicated security research teams and CVE databases. dep-oracle focuses on predictive signals (trust scores, maintenance health, funding, zombie detection) that complement existing tools.

Programmatic 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

Test Suite

dep-oracle has comprehensive test coverage:

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

Changelog

v1.2.0 (2026-02-22)

• Security: Path traversal protection in MCP tools (validated dir/output paths)
• Security: Package name validation (npm naming rules enforced)
• Security: HTML reporter metric values escaped (XSS defense-in-depth)
• Security: GitHub username/repo validation in URL parser
• Security: GitHub Sponsors username validation in funding collector
• Feature: Programmatic API — import { scan, checkPackage } from 'dep-oracle'
• Feature: 3 new MCP tools: dep_oracle_typosquat_check, dep_oracle_compare, dep_oracle_report (8 total)
• Feature: GitHub Action now builds correctly (self-contained bundle)
• Fix: Collector timeout (30s) prevents hanging on slow APIs
• Fix: Trust score weight validation (must sum to 1.0)
• Fix: Patch bonus only applies when vulnerabilities exist
• Fix: Python parser preserves #egg= fragments in git URLs
• Fix: Typosquat homoglyph detection now catches 2-character substitutions
• Fix: Cache error handling distinguishes JSON corruption from I/O errors
• Fix: server.json now included in npm package for MCP registry

v1.1.4 (2026-02-22)

• Package.json Fix: Removed invalid readme field that caused npm to display literal string instead of README content

v1.1.3 (2026-02-22)

• npm README Fix: English README now correctly shown on npmjs.com (excluded Turkish README from npm package via prepack/postpack lifecycle)

v1.1.2 (2026-02-22)

• MCP Registry Links: Updated to official documentation URL

v1.1.1 (2026-02-22)

• MCP Registry: Listed on the official MCP Registry as io.github.ertugrulakben/dep-oracle
• Dynamic Versioning: MCP server and SARIF reporter now read version from package.json (no more hardcoded versions)

v1.1.0 (2026-02-22)

• Typosquat Detection: Expanded to 1,847+ known packages across 40+ categories, plus dynamic npm registry fetch (top 5,000 packages, 7-day cache)
• Migration Advisor: Expanded to 131 package mappings with 192 safer alternatives
• Trust Score Calibration: Diminishing vulnerability penalty (first CVE has highest impact), fast-patch bonus (+10 for <=7 days)
• Poetry.lock Support: Full poetry.lock parsing for Python projects
• Comprehensive Test Suite: 10 test files, 144 tests covering all analyzers, parsers, cache, and utilities
• Turkish README: Full Turkish documentation (README.tr.md)
• Dynamic CLI Version: Version automatically synced from package.json

v1.0.0 (2026-02-22)

• Initial release
• Trust Score engine with 6 weighted metrics
• npm + Python (pip, poetry, pyproject.toml) parsers
• Zombie detection, blast radius analysis
• Typosquat detection with Levenshtein distance
• Trend prediction (3-month risk projection)
• Migration advisor with curated alternatives
• Terminal, HTML, JSON, SARIF output formats
• MCP server for Claude Code integration
• GitHub Action support
• Offline mode with SQLite-compatible cache
• Badge generator (SVG)

Contributing

See CONTRIBUTING.md for development setup, coding standards, and how to add new collectors, parsers, or analyzers.

License

MIT — Ertugrul Akben