depscan

What this skill does

# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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)

```yaml
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

```bash
# 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`:

```jinja
# 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:

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

## Configuration

### Config File

Create `depscan.toml`:

```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:

```bash
depscan --config depscan.toml
```

## Common Use Cases

### 1. Comprehensive SCA Audit

```bash
# 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

```bash
# 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