Time-Aware Dependency CVE Scanner

Scan repositories for newly disclosed CVEs affecting dependencies after a specific cutoff date. This skill helps track when vulnerabilities were introduced and distinguish between pre-existing and newly disclosed security issues.

Quick Start

Basic scan:

python scripts/scan_repository.py /path/to/repo 2023-01-01

Scan only direct dependencies:

python scripts/scan_repository.py /path/to/repo 2023-01-01 --no-transitive

Output as JSON:

python scripts/scan_repository.py /path/to/repo 2023-01-01 --json > report.json

Workflow

1. Parse Dependencies

The scanner automatically detects and parses dependency manifests:

Supported ecosystems:

• npm: package.json, package-lock.json, yarn.lock
• Maven: pom.xml
• Python: requirements.txt, Pipfile.lock, poetry.lock
• Go: go.mod, go.sum
• Cargo: Cargo.toml, Cargo.lock

Manual parsing (if needed):

python scripts/parse_dependencies.py /path/to/repo

This extracts:

• Package names and exact versions
• Direct vs transitive dependency classification
• Ecosystem identification

For detailed manifest formats, see references/dependency_formats.md

2. Query Vulnerability Databases

The scanner queries multiple databases to find CVEs:

Primary source: OSV.dev (Open Source Vulnerabilities)

• No authentication required
• Broad ecosystem coverage (npm, PyPI, Maven, Go, crates.io, etc.)
• Built-in version matching
• Real-time updates

Additional sources:

• NVD (National Vulnerability Database) - Official CVE records
• GitHub Security Advisory - GitHub-curated vulnerabilities

Manual CVE query (for testing):

python scripts/query_cves.py lodash 4.17.20 npm 2023-01-01

For database details and API usage, see references/vulnerability_databases.md

3. Filter by Cutoff Date

The scanner filters CVEs to include only those disclosed after the cutoff date:

• Uses the published date from vulnerability databases
• Excludes CVEs disclosed before or on the cutoff date
• Distinguishes newly disclosed vulnerabilities from pre-existing ones

Example:

• Cutoff date: 2023-01-01
• CVE-2023-12345 published: 2023-06-15 → Included ✓
• CVE-2022-98765 published: 2022-11-20 → Excluded ✗

4. Generate Report

The scanner produces a comprehensive report with:

Summary statistics:

• Total dependencies (direct vs transitive)
• Number of new CVEs found
• CVEs affecting direct vs transitive dependencies
• Severity breakdown (CRITICAL, HIGH, MEDIUM, LOW)

Detailed CVE list: For each CVE:

• CVE identifier (CVE-XXXX-XXXXX or GHSA-XXXX-XXXX-XXXX)
• Affected package and ecosystem
• Version range affected
• Severity score
• Disclosure date
• Summary description

Clear status: If no new CVEs found, explicitly reports "dependency set is clear since the given date"

Use Cases

Security Audit

Scenario: Periodic security review to find vulnerabilities disclosed since last audit

# Last audit was on 2023-06-01, check for new CVEs since then
python scripts/scan_repository.py /path/to/repo 2023-06-01

Output: List of all CVEs disclosed after June 1, 2023 that affect your dependencies

Regression Testing

Scenario: Check if new CVEs affect a specific historical codebase version

# Check if any CVEs disclosed after 2023-01-01 affect code from that date
git checkout <commit-from-2023-01-01>
python scripts/scan_repository.py . 2023-01-01

Output: Shows which vulnerabilities were discovered after the code was written

Compliance Reporting

Scenario: Generate reports showing vulnerability status at specific dates

# Generate quarterly reports
python scripts/scan_repository.py /path/to/repo 2023-01-01 --json > q1_report.json
python scripts/scan_repository.py /path/to/repo 2023-04-01 --json > q2_report.json
python scripts/scan_repository.py /path/to/repo 2023-07-01 --json > q3_report.json

Output: Time-series data showing when vulnerabilities were disclosed

Tracking Security Posture

Scenario: Monitor how security posture changes over time

# Compare vulnerability counts at different dates
python scripts/scan_repository.py /path/to/repo 2022-01-01 | grep "new CVE"
python scripts/scan_repository.py /path/to/repo 2023-01-01 | grep "new CVE"
python scripts/scan_repository.py /path/to/repo 2024-01-01 | grep "new CVE"

Output: Trend analysis of vulnerability accumulation

Advanced Options

Limit Scan Scope

For large repositories, limit the number of dependencies scanned:

python scripts/scan_repository.py /path/to/repo 2023-01-01 --max-deps 50

Direct Dependencies Only

Skip transitive dependencies to focus on direct dependencies:

python scripts/scan_repository.py /path/to/repo 2023-01-01 --no-transitive

JSON Output for Automation

Output structured JSON for integration with other tools:

python scripts/scan_repository.py /path/to/repo 2023-01-01 --json | jq '.summary'

Understanding Results

Report Structure

TIME-AWARE DEPENDENCY CVE SCAN REPORT
======================================================================
Repository: /path/to/repo
Cutoff Date: 2023-01-01
Scan Time: 2024-02-19T10:30:00

DEPENDENCY SUMMARY
----------------------------------------------------------------------
  Total Dependencies: 150
    - Direct: 25
    - Transitive: 125

CVE SUMMARY
----------------------------------------------------------------------
  ⚠ 5 new CVE(s) found after 2023-01-01
    - Affecting direct dependencies: 2
    - Affecting transitive dependencies: 3

  Severity Breakdown:
    - CRITICAL: 1
    - HIGH: 2
    - MEDIUM: 2

DETAILED CVE LIST
----------------------------------------------------------------------

CVE-2023-12345 [CRITICAL]
  Package: lodash (npm)
  Disclosed: 2023-06-15
  Affected Versions: >=4.0.0, <4.17.21
  Summary: Prototype pollution vulnerability...

Interpreting Severity

• CRITICAL: Immediate action required, actively exploited
• HIGH: Serious vulnerability, patch soon
• MEDIUM: Moderate risk, plan remediation
• LOW: Minor issue, low priority
• UNKNOWN: Severity not yet assessed

Next Steps After Scan

1. Review CVEs: Examine each vulnerability's details
2. Check exploitability: Determine if your code uses affected functionality
3. Update dependencies: Upgrade to patched versions
4. Re-scan: Verify fixes with another scan
5. Document: Record findings and remediation actions

Troubleshooting

No dependencies found

• Ensure you're in the repository root
• Check that manifest files exist (package.json, pom.xml, etc.)
• Verify file permissions

API rate limits

• OSV.dev has generous limits, but add delays if hitting limits
• For NVD, get an API key: https://nvd.nist.gov/developers/request-an-api-key
• For GitHub Advisory, set GITHUB_TOKEN environment variable

Parsing errors

• Ensure manifest files are valid JSON/XML/TOML
• Check for syntax errors in dependency declarations
• Some ecosystems may require additional tools (e.g., tomli for Python TOML files)

Dependencies

The scanner scripts require:

• Python 3.7+
• requests library: pip install requests
• Optional: tomli for TOML parsing: pip install tomli