Skip to content

scan_dependencies

Scan project dependencies (requirements.txt, pyproject.toml, package.json) for known security vulnerabilities using the OSV database.

Quick Reference

scan_dependencies(
    project_root: str = None,        # Project directory
    path: str = None,                # Specific file path
    include_dev: bool = True,        # Include dev dependencies
    scan_vulnerabilities: bool = True,  # Query OSV database
    timeout: float = 30              # API timeout
) -> DependencyScanResult

User Stories

Persona Story Tool Value
🛡️ Marcus (Security Engineer) "Check for CVEs in requirements.txt using OSV database" Supply chain security
👥 David (Team Lead) "Ensure no vulnerable dependencies before production release" Risk mitigation
🏢 Jennifer (Enterprise Architect) "Report all CVEs across organization's dependencies" Supply chain risk reporting
🔧 Chris (OSS Contributor) "Add CVE scanning to pre-commit hooks" Development workflow integration

→ See all user stories

Parameters

Parameter Type Required Default Description
project_root string No cwd Project root directory
path string No None Path to specific dependency file
include_dev bool No true Include development dependencies
scan_vulnerabilities bool No true Query OSV for CVEs
timeout float No 30 API request timeout

Supported Formats

File Ecosystem
requirements.txt Python/PyPI
pyproject.toml Python/PyPI
setup.py Python/PyPI
Pipfile.lock Python/PyPI
package.json JavaScript/npm
package-lock.json JavaScript/npm
yarn.lock JavaScript/npm

Response Schema

{
  "data": {
    "dependencies": [
      {
        "name": "string",
        "version": "string",
        "ecosystem": "string",
        "source_file": "string",
        "is_dev": "boolean",
        "vulnerabilities": [
          {
            "id": "string",
            "aliases": ["string"],
            "severity": "string",
            "cvss_score": "float",
            "description": "string",
            "fixed_version": "string",
            "references": ["string"]
          }
        ]
      }
    ],
    "summary": {
      "total_packages": "integer",
      "vulnerable_packages": "integer",
      "critical_vulns": "integer",
      "high_vulns": "integer",
      "medium_vulns": "integer",
      "low_vulns": "integer"
    },
    "files_scanned": ["string"]
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples

Scan Python Project

Scan my project dependencies for vulnerabilities

{
  "project_root": "/project"
}

codescalpel scan-dependencies .

{
  "data": {
    "dependencies": [
      {
        "name": "requests",
        "version": "2.25.0",
        "ecosystem": "PyPI",
        "source_file": "requirements.txt",
        "is_dev": false,
        "vulnerabilities": [
          {
            "id": "GHSA-j8r2-6x86-q33q",
            "aliases": ["CVE-2023-32681"],
            "severity": "HIGH",
            "cvss_score": 7.5,
            "description": "Unintended leak of Proxy-Authorization header in requests",
            "fixed_version": "2.31.0",
            "references": [
              "https://github.com/psf/requests/security/advisories/GHSA-j8r2-6x86-q33q"
            ]
          }
        ]
      },
      {
        "name": "flask",
        "version": "2.0.1",
        "ecosystem": "PyPI",
        "source_file": "requirements.txt",
        "is_dev": false,
        "vulnerabilities": []
      },
      {
        "name": "pytest",
        "version": "7.0.0",
        "ecosystem": "PyPI",
        "source_file": "requirements.txt",
        "is_dev": true,
        "vulnerabilities": []
      }
    ],
    "summary": {
      "total_packages": 25,
      "vulnerable_packages": 1,
      "critical_vulns": 0,
      "high_vulns": 1,
      "medium_vulns": 0,
      "low_vulns": 0
    },
    "files_scanned": ["requirements.txt"]
  },
  "tier_applied": "community",
  "duration_ms": 2350
}

Scan Specific File

Check package.json for vulnerable npm packages

{
  "path": "/project/package.json"
}

codescalpel scan-dependencies package.json

{
  "data": {
    "dependencies": [
      {
        "name": "lodash",
        "version": "4.17.15",
        "ecosystem": "npm",
        "vulnerabilities": [
          {
            "id": "GHSA-jf85-cpcp-j695",
            "aliases": ["CVE-2021-23337"],
            "severity": "HIGH",
            "cvss_score": 7.2,
            "description": "Command Injection in lodash",
            "fixed_version": "4.17.21"
          },
          {
            "id": "GHSA-35jh-r3h4-6jhm",
            "aliases": ["CVE-2020-28500"],
            "severity": "MEDIUM",
            "cvss_score": 5.3,
            "description": "Regular Expression Denial of Service (ReDoS)",
            "fixed_version": "4.17.21"
          }
        ]
      },
      {
        "name": "axios",
        "version": "0.21.1",
        "ecosystem": "npm",
        "vulnerabilities": [
          {
            "id": "GHSA-42xw-2xvc-qx8m",
            "severity": "HIGH",
            "description": "Server-Side Request Forgery in axios",
            "fixed_version": "0.21.2"
          }
        ]
      }
    ],
    "summary": {
      "total_packages": 45,
      "vulnerable_packages": 2,
      "critical_vulns": 0,
      "high_vulns": 2,
      "medium_vulns": 1
    }
  }
}

Production Only

Scan only production dependencies, not dev

{
  "project_root": "/project",
  "include_dev": false
}

codescalpel scan-dependencies . --no-dev

Quick Inventory (No CVE Check)

List all dependencies without checking for vulnerabilities

{
  "project_root": "/project",
  "scan_vulnerabilities": false
}

codescalpel scan-dependencies . --no-scan-vulnerabilities

{
  "data": {
    "dependencies": [
      {"name": "flask", "version": "2.0.1", "is_dev": false},
      {"name": "requests", "version": "2.25.0", "is_dev": false},
      {"name": "sqlalchemy", "version": "1.4.0", "is_dev": false},
      {"name": "pytest", "version": "7.0.0", "is_dev": true}
    ],
    "summary": {
      "total_packages": 4,
      "production_packages": 3,
      "dev_packages": 1
    }
  },
  "duration_ms": 45
}

Severity Levels

Level CVSS Score Action
CRITICAL 9.0 - 10.0 Immediate update required
HIGH 7.0 - 8.9 Update as soon as possible
MEDIUM 4.0 - 6.9 Update in next release cycle
LOW 0.1 - 3.9 Update when convenient

Tier Differences

This tool is available at all tiers. What differs are the limits and capabilities:

Feature Community Pro Enterprise
Availability ✅ Available ✅ Available ✅ Available
Basic dependency scan ✅ ✅ ✅
OSV vulnerability lookup ✅ ✅ ✅
All ecosystems ✅ Python, JS, Go, Rust ✅ Python, JS, Go, Rust ✅ Python, JS, Go, Rust
Transitive dependencies Direct only ✅ Full tree ✅ Full tree
License compliance Not available ✅ SPDX/OSI ✅ Custom policies
SBOM generation Not available Not available ✅ SPDX/CycloneDX
Policy enforcement Not available Not available ✅ Custom rules

Error Handling

File Not Found

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "No dependency files found in /project",
    "suggestion": "Ensure requirements.txt, pyproject.toml, or package.json exists"
  }
}

API Timeout

{
  "data": {
    "dependencies": [...],
    "summary": {...},
    "warning": "Some vulnerability checks timed out"
  },
  "partial_results": true
}

Tier Limits

scan_dependencies capabilities vary by tier:

Feature Community Pro Enterprise
Max dependencies 50 Unlimited Unlimited
OSV lookup ✅ ✅ ✅
Supported ecosystems PyPI, npm PyPI, npm PyPI, npm
Dev dependencies ✅ ✅ ✅
CVE details ✅ Basic ✅ Full ✅ Full
Severity scoring ✅ ✅ ✅ Enhanced
Fix recommendations ✅ Basic ✅ Detailed ✅ Automated
Historical tracking ❌ ✅ ✅
Report generation ❌ ✅ ✅ PDF/Excel
Timeout 30 seconds 30 seconds 60 seconds

Community Tier

  • ✅ Scan up to 50 dependencies for CVEs
  • ✅ OSV database lookup for vulnerabilities
  • ✅ Support for Python (PyPI) and JavaScript (npm)
  • ✅ Basic CVE details (ID, severity, description)
  • ✅ Basic fix recommendations
  • ⚠️ Limited to 50 dependencies - May miss some packages
  • ❌ No historical vulnerability tracking
  • ❌ No report generation

Pro Tier

  • ✅ All Community features
  • ✅ Unlimited dependencies - Scan entire dependency tree
  • ✅ Full CVE details - Complete vulnerability information
  • ✅ Detailed fix recommendations - Step-by-step upgrade paths
  • ✅ Historical tracking - See how vulnerabilities change over time
  • ✅ Report generation - Export to various formats
  • ✅ Enhanced severity scoring - Better risk assessment

Enterprise Tier

  • ✅ All Pro features
  • ✅ Automated fix suggestions - Generate dependency update PRs
  • ✅ PDF/Excel reports - Professional vulnerability reports
  • ✅ Custom vulnerability databases - Private CVE sources
  • ✅ Multi-repository scanning - Organization-wide dependency audit
  • ✅ Policy enforcement - Block known-vulnerable dependencies
  • ✅ 60 second timeout - Handle large dependency trees

Key Difference: Dependency Coverage and Reporting - Community: 50 dependencies - Small projects, quick check - Pro: Unlimited, historical tracking - Production dependency audit - Enterprise: Unlimited, automated fixes, policies - Enterprise supply chain security

→ See tier comparison

CI/CD Integration

GitHub Actions

- name: Dependency Scan
  run: |
    pip install codescalpel
    code-scalpel scan --dependencies ./

- name: Fail on Critical
  run: |
    CRITICAL=$(code-scalpel scan --dependencies ./ --json | jq '.summary.critical_vulns')
    if [ "$CRITICAL" -gt 0 ]; then
      echo "Critical vulnerabilities found!"
      exit 1
    fi

Pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: dependency-scan
        name: Scan Dependencies
        entry: code-scalpel scan --dependencies
        language: system
        pass_filenames: false
        files: (requirements\.txt|pyproject\.toml|package\.json)$

Best Practices

  1. Scan regularly - Weekly or on dependency changes
  2. Fix critical first - Prioritize by severity
  3. Pin versions - Avoid unexpected updates
  4. Use lockfiles - Reproducible builds
  5. Update incrementally - One package at a time