Adapters API

Base Adapter

Base adapter interface for ecosystem-specific scanners

This module defines the abstract base class for ecosystem adapters.

class package_scan.adapters.base.EcosystemAdapter(threat_db: ThreatDatabase, root_dir: Path, spinner: ProgressSpinner = None)

Bases: ABC

Base class for ecosystem-specific scanners

Each adapter is responsible for: 1. Detecting projects for its ecosystem 2. Parsing manifest files (declared dependencies) 3. Parsing lock files (resolved dependencies) 4. Checking installed packages 5. Version matching according to ecosystem conventions

abstractmethod detect_projects() → List[Path]

Detect project directories containing this ecosystem’s files

Walks the directory tree and identifies projects by looking for manifest files (package.json, pom.xml, pyproject.toml, Gemfile, etc.)

Returns:

List of project directory paths

abstractmethod get_lockfile_names() → List[str]

Return list of lockfile names for this ecosystem

Returns:

List of file names (e.g., [‘package-lock.json’, ‘yarn.lock’])

abstractmethod get_manifest_files() → List[str]

Return list of manifest file names for this ecosystem

Returns:

List of file names (e.g., [‘package.json’], [‘pom.xml’, ‘build.gradle’])

scan_all_projects() → List[Finding]

Scan all detected projects in the root directory

Returns:

List of all findings across all projects

abstractmethod scan_project(project_dir: Path) → List[Finding]

Scan a single project directory for compromised packages

This should: 1. Check manifest files for declared dependencies 2. Check lock files for resolved dependencies 3. Check installed packages (if applicable)

Args:

project_dir: Project directory to scan

Returns:

List of findings

class package_scan.adapters.base.ProgressSpinner(enabled: bool = True)

Bases: object

Simple spinner for showing scan progress that updates in place

clear()

Clear the spinner line

update(message: str)

Update the spinner with a new message

NPM Adapter

NPM ecosystem adapter for scanning JavaScript/Node.js projects

This adapter handles JavaScript/Node.js ecosystem scanning (npm, yarn, pnpm).

class package_scan.adapters.npm_adapter.NpmAdapter(threat_db: ThreatDatabase, root_dir: Path, spinner: ProgressSpinner = None)

Bases: EcosystemAdapter

Adapter for scanning npm/JavaScript/Node.js projects

Supports: - Manifest files: package.json - Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml - Installed packages: node_modules/ - Version matching: npm semver ranges (^, ~, >=, etc.)

detect_projects() → List[Path]

Detect npm projects by looking for package.json files

Returns:

List of project directories containing package.json

get_lockfile_names() → List[str]

Return list of lockfile names

get_manifest_files() → List[str]

Return list of manifest file names

scan_project(project_dir: Path) → List[Finding]

if isinstance(project_dir, str):

project_dir = Path(project_dir)

Scan a single npm project for compromised packages

Args:

project_dir: Project directory containing package.json

Returns:

List of findings

Java Adapter

Java ecosystem adapter for scanning Maven and Gradle projects

This adapter handles Maven and Gradle ecosystem scanning.

class package_scan.adapters.java_adapter.JavaAdapter(threat_db: ThreatDatabase, root_dir: Path, spinner: ProgressSpinner = None)

Bases: EcosystemAdapter

Adapter for scanning Java/Maven/Gradle projects

Supports: - Maven: pom.xml (manifest) - Gradle: build.gradle, build.gradle.kts (manifest) - Lock files: gradle.lockfile (Gradle 7+) - Version matching: Maven version ranges, Gradle dynamic versions

Ecosystem identifier: ‘maven’ (matches Maven Central artifact format)

detect_projects() → List[Path]

Detect Maven/Gradle projects by looking for pom.xml or build.gradle files

Returns:

List of project directories

get_lockfile_names() → List[str]

Return list of lockfile names

get_manifest_files() → List[str]

Return list of manifest file names

scan_project(project_dir: Path) → List[Finding]

if isinstance(project_dir, str):

project_dir = Path(project_dir)

Scan a single Java project for compromised packages

Args:

project_dir: Project directory

Returns:

List of findings

Python Adapter

Python ecosystem adapter for scanning pip, poetry, pipenv, and conda projects

This adapter handles Python ecosystem scanning (pip, Poetry, Pipenv, conda).

class package_scan.adapters.python_adapter.PythonAdapter(threat_db: ThreatDatabase, root_dir: Path, spinner: ProgressSpinner = None)

Bases: EcosystemAdapter

Adapter for scanning Python projects

Supports: - pip: requirements.txt, requirements-*.txt - Poetry: pyproject.toml, poetry.lock - Pipenv: Pipfile, Pipfile.lock - conda: environment.yml - Version matching: PEP 440 specifiers (==, >=, ~=, !=, etc.)

Ecosystem identifier: ‘pip’ (matches PyPI package format)

detect_projects() → List[Path]

Detect Python projects by looking for Python manifest files

Returns:

List of project directories

get_lockfile_names() → List[str]

Return list of lockfile names

get_manifest_files() → List[str]

Return list of manifest file names

scan_project(project_dir: Path) → List[Finding]

Scan a single Python project for compromised packages

Args:

project_dir: Project directory

Returns:

List of findings