scan_directory

FIRST STEP: Scan a directory for compliance issues using purl2notices.

This is typically the FIRST tool you should use when analyzing a project. Use this to discover what's in your project before validation or documentation generation.

PURPOSE:

• Scan project source code for licenses (using purl2notices)

• Detect ALL packages including transitive dependencies (scans node_modules/, site-packages/, vendor/)

• Extract copyright statements from source code

• Check for vulnerabilities (using vulnq)

• Validate against policy (using ospac)

WHAT purl2notices DETECTS:

• Project source licenses (from your own code)

• Dependency packages (ALL packages in node_modules/, not just package.json)

• Package licenses (from dependency source code)

• Copyright holders (extracted from actual source files)

IMPORTANT: This tool scans the ENTIRE dependency tree:

• For npm projects: All 50+ packages in node_modules/ (not just the 1-2 in package.json)

• For Python projects: All packages in site-packages/ or virtualenv

• Includes transitive dependencies automatically

WHEN TO USE:

• Starting compliance analysis for a new project (FIRST STEP)

• Need to discover all licenses in source code

• Want to identify all package dependencies (including transitive)

• Beginning vulnerability assessment

• Need comprehensive project analysis with copyright attribution

WHEN NOT TO USE:

• Already have PURLs and just need legal notices → use generate_legal_notices directly

• Analyzing compiled binaries → use scan_binary instead

• Just validating known licenses → use validate_license_list

• Checking single package → use check_package

WORKFLOW POSITION: FIRST STEP in most compliance workflows. Use this to discover what's in your project before validation/generation.

TYPICAL NEXT STEPS:

1. For mobile apps: scan_directory(check_vulnerabilities=True) → validate_license_list(distribution="mobile") → generate_legal_notices(purls=scan_result["packages"])

2. For vulnerability assessment: scan_directory(check_vulnerabilities=True) → analyze_commercial_risk(path=".") → check specific packages with check_package for details

3. For documentation: scan_directory() → generate_legal_notices(purls=scan_result["packages"]) → generate_sbom(path=".")

IMPORTANT NOTES:

• identify_packages parameter is deprecated (purl2notices always detects packages)

• check_vulnerabilities=True: Checks all detected packages for CVEs

• check_licenses parameter is deprecated (purl2notices always scans licenses)

• Scans recursively by default (max depth 3 into node_modules/)

Args: path: Directory or file path to scan recursive: Enable recursive scanning (default: True, max depth 3) check_vulnerabilities: Check for vulnerabilities in detected packages check_licenses: (Deprecated - always True) Scan for licenses identify_packages: (Deprecated - always True) Detect packages policy_file: Optional policy file for license compliance validation

Returns: Dictionary containing: - licenses: List of detected licenses from project and dependencies - packages: List of ALL detected packages with PURLs (includes transitive deps) - vulnerabilities: List of vulnerabilities (if check_vulnerabilities=True) - policy_violations: Policy violations (if policy_file provided) - metadata: Summary information including copyright holders and counts