Core API

Models

Data models for threat scanning findings

This module contains the data model for threat findings.

class package_scan.core.models.Finding(ecosystem: str, finding_type: str, file_path: str, package_name: str, version: str, match_type: str, declared_spec: str | None = None, dependency_type: str | None = None, metadata: ~typing.Dict[str, ~typing.Any] = <factory>)

Bases: object

Standardized finding structure across all ecosystems

declared_spec: str | None = None

dependency_type: str | None = None

ecosystem: str

file_path: str

finding_type: str

classmethod from_legacy_npm_dict(legacy: Dict[str, Any]) → Finding

Convert legacy npm-only finding dict to new Finding model

Args:

legacy: Old-style finding dict from scan_npm_threats.py

Returns:

Finding object

match_type: str

metadata: Dict[str, Any]

package_name: str

to_dict() → Dict[str, Any]

Convert to dictionary for JSON serialization

version: str

Threat Database

Threat database management for multi-ecosystem scanning

This module manages the threat database with multi-ecosystem support.

class package_scan.core.threat_database.ThreatDatabase(threats_dir: str = 'threats')

Bases: object

Manages threat data from CSV files with multi-ecosystem support

Supports: - Loading specific threats by name (e.g., ‘sha1-Hulud’, ‘other-threat’) - Loading all threats from threats/ directory - Loading custom CSV files

CSV Format:

ecosystem,name,version npm,left-pad,1.3.0 maven,org.apache.logging.log4j:log4j-core,2.14.1 pip,requests,2.25.1 gem,strong_migrations,0.7.9

get_all_packages(ecosystem: str | None = None) → Dict[str, Set[str]]

Get all compromised packages, optionally filtered by ecosystem

Args:

ecosystem: Optional ecosystem filter

Returns:

Dictionary mapping package names to sets of compromised versions

get_compromised_versions(ecosystem: str, package_name: str) → Set[str]

Get all compromised versions for a specific package in an ecosystem

Args:

ecosystem: Ecosystem name (npm, maven, pip, gem, etc.) package_name: Package identifier

Returns:

Set of compromised version strings

get_ecosystems() → Set[str]

Get all ecosystems present in the threat database

Returns:

Set of ecosystem names

get_loaded_threats() → List[str]

Get list of loaded threat names

Returns:

List of threat names that were loaded

get_package_count(ecosystem: str | None = None) → int

Get count of unique packages in threat database

Args:

ecosystem: Optional ecosystem filter

Returns:

Number of unique packages

get_version_count(ecosystem: str | None = None) → int

Get count of compromised package versions

Args:

ecosystem: Optional ecosystem filter

Returns:

Total number of compromised versions

is_compromised(ecosystem: str, package_name: str, version: str) → bool

Check if a specific package version is compromised

Args:

ecosystem: Ecosystem name package_name: Package identifier version: Version string

Returns:

True if compromised, False otherwise

load_threats(threat_names: List[str] | None = None, csv_file: str | None = None) → bool

Load threats by name or from custom CSV

Args:

threat_names: List of threat names to load (e.g., [‘sha1-Hulud’]).

If None, loads all threats from threats/ directory.

csv_file: Path to custom CSV file (overrides threat_names).

Returns:

True if at least one threat loaded successfully, False otherwise

print_summary()

Print a summary of loaded threats

Report Engine

Report generation engine for multi-ecosystem threat scanning

This module generates reports from scan findings.

class package_scan.core.report_engine.ReportEngine(scan_dir: str | None = None)

Bases: object

Aggregates findings from all adapters and generates reports

Supports: - Console output with colored formatting - JSON export with optional relative paths - Multi-ecosystem grouping

add_finding(finding: Finding)

Add a single finding

add_findings(findings: List[Finding])

Add multiple findings

clear()

Clear all findings and threats

get_ecosystems() → List[str]

Get list of ecosystems with findings

get_findings_count() → int

Get total number of findings

print_report()

Print formatted console report

save_report(output_file: str) → bool

Save findings to JSON file

Path conversion is handled automatically via SCAN_PATH_PREFIX environment variable.

Args:

output_file: Path to output file

Returns:

True if saved successfully, False otherwise

set_threats(threats: List[str])

Set the list of threats that were scanned