solorider 1.0.0__py3-none-any.whl

solorider/__init__.py

@@ -0,0 +1,7 @@
+"""solorider: an extensible framework which allows security practitioners to efficiently iterate on the rapid detection and profiling of potential supply-chain attacks of libraries hosted on code repositories."""
+
+from .core import Core
+from .plugin_base import PluginBase, exported
+from .solorider import SupplyChainDetector
+
+__all__ = ["Core", "PluginBase", "SupplyChainDetector", "exported"]

solorider/auditors/__init__.py

@@ -0,0 +1,10 @@
+"""solorider audit platform: audit plugins, loader, and dispatcher."""
+
+from .audit_plugin_base import AuditPluginBase
+from .audit_dispatcher import AuditDispatcher, load_audit_plugins
+
+__all__ = [
+    "AuditPluginBase",
+    "AuditDispatcher",
+    "load_audit_plugins",
+]

solorider/auditors/audit_dispatcher.py

@@ -0,0 +1,117 @@
+"""
+Loader and dispatcher for solorider audit plugins.
+
+Mirrors the analyzer plugin loader (``loader.load_plugins_from_directory``):
+audit plugins are discovered from the ``audit_plugins`` directory and
+*initialized* up front, but a given plugin only runs when it is
+dispatched by name.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import textwrap
+from pathlib import Path
+
+from .audit_plugin_base import AuditPluginBase
+
+
+def load_audit_plugins(
+    plugins_dir: Path | None = None,
+) -> list[AuditPluginBase]:
+    """
+    Discover and instantiate every audit plugin in the ``audit_plugins``
+    directory.
+
+    Scans each ``.py`` file (excluding ``_``-prefixed), imports it, and
+    instantiates any class that subclasses ``AuditPluginBase``. Returns
+    a list of *initialized* plugin instances, sorted by filename --
+    consistent with the analyzer plugin loader.
+    """
+    if plugins_dir is None:
+        plugins_dir = Path(__file__).resolve().parent / "audit_plugins"
+
+    plugins: list[AuditPluginBase] = []
+
+    if not plugins_dir.is_dir():
+        return plugins
+
+    for file_path in sorted(plugins_dir.glob("*.py")):
+        if file_path.name.startswith("_"):
+            continue
+
+        module_name = f"_solorider_audit_plugin_{file_path.stem}"
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            continue
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if (
+                issubclass(obj, AuditPluginBase)
+                and obj is not AuditPluginBase
+                and obj.__module__ == module_name
+            ):
+                plugins.append(obj())
+
+    return plugins
+
+
+class AuditDispatcher:
+    """
+    Loads (initializes) all audit plugins on construction, and runs a
+    specific one only when dispatched by name.
+    """
+
+    def __init__(self, plugins_dir: Path | None = None):
+        self.plugins = load_audit_plugins(plugins_dir)
+
+    def get(self, name: str) -> AuditPluginBase | None:
+        """Return the initialized plugin whose ``name`` matches, or None."""
+        for plugin in self.plugins:
+            if plugin.name == name:
+                return plugin
+        return None
+
+    def dispatch(self, name: str, *args, **kwargs):
+        """
+        Run the audit plugin identified by *name* and return its result.
+
+        Any additional positional/keyword arguments are forwarded to the
+        plugin's ``run()`` -- this is how a plugin that requires input
+        (e.g. the npm auditor's target path) receives it.
+
+        Raises:
+            ValueError: if no plugin with that name is registered.
+        """
+        plugin = self.get(name)
+        if plugin is None:
+            available = ", ".join(p.name for p in self.plugins)
+            raise ValueError(
+                f"No audit plugin named '{name}'. Available: {available}"
+            )
+        return plugin.run(*args, **kwargs)
+
+    def list_plugins(self) -> None:
+        """
+        Print the available audit plugins (name + description) to stdout,
+        consistent with ``SupplyChainDetector.list_plugins()``.
+        """
+        wrap_width = 76
+        marker = "  [+] "
+        indent = " " * len(marker)
+
+        heading = "Audit Plugins"
+        print()
+        print(heading)
+        print("=" * len(heading))
+
+        for plugin in self.plugins:
+            print(f"{marker}{plugin.name}")
+            if plugin.description:
+                for line in textwrap.wrap(plugin.description, width=wrap_width):
+                    print(f"{indent}{line}")
+            print()

solorider/auditors/audit_plugin_base.py

@@ -0,0 +1,80 @@
+"""Base class for solorider audit plugins."""
+
+from __future__ import annotations
+
+
+class AuditPluginBase:
+    """
+    Contract for an audit plugin.
+
+    An audit plugin is responsible for, on a single platform (e.g.
+    Python or npm), discovering the packages installed on the local
+    system, determining each package's pinned version, and locating
+    where that specific version's source code lives on disk.
+
+    Subclasses initialize, in their ``__init__``, two object properties:
+        name        : str  -- unique identifier used to invoke the plugin
+        description : str  -- human-readable summary of the plugin
+
+    and a per-instance findings index:
+        PACKAGE_INDEX : list  -- accumulates identified packages
+
+    Subclasses implement three core functions:
+        run()                     -- entry point; orchestrates the audit
+        enum_installed_packages() -- discover installed packages + versions
+        find_package_code()       -- locate each package's code on disk
+
+    ``add_new_package()`` is provided here (its behaviour is identical
+    across platforms) and records a finding into ``PACKAGE_INDEX``.
+
+    NOTE: ``PACKAGE_INDEX`` is initialized per instance in ``__init__``,
+    so each plugin object keeps its own findings list (a fresh list per
+    instantiation) rather than sharing one across plugins or runs.
+    """
+
+    def __init__(self):
+        self.name: str = ""
+        self.description: str = ""
+        self.PACKAGE_INDEX: list = []
+
+    # ---- core functions (implemented by subclasses) ----------------------
+
+    def run(self, *args, **kwargs) -> list:
+        """
+        Entry point for the audit.
+
+        Orchestrates ``enum_installed_packages()`` and
+        ``find_package_code()``, recording each result via
+        ``add_new_package()``, and returns ``PACKAGE_INDEX``.
+
+        Accepts optional arguments for plugins that require input (e.g.
+        a path to scan); plugins that need no input ignore them.
+        """
+        raise NotImplementedError
+
+    def enum_installed_packages(self):
+        """Discover installed packages and their pinned versions."""
+        raise NotImplementedError
+
+    def find_package_code(self):
+        """Determine where each installed package's code lives on disk."""
+        raise NotImplementedError
+
+    # ---- shared functionality --------------------------------------------
+
+    def add_new_package(self, pinned_version, path_to_code) -> None:
+        """
+        Record an identified package in ``PACKAGE_INDEX``.
+
+        Args:
+            pinned_version: the determined pinned version
+                (e.g. ``flask==3.0.3`` / ``express@5.2.1``).
+            path_to_code: filesystem path to where that specific
+                version's source code actually lives.
+        """
+        self.PACKAGE_INDEX.append(
+            {"pinned_version": pinned_version, "path_to_code": path_to_code}
+        )
+
+    def __repr__(self) -> str:
+        return f"<AuditPlugin name={self.name!r} found={len(self.PACKAGE_INDEX)}>"

solorider/auditors/audit_plugins/__init__.py

@@ -0,0 +1 @@
+"""Audit plugins package. Plugins are auto-discovered by the dispatcher."""

solorider/auditors/audit_plugins/npm_auditor.py

@@ -0,0 +1,197 @@
+"""npm platform audit plugin."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from solorider.auditors.audit_plugin_base import AuditPluginBase
+from solorider.lib.helpers import npm_lockfile_parser
+
+
+class NpmAuditor(AuditPluginBase):
+    """Audits npm packages installed under a node_modules tree.
+
+    Unlike the Python auditor (whose environment is implicit), npm
+    packages live under a ``node_modules`` directory that must be
+    supplied. The target -- a ``node_modules`` directory or a project
+    root containing one -- can be passed at construction or to ``run()``
+    (and therefore via ``AuditDispatcher.dispatch("npm", target)``).
+
+    When a lockfile is present (the hidden
+    ``node_modules/.package-lock.json``, or a project-root
+    ``package-lock.json`` / ``npm-shrinkwrap.json``),
+    ``enum_installed_packages`` uses the shared
+    ``lib.helpers.npm_lockfile_parser``, which returns each package's
+    pinned version together with its install path -- so the code
+    location is resolved directly (project root + install path), and
+    every distinct install directory is represented (the same version at
+    two locations yields two entries). When no lockfile is present, it
+    falls back to a scope- and nesting-aware walk of ``node_modules``
+    reading each ``package.json``.
+    """
+
+    def __init__(self, target=None):
+        super().__init__()
+        self.name = "npm"
+        self.description = (
+            "Audits npm packages installed under a node_modules tree, "
+            "resolving each to a pinned version (name@version) and the "
+            "on-disk location of its source code. Requires a target "
+            "argument: the path to a node_modules directory or a "
+            "project root containing one (passed to run() or via "
+            "dispatch('npm', target))."
+        )
+        self.PACKAGE_INDEX = []
+        self.target = target
+
+    # ---- core functions --------------------------------------------------
+
+    def run(self, target=None, **kwargs) -> list:
+        """
+        Entry point. Enumerates the installed packages, validates each
+        package's code location, and records every finding via
+        ``add_new_package()``.
+
+        Args:
+            target: path to a ``node_modules`` directory or a project
+                root containing one. Falls back to the target supplied
+                at construction. If neither is set, the auditor does not
+                run and returns an empty list.
+
+        Extra keyword arguments are accepted and ignored, so callers
+        (e.g. the dispatcher forwarding assessment kwargs) can pass
+        through arguments this plugin does not need.
+        """
+        self.PACKAGE_INDEX = []
+
+        for record in self.enum_installed_packages(target):
+            code_path = self.find_package_code(record)
+            if code_path is None:
+                continue
+            self.add_new_package(record["pinned_version"], str(code_path))
+
+        return self.PACKAGE_INDEX
+
+    def enum_installed_packages(self, target=None) -> list:
+        """
+        Enumerate installed npm packages with their pinned version and
+        install path.
+
+        If a lockfile is identified, uses the shared
+        ``npm_lockfile_parser`` from ``/lib`` -- which returns each
+        package's ``pinned_version`` and ``install_path`` -- and
+        resolves the path against the project root. Otherwise falls back
+        to walking ``node_modules``. Returns a list of records, each
+        with ``pinned_version`` and an absolute ``path``.
+
+        If no target was provided (here or at construction), the auditor
+        does not run and returns an empty list.
+        """
+        target = target if target is not None else self.target
+        if target is None:
+            return []
+
+        node_modules = self._resolve_node_modules(Path(target))
+        if node_modules is None:
+            return []
+
+        project_root = node_modules.parent
+        lockfile = self._find_lockfile(node_modules, project_root)
+
+        if lockfile is not None:
+            # Lockfile present: pinned version + install path come
+            # straight from the shared parser; resolve the path against
+            # the project root.
+            return [
+                {
+                    "pinned_version": entry["pinned_version"],
+                    "path": project_root / entry["install_path"],
+                }
+                for entry in npm_lockfile_parser(lockfile)
+            ]
+
+        # No lockfile: walk node_modules (yields pinned_version + path).
+        return self._walk_node_modules(node_modules)
+
+    def find_package_code(self, record) -> Path | None:
+        """
+        Return the on-disk code location for an enumerated *record*,
+        validated to exist as a directory (else ``None``).
+        """
+        path = Path(record["path"])
+        return path if path.is_dir() else None
+
+    # ---- helpers: target / lockfile --------------------------------------
+
+    @staticmethod
+    def _resolve_node_modules(target: Path) -> Path | None:
+        """Resolve *target* to a node_modules directory, or None."""
+        if (target / "node_modules").is_dir():
+            return target / "node_modules"
+        if target.is_dir():
+            return target
+        return None
+
+    @staticmethod
+    def _find_lockfile(node_modules: Path, project_root: Path) -> Path | None:
+        """Locate the authoritative lockfile, if present."""
+        for candidate in (
+            node_modules / ".package-lock.json",
+            project_root / "package-lock.json",
+            project_root / "npm-shrinkwrap.json",
+        ):
+            if candidate.is_file():
+                return candidate
+        return None
+
+    # ---- helpers: filesystem walk fallback -------------------------------
+
+    def _walk_node_modules(self, node_modules: Path) -> list:
+        """
+        Scope- and nesting-aware walk of *node_modules*, reading each
+        package's ``package.json`` for name/version. Used when no
+        lockfile is available.
+        """
+        records: list = []
+        self._scan_dir(node_modules, records)
+        return records
+
+    def _scan_dir(self, modules_dir: Path, records: list) -> None:
+        """Scan one node_modules level, descending into scopes."""
+        if not modules_dir.is_dir():
+            return
+
+        for entry in sorted(modules_dir.iterdir()):
+            if entry.name.startswith("."):
+                # .bin, .cache, .package-lock.json, etc.
+                continue
+            if not entry.is_dir():
+                continue
+
+            if entry.name.startswith("@"):
+                # scope directory: each child is a package
+                for scoped in sorted(entry.iterdir()):
+                    if scoped.is_dir():
+                        self._collect_package(scoped, records)
+            else:
+                self._collect_package(entry, records)
+
+    def _collect_package(self, pkg_dir: Path, records: list) -> None:
+        """Record a single package, then recurse into nested node_modules."""
+        manifest = pkg_dir / "package.json"
+        if manifest.is_file():
+            try:
+                data = json.loads(manifest.read_text(encoding="utf-8"))
+            except (ValueError, OSError):
+                data = {}
+            name = data.get("name")
+            version = data.get("version")
+            if name and version:
+                records.append(
+                    {"pinned_version": f"{name}@{version}", "path": pkg_dir}
+                )
+
+        nested = pkg_dir / "node_modules"
+        if nested.is_dir():
+            self._scan_dir(nested, records)

solorider/auditors/audit_plugins/python_auditor.py

@@ -0,0 +1,149 @@
+"""Python platform audit plugin."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from pathlib import Path
+
+from solorider.auditors.audit_plugin_base import AuditPluginBase
+
+
+class PythonAuditor(AuditPluginBase):
+    """Audits Python packages installed in the local environment.
+
+    Uses ``importlib.metadata`` as the authoritative source of installed
+    distributions (it correctly handles regular packages, single-file
+    modules, namespace packages, and multi-directory distributions),
+    resolving each to a pinned version (``name==version``) and the
+    on-disk location(s) of its source code.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.name = "python"
+        self.description = (
+            "Audits Python packages installed in the local environment, "
+            "resolving each to a pinned version (name==version) and the "
+            "on-disk location of its source code."
+        )
+        self.PACKAGE_INDEX = []
+
+    # ---- core functions --------------------------------------------------
+
+    def run(self, **kwargs) -> list:
+        """
+        Entry point. Enumerates installed distributions, resolves each to
+        a pinned version and its code path(s), records every finding via
+        ``add_new_package()``, and returns ``PACKAGE_INDEX``.
+
+        A distribution that installs more than one top-level (e.g.
+        ``setuptools`` -> setuptools/, pkg_resources/, _distutils_hack/)
+        yields one entry per code location, all sharing the same pinned
+        version. ``PACKAGE_INDEX`` is reset at the start so repeated runs
+        are idempotent.
+
+        This auditor needs no input (the environment is implicit); extra
+        keyword arguments are accepted and ignored.
+        """
+        self.PACKAGE_INDEX = []
+
+        for distribution in self.enum_installed_packages():
+            name = distribution.metadata["Name"]
+            version = distribution.version
+            if not name or not version:
+                continue
+
+            pinned_version = f"{name}=={version}"
+            for code_path in self.find_package_code(distribution):
+                self.add_new_package(pinned_version, str(code_path))
+
+        return self.PACKAGE_INDEX
+
+    def enum_installed_packages(self) -> list:
+        """
+        Enumerate installed Python distributions via
+        ``importlib.metadata.distributions()``.
+
+        Returns the ``Distribution`` objects, de-duplicated by
+        (name, version) so packages discovered on more than one
+        ``sys.path`` entry are not reported twice.
+        """
+        seen = set()
+        distributions = []
+
+        for distribution in importlib.metadata.distributions():
+            name = distribution.metadata["Name"]
+            version = distribution.version
+            if not name or not version:
+                continue
+
+            key = (name.lower(), version)
+            if key in seen:
+                continue
+            seen.add(key)
+            distributions.append(distribution)
+
+        return distributions
+
+    def find_package_code(self, distribution) -> list:
+        """
+        Resolve where *distribution*'s source code lives on disk.
+
+        Determines the distribution's top-level importable name(s) and
+        maps each to a real path: a package directory
+        (``site-packages/<name>``) or a single-file module
+        (``site-packages/<name>.py``). Returns a de-duplicated list of
+        ``Path`` objects (empty if nothing could be resolved, e.g. an
+        editable install whose code lives outside site-packages).
+        """
+        code_paths = []
+
+        for top_level in self._top_level_names(distribution):
+            directory = Path(distribution.locate_file(top_level))
+            if directory.is_dir():
+                code_paths.append(directory)
+                continue
+
+            module = Path(distribution.locate_file(f"{top_level}.py"))
+            if module.is_file():
+                code_paths.append(module)
+
+        return list(dict.fromkeys(code_paths))
+
+    # ---- helpers ---------------------------------------------------------
+
+    @staticmethod
+    def _top_level_names(distribution) -> list:
+        """
+        Determine a distribution's top-level importable names.
+
+        Prefers the authoritative ``top_level.txt``; if absent (some
+        newer wheels omit it), infers the names from the installed file
+        manifest (RECORD), skipping metadata/data directories.
+        """
+        text = distribution.read_text("top_level.txt")
+        if text:
+            names = [line.strip() for line in text.splitlines() if line.strip()]
+            if names:
+                return list(dict.fromkeys(names))
+
+        names = []
+        for file in distribution.files or []:
+            parts = file.parts
+            if not parts:
+                continue
+
+            first = parts[0]
+            if first.endswith((".dist-info", ".egg-info", ".data")):
+                continue
+
+            if len(parts) == 1:
+                # A top-level single-file module (e.g. six.py -> six).
+                leaf = Path(first)
+                if leaf.suffix == ".py":
+                    names.append(leaf.stem)
+            else:
+                # A top-level package directory.
+                names.append(first)
+
+        return list(dict.fromkeys(names))

solorider/cache/.gitkeep

@@ -0,0 +1,7 @@
+# This placeholder ensures the `cache/` directory ships with the
+# installed package. Python packaging cannot include an empty
+# directory, so this file gives it something to carry.
+#
+# Session output (downloads/, extracted/, other/) is written here at
+# runtime by solorider.lib.helpers.create_session_dirs(), which creates
+# any missing subdirectories on demand.