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

Check a specific package using intelligent tool selection.

This tool intelligently analyzes package files by:

1. For archives (.jar, .whl, .rpm, .gem, etc.): Use upmex for metadata extraction

2. If upmex fails or for non-archives: Fall back to osslili for license detection

3. For PURLs: Use package registry APIs when available

Args: identifier: Package identifier (PURL like pkg:maven/com.google.gson/gson@2.10.1, file path to archive, or package file) check_vulnerabilities: Whether to check for vulnerabilities (default: False for speed) check_licenses: Whether to extract license information (default: True)

Returns: Dictionary containing package metadata, licenses, and optionally vulnerabilities

Validate if licenses are approved or rejected for a specific project/distribution type.

This tool evaluates licenses against organizational policies and returns clear APPROVE or DENY decisions based on the distribution type. This is the primary tool for answering: "Can I use these licenses for my [mobile/commercial/saas/etc] project?"

Key Use Cases:

• Check if licenses are approved for mobile app distribution

• Validate licenses for commercial products

• Ensure SaaS deployment compliance

• Verify licenses for embedded systems

• Check licenses for any distribution type

Returns clear approve/deny decisions:

• action: "approve" (licenses are allowed), "deny" (licenses blocked), or "review" (manual review needed)

• severity: "info" (approved), "warning" (review), "error" (denied)

• message: Explanation of the decision

• requirements: What must be done to comply (if approved)

• remediation: How to fix the issue (if denied)

Args: licenses: List of SPDX license IDs to validate (e.g., ["MIT", "Apache-2.0", "GPL-3.0"]) policy_file: Optional custom policy directory (uses enterprise defaults if not provided) distribution: Distribution type - determines policy rules: - "mobile": iOS/Android apps (blocks GPL, allows permissive) - "commercial": Commercial products (blocks strong copyleft) - "saas": Software as a Service (blocks AGPL, allows GPL) - "embedded": Embedded systems (blocks copyleft) - "desktop": Desktop applications - "web": Web applications - "open_source": Open source projects (allows most licenses) - "internal": Internal use only (allows all) context: Optional usage context (e.g., "static_linking", "dynamic_linking")

Returns: Dictionary with: - licenses: List of licenses evaluated - distribution: Distribution type used - context: Context evaluated - result.action: "approve", "deny", or "review" - result.severity: "info" (approved), "warning" (review), or "error" (denied) - result.message: Human-readable decision explanation - result.requirements: List of compliance requirements (if approved) - result.remediation: Suggested fix (if denied, e.g., "Replace with MIT alternative") - using_default_policy: Whether default enterprise policy was used

Examples: # Check if licenses are approved for mobile app validate_policy(["MIT", "Apache-2.0"], distribution="mobile") → action: "approve" ✓

# Check GPL for mobile (will be denied)
validate_policy(["GPL-3.0"], distribution="mobile")
→ action: "deny", remediation: "Replace with permissive alternative"

# Check licenses for commercial distribution
validate_policy(["MIT", "LGPL-2.1", "Apache-2.0"], distribution="commercial")
→ action: "approve" or "review" depending on policy

# Check AGPL for SaaS (will be denied)
validate_policy(["AGPL-3.0"], distribution="saas")
→ action: "deny", reason: "Network copyleft requires source disclosure"

Workflow Integration: 1. After scanning: scan_directory() → extract licenses → validate_policy() 2. Quick check: validate_policy(["GPL-3.0"], distribution="mobile") → see if approved 3. Policy enforcement: validate_policy() → if action=="deny" → block deployment

Get detailed obligations for specified licenses.

This tool answers the critical question: "What must I do to comply with these licenses?"

Args: licenses: List of SPDX license IDs (e.g., ["MIT", "Apache-2.0", "GPL-3.0"]) output_format: Output format (json, text, checklist, markdown)

Returns: Comprehensive obligations including: - Required actions (attribution, notices, disclosure, etc.) - Permissions (commercial use, modification, distribution, etc.) - Limitations (liability, warranty, trademark use, etc.) - Conditions (source disclosure, license preservation, state changes, etc.) - Key requirements for compliance

Example: For MIT license, returns obligations like: - Include original license text in distributions - Preserve copyright notices - No trademark rights granted

Check if two licenses are compatible for use together.

This tool answers: "Can I combine code under these two licenses?"

Args: license1: First SPDX license ID (e.g., "MIT") license2: Second SPDX license ID (e.g., "GPL-3.0") context: Usage context (general, static_linking, dynamic_linking)

Returns: Compatibility assessment including: - compatible: True/False indicating if licenses can be combined - reason: Explanation of why they are/aren't compatible - restrictions: Any special conditions or restrictions - recommendations: Suggested actions if incompatible

Example: Checking MIT vs GPL-3.0 returns: - compatible: False - reason: GPL-3.0 is strongly copyleft and requires derivative works to be GPL-3.0 - recommendations: Use dynamic linking, keep code separate, or relicense

Get comprehensive details about a specific license.

This tool provides complete license information including the full license text for generating NOTICE files and understanding license requirements.

Args: license_id: SPDX license ID (e.g., "Apache-2.0", "MIT", "GPL-3.0") include_full_text: Include full license text (can be long, ~5-20KB)

Returns: License information including: - name: Full license name - type: License category (permissive, copyleft_weak, copyleft_strong, etc.) - properties: Characteristics (OSI approved, FSF free, etc.) - permissions: What you CAN do (commercial use, modify, distribute, etc.) - requirements: What you MUST do (include license, preserve copyright, etc.) - limitations: What is NOT provided (liability, warranty, etc.) - obligations: Specific compliance requirements - full_text: Complete license text (if include_full_text=True, fetched from SPDX API)

Example: For Apache-2.0, returns complete license data including: - Full license text for NOTICE files - Patent grant information - Attribution requirements

Analyze commercial licensing risk for a project.

QUICK answer to: "Can I ship this with these licenses?"

This tool analyzes a list of licenses without requiring a filesystem path, making it ideal for quick validation checks.

WHEN TO USE:

• You have a list of licenses (from scan results)

• Need to validate for specific distribution type (mobile, desktop, saas, embedded)

• Want app store compatibility check (iOS/Android)

• Fast compliance validation without deep analysis

• Quick go/no-go decision for shipping

WHEN NOT TO USE:

• Need to scan codebase first → use scan_directory

• Need detailed policy evaluation → use validate_policy

• Need complete legal documentation → use generate_legal_notices after validation

• Don't have license list yet → use scan_directory first

WORKFLOW POSITION: Use AFTER scan_directory/check_package to validate licenses, BEFORE generate_legal_notices to confirm compliance.

COMMON WORKFLOW: scan_directory(identify_packages=True) → validate_license_list(distribution="mobile") [VALIDATION STEP] → generate_legal_notices(purls=[...]) [IF APPROVED]

RETURNS CLEAR DECISION:

• safe_for_distribution: true/false

• app_store_compatible: true/false (if check_app_store_compatibility=True)

• recommendations: What to do next

• violations: What's wrong (if any)

Args: licenses: List of SPDX license identifiers (e.g., ["MIT", "Apache-2.0"]) distribution: Target distribution type - "mobile", "desktop", "saas", "embedded", "general" check_app_store_compatibility: Check specific App Store (iOS/Android) compatibility

Returns: Dictionary with: - safe_for_distribution: bool - Overall safety assessment - copyleft_risk: str - "none", "weak", or "strong" - risk_level: str - "LOW", "MEDIUM", or "HIGH" - violations: List of identified issues - recommendations: List of actionable recommendations - app_store_compatible: bool - iOS/Android app store compatibility - license_details: Summary of each license

PRIMARY TOOL: Generate legal notices by scanning source code directly (DEFAULT - FAST).

This is the RECOMMENDED tool for creating legal compliance documentation. Scans your project's source code directly to detect ALL packages (including transitive dependencies) and generates comprehensive attribution notices.

⚠️ THIS IS THE DEFAULT TOOL - Use this for most cases!

• Scans source code directly (node_modules/, site-packages/, vendor/)

• Detects ALL packages automatically (transitive dependencies included)

• 10x faster than downloading from registries

• No need to extract PURLs manually

WHEN TO USE THIS TOOL:

• You have source code locally with dependencies installed

• npm project with node_modules/ directory

• Python project with site-packages/ or virtualenv

• Any project with locally installed dependencies

WHEN NOT TO USE:

• Dependencies not installed locally → Use generate_legal_notices_from_purls instead

• You already have a PURL list → Use generate_legal_notices_from_purls instead

PURPOSE: Creates production-ready legal compliance documentation including:

• Complete copyright holder attributions (auto-extracted)

• Full license texts from SPDX

• Formatted for NOTICE file inclusion

• Ready for app store submission

• Professional legal documentation

WHEN TO USE (MOST COMMON SCENARIOS):

• Creating NOTICE files for distribution (PRIMARY USE CASE)

• Generating legal compliance documentation for any product

• After scanning packages and need complete attribution

• Preparing legal docs for app store submissions (iOS/Android)

• Need copyright holder information (automatically extracted)

• Anytime you need production-ready legal documentation

WHEN NOT TO USE:

• Understanding individual license obligations → use get_license_obligations

• Just checking license compatibility → use check_license_compatibility

• Quick validation only → use validate_license_list

• Want one-shot complete workflow → use run_compliance_check

• DON'T have PURLs yet → use scan_directory FIRST to get them

WORKFLOW POSITION: Typically used AFTER scan_directory/check_package and validation (validate_license_list), as the FINAL step to generate legal documentation.

COMMON WORKFLOWS:

1. Mobile App Compliance (MOST COMMON): scan_directory(check_vulnerabilities=True, identify_packages=True) → validate_license_list(distribution="mobile") → generate_legal_notices(purls=[...], output_file="NOTICE.txt") [PRIMARY] → generate_sbom(path=".")

2. After Package Analysis: check_package(identifier="pkg:npm/express@4.0.0") → validate_policy(licenses=[...]) → generate_legal_notices(purls=[...])

3. Batch Compliance: scan_directory(path=".", identify_packages=True) → (parallel) generate_sbom + generate_legal_notices

BACKEND: Uses purl2notices in scan mode to read source code directly. Automatically extracts copyright holders, fetches license texts from SPDX, and formats complete attribution.

Args: path: Path to source directory to scan (project root with dependencies installed) output_format: Output format - "text" (default), "html", "markdown" output_file: Optional path to save the output file include_license_text: If True, include full license texts (default: True)

Returns: Dictionary containing: - notices: The generated legal notices text - packages_processed: Number/description of packages processed - packages_failed: Number of packages that failed processing - output_file: Path to saved file (if output_file was specified) - format: The output format used - mode: "scan_directory" (indicates source code scanning was used)

Examples: # Generate text NOTICE file for npm project generate_legal_notices( path="/path/to/npm-project", output_file="NOTICE.txt" )

# Generate HTML notices for Python project
generate_legal_notices(
    path="/path/to/python-project",
    output_format="html",
    output_file="NOTICE.html"
)

# Quick scan without saving to file
result = generate_legal_notices(path=".")
print(result["notices"])

ALTERNATIVE TOOL: Generate legal notices from PURL list (downloads from registries - SLOWER).

Use this tool ONLY when:

• Dependencies are NOT installed locally (no node_modules/, site-packages/)

• You already have a list of PURLs from another source

• You're working with a PURL list, not source code

⚠️ PERFORMANCE WARNING: This downloads packages from registries (slow)

• Downloads each package from npm/PyPI/etc (1-2 seconds per package)

• For 49 packages: ~60-120 seconds

• Use generate_legal_notices(path=...) instead if you have source code

⚠️ CRITICAL: DO NOT manually extract PURLs from package.json or requirements.txt!

• WRONG: Reading package.json, extracting "http-server@14.1.1" → 1 PURL

• RIGHT: Use scan_directory() to get ALL transitive dependencies → 49 PURLs

• Example: npm project with 1 dependency = ~50 packages in node_modules (all needed!)

WHEN TO USE THIS TOOL:

• Source code not available locally

• Working with a pre-existing PURL list

• Dependencies not installed (no node_modules/ or site-packages/)

WHEN NOT TO USE (use generate_legal_notices instead):

• You have source code with dependencies installed locally

• npm project with node_modules/ → Use generate_legal_notices(path=...)

• Python project with virtualenv → Use generate_legal_notices(path=...)

Args: purls: List of Package URLs (e.g., ["pkg:npm/express@4.0.0", "pkg:pypi/django@4.2.0"]) output_format: Output format - "text" (default), "html", "markdown" output_file: Optional path to save the output file include_license_text: If True, include full license texts (default: True)

Returns: Dictionary containing: - notices: The generated legal notices text - packages_processed: Number of packages successfully processed - packages_failed: Number of packages that failed processing - output_file: Path to saved file (if output_file was specified) - format: The output format used - mode: "download_purls" (indicates registry downloads were used)

Examples: # Generate notices from PURL list (after scan_directory) scan_result = scan_directory("/path/to/project") purls = [pkg["purl"] for pkg in scan_result["packages"]] generate_legal_notices_from_purls( purls=purls, output_file="NOTICE.txt" )

# Generate HTML notices from specific PURLs
generate_legal_notices_from_purls(
    purls=["pkg:npm/express@4.21.2", "pkg:npm/body-parser@1.20.3"],
    output_format="html",
    output_file="NOTICE.html"
)

Download package source from registry and perform comprehensive analysis.

⚠️ IMPORTANT: This tool CAN and WILL download source code from package registries!

Workflow (tries methods in order until sufficient data is collected):

1. Primary: Use purl2notices to download and analyze (fastest, most comprehensive)

2. Deep scan: If incomplete, use purl2src to get download URL → download artifact → run osslili for deep license scanning + upmex for metadata

   • Maven-specific: If license still missing for Maven packages, uses upmex with --registry --api clearlydefined to resolve parent POM licenses

3. Online fallback: If still incomplete, use upmex --api clearlydefined/purldb for online metadata

What this tool does:

• Downloads the actual package source code from npm/PyPI/Maven/etc registries

• Performs comprehensive license and copyright analysis

• Extracts package metadata (name, version, homepage, description)

• Scans ALL source files for embedded licenses (not just package.json/setup.py/pom.xml)

• Returns copyright statements found in actual source code

• Maven packages: Automatically resolves parent POM licenses when not declared in package POM

When to use this tool:

• Package metadata is incomplete or missing (e.g., "UNKNOWN" license in PyPI)

• Need to verify what's ACTUALLY in the package files (not just metadata)

• Want to analyze source code directly (not just manifests)

• Security auditing - see actual package contents before approval

• License compliance - find licenses embedded in source files

• Need to extract copyright statements from source code

Real-world example: User asks: "Can you check if duckdb@0.2.3 has license info in the source code?"

• PyPI metadata shows "UNKNOWN" license

• This tool downloads the actual .whl/.tar.gz from PyPI

• Scans ALL files in the package for license information

• Finds licenses embedded in source code that aren't in metadata

• Returns: {"method_used": "purl2notices", "declared_license": "UNKNOWN", "detected_licenses": ["CC0-1.0"], ...}

Performance:

• Primary (purl2notices): 5-15 seconds (fastest)

• Deep scan (download + osslili + upmex): 10-30 seconds

• Online fallback (upmex --api): 2-5 seconds (but less complete)

Security note:

• Downloads are verified against package checksums when available

• Files are scanned but NOT executed

• Temporary files are cleaned up unless keep_download=True

Args: purl: Package URL (e.g., "pkg:pypi/duckdb@0.2.3", "pkg:npm/express@4.21.2") keep_download: If True, keeps downloaded files for manual inspection (default: False)

Returns: Dictionary containing: - purl: The package URL analyzed - method_used: Which method succeeded ("purl2notices", "deep_scan", "online_fallback") - download_path: Where package was downloaded (if keep_download=True) - metadata: Package metadata (name, version, homepage, etc.) - declared_license: License from package metadata - detected_licenses: List of licenses found by scanning source files - copyright_statements: Copyright statements extracted from source - files_scanned: Number of files analyzed - scan_summary: Summary of what was found

Examples: # Check if package has license info in source code download_and_scan_package(purl="pkg:pypi/duckdb@0.2.3")

# Download and keep files for manual inspection
result = download_and_scan_package(
    purl="pkg:npm/suspicious-package@1.0.0",
    keep_download=True
)
print(f"Inspect files at: {result['download_path']}")

Generate a Software Bill of Materials (SBOM) in CycloneDX format using purl2notices.

This tool creates comprehensive SBOMs in CycloneDX 1.4 JSON format for software inventory, vulnerability tracking, and compliance documentation.

SBOM includes: name, version, PURL, licenses, homepage (external references). Data is sourced from purl2notices scan mode which provides accurate package metadata.

Use this tool when:

• You need to generate an SBOM for a project or package list

• Creating inventory documentation for compliance

• After analyzing packages and need structured output

• Preparing documentation for security audits

• Required by procurement or regulatory requirements

Input modes:

• Provide purls (list of Package URLs) for packages you've already identified

• Provide path to scan a directory and generate SBOM from discovered packages

• At least one of purls or path must be provided

Args: purls: Optional list of Package URLs (PURLs) to include in SBOM path: Optional directory path to scan for packages output_file: Optional path to save the SBOM file (CycloneDX JSON format) include_licenses: If True, include license information (default: True)

Returns: Dictionary containing: - sbom: The generated SBOM structure (CycloneDX 1.4 JSON) - packages_count: Number of packages included - output_file: Path to saved file (if output_file was specified)

Examples: # Generate SBOM from PURLs (after batch analysis) generate_sbom( purls=["pkg:npm/express@4.0.0", "pkg:pypi/django@4.2.0"], output_file="/tmp/sbom.json" )

# Generate SBOM by scanning directory
generate_sbom(path="/path/to/project")

# After batch scan workflow
scan_result = check_package("package.jar")
generate_sbom(purls=[scan_result["purl"]], include_licenses=True)

Scan binary files for OSS components and licenses using BinarySniffer.

This tool analyzes compiled binaries, executables, libraries, and archives (APK, EXE, DLL, SO, JAR, etc.) to detect open source components, extract license information, and identify security issues.

Use this tool when:

• Analyzing mobile apps (APK, IPA)

• Scanning executables (EXE, ELF binaries)

• Examining shared libraries (DLL, SO, DYLIB)

• Analyzing Java archives (JAR, WAR, EAR)

• Scanning firmware or embedded binaries

• Generating SBOM for binary distributions

Args: path: Path to binary file or directory to analyze analysis_mode: Analysis depth - "fast" (quick scan), "standard" (balanced), or "deep" (thorough analysis, slower) generate_sbom: If True, generate SBOM in CycloneDX format check_licenses: If True, perform detailed license analysis check_compatibility: If True, check license compatibility and show warnings confidence_threshold: Minimum confidence level (0.0-1.0) for component detection output_format: Output format - "json", "table", "csv" (default: json)

Returns: Dictionary containing: - components: List of detected OSS components with licenses - licenses: Summary of all licenses found - compatibility_warnings: License compatibility issues (if check_compatibility=True) - sbom: CycloneDX SBOM (if generate_sbom=True) - metadata: Scan statistics and file information

Examples: # Scan an Android APK scan_binary("app.apk")

# Deep analysis with SBOM generation
scan_binary("firmware.bin", analysis_mode="deep", generate_sbom=True)

# Check license compatibility
scan_binary("library.so", check_compatibility=True)

UNIVERSAL COMPLIANCE WORKFLOW: One-shot compliance check for ANY project type.

This is a convenience tool that runs the complete standard compliance workflow:

1. Scan for licenses and packages (scan_directory)

2. Generate legal notices with purl2notices (generate_legal_notices)

3. Validate against policy using ospac (validate_policy or default policy)

4. Generate SBOM for documentation (generate_sbom)

5. Check for vulnerabilities (if enabled)

6. Return comprehensive summary with APPROVE/REJECT decision

This tool works for ANY distribution type (mobile, desktop, embedded, SaaS, etc.) - no specialized tools needed. Distribution type is used for policy validation context.

WHEN TO USE:

• You want a complete compliance assessment in one call

• Starting a new project compliance review

• Need approve/reject decision with full documentation

• Don't want to orchestrate multiple tool calls manually

• Want standardized compliance workflow

WHEN NOT TO USE:

• You need fine-grained control over each step → call individual tools

• You only need specific information → use targeted tools (scan_directory, etc.)

• You want to customize the workflow → use individual tools in your preferred sequence

WORKFLOW EXECUTED:

1. scan_directory(path, identify_packages=True, check_licenses=True)

2. generate_legal_notices(purls, output_file=NOTICE.txt)

3. validate_policy(licenses, policy_file or default_policy)

4. generate_sbom(purls, output_file=sbom.json)

5. check vulnerabilities (if check_vulnerabilities=True)

6. Aggregate results → FINAL DECISION: approved/rejected + risk level

Args: path: Directory or project to analyze distribution_type: Optional - mobile, desktop, saas, embedded, etc. (for policy context) policy_file: Optional - Path to custom ospac policy. Uses default if not specified. check_vulnerabilities: Check for security vulnerabilities (default: True) output_dir: Optional - Directory to save outputs (NOTICE.txt, sbom.json). Uses path if not specified.

Returns: Dictionary containing: - decision: "APPROVED" or "REJECTED" - risk_level: "LOW", "MEDIUM", or "HIGH" - summary: Human-readable summary of findings - licenses: List of detected licenses - packages: List of identified packages (PURLs) - vulnerabilities: List of vulnerabilities (if checked) - policy_violations: List of policy violations (if any) - artifacts_created: List of files generated (NOTICE.txt, sbom.json) - recommendations: Actionable next steps

Example: # Complete compliance check with default settings result = run_compliance_check("/path/to/project")

# Mobile app compliance with custom policy
result = run_compliance_check(
    path="/path/to/mobile/app",
    distribution_type="mobile",
    policy_file="/policies/mobile_policy.json"
)

# Check decision
if result["decision"] == "APPROVED":
    print("✓ Ready to ship!")
else:
    print("✗ Issues found:", result["policy_violations"])