pipsutra 0.1.0__py3-none-any.whl

pipsutra/__init__.py

@@ -0,0 +1,20 @@
+"""PipSutra: explainable security analysis for Python dependencies."""
+
+from pipsutra._version import __version__
+from pipsutra.api import build_inventory_report, scan_project
+from pipsutra.models import Dependency, DependencyEdge, Inventory, Package
+
+__author__ = "Nikhil Mutreja"
+__license__ = "Apache-2.0"
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__license__",
+    "build_inventory_report",
+    "scan_project",
+    "Dependency",
+    "DependencyEdge",
+    "Inventory",
+    "Package",
+]

pipsutra/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pipsutra/api.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from pipsutra._version import __version__
+from pipsutra.discovery import build_inventory
+from pipsutra.models import Inventory, ScanReport
+from pipsutra.risk import calculate_risk
+from pipsutra.static_analysis import scan_python_source
+from pipsutra.vulnerability import query_osv
+
+
+def build_inventory_report(
+    project: str | Path = ".", environment: str | Path | None = None
+) -> Inventory:
+    selected_environment = Path(environment) if environment else Path(sys.prefix)
+    return build_inventory(project, selected_environment)
+
+
+def scan_project(
+    project: str | Path = ".",
+    environment: str | Path | None = None,
+    *,
+    check_vulnerabilities: bool = True,
+    check_static: bool = True,
+    network_timeout: float = 15.0,
+) -> ScanReport:
+    inventory = build_inventory_report(project, environment)
+    errors: list[str] = []
+    checks = {
+        "inventory": (
+            "completed" if inventory.discovery_status == "complete" else "partial"
+        )
+    }
+
+    osv_errors: list[str] = []
+    if check_vulnerabilities:
+        relevant_packages = [
+            package
+            for package in inventory.packages
+            if package.direct or package.dependency_depth is not None
+        ]
+        vulnerabilities, osv_errors = query_osv(
+            relevant_packages, timeout=network_timeout
+        )
+        errors.extend(osv_errors)
+        checks["osv"] = "completed" if not osv_errors else "failed"
+    else:
+        vulnerabilities = []
+        checks["osv"] = "skipped"
+
+    if check_static:
+        static_findings, static_warnings = scan_python_source(inventory.project_path)
+        inventory.warnings.extend(static_warnings)
+        checks["static_analysis"] = "partial" if static_warnings else "completed"
+    else:
+        static_findings = []
+        checks["static_analysis"] = "skipped"
+
+    risk = calculate_risk(vulnerabilities, static_findings)
+    incomplete_checks = [
+        name for name, status in checks.items() if status != "completed"
+    ]
+    if incomplete_checks:
+        reason = ", ".join(incomplete_checks)
+        risk = risk.model_copy(
+            update={
+                "level": "UNKNOWN",
+                "explanation": (
+                    risk.explanation
+                    + f" Coverage is incomplete; check status: {reason}."
+                ),
+            }
+        )
+
+    return ScanReport(
+        tool_version=__version__,
+        project_path=inventory.project_path,
+        environment_path=inventory.environment_path,
+        inventory=inventory,
+        vulnerabilities=vulnerabilities,
+        static_findings=static_findings,
+        risk=risk,
+        checks=checks,
+        errors=errors,
+    )

pipsutra/cli.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from pipsutra._version import __version__
+from pipsutra.api import build_inventory_report, scan_project
+from pipsutra.models import ScanReport
+
+app = typer.Typer(
+    name="pipsutra",
+    help="Explainable security analysis for Python dependencies.",
+    no_args_is_help=True,
+    epilog="Developed by Nikhil Mutreja | Apache-2.0 License",
+)
+console = Console()
+_SEVERITY_RANK = {"LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
+
+
+def _has_blocking_findings(report: ScanReport, threshold: str) -> bool:
+    if threshold == "none":
+        return False
+    minimum = _SEVERITY_RANK[threshold.upper()]
+    vulnerability_match = any(
+        _SEVERITY_RANK.get(finding.severity, 0) >= minimum
+        for finding in report.vulnerabilities
+    )
+    static_match = any(
+        _SEVERITY_RANK.get(finding.severity, 0) >= minimum
+        for finding in report.static_findings
+    )
+    return vulnerability_match or static_match
+
+
+@app.command()
+def version() -> None:
+    """Print the installed PipSutra version."""
+    console.print(f"PipSutra {__version__}\nDeveloped by Nikhil Mutreja")
+
+
+def _write_json(payload: str, output: Path | None) -> None:
+    if output is None:
+        console.print(payload)
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(payload + "\n", encoding="utf-8")
+    console.print(f"[green]JSON report written to {output}[/green]")
+
+
+@app.command()
+def inventory(
+    project: Path = typer.Option(
+        Path("."), "--project", "-p", exists=True, file_okay=False
+    ),
+    environment: Path | None = typer.Option(
+        None, "--environment", "-e", exists=True, file_okay=False
+    ),
+    output: Path | None = typer.Option(None, "--output", "-o"),
+) -> None:
+    """Discover declared and installed dependencies and export an inventory."""
+    try:
+        report = build_inventory_report(project, environment)
+    except (ValueError, OSError) as exc:
+        console.print(f"[red]Inventory failed:[/red] {exc}")
+        raise typer.Exit(code=2) from exc
+
+    table = Table(title="PipSutra dependency inventory")
+    for heading in ("Package", "Version", "Classification", "Depth"):
+        table.add_column(heading)
+    for package in report.packages:
+        if package.direct:
+            classification = "direct"
+        elif package.dependency_depth is not None:
+            classification = "transitive"
+        else:
+            classification = "unlinked"
+        depth = (
+            str(package.dependency_depth)
+            if package.dependency_depth is not None
+            else "—"
+        )
+        table.add_row(package.name, package.version, classification, depth)
+    console.print(table)
+    console.print(
+        f"Declared: {len(report.declared_dependencies)} | "
+        f"Installed: {len(report.packages)} | Edges: {len(report.edges)} | "
+        f"Missing direct: {len(report.missing_declared)}"
+    )
+    for warning in report.warnings:
+        console.print(f"[yellow]Warning:[/yellow] {warning}")
+    if output:
+        _write_json(report.model_dump_json(indent=2), output)
+
+
+@app.command()
+def scan(
+    project: Path = typer.Option(
+        Path("."), "--project", "-p", exists=True, file_okay=False
+    ),
+    environment: Path | None = typer.Option(
+        None, "--environment", "-e", exists=True, file_okay=False
+    ),
+    output: Path | None = typer.Option(None, "--output", "-o"),
+    no_osv: bool = typer.Option(
+        False, "--no-osv", help="Skip online OSV vulnerability checks."
+    ),
+    no_static: bool = typer.Option(
+        False, "--no-static", help="Skip Python AST checks."
+    ),
+    timeout: float = typer.Option(15.0, "--timeout", min=1.0, max=120.0),
+    fail_on: Literal["none", "low", "medium", "high", "critical"] = typer.Option(
+        "none",
+        "--fail-on",
+        help="Exit with status 1 when a finding meets this severity threshold.",
+    ),
+) -> None:
+    """Run dependency inventory, OSV checks, and Python AST rules."""
+    try:
+        report = scan_project(
+            project,
+            environment,
+            check_vulnerabilities=not no_osv,
+            check_static=not no_static,
+            network_timeout=timeout,
+        )
+    except (ValueError, OSError) as exc:
+        console.print(f"[red]Scan failed:[/red] {exc}")
+        raise typer.Exit(code=2) from exc
+
+    console.print(f"[bold]PipSutra scan:[/bold] {report.project_path}")
+    console.print(f"Risk: [bold]{report.risk.level} ({report.risk.score}/100)[/bold]")
+    console.print(report.risk.explanation)
+    if report.vulnerabilities:
+        table = Table(title="Known vulnerabilities (OSV)")
+        for heading in ("Package", "Version", "ID", "Severity", "Summary"):
+            table.add_column(heading)
+        for finding in report.vulnerabilities:
+            table.add_row(
+                finding.package,
+                finding.version,
+                finding.vulnerability_id,
+                finding.severity,
+                finding.summary[:80],
+            )
+        console.print(table)
+    else:
+        osv_status = report.checks["osv"]
+        console.print(
+            "OSV findings: 0" if osv_status == "completed" else f"OSV: {osv_status}"
+        )
+    if report.static_findings:
+        table = Table(title="Static analysis findings")
+        for heading in ("Severity", "Rule", "Location", "Finding"):
+            table.add_column(heading)
+        for sf in report.static_findings:
+            table.add_row(
+                sf.severity,
+                sf.rule_id,
+                f"{sf.file}:{sf.line}",
+                sf.title,
+            )
+        console.print(table)
+    else:
+        console.print("Static findings: 0")
+    for error in report.errors:
+        console.print(f"[yellow]Warning:[/yellow] {error}")
+    if output:
+        _write_json(report.model_dump_json(indent=2), output)
+    if _has_blocking_findings(report, fail_on):
+        console.print(f"[red]Findings meet the --fail-on {fail_on} threshold.[/red]")
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

pipsutra/discovery.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import re
+import tomllib
+from collections.abc import Iterable
+from importlib import metadata
+from pathlib import Path
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+from pipsutra.models import Dependency, DependencyEdge, Inventory, Package
+
+
+def _parse_requirement(
+    raw: str, *, source: str, group: str = "main"
+) -> Dependency | None:
+    value = raw.strip()
+    if not value or value.startswith("#"):
+        return None
+    if value.startswith(("-r ", "--requirement ", "-c ", "--constraint ")):
+        raise ValueError(
+            f"Nested requirements and constraints are not supported in v0.1.0: {value}"
+        )
+    if value.startswith(("-e ", "--editable ")):
+        raise ValueError(
+            f"Editable/VCS requirements are not supported in v0.1.0: {value}"
+        )
+    try:
+        requirement = Requirement(value)
+    except InvalidRequirement as exc:
+        raise ValueError(f"Invalid requirement {value!r}: {exc}") from exc
+
+    if requirement.url and requirement.url.startswith(("git+", "hg+", "svn+", "bzr+")):
+        raise ValueError(f"VCS requirements are not supported in v0.1.0: {value}")
+
+    active = requirement.marker is None or requirement.marker.evaluate()
+
+    return Dependency(
+        name=requirement.name,
+        normalized_name=canonicalize_name(requirement.name),
+        specifier=str(requirement.specifier),
+        source=source,
+        group=group,
+        marker=str(requirement.marker) if requirement.marker else None,
+        active=active,
+    )
+
+
+def discover_requirements(path: Path) -> list[Dependency]:
+    dependencies: list[Dependency] = []
+    for line_number, line in enumerate(
+        path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        # Strip inline comments only when separated by whitespace.
+        content = line.split(" #", maxsplit=1)[0].strip()
+        if not content or content.startswith("#"):
+            continue
+        if content.startswith(
+            (
+                "--index-url",
+                "--extra-index-url",
+                "--trusted-host",
+                "--find-links",
+                "-f ",
+                "--no-index",
+                "--pre",
+                "--only-binary",
+                "--no-binary",
+                "--require-hashes",
+                "--prefer-binary",
+                "--no-deps",
+            )
+        ):
+            continue
+        content = re.sub(r"\s+--hash(?:=|\s+)\S+", "", content).strip()
+        if not content:
+            continue
+        try:
+            dependency = _parse_requirement(
+                content, source=f"requirements.txt:{line_number}"
+            )
+        except ValueError as exc:
+            raise ValueError(f"{path}:{line_number}: {exc}") from exc
+        if dependency is not None:
+            dependencies.append(dependency)
+    return dependencies
+
+
+def discover_pyproject(path: Path) -> list[Dependency]:
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    project = data.get("project", {})
+    dependencies: list[Dependency] = []
+
+    for raw in project.get("dependencies", []):
+        dependency = _parse_requirement(
+            raw, source="pyproject.toml:[project].dependencies"
+        )
+        if dependency:
+            dependencies.append(dependency)
+
+    for group, values in project.get("optional-dependencies", {}).items():
+        for raw in values:
+            dependency = _parse_requirement(
+                raw,
+                source=f"pyproject.toml:[project].optional-dependencies.{group}",
+                group=group,
+            )
+            if dependency:
+                dependencies.append(dependency)
+
+    return dependencies
+
+
+def discover_declared(project_path: Path) -> tuple[list[Dependency], list[str]]:
+    dependencies: list[Dependency] = []
+    warnings: list[str] = []
+
+    requirements_file = project_path / "requirements.txt"
+    pyproject_file = project_path / "pyproject.toml"
+
+    if requirements_file.is_file():
+        dependencies.extend(discover_requirements(requirements_file))
+    if pyproject_file.is_file():
+        dependencies.extend(discover_pyproject(pyproject_file))
+        pyproject_data = tomllib.loads(pyproject_file.read_text(encoding="utf-8"))
+        dynamic_fields = pyproject_data.get("project", {}).get("dynamic", [])
+        if any(
+            field in {"dependencies", "optional-dependencies"}
+            for field in dynamic_fields
+        ):
+            warnings.append(
+                "Dynamic dependency fields in pyproject.toml are not resolved "
+                "by PipSutra v0.1.0."
+            )
+
+    if not requirements_file.is_file() and not pyproject_file.is_file():
+        warnings.append(
+            "No supported manifest found (requirements.txt or pyproject.toml)."
+        )
+
+    # Keep separate source records but avoid exact duplicates.
+    unique: dict[tuple[str, str, str], Dependency] = {}
+    for dependency in dependencies:
+        key = (
+            dependency.normalized_name,
+            dependency.specifier,
+            dependency.group,
+        )
+        unique.setdefault(key, dependency)
+
+    return list(unique.values()), warnings
+
+
+def _distribution_requirements(dist: metadata.Distribution) -> Iterable[Requirement]:
+    for raw in dist.requires or []:
+        try:
+            requirement = Requirement(raw)
+        except InvalidRequirement:
+            continue
+        if requirement.marker is None or requirement.marker.evaluate():
+            yield requirement
+
+
+def _metadata_search_paths(environment_path: Path) -> list[str]:
+    """Find site-packages directories for a venv or an explicit metadata path."""
+    candidates = [
+        *environment_path.glob("lib/python*/site-packages"),
+        environment_path / "Lib" / "site-packages",
+        environment_path,
+    ]
+    return [str(path) for path in candidates if path.is_dir()]
+
+
+def discover_installed(
+    environment_path: Path,
+) -> tuple[list[Package], list[DependencyEdge]]:
+    # importlib.metadata reads distribution metadata from site-packages. It does
+    # not import or execute the distributions' Python modules.
+    search_paths = _metadata_search_paths(environment_path)
+    distributions = list(metadata.distributions(path=search_paths))
+    by_name: dict[str, metadata.Distribution] = {}
+    packages: list[Package] = []
+
+    for dist in distributions:
+        name = dist.metadata["Name"]
+        version = dist.version
+        if not name or not version:
+            continue
+        normalized = canonicalize_name(name)
+        by_name[normalized] = dist
+        packages.append(
+            Package(
+                name=name,
+                normalized_name=normalized,
+                version=version,
+                location=str(dist.locate_file("")),
+            )
+        )
+
+    edges: list[DependencyEdge] = []
+    for parent_name, dist in by_name.items():
+        for requirement in _distribution_requirements(dist):
+            child_name = canonicalize_name(requirement.name)
+            if child_name in by_name:
+                edges.append(
+                    DependencyEdge(
+                        parent=parent_name,
+                        child=child_name,
+                        requirement=str(requirement),
+                        marker=str(requirement.marker) if requirement.marker else None,
+                    )
+                )
+
+    return packages, edges
+
+
+def build_inventory(
+    project_path: str | Path, environment_path: str | Path
+) -> Inventory:
+    project = Path(project_path).expanduser().resolve()
+    environment = Path(environment_path).expanduser().resolve()
+
+    if not project.exists() or not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    if not environment.exists() or not environment.is_dir():
+        raise ValueError(f"Environment directory does not exist: {environment}")
+
+    declared, warnings = discover_declared(project)
+    packages, edges = discover_installed(environment)
+
+    direct_names = {
+        item.normalized_name
+        for item in declared
+        if item.group == "main" and item.active
+    }
+    installed_names = {item.normalized_name for item in packages}
+    missing = sorted(direct_names - installed_names)
+
+    # Compute transitive reachability from declared main dependencies.
+    adjacency: dict[str, set[str]] = {}
+    for edge in edges:
+        adjacency.setdefault(edge.parent, set()).add(edge.child)
+
+    depth: dict[str, int] = {}
+    queue = [(name, 0) for name in sorted(direct_names & installed_names)]
+    while queue:
+        node, current_depth = queue.pop(0)
+        if node in depth and depth[node] <= current_depth:
+            continue
+        depth[node] = current_depth
+        for child in sorted(adjacency.get(node, set())):
+            if child not in depth or current_depth + 1 < depth[child]:
+                queue.append((child, current_depth + 1))
+
+    updated_packages = [
+        package.model_copy(
+            update={
+                "direct": package.normalized_name in direct_names,
+                "dependency_depth": depth.get(package.normalized_name),
+            }
+        )
+        for package in packages
+    ]
+
+    if missing:
+        warnings.append(
+            "Some declared main dependencies are not installed in the selected "
+            "environment: " + ", ".join(missing)
+        )
+
+    return Inventory(
+        project_path=str(project),
+        environment_path=str(environment),
+        declared_dependencies=declared,
+        packages=sorted(updated_packages, key=lambda item: item.normalized_name),
+        edges=sorted(edges, key=lambda item: (item.parent, item.child)),
+        missing_declared=missing,
+        warnings=warnings,
+        discovery_status="partial" if warnings or missing else "complete",
+    )

pipsutra/models.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Dependency(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    name: str
+    normalized_name: str
+    specifier: str = ""
+    source: str
+    group: str = "main"
+    marker: str | None = None
+    active: bool = True
+    direct: bool = True
+
+
+class Package(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    name: str
+    normalized_name: str
+    version: str
+    location: str | None = None
+    direct: bool = False
+    dependency_depth: int | None = None
+    metadata_complete: bool = True
+
+
+class DependencyEdge(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    parent: str
+    child: str
+    requirement: str | None = None
+    marker: str | None = None
+
+
+class VulnerabilityFinding(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    package: str
+    version: str
+    vulnerability_id: str
+    summary: str = ""
+    details: str = ""
+    aliases: list[str] = Field(default_factory=list)
+    references: list[str] = Field(default_factory=list)
+    severity: str = "UNKNOWN"
+    source: str = "OSV"
+
+
+class StaticFinding(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    rule_id: str
+    title: str
+    severity: Literal["LOW", "MEDIUM", "HIGH"]
+    confidence: Literal["LOW", "MEDIUM", "HIGH"]
+    message: str
+    file: str
+    line: int
+    evidence: str
+    recommendation: str
+
+
+class RiskSummary(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    score: int = Field(ge=0, le=100)
+    level: Literal["LOW", "MEDIUM", "HIGH", "CRITICAL", "UNKNOWN"]
+    explanation: str
+
+
+class Inventory(BaseModel):
+    schema_version: Literal["1.0"] = "1.0"
+    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    project_path: str
+    environment_path: str
+    declared_dependencies: list[Dependency] = Field(default_factory=list)
+    packages: list[Package] = Field(default_factory=list)
+    edges: list[DependencyEdge] = Field(default_factory=list)
+    missing_declared: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    discovery_status: Literal["complete", "partial"] = "complete"
+
+
+class ScanReport(BaseModel):
+    schema_version: Literal["1.0"] = "1.0"
+    tool: str = "PipSutra"
+    tool_version: str
+    generated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    project_path: str
+    environment_path: str
+    inventory: Inventory
+    vulnerabilities: list[VulnerabilityFinding] = Field(default_factory=list)
+    static_findings: list[StaticFinding] = Field(default_factory=list)
+    risk: RiskSummary
+    checks: dict[str, str] = Field(default_factory=dict)
+    errors: list[str] = Field(default_factory=list)