spidercob-osv

OSV.dev dependency vulnerability scanner for Node.js projects. Zero dependencies, works with package-lock.json or package.json. Built for CI pipelines and git hooks.

Install

# Global
npm install -g spidercob-osv

# Dev dependency (CI/CD)
npm install --save-dev spidercob-osv

# One-off (no install)
npx spidercob-osv

CLI

# Scan current project
spidercob-osv

# Only fail on CRITICAL (default: HIGH)
spidercob-osv --fail-on=CRITICAL

# Specific directory
spidercob-osv --dir=./my-app

# Explicit lock file
spidercob-osv --lock=./package-lock.json

# JSON output (for CI parsing)
spidercob-osv --json
spidercob-osv --json | jq '.vulnerabilities[] | select(.severity=="CRITICAL")'

Exit codes: 0 = clean, 1 = vulnerabilities at threshold, 2 = error

Programmatic API

const { scan } = require('spidercob-osv');

const result = await scan({ cwd: process.cwd() });

console.log(result.packagesScanned);   // 342
console.log(result.hasFindings);       // true
console.log(result.summary);           // "2 CRITICAL, 5 HIGH"

for (const vuln of result.vulnerabilities) {
  console.log(vuln.package, vuln.version, vuln.severity);
  console.log(vuln.id, vuln.summary);
  console.log(vuln.fixedVersions);     // ["2.0.1", "1.9.8"]
  console.log(vuln.link);              // https://osv.dev/vulnerability/...
}

CI/CD Integration

GitHub Actions

- name: OSV Vulnerability Scan
  run: npx spidercob-osv --fail-on=HIGH

GitLab CI

osv-scan:
  image: node:20-alpine
  script:
    - npx spidercob-osv --fail-on=HIGH --json > osv-report.json
  artifacts:
    paths: [osv-report.json]
    when: always

package.json scripts

{
  "scripts": {
    "audit:osv": "spidercob-osv --fail-on=HIGH",
    "audit:osv:strict": "spidercob-osv --fail-on=MEDIUM"
  }
}

Git Hooks

Pre-push (recommended)

# Add to .git/hooks/pre-push
cat >> .git/hooks/pre-push << 'EOF'
#!/bin/sh
npx spidercob-osv --fail-on=CRITICAL
EOF
chmod +x .git/hooks/pre-push

Pre-commit with husky

npm install --save-dev husky
npx husky add .husky/pre-push "npx spidercob-osv --fail-on=CRITICAL"

lint-staged / lefthook

# lefthook.yml
pre-push:
  commands:
    osv:
      run: npx spidercob-osv --fail-on=HIGH

How It Works

1. Reads package-lock.json (exact versions, recommended) or package.json (version ranges)
2. Batch-queries OSV.dev API — free, no API key required
3. Maps CVSS v3 scores to severity levels
4. Returns structured findings with fix versions and direct OSV links

No telemetry. No external auth. Pure HTTPS to api.osv.dev.