dep-oracle 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ertugrul Akben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# 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.
+
+[![npm version](https://img.shields.io/npm/v/dep-oracle.svg)](https://www.npmjs.com/package/dep-oracle)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Why?
+
+- **62% of breaches** in 2025 came from supply chain attacks
+- The average project has **683 transitive dependencies**
+- `npm audit` only catches **known** CVEs — dep-oracle **predicts** future risks
+- You audit your code. But do you audit your **trust**?
+
+**Claude Code Security** scans YOUR code. **dep-oracle** scans everything your code **depends on**.
+
+## Quick Start
+
+```bash
+# Zero install — just run it
+npx dep-oracle
+
+# Or install globally
+npm install -g dep-oracle
+dep-oracle scan
+```
+
+## What It Does
+
+| Feature | Description |
+|---------|-------------|
+| **Trust Score** | 0-100 weighted score per package (maintainer health, security, 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** | Catches suspicious package names similar to popular packages |
+| **Trend Prediction** | 3-month risk projection based on download/commit trends |
+| **Migration Advisor** | Suggests safer alternatives for risky dependencies |
+| **Offline Mode** | Works from cache without internet (`--offline`) |
+
+## Usage
+
+```bash
+# Scan current project
+dep-oracle scan
+
+# Scan with specific output
+dep-oracle scan --format json
+dep-oracle scan --format html
+dep-oracle scan --format sarif
+
+# Check a single package
+dep-oracle check lodash
+
+# Offline mode (uses cached data)
+dep-oracle scan --offline
+
+# Set minimum score threshold (CI/CD)
+dep-oracle scan --threshold 60
+
+# Ignore specific packages
+dep-oracle scan --ignore deprecated-but-needed,legacy-pkg
+```
+
+## Output Example
+
+```
+🔮 dep-oracle v1.0.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
+
+✅ 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, average patch time, vulnerability density |
+| Maintainer Health | 25% | Active maintainers (bus factor), issue response time, PR merge speed |
+| Activity | 20% | Commit frequency trend, release cadence, last publish date |
+| 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
+
+## Claude Code Integration (MCP)
+
+dep-oracle works as an MCP server for Claude Code:
+
+```json
+// .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"
+
+## GitHub Action
+
+```yaml
+name: Dependency Trust Check
+on: [pull_request]
+
+jobs:
+  dep-oracle:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ertugrulakben/dep-oracle-action@v1
+        with:
+          threshold: 60
+          format: sarif
+```
+
+## Configuration
+
+Create `.dep-oraclerc.json` in your project root:
+
+```json
+{
+  "threshold": 60,
+  "ignore": ["known-risky-but-needed"],
+  "format": "terminal",
+  "offline": false,
+  "githubToken": "$GITHUB_TOKEN",
+  "cacheTtl": 86400
+}
+```
+
+Or add to `package.json`:
+
+```json
+{
+  "dep-oracle": {
+    "threshold": 60,
+    "ignore": []
+  }
+}
+```
+
+## 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 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Predictive risk | ❌ | ❌ | Partial | ❌ | **✅** |
+| Trust Score (0-100) | ❌ | ❌ | ❌ | ❌ | **✅** |
+| Zombie detection | ❌ | ❌ | ❌ | ❌ | **✅** |
+| Blast radius | ❌ | ❌ | ❌ | ❌ | **✅** |
+| Typosquat detection | ❌ | ❌ | ✅ | ❌ | **✅** |
+| Trend prediction | ❌ | ❌ | ❌ | ❌ | **✅** |
+| MCP integration | ❌ | ❌ | ✅ | ✅ | **✅** |
+| Zero install (npx) | ✅ | ❌ | ❌ | ❌ | **✅** |
+| Free | ✅ | ✅ | Freemium | Freemium | **✅** |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and how to add new collectors/parsers.
+
+## License
+
+[MIT](LICENSE) — Ertugrul Akben

package/action/action.yml

@@ -0,0 +1,21 @@
+name: 'dep-oracle'
+description: 'Predictive dependency security scan — Trust Scores, zombie detection, blast radius analysis'
+branding:
+  icon: 'shield'
+  color: 'blue'
+inputs:
+  min-score:
+    description: 'Minimum trust score threshold (0-100). Packages below this score cause the action to fail.'
+    required: false
+    default: '50'
+  format:
+    description: 'Output format (table, json, sarif)'
+    required: false
+    default: 'table'
+  github-token:
+    description: 'GitHub token for API rate limits'
+    required: false
+    default: '${{ github.token }}'
+runs:
+  using: 'node20'
+  main: 'index.js'

package/action/index.ts

@@ -0,0 +1,302 @@
+/**
+ * GitHub Action entry point for dep-oracle.
+ *
+ * Reads inputs from environment variables (GitHub Actions convention),
+ * runs a full dependency scan using the core engine, and outputs results
+ * in the requested format. Exits with code 1 if any package falls below
+ * the minimum trust score threshold.
+ *
+ * Environment variables set by GitHub Actions:
+ *   INPUT_MIN_SCORE    - Minimum trust score threshold (default: 50)
+ *   INPUT_FORMAT       - Output format: table, json, sarif (default: table)
+ *   INPUT_GITHUB_TOKEN - GitHub token for higher API rate limits
+ *   GITHUB_WORKSPACE   - Path to the checked-out repository
+ *   GITHUB_OUTPUT      - Path to the file for setting action outputs
+ *   GITHUB_STEP_SUMMARY - Path to the file for job summary markdown
+ */
+
+import { resolve } from 'node:path';
+import { appendFile } from 'node:fs/promises';
+
+import { CacheManager } from '../src/cache/store.js';
+import { NpmParser } from '../src/parsers/npm.js';
+import { PythonParser } from '../src/parsers/python.js';
+import type { DependencyTree, TrustReport, ScanResult } from '../src/parsers/schema.js';
+import { CollectorOrchestrator } from '../src/collectors/orchestrator.js';
+import { TrustScoreEngine } from '../src/analyzers/trust-score.js';
+import { ZombieDetector } from '../src/analyzers/zombie-detector.js';
+import { MigrationAdvisor } from '../src/analyzers/migration-advisor.js';
+import { TyposquatDetector } from '../src/analyzers/typosquat.js';
+import { buildImportGraph, getBlastRadius } from '../src/utils/graph.js';
+import { JsonReporter } from '../src/reporters/json.js';
+
+// ---------------------------------------------------------------------------
+// Configuration from GitHub Action inputs
+// ---------------------------------------------------------------------------
+
+process.env.GITHUB_TOKEN =
+  process.env.INPUT_GITHUB_TOKEN ?? process.env.GITHUB_TOKEN ?? '';
+
+const minScore = parseInt(process.env.INPUT_MIN_SCORE ?? '50', 10);
+const format = (process.env.INPUT_FORMAT ?? 'table').toLowerCase();
+const workspaceDir = resolve(process.env.GITHUB_WORKSPACE ?? process.cwd());
+
+// ---------------------------------------------------------------------------
+// Core engine instances
+// ---------------------------------------------------------------------------
+
+const cache = new CacheManager();
+const orchestrator = new CollectorOrchestrator(cache, {
+  githubToken: process.env.GITHUB_TOKEN,
+});
+const trustEngine = new TrustScoreEngine();
+const zombieDetector = new ZombieDetector();
+const migrationAdvisor = new MigrationAdvisor();
+const typosquatDetector = new TyposquatDetector();
+const jsonReporter = new JsonReporter();
+const parsers = [new NpmParser(), new PythonParser()];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function parseProject(dir: string): Promise<DependencyTree | null> {
+  for (const parser of parsers) {
+    if (await parser.detect(dir)) {
+      return parser.parse(dir);
+    }
+  }
+  return null;
+}
+
+async function buildTrustReport(
+  packageName: string,
+  version: string,
+  blastRadius: number = 0,
+): Promise<TrustReport> {
+  const results = await orchestrator.collectAll(packageName, version);
+  const trustResult = trustEngine.calculate(results);
+  const zombie = zombieDetector.detect(
+    results.registry.data,
+    results.github.data,
+  );
+  const typosquat = typosquatDetector.check(packageName);
+  const alternatives = migrationAdvisor.suggest(
+    packageName,
+    zombie.isZombie ? 'zombie dependency' : 'low trust score',
+  );
+  const trend = results.popularity.data?.trend ?? 'stable';
+
+  return {
+    package: packageName,
+    version,
+    trustScore: trustResult.trustScore,
+    metrics: trustResult.metrics,
+    isZombie: zombie.isZombie,
+    blastRadius,
+    alternatives: alternatives.map((a) => a.alternative),
+    trend,
+    typosquatRisk: typosquat.isRisky ? 1.0 : 0.0,
+  };
+}
+
+/** Set a GitHub Actions output variable. */
+async function setOutput(name: string, value: string): Promise<void> {
+  const outputFile = process.env.GITHUB_OUTPUT;
+  if (outputFile) {
+    await appendFile(outputFile, `${name}=${value}\n`, 'utf-8');
+  }
+}
+
+/** Append content to the GitHub Actions job summary. */
+async function addSummary(markdown: string): Promise<void> {
+  const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+  if (summaryFile) {
+    await appendFile(summaryFile, markdown + '\n', 'utf-8');
+  }
+}
+
+function formatTable(reports: TrustReport[], overallScore: number): string {
+  const lines: string[] = [];
+
+  lines.push('dep-oracle -- Dependency Trust Report');
+  lines.push('='.repeat(60));
+  lines.push(`Overall Trust Score: ${overallScore}/100`);
+  lines.push('');
+  lines.push(
+    'Package'.padEnd(30) +
+    'Score'.padEnd(8) +
+    'Zombie'.padEnd(8) +
+    'Blast'.padEnd(8) +
+    'Trend',
+  );
+  lines.push('-'.repeat(62));
+
+  const sorted = [...reports].sort((a, b) => a.trustScore - b.trustScore);
+
+  for (const r of sorted) {
+    lines.push(
+      r.package.padEnd(30) +
+      String(r.trustScore).padEnd(8) +
+      (r.isZombie ? 'Yes' : 'No').padEnd(8) +
+      String(r.blastRadius).padEnd(8) +
+      r.trend,
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function formatMarkdownSummary(
+  reports: TrustReport[],
+  overallScore: number,
+): string {
+  const lines: string[] = [];
+
+  const statusEmoji = overallScore >= 80 ? 'white_check_mark' : overallScore >= 50 ? 'warning' : 'x';
+  lines.push(`## dep-oracle Dependency Report :${statusEmoji}:`);
+  lines.push('');
+  lines.push(`**Overall Trust Score:** ${overallScore}/100`);
+  lines.push('');
+
+  const zombieCount = reports.filter((r) => r.isZombie).length;
+  const criticalCount = reports.filter((r) => r.trustScore < 50).length;
+  const typosquatCount = reports.filter((r) => r.typosquatRisk > 0.5).length;
+
+  lines.push(`| Metric | Count |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Total scanned | ${reports.length} |`);
+  lines.push(`| Critical (score < 50) | ${criticalCount} |`);
+  lines.push(`| Zombie dependencies | ${zombieCount} |`);
+  lines.push(`| Typosquat risks | ${typosquatCount} |`);
+  lines.push('');
+
+  // Package table
+  lines.push('| Package | Score | Zombie | Blast Radius | Trend |');
+  lines.push('|---------|-------|--------|--------------|-------|');
+
+  const sorted = [...reports].sort((a, b) => a.trustScore - b.trustScore);
+  for (const r of sorted) {
+    const scoreIcon = r.trustScore >= 80 ? ':green_circle:' : r.trustScore >= 50 ? ':yellow_circle:' : ':red_circle:';
+    lines.push(
+      `| ${r.package} | ${scoreIcon} ${r.trustScore} | ${r.isZombie ? ':skull:' : ':heavy_check_mark:'} | ${r.blastRadius} files | ${r.trend} |`,
+    );
+  }
+
+  // Migration suggestions
+  const withAlternatives = reports.filter(
+    (r) => r.trustScore < 50 && r.alternatives.length > 0,
+  );
+  if (withAlternatives.length > 0) {
+    lines.push('');
+    lines.push('### Migration Suggestions');
+    lines.push('');
+    for (const r of withAlternatives) {
+      lines.push(`- **${r.package}** -> consider: ${r.alternatives.join(', ')}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('---');
+  lines.push('*Generated by [dep-oracle](https://github.com/ertugrulakben/dep-oracle)*');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log(`dep-oracle: scanning ${workspaceDir}`);
+  console.log(`  min-score: ${minScore}, format: ${format}`);
+
+  // Parse project
+  const tree = await parseProject(workspaceDir);
+  if (!tree) {
+    console.error(
+      'dep-oracle: No supported manifest file found in the workspace. ' +
+      'Supported: package.json, requirements.txt, pyproject.toml, Pipfile.',
+    );
+    process.exit(1);
+  }
+
+  // Build import graph for blast radius
+  const importGraph = await buildImportGraph(workspaceDir);
+
+  // Collect trust reports
+  const directNodes = Array.from(tree.nodes.values()).filter((n) => n.isDirect);
+  console.log(`dep-oracle: analyzing ${directNodes.length} direct dependencies...`);
+
+  const reports: TrustReport[] = [];
+  for (const node of directNodes) {
+    const blastRadius = getBlastRadius(node.name, importGraph);
+    const report = await buildTrustReport(node.name, node.version, blastRadius);
+    reports.push(report);
+  }
+
+  // Overall score
+  const overallScore =
+    reports.length > 0
+      ? Math.round(
+          reports.reduce((sum, r) => sum + r.trustScore, 0) / reports.length,
+        )
+      : 100;
+
+  // Output in requested format
+  if (format === 'json' || format === 'sarif') {
+    const zombieCount = reports.filter((r) => r.isZombie).length;
+    const criticalCount = reports.filter((r) => r.trustScore < 50).length;
+    const scanResult: ScanResult = {
+      tree,
+      reports,
+      overallScore,
+      summary:
+        `Scanned ${reports.length} direct dependencies. ` +
+        `Overall trust score: ${overallScore}/100. ` +
+        `${zombieCount} zombie(s) detected. ` +
+        `${criticalCount} package(s) below trust threshold.`,
+    };
+    console.log(jsonReporter.report(scanResult));
+  } else {
+    console.log(formatTable(reports, overallScore));
+  }
+
+  // Set GitHub Actions outputs
+  await setOutput('overall-score', String(overallScore));
+  await setOutput('package-count', String(reports.length));
+  await setOutput(
+    'zombie-count',
+    String(reports.filter((r) => r.isZombie).length),
+  );
+  await setOutput(
+    'critical-count',
+    String(reports.filter((r) => r.trustScore < minScore).length),
+  );
+
+  // Write job summary
+  await addSummary(formatMarkdownSummary(reports, overallScore));
+
+  // Determine exit code
+  const failedPackages = reports.filter((r) => r.trustScore < minScore);
+  if (failedPackages.length > 0) {
+    console.error('');
+    console.error(
+      `dep-oracle: ${failedPackages.length} package(s) below minimum trust score of ${minScore}:`,
+    );
+    for (const pkg of failedPackages) {
+      console.error(`  - ${pkg.package} (score: ${pkg.trustScore})`);
+    }
+    process.exit(1);
+  }
+
+  console.log('');
+  console.log(
+    `dep-oracle: All ${reports.length} packages meet the minimum trust score of ${minScore}. Passed.`,
+  );
+}
+
+main().catch((err) => {
+  console.error('dep-oracle: Unexpected error:', err);
+  process.exit(1);
+});