Dep Oracle

[dep-oracle cover]

dep-oracle

Predictive Dependency Security Engine

[npm version] [License: MIT] [npm downloads] [GitHub stars] [MCP Registry]

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 itnpx dep-oracle
# Or install globallynpm install -g dep-oracledep-oracle scan
# Check a single packagedep-oracle check express

Features

Usage

# Scan current projectdep-oracle scan
# Scan with specific output formatdep-oracle scan --format jsondep-oracle scan --format htmldep-oracle scan --format sarif
# Check a single packagedep-oracle check lodashdep-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 packagesdep-oracle scan --ignore deprecated-but-needed,legacy-pkg
# Verbose loggingdep-oracle scan --verbose

Output Example

dep-oracle v1.2.0Scanning package.json...Found 47 direct dependencies, 683 transitiveCollecting 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

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, luxonrequest    → axios, got, node-fetch, undicilodash     → lodash-es, radash, just (native alternatives)express    → fastify, koa, honogulp       → esbuild, tsup, vitemocha      → 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 Checkon: [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 projectconst report = await scan({ dir: './my-project', format: 'json' });
// Check a single packageconst result = await checkPackage('express');console.log(result.trustScore); // 74console.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 testsnpm 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