{
  "markdown": "<p align=\"center\">\n  <img src=\"cover.jpeg\" alt=\"dep-oracle cover\" width=\"100%\">\n</p>\n\n<p align=\"center\">\n  <h1 align=\"center\">dep-oracle</h1>\n  <p align=\"center\"><strong>Predictive Dependency Security Engine</strong></p>\n  <p align=\"center\">\n    <a href=\"https://www.npmjs.com/package/dep-oracle\"><img src=\"https://img.shields.io/npm/v/dep-oracle.svg\" alt=\"npm version\"></a>\n    <a href=\"https://opensource.org/licenses/MIT\"><img src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"></a>\n    <a href=\"https://www.npmjs.com/package/dep-oracle\"><img src=\"https://img.shields.io/npm/dm/dep-oracle.svg\" alt=\"npm downloads\"></a>\n    <a href=\"https://github.com/ertugrulakben/dep-oracle\"><img src=\"https://img.shields.io/github/stars/ertugrulakben/dep-oracle.svg?style=social\" alt=\"GitHub stars\"></a>\n    <a href=\"https://modelcontextprotocol.io/registry\"><img src=\"https://img.shields.io/badge/MCP-Registry-blue\" alt=\"MCP Registry\"></a>\n  </p>\n  <p align=\"center\">\n    <a href=\"#quick-start\">Quick Start</a> &middot;\n    <a href=\"#features\">Features</a> &middot;\n    <a href=\"#trust-score-algorithm\">Algorithm</a> &middot;\n    <a href=\"#claude-code-integration-mcp\">MCP</a> &middot;\n    <a href=\"#comparison\">Comparison</a>\n  </p>\n  <p align=\"center\">\n    <strong>English</strong> | <a href=\"README.tr.md\">Turkce</a>\n  </p>\n</p>\n\n---\n\n> **Your dependencies have dependencies. Who's watching them?**\n\n**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.\n\n**Claude Code Security** scans YOUR code. **dep-oracle** scans everything your code **depends on**.\n\n## Why?\n\n- Supply chain attacks increased **742% since 2019** ([Sonatype 2024 Report](https://www.sonatype.com/state-of-the-software-supply-chain/introduction))\n- The average npm project pulls in **hundreds of transitive dependencies** — any one could be compromised\n- `npm audit` only catches **known** CVEs — dep-oracle **predicts** future risks\n- You audit your code. But do you audit your **trust**?\n\n## Quick Start\n\n```bash\n# Zero install — just run it\nnpx dep-oracle\n\n# Or install globally\nnpm install -g dep-oracle\ndep-oracle scan\n\n# Check a single package\ndep-oracle check express\n```\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Trust Score** | 0-100 weighted score per package (security, maintainer health, activity, popularity, funding, license) |\n| **Zombie Detection** | Finds unmaintained but critical packages (no commits in 12+ months) |\n| **Blast Radius** | Shows how many files are affected if a dependency is compromised |\n| **Typosquat Detection** | 1,847+ known packages + live npm registry lookup to catch suspicious names |\n| **Trend Prediction** | 3-month risk projection based on download/commit/release trends |\n| **Migration Advisor** | 131 package mappings with 192 safer alternatives for risky dependencies |\n| **Offline Mode** | Works from cache without internet (`--offline`) |\n| **MCP Server** | Native Claude Code integration — ask about your dependencies in natural language |\n| **Multi-Format Output** | Terminal (colored tree), HTML, JSON, and SARIF |\n| **GitHub Action** | Automate trust checks in your CI/CD pipeline |\n\n## Usage\n\n```bash\n# Scan current project\ndep-oracle scan\n\n# Scan with specific output format\ndep-oracle scan --format json\ndep-oracle scan --format html\ndep-oracle scan --format sarif\n\n# Check a single package\ndep-oracle check lodash\ndep-oracle check express@4.18.2\n\n# Offline mode (uses cached data only)\ndep-oracle scan --offline\n\n# Set minimum score threshold (exit code 1 if below)\ndep-oracle scan --threshold 60\n\n# Ignore specific packages\ndep-oracle scan --ignore deprecated-but-needed,legacy-pkg\n\n# Verbose logging\ndep-oracle scan --verbose\n```\n\n## Output Example\n\n```\ndep-oracle v1.2.0\nScanning package.json...\nFound 47 direct dependencies, 683 transitive\nCollecting data... [=============================] 100% (2.3s)\n\nDEPENDENCY TRUST REPORT\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n  CRITICAL (score < 50)\n\n  ■ event-stream@3.3.6         Score: 12  ZOMBIE\n    Last commit: 2018 | 0 maintainers active\n    Blast radius: 14 files | Alternative: highland\n\n  WARNING (score 50-79)\n\n  ■ moment@2.29.4              Score: 58  ZOMBIE\n    Maintenance mode | No new features\n    Blast radius: 23 files | Alternative: dayjs, date-fns, luxon\n\n  SAFE (score 80+): 679 packages\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nSUMMARY\n  Overall Trust Score: 74/100\n  Critical: 2 | Warning: 3 | Safe: 679\n  Zombies: 2 | Deprecated: 1\n```\n\n## Trust Score Algorithm\n\nEach package is scored 0-100 based on six weighted metrics:\n\n| Metric | Weight | What It Measures |\n|--------|--------|------------------|\n| Security History | 25% | CVE count with diminishing penalty, average patch time, fast-patch bonus |\n| Maintainer Health | 25% | Active maintainers (bus factor), issue response time, PR merge speed |\n| Activity | 20% | Commit frequency trend, release cadence, last publish recency |\n| Popularity | 15% | Weekly downloads, dependent count, GitHub stars |\n| Funding | 10% | GitHub Sponsors, OpenCollective, corporate backing |\n| License | 5% | MIT/Apache = safe, GPL = risk, Unknown = red flag |\n\n**Score Ranges:** 80-100 Safe | 50-79 Warning | 0-49 Critical\n\n### Security Scoring\n\nThe security metric uses a **diminishing penalty** model — the first vulnerability has the highest impact, and each additional one has progressively less effect:\n\n| Vulnerabilities | Security Score |\n|-----------------|---------------|\n| 0 | 100 |\n| 1 | 85 |\n| 2 | 72 |\n| 3 | 60 |\n| 4 | 50 |\n| 5+ | max(20, 100 - n*12) |\n\nPackages that patch vulnerabilities quickly (within 7 days) receive a **+10 bonus**. Slower patches (within 30 days) receive **+5**.\n\n### Graceful Degradation\n\nIf 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.\n\n### Blast Radius Methodology\n\nThe blast radius metric counts how many of your source files directly import a given dependency:\n\n1. Recursively collects all `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.mts`, `.cjs`, `.cts` files\n2. Skips `node_modules`, `.git`, `dist`, `build`, `coverage`, and other build directories\n3. Searches each file for `import ... from 'pkg'`, `require('pkg')`, and dynamic `import('pkg')` patterns\n4. Reports the count, file paths, and percentage of codebase affected\n\n**Current limitations:**\n- Only scans JavaScript/TypeScript import patterns\n- Python `import` statements are not yet analyzed (blast radius returns 0 for Python-only projects)\n- Does not trace re-exports or barrel files — counts direct imports only\n\n### Weight Rationale\n\nWeights 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.\n\nWhen 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.\n\n## Typosquat Detection\n\ndep-oracle uses a multi-layer approach to catch typosquatting:\n\n1. **Static registry** — 1,847+ known popular package names across 40+ categories (React, Vue, Angular, Express, testing, CLI tools, etc.)\n2. **Dynamic npm lookup** — Fetches the top 5,000 most-downloaded packages from npm and caches them for 7 days\n3. **Pattern matching** — Levenshtein distance, prefix/suffix manipulation, character swap, missing/extra letter detection\n\n```bash\ndep-oracle check expresss    # Catches: similar to \"express\" (distance: 1)\ndep-oracle check lodashe     # Catches: similar to \"lodash\" (distance: 1)\ndep-oracle check react-js    # Catches: suffix pattern of \"react\"\n```\n\n## Migration Advisor\n\nWhen 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**:\n\n```\nmoment     → dayjs, date-fns, luxon\nrequest    → axios, got, node-fetch, undici\nlodash     → lodash-es, radash, just (native alternatives)\nexpress    → fastify, koa, hono\ngulp       → esbuild, tsup, vite\nmocha      → vitest, jest, node:test\n...and 125 more\n```\n\nEach suggestion includes difficulty rating (easy/moderate/hard) and migration context.\n\n## Claude Code Integration (MCP)\n\ndep-oracle is listed on the official **[MCP Registry](https://modelcontextprotocol.io/registry)** and works as an MCP server for Claude Code:\n\n```json\n// .claude/settings.json\n{\n  \"mcpServers\": {\n    \"dep-oracle\": {\n      \"command\": \"npx\",\n      \"args\": [\"dep-oracle\", \"mcp\"]\n    }\n  }\n}\n```\n\nThen in Claude Code, just ask:\n- *\"What's the riskiest dependency in this project?\"*\n- *\"Is lodash safe to use?\"*\n- *\"Show me zombie dependencies\"*\n- *\"Suggest alternatives for moment.js\"*\n\n**Available MCP Tools:**\n\n| Tool | Description |\n|------|-------------|\n| `dep_oracle_scan` | Full project dependency scan |\n| `dep_oracle_trust_score` | Trust score for a single package |\n| `dep_oracle_blast_radius` | Impact analysis for a package |\n| `dep_oracle_zombies` | List all zombie dependencies |\n| `dep_oracle_suggest_migration` | Get alternative package suggestions |\n| `dep_oracle_typosquat_check` | Check typosquatting risk for a package name |\n| `dep_oracle_compare` | Compare two packages side-by-side |\n| `dep_oracle_report` | Generate a JSON report, optionally to file |\n\n## GitHub Action\n\n```yaml\nname: Dependency Trust Check\non: [pull_request]\n\njobs:\n  dep-oracle:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - name: Run dep-oracle\n        run: npx dep-oracle scan --format sarif --min-score 60\n        env:\n          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n## Configuration\n\nCreate `.dep-oraclerc.json` in your project root:\n\n```json\n{\n  \"threshold\": 60,\n  \"ignore\": [\"known-risky-but-needed\"],\n  \"format\": \"terminal\",\n  \"offline\": false,\n  \"githubToken\": \"$GITHUB_TOKEN\",\n  \"cacheTtl\": 86400\n}\n```\n\nOr add to `package.json`:\n\n```json\n{\n  \"dep-oracle\": {\n    \"threshold\": 60,\n    \"ignore\": []\n  }\n}\n```\n\n### Configuration Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `threshold` | `60` | Minimum trust score. Packages below trigger warnings and non-zero exit |\n| `ignore` | `[]` | Packages to skip during scanning |\n| `format` | `\"terminal\"` | Output format: `terminal`, `json`, `html`, `sarif` |\n| `offline` | `false` | Use only cached data, skip all API calls |\n| `githubToken` | `null` | GitHub token for higher API rate limits (5000/hr vs 60/hr) |\n| `cacheTtl` | `86400` | Cache TTL in seconds (default: 24 hours) |\n\n## Supported Package Managers\n\n| Manager | Manifest | Lock File | Status |\n|---------|----------|-----------|--------|\n| npm | `package.json` | `package-lock.json` | Supported |\n| yarn | `package.json` | `yarn.lock` | Supported |\n| pnpm | `package.json` | `pnpm-lock.yaml` | Supported |\n| pip | `requirements.txt` | `Pipfile.lock` | Supported |\n| poetry | `pyproject.toml` | `poetry.lock` | Supported |\n\n## Comparison\n\n| Feature | npm audit | Dependabot | Socket.dev | Snyk | **dep-oracle** |\n|---------|-----------|------------|------------|------|----------------|\n| Known CVE scan | Yes | Yes | Yes | Yes | **Yes** |\n| Predictive risk | No | No | Partial | Partial | **Yes** |\n| Trust Score (0-100) | No | No | No | No | **Yes** |\n| Zombie detection | No | No | No | No | **Yes** |\n| Blast radius | No | Partial | No | No | **Yes** |\n| Typosquat detection | No | No | Yes | No | **Yes** |\n| Trend prediction | No | No | No | No | **Yes** |\n| Migration advisor | No | Partial | No | Partial | **Yes (131 pkgs)** |\n| MCP integration | No | No | No | No | **Yes** |\n| Zero install (npx) | Yes | No | No | No | **Yes** |\n| Free & open source | Yes | Yes | Freemium | Freemium | **Yes** |\n\n> **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.\n\n## Programmatic API\n\n```typescript\nimport { scan, checkPackage } from 'dep-oracle';\n\n// Scan a project\nconst report = await scan({ dir: './my-project', format: 'json' });\n\n// Check a single package\nconst result = await checkPackage('express');\nconsole.log(result.trustScore); // 74\nconsole.log(result.isZombie);   // false\n```\n\n## Test Suite\n\ndep-oracle has comprehensive test coverage:\n\n```\n10 test files | 144 tests | 100% passing\n\n  trust-score.test.ts     34 tests   Scoring engine, metrics, edge cases\n  zombie-detector.test.ts 10 tests   Zombie detection logic\n  typosquat.test.ts       15 tests   Typosquat pattern matching\n  migration-advisor.test.ts 12 tests Migration suggestions\n  trend-predictor.test.ts 10 tests   Trend prediction engine\n  parsers.test.ts         17 tests   npm + Python parsers\n  cache.test.ts           15 tests   Cache store operations\n  logger.test.ts          17 tests   Logger utility\n  rate-limiter.test.ts    6 tests    Rate limiter\n  schema.test.ts          8 tests    Zod schema validation\n```\n\n```bash\nnpm test          # Run all tests\nnpm run lint      # TypeScript type checking\n```\n\n## Changelog\n\n### v1.2.0 (2026-02-22)\n\n- **Security**: Path traversal protection in MCP tools (validated dir/output paths)\n- **Security**: Package name validation (npm naming rules enforced)\n- **Security**: HTML reporter metric values escaped (XSS defense-in-depth)\n- **Security**: GitHub username/repo validation in URL parser\n- **Security**: GitHub Sponsors username validation in funding collector\n- **Feature**: Programmatic API — `import { scan, checkPackage } from 'dep-oracle'`\n- **Feature**: 3 new MCP tools: `dep_oracle_typosquat_check`, `dep_oracle_compare`, `dep_oracle_report` (8 total)\n- **Feature**: GitHub Action now builds correctly (self-contained bundle)\n- **Fix**: Collector timeout (30s) prevents hanging on slow APIs\n- **Fix**: Trust score weight validation (must sum to 1.0)\n- **Fix**: Patch bonus only applies when vulnerabilities exist\n- **Fix**: Python parser preserves `#egg=` fragments in git URLs\n- **Fix**: Typosquat homoglyph detection now catches 2-character substitutions\n- **Fix**: Cache error handling distinguishes JSON corruption from I/O errors\n- **Fix**: `server.json` now included in npm package for MCP registry\n\n### v1.1.4 (2026-02-22)\n\n- **Package.json Fix**: Removed invalid `readme` field that caused npm to display literal string instead of README content\n\n### v1.1.3 (2026-02-22)\n\n- **npm README Fix**: English README now correctly shown on npmjs.com (excluded Turkish README from npm package via prepack/postpack lifecycle)\n\n### v1.1.2 (2026-02-22)\n\n- **MCP Registry Links**: Updated to official documentation URL\n\n### v1.1.1 (2026-02-22)\n\n- **MCP Registry**: Listed on the official [MCP Registry](https://modelcontextprotocol.io/registry) as `io.github.ertugrulakben/dep-oracle`\n- **Dynamic Versioning**: MCP server and SARIF reporter now read version from package.json (no more hardcoded versions)\n\n### v1.1.0 (2026-02-22)\n\n- **Typosquat Detection**: Expanded to 1,847+ known packages across 40+ categories, plus dynamic npm registry fetch (top 5,000 packages, 7-day cache)\n- **Migration Advisor**: Expanded to 131 package mappings with 192 safer alternatives\n- **Trust Score Calibration**: Diminishing vulnerability penalty (first CVE has highest impact), fast-patch bonus (+10 for <=7 days)\n- **Poetry.lock Support**: Full poetry.lock parsing for Python projects\n- **Comprehensive Test Suite**: 10 test files, 144 tests covering all analyzers, parsers, cache, and utilities\n- **Turkish README**: Full Turkish documentation (README.tr.md)\n- **Dynamic CLI Version**: Version automatically synced from package.json\n\n### v1.0.0 (2026-02-22)\n\n- Initial release\n- Trust Score engine with 6 weighted metrics\n- npm + Python (pip, poetry, pyproject.toml) parsers\n- Zombie detection, blast radius analysis\n- Typosquat detection with Levenshtein distance\n- Trend prediction (3-month risk projection)\n- Migration advisor with curated alternatives\n- Terminal, HTML, JSON, SARIF output formats\n- MCP server for Claude Code integration\n- GitHub Action support\n- Offline mode with SQLite-compatible cache\n- Badge generator (SVG)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to add new collectors, parsers, or analyzers.\n\n## License\n\n[MIT](LICENSE) — [Ertugrul Akben](https://ertugrulakben.com)\n",
  "bytes": 17015,
  "sha": "5a2a7b9ed847f41ec2bad71cc4c2418a74f1b97a787315ceab270e55b6ddfb44",
  "repo_slug": "ertugrulakben/dep-oracle",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ertugrulakben_dep_oracle_d1e22ed6/readme"
}