igbuend/depscan

OWASP Depscan - Next-Generation SCA

When to Use Depscan

Ideal scenarios:

• Advanced Software Composition Analysis (SCA)
• Vulnerability Disclosure Report (VDR) generation
• SBOM (Software Bill of Materials) creation and analysis
• CSAF 2.0 VEX (Vulnerability Exploitability eXchange) documents
• License compliance auditing
• Risk assessment and scoring
• Supply chain security analysis
• Multi-format vulnerability reporting

Complements other tools:

• More comprehensive than OSV-Scanner for SCA needs
• Use with CDXGen for enhanced SBOM generation
• Combine with code scanners (Semgrep, CodeQL) for complete coverage
• Use with SARIF Issue Reporter for findings analysis

When NOT to Use

Do NOT use this skill for:

• Application code vulnerability scanning (use Semgrep or CodeQL)
• Secrets detection (use Gitleaks)
• IaC security analysis (use KICS)
• API endpoint discovery (use Noir)
• Quick lightweight SCA (use OSV-Scanner instead)

Installation

# pip/pipx (recommended)
pipx install owasp-depscan

# pip
pip install owasp-depscan

# With SARIF tools
pipx install owasp-depscan sarif-tools

# Docker
docker pull ghcr.io/owasp-dep-scan/dep-scan:latest

# From source
git clone https://github.com/owasp-dep-scan/dep-scan.git
cd dep-scan
pip install .

# Verify
depscan --version

Core Workflow

1. Quick Scan

# Scan current directory
depscan --src .

# Scan specific directory
depscan --src /path/to/project

# Scan with reports directory
depscan --src /path/to/project --reports-dir ./reports

2. SARIF Output

# Generate SARIF report
depscan --src /path/to/project \
  --reports-dir ./reports \
  --report-template sarif

# Multiple report formats
depscan --src /path/to/project \
  --reports-dir ./reports \
  --report-template sarif,json,html

# Critical vulnerabilities only (SARIF)
depscan --src /path/to/project \
  --reports-dir ./reports \
  --report-template sarif-critical

3. SBOM Generation

# Create CycloneDX SBOM
depscan --src /path/to/project \
  --reports-dir ./reports \
  --type bom

# SBOM with VDR (Vulnerability Disclosure Report)
depscan --src /path/to/project \
  --reports-dir ./reports \
  --type sbom-vdr

# Use existing SBOM
depscan --bom /path/to/sbom.json --reports-dir ./reports

4. VEX Document Generation

# Generate CSAF 2.0 VEX
depscan --src /path/to/project \
  --reports-dir ./reports \
  --vex

# VEX with existing SBOM
depscan --bom sbom.json \
  --reports-dir ./reports \
  --vex

Supported Package Managers

| Ecosystem | Manifest Files | Lock Files | |-----------|----------------|------------| | npm | package.json | package-lock.json, yarn.lock, pnpm-lock.yaml | | Python | requirements.txt, setup.py, pyproject.toml | Pipfile.lock, poetry.lock, pdm.lock | | Go | go.mod | go.sum | | Rust | Cargo.toml | Cargo.lock | | Java/Maven | pom.xml | - | | Gradle | build.gradle, build.gradle.kts | - | | Ruby | Gemfile | Gemfile.lock | | PHP | composer.json | composer.lock | | .NET | packages.config, *.csproj | packages.lock.json, paket.lock | | Dart | pubspec.yaml | pubspec.lock | | Swift | Package.swift | Package.resolved |

Advanced Features

Risk Scoring

# Enable risk audit
depscan --src /path/to/project \
  --reports-dir ./reports \
  --risk-audit

# Risk score is calculated based on:
# - Vulnerability severity
# - CVSS scores
# - Exploitability
# - Attack complexity
# - Package popularity
# - Maintenance status

License Compliance

# License audit
depscan --src /path/to/project \
  --reports-dir ./reports \
  --license-scan

# Fail on license violations
depscan --src /path/to/project \
  --reports-dir ./reports \
  --license-scan \
  --no-banner \
  --fail-on-license-violation

CDXGen Integration

Depscan includes CDXGen for SBOM generation:

# Use cdxgen directly
cdxgen -r /path/to/project -o sbom.json

# Generate SBOM with evidence
cdxgen -r /path/to/project -o sbom.json --evidence

# Multiple languages
cdxgen -r /monorepo -o sbom.json --multi-language

# Then scan SBOM
depscan --bom sbom.json --reports-dir ./reports

Specific Language Scans

# Python specific
depscan --src /python/project --type python --reports-dir ./reports

# Node.js specific
depscan --src /nodejs/project --type nodejs --reports-dir ./reports

# Java specific
depscan --src /java/project --type java --reports-dir ./reports

# Go specific
depscan --src /go/project --type go --reports-dir ./reports

CI/CD Integration (GitHub Actions)

name: OWASP Depscan

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * *'  # Daily

jobs:
  depscan:
    runs-on: ubuntu-latest
    container: ghcr.io/owasp-dep-scan/dep-scan:latest

    steps:
      - uses: actions/checkout@v4

      - name: Run Depscan
        run: |
          depscan --src ${{ github.workspace }} \
            --reports-dir ${{ github.workspace }}/reports \
            --report-template sarif,json,html \
            --risk-audit \
            --license-scan

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: reports/depscan.sarif
          category: depscan

      - name: Upload Reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: depscan-reports
          path: reports/

      - name: Generate SBOM
        run: |
          cdxgen -r ${{ github.workspace }} \
            -o reports/sbom.json \
            --evidence

      - name: Upload SBOM
        uses: actions/upload-artifact@v4
        with:
          name: sbom
          path: reports/sbom.json

Report Templates

Available Templates

# SARIF (all vulnerabilities)
--report-template sarif

# SARIF (critical only)
--report-template sarif-critical

# JSON format
--report-template json

# HTML report
--report-template html

# Custom template
--report-template custom.j2

Custom Jinja Templates

Create custom-report.j2:

# Vulnerability Report

Project: {{ project_name }}
Scan Date: {{ scan_date }}

## Summary

Total Vulnerabilities: {{ total_vulnerabilities }}
- Critical: {{ critical_count }}
- High: {{ high_count }}
- Medium: {{ medium_count }}
- Low: {{ low_count }}

## Vulnerabilities

{% for vuln in vulnerabilities %}
### {{ vuln.id }} - {{ vuln.severity }}

**Package:** {{ vuln.package }}@{{ vuln.version }}
**Fixed in:** {{ vuln.fixed_version }}
**CVSS:** {{ vuln.cvss_score }}

{{ vuln.description }}

---
{% endfor %}

Use custom template:

depscan --src /path/to/project \
  --reports-dir ./reports \
  --report-template custom-report.j2

Configuration

Config File

Create depscan.toml:

# Source paths
src = "/path/to/project"
reports_dir = "./reports"

# Scan options
risk_audit = true
license_scan = true
no_banner = true

# Report formats
report_template = ["sarif", "json", "html"]

# VEX generation
vex = true

# Fail conditions
fail_on_license_violation = false

# Exclude paths
exclude = [
    "**/test/**",
    "**/tests/**",
    "**/node_modules/**",
    "**/.venv/**"
]

# License allowlist
allowed_licenses = [
    "MIT",
    "Apache-2.0",
    "BSD-3-Clause",
    "BSD-2-Clause",
    "ISC"
]

Use config:

depscan --config depscan.toml

Common Use Cases

1. Comprehensive SCA Audit

# Full audit with all features
depscan --src /path/to/project \
  --reports-dir ./audit-reports \
  --report-template sarif,json,html \
  --risk-audit \
  --license-scan \
  --vex

# Review reports
ls -la ./audit-reports/
# - depscan.sarif
# - depscan.json
# - depscan.html
# - bom.json (SBOM)
# - vex.json (VEX document)

2. SBOM + VDR Workflow

# Step 1: Generate SBOM with evidence
cdxgen -r /path/to/project -o sbom.json --evidence

# Step 2: Scan SBOM for vulnerabilities
depscan --bom sbom.json \
  --reports-dir ./reports \
  --type sbom-vdr

# Step 3: Generate VEX
depscan --bom sbom.json \
  --reports-dir ./reports \
  --vex

# Outputs:
# - sbom.json (Software Bill of Materials)
# - vdr.json (Vulnerability Disclosure Report)
# - vex.json (Vulnerability Exploitability eXchange)

3. License Compliance Check

# Audit licenses
depscan --src /path/to/project \
  --license-scan \
  --reports-dir ./compliance

# Review license report
cat ./compliance/license-report.json | jq '.licenses[] | select(.approved == false)'

# Fail build on violations
depscan --src /path/to/project \
  --license-scan \
  --fail-on-license-violation

4. Container Image Analysis

# Extract container filesystem
docker export $(docker create myimage:latest) | tar -C /tmp/container-fs -xf -

# Scan extracted filesystem
depscan --src /tmp/container-fs \
  --reports-dir ./container-reports \
  --report-template sarif

# Or use with Docker
docker run --rm -v $(pwd):/app ghcr.io/owasp-dep-scan/dep-scan \
  depscan --src /app --reports-dir /app/reports

Understanding Output

SARIF Structure

Depscan SARIF includes:

• Rules: Each vulnerability type
• Results: Vulnerable dependencies
• Properties:
  • Package name and version
  • Vulnerability ID (CVE, GHSA, etc.)
  • Severity and CVSS
  • Fix versions
  • Risk score
  • Exploitability metrics
  • License information

VDR Structure

Vulnerability Disclosure Report (VDR) in CycloneDX format:

{
  "vulnerabilities": [
    {
      "id": "CVE-2024-12345",
      "source": {
        "name": "NVD",
        "url": "https://nvd.nist.gov/vuln/detail/CVE-2024-12345"
      },
      "ratings": [
        {
          "score": 9.8,
          "severity": "critical",
          "method": "CVSSv3",
          "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
        }
      ],
      "affects": [
        {
          "ref": "pkg:npm/[email protected]"
        }
      ],
      "recommendation": "Upgrade to version 4.17.21 or later"
    }
  ]
}

VEX Structure

CSAF 2.0 VEX document:

{
  "document": {
    "category": "csaf_vex",
    "title": "Vulnerability Exploitability eXchange"
  },
  "vulnerabilities": [
    {
      "cve": "CVE-2024-12345",
      "product_status": {
        "known_affected": ["pkg:npm/[email protected]"]
      },
      "remediation": [
        {
          "category": "vendor_fix",
          "details": "Update to version 4.17.21"
        }
      ]
    }
  ]
}

Remediation Workflow

Step 1: Scan

depscan --src /project \
  --reports-dir ./reports \
  --report-template json,sarif \
  --risk-audit

Step 2: Prioritize

# Extract high-risk vulnerabilities
jq '.results[] | select(.risk_score > 7)' reports/depscan.json

# Group by package
jq -r '.results[] | "\(.package): \(.vulnerabilities | length) vulns"' reports/depscan.json | sort

Step 3: Fix

# Review fix recommendations
jq -r '.results[] | "\(.package)@\(.version) -> \(.fixed_version // "No fix available")"' reports/depscan.json

# Apply updates
npm update
pip install --upgrade -r requirements.txt

Step 4: Verify

# Rescan
depscan --src /project --reports-dir ./post-fix

# Compare
diff <(jq '.results[].id' reports/depscan.json | sort) \
     <(jq '.results[].id' post-fix/depscan.json | sort)

Performance Optimization

# Skip network calls for faster offline scanning
depscan --src /project --offline

# Limit report generation
depscan --src /project --report-template sarif

# Exclude test directories
depscan --src /project --exclude "**/test/**,**/tests/**"

# Use existing SBOM instead of regenerating
depscan --bom sbom.json --reports-dir ./reports

Integration with Other Tools

SARIF Tools

# Generate SARIF
depscan --src /project --reports-dir ./reports --report-template sarif

# Analyze with sarif-tools
pip install sarif-tools
sarif summary reports/depscan.sarif
sarif ls reports/depscan.sarif
sarif trends reports/*.sarif

Dependency Track

# Generate SBOM+VDR for Dependency Track
depscan --src /project \
  --reports-dir ./reports \
  --type sbom-vdr

# Upload to Dependency Track
curl -X POST "https://dependency-track/api/v1/bom" \
  -H "X-API-Key: ${API_KEY}" \
  -F "bom=@reports/bom.json"

Limitations

• Performance: Slower than OSV-Scanner due to deeper analysis
• Network required: Needs internet for vulnerability database (unless offline mode)
• Memory usage: Large projects may require significant RAM
• False positives: Risk scoring heuristics may over/under estimate
• Private packages: Only scans public vulnerability databases

Rationalizations to Reject

| Shortcut | Why It's Wrong | |----------|----------------| | "OSV-Scanner is enough" | Depscan provides VDR, VEX, risk scoring, and license compliance OSV lacks | | "Skip VEX generation" | VEX documents are critical for communicating vulnerability status to stakeholders | | "Disable risk audit for speed" | Risk scores help prioritize fixes; speed shouldn't compromise decision quality | | "Ignore license violations" | License compliance is legal requirement; violations can block product release | | "Only scan production dependencies" | Dev dependencies can introduce supply chain attacks |

References

• Repository: https://github.com/owasp-dep-scan/dep-scan
• Documentation: https://depscan.readthedocs.io/
• OWASP Project: https://owasp.org/www-project-dep-scan/
• CDXGen: https://github.com/CycloneDX/cdxgen
• CycloneDX Spec: https://cyclonedx.org/
• CSAF Spec: https://docs.oasis-open.org/csaf/csaf/v2.0/csaf-v2.0.html
• SARIF Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html