xpl-core 0.3.0__py3-none-any.whl

xpl_core/__init__.py

@@ -0,0 +1,3 @@
+"""xpl-core — Shared schemas, policies and registry for XPL-Suite."""
+
+__version__ = "0.3.0"

xpl_core/config.py

@@ -0,0 +1,74 @@
+"""Canonical JSON-based config loader for XPL-Suite forges."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+_DEFAULT_CONFIG_DIR = Path.home() / ".config" / "xpl-suite"
+
+
+class ForgeConfig:
+    """Per-forge JSON configuration with defaults and persistence."""
+
+    def __init__(
+        self,
+        forge_name: str,
+        config_dir: str | Path | None = None,
+        defaults: dict[str, Any] | None = None,
+    ) -> None:
+        self._forge = forge_name
+        base = Path(config_dir) if config_dir else _DEFAULT_CONFIG_DIR
+        base.mkdir(parents=True, exist_ok=True)
+        self._path = base / f"{forge_name}.json"
+        self._defaults: dict[str, Any] = defaults or {}
+        self._data: dict[str, Any] = {}
+        self._load()
+
+    def _load(self) -> None:
+        if self._path.exists():
+            try:
+                self._data = json.loads(self._path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                self._data = {}
+        else:
+            self._data = {}
+
+    def _save(self) -> None:
+        self._path.write_text(json.dumps(self._data, indent=2), encoding="utf-8")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, self._defaults.get(key, default))
+
+    def set_val(self, key: str, value: Any) -> None:
+        self._data[key] = value
+        self._save()
+
+    def delete(self, key: str) -> bool:
+        if key in self._data:
+            del self._data[key]
+            self._save()
+            return True
+        return False
+
+    def reset(self) -> None:
+        self._data = {}
+        self._save()
+
+    def all_keys(self) -> list[str]:
+        keys = set(self._defaults.keys()) | set(self._data.keys())
+        return sorted(keys)
+
+    def to_dict(self) -> dict[str, Any]:
+        merged = dict(self._defaults)
+        merged.update(self._data)
+        return merged
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def forge_name(self) -> str:
+        return self._forge

xpl_core/credential.py

@@ -0,0 +1,112 @@
+"""Canonical credential models for XPL-Suite forges."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class BaseCredential:
+    """Minimal credential shared by all forge types."""
+
+    username: str | None = None
+    password: str | None = None
+
+    @property
+    def has_password(self) -> bool:
+        return self.password is not None and len(self.password) > 0
+
+    def masked(self) -> str:
+        user = self.username or "(none)"
+        pwd = "****" if self.has_password else "(empty)"
+        return f"{user}:{pwd}"
+
+
+@dataclass(frozen=True)
+class ADCredential(BaseCredential):
+    """Active Directory credential with hash/ticket support."""
+
+    domain: str = ""
+    lm_hash: str = ""
+    nt_hash: str = ""
+    aes_key: str = ""
+    ticket: str = ""
+
+    @classmethod
+    def from_args(cls, args: Any) -> ADCredential:
+        return cls(
+            username=getattr(args, "username", None),
+            password=getattr(args, "password", None),
+            domain=getattr(args, "domain", "") or "",
+            lm_hash=getattr(args, "lm_hash", "") or "",
+            nt_hash=getattr(args, "nt_hash", "") or "",
+            aes_key=getattr(args, "aes_key", "") or "",
+            ticket=getattr(args, "ticket", "") or "",
+        )
+
+    @property
+    def has_hash(self) -> bool:
+        return bool(self.lm_hash or self.nt_hash)
+
+    @property
+    def impacket_hash(self) -> str:
+        lm = self.lm_hash or "aad3b435b51404eeaad3b435b51404ee"
+        nt = self.nt_hash or "31d6cfe0d16ae931b73c59d7e0c089c0"
+        return f"{lm}:{nt}"
+
+
+@dataclass(frozen=True)
+class CloudCredential(BaseCredential):
+    """Cloud provider credential with key/token support."""
+
+    provider: str = ""
+    identity: str = ""
+    credential_type: str = "unknown"
+    access_key: str | None = None
+    secret_key: str | None = None
+    token: str | None = None
+    profile: str | None = None
+    region: str | None = None
+
+    @property
+    def masked_secret(self) -> str:
+        if not self.secret_key:
+            return "(none)"
+        if len(self.secret_key) <= 8:
+            return "****"
+        return self.secret_key[:4] + "****" + self.secret_key[-4:]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "provider": self.provider,
+            "identity": self.identity,
+            "credential_type": self.credential_type,
+            "access_key": self.access_key,
+            "secret_key": self.masked_secret,
+            "token": "****" if self.token else None,
+            "profile": self.profile,
+            "region": self.region,
+        }
+
+
+@dataclass
+class NetworkCredential:
+    """Generic network credential for embedded/industrial/wireless forges."""
+
+    username: str = ""
+    password: str = ""
+    protocol: str = ""
+    port: int = 0
+    community: str = ""
+    private_key: str | None = None
+    tags: list[str] = field(default_factory=list)
+
+    @property
+    def has_password(self) -> bool:
+        return len(self.password) > 0
+
+    def masked(self) -> str:
+        user = self.username or "(none)"
+        pwd = "****" if self.has_password else "(empty)"
+        return f"{user}:{pwd}@{self.protocol}:{self.port}"

xpl_core/dispatcher.py

@@ -0,0 +1,98 @@
+"""Dispatcher — route commands to registered modules.
+
+Generic dispatcher compatible with both function-based modules
+(ADXPL pattern: def run(args) -> int) and class-based modules
+(BaseModule subclasses). Works with PluginRegistry for discovery.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from xpl_core.module import BaseModule, FunctionModule, ModuleResult
+from xpl_core.registry import PluginRegistry, RegisteredModule
+
+
+class DispatchError(Exception):
+    pass
+
+
+class Dispatcher:
+    """Route category/name commands to the appropriate module."""
+
+    def __init__(self, registry: PluginRegistry | None = None) -> None:
+        self._registry = registry or PluginRegistry()
+
+    @property
+    def registry(self) -> PluginRegistry:
+        return self._registry
+
+    def dispatch(self, category: str, name: str, **kwargs: Any) -> ModuleResult:
+        """Dispatch to a registered module by category and name."""
+        entry = self._registry.get(category, name)
+        if entry is None:
+            raise DispatchError(f"Unknown module: {category}/{name}")
+
+        mod = self._load_module(entry)
+        return self._execute(mod, **kwargs)
+
+    def dispatch_args(self, args: Any) -> int:
+        """Dispatch using an argparse Namespace (ADXPL compatibility).
+
+        Expects args.command (category) and args.module (name).
+        Returns an integer exit code.
+        """
+        command: str = getattr(args, "command", "")
+        module_name: str = getattr(args, "module", "")
+
+        entry = self._registry.get(command, module_name)
+        if entry is None:
+            print(
+                f"[!] Unknown module: {command}/{module_name}",
+                file=sys.stderr,
+            )
+            return 1
+
+        try:
+            loaded = entry.load()
+        except ImportError as exc:
+            print(f"[!] Failed to load {entry.import_path}: {exc}", file=sys.stderr)
+            return 1
+
+        if hasattr(loaded, "run") and callable(loaded.run):
+            return int(loaded.run(args))
+        return 1
+
+    def _load_module(self, entry: RegisteredModule) -> BaseModule:
+        loaded = entry.load()
+
+        if isinstance(loaded, type) and issubclass(loaded, BaseModule):
+            return loaded()
+
+        module_cls: Any = getattr(loaded, "Module", None)
+        if module_cls is not None and isinstance(module_cls, type) and issubclass(module_cls, BaseModule):
+            instance: BaseModule = module_cls()
+            return instance
+
+        run_func = getattr(loaded, "run", None)
+        manifest_data = getattr(loaded, "MANIFEST", {})
+        if callable(run_func):
+            manifest_data.setdefault("name", entry.name)
+            manifest_data.setdefault("capability_id", f"{entry.category}.{entry.name}")
+            return FunctionModule(manifest_data, run_func)
+
+        raise DispatchError(
+            f"Module {entry.import_path} has no BaseModule class, "
+            f"Module attribute, or run() function"
+        )
+
+    def _execute(self, module: BaseModule, **kwargs: Any) -> ModuleResult:
+        return module.execute(**kwargs)
+
+    def list_commands(self) -> dict[str, list[str]]:
+        """Return a dict of category -> module names."""
+        result: dict[str, list[str]] = {}
+        for cat in self._registry.list_categories():
+            result[cat] = [m.name for m in self._registry.list_modules(cat)]
+        return result

xpl_core/module.py

@@ -0,0 +1,168 @@
+"""BaseModule ABC — standard interface for all XPL-Suite forge modules.
+
+Every module in the suite (enumeration, attack, exploit, recon, etc.)
+inherits from BaseModule. This ensures a consistent lifecycle:
+    configure → check → run → cleanup
+
+Forges that use function-based modules (def run(args)) can wrap them
+with FunctionModule for compatibility with the dispatcher.
+"""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class SafetyClass(Enum):
+    PASSIVE = "PASSIVE"
+    ACTIVE = "ACTIVE"
+    INTRUSIVE = "INTRUSIVE"
+    DESTRUCTIVE = "DESTRUCTIVE"
+
+
+@dataclass
+class ModuleManifest:
+    capability_id: str
+    name: str
+    description: str = ""
+    safety_class: SafetyClass = SafetyClass.ACTIVE
+    requires_authorization: bool = True
+    side_effects: list[str] = field(default_factory=list)
+    output_schema: str = "xpl.finding.v1"
+    mitre: list[str] = field(default_factory=list)
+    cve: list[str] = field(default_factory=list)
+    authors: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    forge: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "capability_id": self.capability_id,
+            "name": self.name,
+            "description": self.description,
+            "safety_class": self.safety_class.value,
+            "requires_authorization": self.requires_authorization,
+            "side_effects": self.side_effects,
+            "output_schema": self.output_schema,
+            "mitre": self.mitre,
+            "cve": self.cve,
+            "authors": self.authors,
+            "tags": self.tags,
+            "forge": self.forge,
+        }
+
+
+class ModuleStatus(Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILURE = "failure"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class ModuleResult:
+    status: ModuleStatus = ModuleStatus.PENDING
+    exit_code: int = 0
+    findings: list[Any] = field(default_factory=list)
+    output: str = ""
+    error: str = ""
+    elapsed_s: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseModule(ABC):
+    """Abstract base class for XPL-Suite modules."""
+
+    def __init__(self) -> None:
+        self._result = ModuleResult()
+        self._start_time: float = 0.0
+
+    @property
+    @abstractmethod
+    def manifest(self) -> ModuleManifest:
+        ...
+
+    def configure(self, **kwargs: Any) -> None:
+        """Configure module parameters before execution."""
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+
+    def check(self) -> bool | None:
+        """Pre-flight check. Return True if target is likely vulnerable,
+        False if not, None if check is not implemented."""
+        return None
+
+    @abstractmethod
+    def run(self) -> ModuleResult:
+        ...
+
+    def cleanup(self) -> None:  # noqa: B027
+        """Post-execution cleanup. Override if the module allocates resources."""
+
+    def execute(self, **kwargs: Any) -> ModuleResult:
+        """Full lifecycle: configure → check → run → cleanup."""
+        self.configure(**kwargs)
+        self._start_time = time.monotonic()
+        self._result = ModuleResult(status=ModuleStatus.RUNNING)
+        try:
+            self._result = self.run()
+        except Exception as exc:
+            self._result = ModuleResult(
+                status=ModuleStatus.FAILURE,
+                exit_code=1,
+                error=str(exc),
+            )
+        finally:
+            self._result.elapsed_s = time.monotonic() - self._start_time
+            self.cleanup()
+        return self._result
+
+    @property
+    def result(self) -> ModuleResult:
+        return self._result
+
+
+class FunctionModule(BaseModule):
+    """Adapter that wraps a function-based module (def run(args) -> int)
+    into the BaseModule interface."""
+
+    def __init__(
+        self,
+        manifest_data: dict[str, Any],
+        run_func: Any,
+    ) -> None:
+        super().__init__()
+        self._manifest = ModuleManifest(
+            capability_id=manifest_data.get("capability_id", "unknown"),
+            name=manifest_data.get("name", "unnamed"),
+            description=manifest_data.get("description", ""),
+            safety_class=SafetyClass(manifest_data.get("safety_class", "ACTIVE")),
+            requires_authorization=manifest_data.get("requires_authorization", True),
+            side_effects=manifest_data.get("side_effects", []),
+            output_schema=manifest_data.get("output_schema", "xpl.finding.v1"),
+            mitre=manifest_data.get("mitre", []),
+            cve=manifest_data.get("cve", []),
+            authors=manifest_data.get("authors", []),
+            tags=manifest_data.get("tags", []),
+            forge=manifest_data.get("forge", ""),
+        )
+        self._run_func = run_func
+        self._args: Any = None
+
+    @property
+    def manifest(self) -> ModuleManifest:
+        return self._manifest
+
+    def configure(self, **kwargs: Any) -> None:
+        self._args = kwargs.get("args")
+
+    def run(self) -> ModuleResult:
+        exit_code = self._run_func(self._args)
+        status = ModuleStatus.SUCCESS if exit_code == 0 else ModuleStatus.FAILURE
+        return ModuleResult(status=status, exit_code=exit_code)

xpl_core/pool.py

@@ -0,0 +1,87 @@
+"""Canonical adaptive thread/process pool for XPL-Suite forges."""
+
+from __future__ import annotations
+
+import os
+from concurrent.futures import Future, ProcessPoolExecutor, ThreadPoolExecutor
+from enum import Enum
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+T = TypeVar("T")
+R = TypeVar("R")
+
+
+class PoolStrategy(Enum):
+    THREADS = "threads"
+    PROCESSES = "processes"
+    AUTO = "auto"
+
+
+class SmartPool:
+    """Adaptive pool that picks threads vs processes based on workload heuristics."""
+
+    def __init__(
+        self,
+        max_workers: int = 0,
+        strategy: PoolStrategy = PoolStrategy.AUTO,
+        thread_name_prefix: str = "xpl-pool",
+    ) -> None:
+        if max_workers <= 0:
+            max_workers = min(32, (os.cpu_count() or 4) + 4)
+        self._max_workers = max_workers
+        self._strategy = strategy
+        self._prefix = thread_name_prefix
+        self._executor: ThreadPoolExecutor | ProcessPoolExecutor | None = None
+
+    def _get_executor(self, io_bound: bool = True) -> ThreadPoolExecutor | ProcessPoolExecutor:
+        if self._executor is not None:
+            return self._executor
+        if self._strategy == PoolStrategy.THREADS or (
+            self._strategy == PoolStrategy.AUTO and io_bound
+        ):
+            self._executor = ThreadPoolExecutor(
+                max_workers=self._max_workers,
+                thread_name_prefix=self._prefix,
+            )
+        else:
+            self._executor = ProcessPoolExecutor(max_workers=self._max_workers)
+        return self._executor
+
+    def submit(self, fn: Callable[..., R], *args: Any, **kwargs: Any) -> Future[R]:
+        return self._get_executor().submit(fn, *args, **kwargs)
+
+    def map_unordered(
+        self,
+        fn: Callable[[T], R],
+        items: Sequence[T],
+        timeout_per_item: float = 0,
+        on_result: Callable[[R], None] | None = None,
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> list[R]:
+        results: list[R] = []
+        futures = {self.submit(fn, item): item for item in items}
+        for future in futures:
+            try:
+                timeout = timeout_per_item if timeout_per_item > 0 else None
+                result = future.result(timeout=timeout)
+                results.append(result)
+                if on_result:
+                    on_result(result)
+            except Exception as exc:
+                if on_error:
+                    on_error(exc)
+        return results
+
+    def shutdown(self, wait: bool = False) -> None:
+        if self._executor is not None:
+            self._executor.shutdown(wait=wait)
+            self._executor = None
+
+    def __enter__(self) -> SmartPool:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.shutdown(wait=True)

xpl_core/registry.py

@@ -0,0 +1,127 @@
+"""Plugin registry — dynamic module discovery for XPL-Suite.
+
+Supports three discovery mechanisms:
+  1. entry_points (pip-installed forges advertise modules via pyproject.toml)
+  2. module_map (static dict like ADXPL's _MODULE_MAP for import-based routing)
+  3. scan (filesystem scan for modules with MANIFEST dicts)
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RegisteredModule:
+    name: str
+    category: str
+    import_path: str
+    forge: str = ""
+    manifest: dict[str, Any] = field(default_factory=dict)
+    _loaded: Any = field(default=None, repr=False)
+
+    def load(self) -> Any:
+        if self._loaded is None:
+            self._loaded = importlib.import_module(self.import_path)
+        return self._loaded
+
+
+class PluginRegistry:
+    """Central registry for all XPL-Suite modules across forges."""
+
+    def __init__(self) -> None:
+        self._modules: dict[str, RegisteredModule] = {}
+        self._categories: dict[str, list[str]] = {}
+
+    @property
+    def count(self) -> int:
+        return len(self._modules)
+
+    def register(
+        self,
+        name: str,
+        category: str,
+        import_path: str,
+        forge: str = "",
+        manifest: dict[str, Any] | None = None,
+    ) -> None:
+        key = f"{category}/{name}"
+        mod = RegisteredModule(
+            name=name,
+            category=category,
+            import_path=import_path,
+            forge=forge,
+            manifest=manifest or {},
+        )
+        self._modules[key] = mod
+        self._categories.setdefault(category, []).append(key)
+
+    def get(self, category: str, name: str) -> RegisteredModule | None:
+        return self._modules.get(f"{category}/{name}")
+
+    def list_categories(self) -> list[str]:
+        return sorted(self._categories.keys())
+
+    def list_modules(self, category: str | None = None) -> list[RegisteredModule]:
+        if category is not None:
+            keys = self._categories.get(category, [])
+            return [self._modules[k] for k in keys]
+        return list(self._modules.values())
+
+    def search(self, query: str) -> list[RegisteredModule]:
+        q = query.lower()
+        return [
+            m for m in self._modules.values()
+            if q in m.name.lower()
+            or q in m.category.lower()
+            or q in m.import_path.lower()
+            or any(q in str(v).lower() for v in m.manifest.values())
+        ]
+
+    def load_from_map(
+        self,
+        module_map: dict[str, dict[str, str]],
+        forge: str = "",
+    ) -> int:
+        """Load modules from a static category->name->import_path map
+        (compatible with ADXPL's _MODULE_MAP pattern)."""
+        count = 0
+        for category, modules in module_map.items():
+            for name, import_path in modules.items():
+                self.register(name, category, import_path, forge=forge)
+                count += 1
+        return count
+
+    def load_from_entry_points(self, group: str = "xpl_suite.modules") -> int:
+        """Discover modules from pip entry_points (PEP 621)."""
+        count = 0
+        from importlib.metadata import entry_points
+        eps: Any = entry_points(group=group)
+
+        for ep in eps:
+            parts = ep.name.split(".", 1)
+            category = parts[0] if len(parts) > 1 else "default"
+            name = parts[-1]
+            self.register(
+                name=name,
+                category=category,
+                import_path=ep.value if isinstance(ep.value, str) else f"{ep.value}",
+                forge=ep.group if hasattr(ep, "group") else "",
+            )
+            count += 1
+        return count
+
+    def unregister(self, category: str, name: str) -> bool:
+        key = f"{category}/{name}"
+        if key in self._modules:
+            del self._modules[key]
+            if key in self._categories.get(category, []):
+                self._categories[category].remove(key)
+            return True
+        return False
+
+    def clear(self) -> None:
+        self._modules.clear()
+        self._categories.clear()