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

Feature	Description
Trust Score	0-100 weighted score per package (security, maintainer health, activity, popularity, funding, license)
Zombie Detection	Finds unmaintained but critical packages (no commits in 12+ months)
Blast Radius	Shows how many files are affected if a dependency is compromised
Typosquat Detection	1,847+ known packages + live npm registry lookup to catch suspicious names
Trend Prediction	3-month risk projection based on download/commit/release trends
Migration Advisor	131 package mappings with 192 safer alternatives for risky dependencies
Offline Mode	Works from cache without internet (--offline)
MCP Server	Native Claude Code integration — ask about your dependencies in natural language
Multi-Format Output	Terminal (colored tree), HTML, JSON, and SARIF
GitHub Action	Automate trust checks in your CI/CD pipeline

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:

Metric	Weight	What It Measures
Security History	25%	CVE count with diminishing penalty, average patch time, fast-patch bonus
Maintainer Health	25%	Active maintainers (bus factor), issue response time, PR merge speed
Activity	20%	Commit frequency trend, release cadence, last publish recency
Popularity	15%	Weekly downloads, dependent count, GitHub stars
Funding	10%	GitHub Sponsors, OpenCollective, corporate backing
License	5%	MIT/Apache = safe, GPL = risk, Unknown = red flag

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:

Vulnerabilities	Security Score
0	100
1	85
2	72
3	60
4	50
5+	max(20, 100 - n*12)

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:

Tool	Description
dep_oracle_scan	Full project dependency scan
dep_oracle_trust_score	Trust score for a single package
dep_oracle_blast_radius	Impact analysis for a package
dep_oracle_zombies	List all zombie dependencies
dep_oracle_suggest_migration	Get alternative package suggestions
dep_oracle_typosquat_check	Check typosquatting risk for a package name
dep_oracle_compare	Compare two packages side-by-side
dep_oracle_report	Generate a JSON report, optionally to file

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

Option	Default	Description
threshold	60	Minimum trust score. Packages below trigger warnings and non-zero exit
ignore	[]	Packages to skip during scanning
format	"terminal"	Output format: terminal, json, html, sarif
offline	false	Use only cached data, skip all API calls
githubToken	null	GitHub token for higher API rate limits (5000/hr vs 60/hr)
cacheTtl	86400	Cache TTL in seconds (default: 24 hours)

Supported Package Managers

Manager	Manifest	Lock File	Status
npm	package.json	package-lock.json	Supported
yarn	package.json	yarn.lock	Supported
pnpm	package.json	pnpm-lock.yaml	Supported
pip	requirements.txt	Pipfile.lock	Supported
poetry	pyproject.toml	poetry.lock	Supported

Comparison

Feature	npm audit	Dependabot	Socket.dev	Snyk	dep-oracle
Known CVE scan	Yes	Yes	Yes	Yes	Yes
Predictive risk	No	No	Partial	Partial	Yes
Trust Score (0-100)	No	No	No	No	Yes
Zombie detection	No	No	No	No	Yes
Blast radius	No	Partial	No	No	Yes
Typosquat detection	No	No	Yes	No	Yes
Trend prediction	No	No	No	No	Yes
Migration advisor	No	Partial	No	Partial	Yes (131 pkgs)
MCP integration	No	No	No	No	Yes
Zero install (npx)	Yes	No	No	No	Yes
Free & open source	Yes	Yes	Freemium	Freemium	Yes

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