dependency-check-security-scan

name: dependency-check-security-scan description: Scan project dependencies for known vulnerabilities (CVEs) using OWASP Dependency-Check. (1) Primary use for Software Composition Analysis (SCA) of Java (.jar, .war, .ear), .NET (.dll, .exe, .nupkg), JavaScript (package.json, .js), Python (requirements.txt), Ruby (Gemfile.lock), and Go (go.mod) projects. (2) Detects CVEs from NVD, CISA KEV, OSS Index, RetireJS. (3) Use for dependency audits, CI/CD security gates, compliance scanning, supply chain risk assessment. Do NOT use for source code vulnerabilities (use bandit, graudit) or malicious package detection (use guarddog).

OWASP Dependency-Check Security Scanning Skill

This skill enables scanning project dependencies for known vulnerabilities using OWASP Dependency-Check - a Software Composition Analysis (SCA) tool that identifies CVEs in third-party libraries by matching dependencies to the National Vulnerability Database (NVD).

Key Distinction: Dependency-Check detects known vulnerabilities (CVEs) in dependencies. For malicious package detection (malware, supply chain attacks), use guarddog. For source code vulnerabilities, use bandit (Python), graudit (multi-language), or shellcheck (shell scripts).

Quick Reference

When to Use This Skill

PRIMARY USE CASES:

• Audit third-party dependencies for known CVEs before deployment
• CI/CD security gates requiring vulnerability-free dependencies
• Compliance scanning (SOC2, PCI-DSS, HIPAA) requiring SCA
• Supply chain risk assessment for software bill of materials (SBOM)
• Investigating security advisories for affected dependencies
• Pre-merge checks for dependency updates

SUPPORTED ECOSYSTEMS:

• Java/Kotlin: .jar, .war, .ear, Maven pom.xml, Gradle
• .NET/C#: .dll, .exe, .nupkg, packages.config, *.csproj
• JavaScript/Node.js: package.json, package-lock.json, .js files
• Python: requirements.txt, setup.py, PKG-INFO (experimental)
• Ruby: Gemfile.lock, *.gemspec (experimental)
• Go: go.mod, Gopkg.lock (experimental)
• PHP: composer.lock (experimental)
• Swift: Package.swift (experimental)
• Dart: pubspec.yaml (experimental)

DO NOT USE FOR:

• Detecting malicious packages/malware → use guarddog
• Scanning your own source code for vulnerabilities → use bandit, graudit
• Shell script security → use shellcheck
• Secrets detection → use graudit -d secrets

Decision Tree: Choosing the Right Tool

What are you analyzing?
│
├── Third-party dependencies for KNOWN CVEs?
│   └── dependency-check --scan ./project
│
├── Third-party packages for MALWARE/supply chain attacks?
│   └── guarddog pypi/npm scan <package>
│
├── Your own source code?
│   ├── Python → bandit -r ./src
│   ├── Multi-language → graudit -d <lang> ./src
│   └── Shell scripts → shellcheck *.sh
│
└── Combined audit?
    ├── Step 1: dependency-check (CVEs in dependencies)
    ├── Step 2: guarddog (malware in packages)
    └── Step 3: bandit/graudit (source code vulnerabilities)

Prerequisites

Installation Options

Option 1: Homebrew (macOS - Recommended)

brew install dependency-check
dependency-check --help

Option 2: CLI Standalone Download

# Get latest version
VERSION=$(curl -s https://dependency-check.github.io/DependencyCheck/current.txt)

# Download and extract
curl -Ls "https://github.com/dependency-check/DependencyCheck/releases/download/v$VERSION/dependency-check-$VERSION-release.zip" -o dependency-check.zip
unzip dependency-check.zip

# Run (Linux/macOS)
./dependency-check/bin/dependency-check.sh --help

# Run (Windows)
.\dependency-check\bin\dependency-check.bat --help

Option 3: Docker (No Local Install)

docker pull owasp/dependency-check:latest

# Create alias for convenience
alias dependency-check='docker run --rm -v "$(pwd):/src" -v "$HOME/.dependency-check:/usr/share/dependency-check/data" owasp/dependency-check'

Option 4: Maven Plugin

<plugin>
  <groupId>org.owasp</groupId>
  <artifactId>dependency-check-maven</artifactId>
  <version>12.2.0</version>
</plugin>

mvn org.owasp:dependency-check-maven:check

Option 5: Gradle Plugin

plugins {
    id 'org.owasp.dependencycheck' version '12.2.0'
}

./gradlew dependencyCheckAnalyze

NVD API Key (Highly Recommended)

Without an API key, database updates are extremely slow (rate limited).

1. Register at: https://nvd.nist.gov/developers/request-an-api-key
2. Set via command line: --nvdApiKey YOUR_KEY
3. Or environment variable: export NVD_API_KEY=your-key

Core Scanning Commands

Basic Project Scan

# Scan current directory with HTML report
dependency-check.sh --scan ./ --out ./reports --project "MyProject"

# Scan specific paths
dependency-check.sh --scan ./lib --scan ./target --out ./reports

# Scan with NVD API key (recommended)
dependency-check.sh --scan ./ --out ./reports --nvdApiKey $NVD_API_KEY

Output Formats

# HTML report (default, human-readable)
dependency-check.sh --scan ./ --format HTML --out ./reports

# JSON report (for automation)
dependency-check.sh --scan ./ --format JSON --prettyPrint --out ./reports

# SARIF report (for GitHub Security, CI/CD)
dependency-check.sh --scan ./ --format SARIF --out ./reports

# Multiple formats at once
dependency-check.sh --scan ./ --format HTML --format JSON --format SARIF --out ./reports

# All formats
dependency-check.sh --scan ./ --format ALL --out ./reports

CI/CD Integration Commands

# Fail build if any CVE has CVSS score >= 7 (HIGH or CRITICAL)
dependency-check.sh --scan ./ --failOnCVSS 7 --format SARIF --out ./reports

# Fail on CRITICAL only (CVSS >= 9)
dependency-check.sh --scan ./ --failOnCVSS 9 --format JSON --out ./reports

# With suppression file for known false positives
dependency-check.sh --scan ./ --suppression ./suppression.xml --failOnCVSS 7

Docker Scanning

# Basic Docker scan
docker run --rm \
    -v $(pwd):/src:z \
    -v $(pwd)/reports:/report:z \
    -v $HOME/.dependency-check:/usr/share/dependency-check/data:z \
    owasp/dependency-check:latest \
    --scan /src \
    --format HTML \
    --format JSON \
    --out /report \
    --project "MyProject"

# With NVD API key
docker run --rm \
    -e NVD_API_KEY=$NVD_API_KEY \
    -v $(pwd):/src:z \
    -v $(pwd)/reports:/report:z \
    owasp/dependency-check:latest \
    --scan /src \
    --nvdApiKey $NVD_API_KEY \
    --out /report

Database Management

# Update database only (no scan)
dependency-check.sh --updateonly --nvdApiKey $NVD_API_KEY

# Purge and rebuild database
dependency-check.sh --purge
dependency-check.sh --updateonly --nvdApiKey $NVD_API_KEY

# Skip update during scan (use cached data)
dependency-check.sh --scan ./ --noupdate

CLI Options Reference

Available Analyzers

Production Analyzers (Enabled by Default)

Experimental Analyzers (Enable with --enableExperimental)

Vulnerability Sources

OWASP Dependency-Check aggregates vulnerability data from multiple sources:

MITRE ATT&CK Mappings

Vulnerabilities detected by Dependency-Check map to these attack techniques:

Workflow for Security Audit

Quick Scan (Development)

# Fast scan with cached database
dependency-check.sh --scan ./ --noupdate --format HTML --out ./reports

Standard Scan (Pre-Deployment)

# Full scan with latest data
dependency-check.sh --scan ./ \
    --nvdApiKey $NVD_API_KEY \
    --format HTML --format JSON \
    --out ./reports \
    --project "MyApp-v1.0"

CI/CD Gate Scan

# Fail on high/critical vulnerabilities
dependency-check.sh --scan ./ \
    --nvdApiKey $NVD_API_KEY \
    --failOnCVSS 7 \
    --suppression ./suppression.xml \
    --format SARIF \
    --out ./reports

Complete Security Audit Workflow

# Step 1: Scan dependencies for known CVEs
dependency-check.sh --scan ./ --format JSON --out ./reports --nvdApiKey $NVD_API_KEY

# Step 2: Check for malicious packages (if Python/Node.js)
guarddog pypi verify requirements.txt
guarddog npm verify package-lock.json

# Step 3: Scan source code for vulnerabilities
bandit -r ./src -f json -o bandit-report.json  # Python
graudit -d secrets ./src                        # Secrets detection

# Step 4: Review results
cat ./reports/dependency-check-report.json | jq '.dependencies[] | select(.vulnerabilities)'

CI/CD Integration

GitHub Actions

name: Dependency Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Cache Dependency-Check data
        uses: actions/cache@v4
        with:
          path: ~/.dependency-check
          key: ${{ runner.os }}-dc-${{ github.run_id }}
          restore-keys: ${{ runner.os }}-dc-
      
      - name: Run Dependency-Check
        uses: dependency-check/Dependency-Check_Action@main
        with:
          project: '${{ github.repository }}'
          path: '.'
          format: 'HTML,JSON,SARIF'
          args: >
            --nvdApiKey ${{ secrets.NVD_API_KEY }}
            --failOnCVSS 7
            --enableExperimental
      
      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: reports/dependency-check-report.sarif
      
      - name: Upload Reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: dependency-check-reports
          path: reports/

GitLab CI

dependency-check:
  image: owasp/dependency-check:latest
  stage: test
  script:
    - /usr/share/dependency-check/bin/dependency-check.sh
        --scan .
        --format GITLAB
        --format JSON
        --out ./reports
        --nvdApiKey $NVD_API_KEY
        --failOnCVSS 7
  artifacts:
    paths:
      - reports/
    reports:
      dependency_scanning: reports/dependency-check-report.json
  allow_failure: true

Jenkins Pipeline

pipeline {
    agent any
    stages {
        stage('Dependency Check') {
            steps {
                dependencyCheck additionalArguments: '''
                    --scan .
                    --format HTML
                    --format JSON
                    --nvdApiKey ${NVD_API_KEY}
                    --failOnCVSS 7
                ''', odcInstallation: 'dependency-check'
            }
            post {
                always {
                    dependencyCheckPublisher pattern: 'dependency-check-report.xml'
                }
            }
        }
    }
}

Managing False Positives

Suppression File Format

Create suppression.xml to exclude known false positives:

<?xml version="1.0" encoding="UTF-8"?>
<suppressions xmlns="https://jeremylong.github.io/DependencyCheck/dependency-suppression.1.4.xsd">
   
   <!-- Suppress by SHA1 hash and CPE -->
   <suppress>
      <notes><![CDATA[False positive - driver CVE applies to server, not client]]></notes>
      <sha1>66734244CE86857018B023A8C56AE0635C56B6A1</sha1>
      <cpe>cpe:/a:mysql:mysql:5.7</cpe>
   </suppress>
   
   <!-- Suppress specific CVE -->
   <suppress>
      <notes><![CDATA[Not applicable - we don't use the affected feature]]></notes>
      <cve>CVE-2024-12345</cve>
   </suppress>
   
   <!-- Suppress by file path pattern -->
   <suppress>
      <notes><![CDATA[Test dependencies only]]></notes>
      <filePath regex="true">.*test.*\.jar</filePath>
      <cvssBelow>7</cvssBelow>
   </suppress>
   
   <!-- Temporary suppression with expiration -->
   <suppress until="2026-06-01Z">
      <notes><![CDATA[Pending upgrade - ticket PROJ-123]]></notes>
      <gav regex="true">^com\.example:vulnerable-lib:.*$</gav>
   </suppress>
   
</suppressions>

Using Suppression File

dependency-check.sh --scan ./ --suppression ./suppression.xml --out ./reports

Interpreting Results

HTML Report Sections

1. Summary: Total dependencies, vulnerable count, severity breakdown
2. Dependencies: List of all scanned files with identification confidence
3. Vulnerabilities: CVE details with CVSS scores, descriptions, references

JSON Report Key Fields

# Extract vulnerable dependencies
cat report.json | jq '.dependencies[] | select(.vulnerabilities != null) | {file: .fileName, vulns: [.vulnerabilities[].name]}'

# List all HIGH/CRITICAL CVEs
cat report.json | jq '.dependencies[].vulnerabilities[]? | select(.cvssv3.baseScore >= 7) | {cve: .name, score: .cvssv3.baseScore}'

# Count by severity
cat report.json | jq '[.dependencies[].vulnerabilities[]?] | group_by(.severity) | map({severity: .[0].severity, count: length})'

Severity Levels

Limitations

Known Limitations

1. False Positives: CPE-based matching can incorrectly identify libraries. Database drivers often match server CVEs. Use suppression files.

2. False Negatives: Libraries with insufficient metadata may not be identified. Built-from-source artifacts may differ from published versions.

3. No Hash-Based Matching: Does not use file hashes for identification, relying on metadata/evidence instead.

4. Initial Download Time: First run requires 5-20 minutes to download NVD data (faster with API key).

5. Rate Limiting: NVD API enforces rate limits. Multiple concurrent builds with same API key may fail with 403 errors.

6. Internet Required: Must access NVD, CISA, OSS Index for vulnerability data.

7. External Tool Dependencies:

   • .NET analysis requires dotnet 8.0 runtime
   • Ruby analysis requires bundle-audit gem
   • Node.js analysis requires npm/yarn

8. No Malware Detection: Detects only known CVEs, not malicious code. Use guarddog for malware detection.

Performance Optimization

# Parallel execution (set Java heap)
export JAVA_OPTS="-Xmx4g"

# Use NVD API key (required for reasonable speed)
dependency-check.sh --scan ./ --nvdApiKey $NVD_API_KEY

# Cache database between runs
# Database stored in ~/.dependency-check by default

# Skip update for quick scans (use cached data)
dependency-check.sh --scan ./ --noupdate

Combining with Other Security Tools

Complete Supply Chain Audit

#!/bin/bash
# Full supply chain security audit

echo "=== Step 1: Dependency CVE Scan ==="
dependency-check.sh --scan ./ --format JSON --out ./reports --nvdApiKey $NVD_API_KEY

echo "=== Step 2: Malicious Package Detection ==="
[ -f requirements.txt ] && guarddog pypi verify requirements.txt
[ -f package-lock.json ] && guarddog npm verify package-lock.json

echo "=== Step 3: Source Code Security ==="
find . -name "*.py" -type f | head -1 && bandit -r ./src -f json -o bandit.json
graudit -d secrets ./

echo "=== Step 4: Shell Script Audit ==="
find . -name "*.sh" -exec shellcheck {} \;

echo "=== Audit Complete ==="

Troubleshooting

Additional Resources

• Official Documentation
• GitHub Repository
• NVD API Key Registration
• Suppression File Examples
• Common Vulnerabilities Reference