Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

18.3 KB
Raw Blame
"""
ARES Plugin Loader
Auto-discovers modules via three mechanisms (in priority order):

1. Built-in   - ares/modules/**/*.py   (always loaded, trusted)
2. Entry points - third-party packages that register ares.modules entry points
3. External dir - ARES_PLUGIN_DIR env var (drop-in .py files, no install needed)

Security controls added in v1.0.0:
  - Signature verification before loading external/entry-point modules
  - Capability enforcement: modules can only declare allowed caps for their trust level
  - Trust level assigned per source: builtin > entrypoint > external > unsigned
  - Unsigned external modules loaded with capability restriction warning

Trust levels:
  builtin     - shipped with ARES, always trusted
  entrypoint  - installed pip package with ares.modules entry point → WARN_UNSIGNED
  external    - .py file in plugin dir → REQUIRE_SIGNED (configurable)
  unsigned    - passes WARN/ALLOW policy, cap-restricted

Config:
  ARES_PLUGIN_SIGNING_POLICY = require_signed | warn_unsigned | allow_all
  ARES_PLUGIN_DIR             = ~/.ares/plugins
"""

from __future__ import annotations

import importlib
import importlib.metadata
import importlib.util
import inspect
import os as _os
import sys
from collections.abc import Iterable
from pathlib import Path
from typing import TYPE_CHECKING, Any

from ares.core.logger import get_logger

logger = get_logger("ares.plugin.loader")

if TYPE_CHECKING:
    from ares.modules.base import BaseModule


# ── Security config ────────────────────────────────────────────────────────────
# Operator configures via env var or AresSettings
_SIGNING_POLICY = _os.environ.get("ARES_PLUGIN_SIGNING_POLICY", "warn_unsigned")


def _get_signing_policy():
    """Lazy import to avoid circular deps."""
    try:
        from ares.core.signing import ModuleVerifier, SigningPolicy

        policies = {
            "require_signed": SigningPolicy.REQUIRE_SIGNED,
            "warn_unsigned": SigningPolicy.WARN_UNSIGNED,
            "allow_all": SigningPolicy.ALLOW_ALL,
            "trusted_only": SigningPolicy.TRUSTED_ONLY,
        }
        return ModuleVerifier(
            policy=policies.get(_SIGNING_POLICY, SigningPolicy.WARN_UNSIGNED)
        )
    except ImportError:
        return None


def _is_path_within_base(path: Path, base: Path) -> bool:
    return path == base or path.is_relative_to(base)


def _enforce_capabilities(cls: Any, source: str) -> list[str]:
    """
    Check a module's declared CAPABILITIES against its trust level.
    Returns list of violation messages. Empty = clean.
    """
    try:
        from ares.core.capabilities import (
            CapabilityPolicy,
            default_capabilities_for_category,
        )

        trust_map = {"builtin": "builtin", "entrypoint": "community"}
        trust_level = trust_map.get(source.split(":")[0], "external")
        caps = getattr(cls, "CAPABILITIES", None)
        if caps is None:
            # Assign sensible defaults if not declared
            category = getattr(cls, "MODULE_CATEGORY", "")
            cls.CAPABILITIES = default_capabilities_for_category(category)
            return []
        return CapabilityPolicy.validate(
            getattr(cls, "MODULE_ID", "?"), frozenset(caps), trust_level
        )
    except (AttributeError, ImportError, TypeError):
        return []


# ── Module Registry ───────────────────────────────────────────────────────────


class ModuleRegistry:
    """
    Central registry for all loaded ARES modules.
    Supports tagging, filtering, and metadata lookup.
    """

    def __init__(self) -> None:
        self._registry: dict[str, type[BaseModule]] = {}
        self._disabled: dict[str, type[BaseModule]] = {}
        self._sources: dict[str, str] = (
            {}
        )  # module_id → source (builtin/entrypoint/external)

    def register(self, cls: type[BaseModule], source: str = "builtin") -> None:
        mid = getattr(cls, "MODULE_ID", "")
        if not mid:
            return
        if getattr(cls, "ENABLED", True) is False:
            self._disabled[mid] = cls
            self._sources[mid] = source
            logger.info("registry_disabled_module", mid=mid, source=source)
            return
        if mid in self._registry:
            existing_source = self._sources.get(mid, "unknown")
            logger.debug(
                "registry_skipping_duplicate_from_already_from",
                mid=mid,
                source=source,
                existing_source=existing_source,
            )
            return
        self._registry[mid] = cls
        self._sources[mid] = source
        logger.debug("registry_registered_from", mid=mid, source=source)

    def is_disabled(self, module_id: str) -> bool:
        if module_id in self._disabled:
            return True
        cls = self._registry.get(module_id)
        if cls is not None and getattr(cls, "ENABLED", True) is False:
            return True
        return False

    def get_disabled_reason(self, module_id: str) -> str | None:
        cls = self._disabled.get(module_id) or self._registry.get(module_id)
        if cls is not None:
            return getattr(cls, "DISABLED_REASON", "") or "module disabled"
        return None

    def get(self, module_id: str) -> type[BaseModule] | None:
        return self._registry.get(module_id)

    def get_disabled(self, module_id: str) -> type[BaseModule] | None:
        return self._disabled.get(module_id)

    def __setitem__(self, module_id: str, cls: type[BaseModule]) -> None:
        if getattr(cls, "ENABLED", True) is False:
            self._disabled[module_id] = cls
        else:
            self._registry[module_id] = cls

    def all(self) -> list[type[BaseModule]]:
        return [
            cls for mid, cls in self._registry.items()
            if getattr(cls, "ENABLED", True) is not False and mid not in self._disabled
        ]

    def by_category(self, category: str) -> list[type[BaseModule]]:
        return [
            cls
            for mid, cls in self._registry.items()
            if cls.MODULE_CATEGORY == category
            and getattr(cls, "ENABLED", True) is not False
            and mid not in self._disabled
        ]

    def list_metadata(self) -> list[dict[str, Any]]:
        """
        Return full metadata for every registered module.

        Delegates to BaseModule.metadata() so the shape is always consistent
        with what operators see in the CLI, dashboard, and /modules API endpoint.
        Adds the registry-specific 'source' field (builtin/entrypoint/external).
        """
        result = []
        for mid, cls in sorted(self._registry.items()):
            if getattr(cls, "ENABLED", True) is False or mid in self._disabled:
                continue
            try:
                # BaseModule.metadata() returns the canonical dict including
                # opsec_level, requires, outputs, mitre_list, min_noise_profile
                meta = cls.metadata()
            except Exception:
                # Fallback for malformed community modules
                meta = {
                    "id": mid,
                    "name": getattr(cls, "MODULE_NAME", mid),
                    "category": getattr(cls, "MODULE_CATEGORY", ""),
                    "description": getattr(cls, "MODULE_DESCRIPTION", ""),
                    "opsec_level": str(getattr(cls, "OPSEC_LEVEL", "unknown")),
                    "requires": list(getattr(cls, "REQUIRES", [])),
                    "outputs": list(getattr(cls, "OUTPUTS", [])),
                    "mitre": ", ".join(getattr(cls, "MITRE_TECHNIQUES", [])),
                    "mitre_list": list(getattr(cls, "MITRE_TECHNIQUES", [])),
                    "author": getattr(cls, "MODULE_AUTHOR", "ARES Team"),
                    "min_noise_profile": getattr(cls, "MIN_NOISE_PROFILE", None),
                }
            # Inject the registry source tag
            meta["source"] = self._sources.get(mid, "unknown")
            result.append(meta)
        return result

    def __len__(self) -> int:
        return len(self._registry)

    def __contains__(self, module_id: str) -> bool:
        return module_id in self._registry and not self.is_disabled(module_id)


# ── Loader ────────────────────────────────────────────────────────────────────


class PluginLoader:
    """
    Three-source module loader.

    Usage:
        loader = PluginLoader()
        registry = loader.load_all()
    """

    BUILTIN_MODULES_PATH = Path(__file__).parent.parent.parent / "modules"
    ENTRY_POINT_GROUP = "ares.modules"
    EXTERNAL_DIR_ENV = "ARES_PLUGIN_DIR"

    def __init__(
        self,
        *,
        trusted_external_roots: Iterable[str | Path] | None = None,
    ) -> None:
        self.registry = ModuleRegistry()
        self._errors: list[dict[str, str]] = []
        # Explicit process-local injection for controlled embedding/tests only;
        # it never expands the production environment/default allowlist.
        self._trusted_external_roots = tuple(
            Path(root).resolve() for root in (trusted_external_roots or ())
        )

    # ── Public API ─────────────────────────────────────────────────────────

    def load_all(self, external_dir: str | None = None) -> ModuleRegistry:
        """Load from all three sources. Returns the registry."""
        n_builtin = self._load_builtin()
        n_entrypoint = self._load_entry_points()
        n_external = self._load_external(external_dir)

        total = len(self.registry)
        logger.info(
            f"[plugin_loader] Loaded {total} modules "
            f"(builtin={n_builtin} entrypoints={n_entrypoint} external={n_external})"
        )
        if self._errors:
            logger.warning("plugin_loader_load_errors")
            for err in self._errors:
                logger.debug(
                    "plugin_load_error",
                    path=err.get("path", ""),
                    error=err.get("error", ""),
                )

        return self.registry

    @property
    def errors(self) -> list[dict[str, str]]:
        return list(self._errors)

    # ── Source 1: Built-in ─────────────────────────────────────────────────

    def _load_builtin(self) -> int:
        before = len(self.registry)
        for py_file in sorted(self.BUILTIN_MODULES_PATH.rglob("*.py")):
            if py_file.stem.startswith("_") or py_file.stem == "base":
                continue
            rel = py_file.relative_to(self.BUILTIN_MODULES_PATH.parent.parent)
            module_path = ".".join(rel.with_suffix("").parts)
            self._import_and_register(module_path, source="builtin")
        return len(self.registry) - before

    # ── Source 2: Entry points ─────────────────────────────────────────────

    def _load_entry_points(self) -> int:
        """
        Third-party packages can ship ARES modules by adding to their pyproject.toml:

            [project.entry-points."ares.modules"]
            my_module = "my_package.modules.my_module:MyModule"

        ARES will discover and load them automatically.
        """
        before = len(self.registry)
        try:
            eps = importlib.metadata.entry_points(group=self.ENTRY_POINT_GROUP)
        except Exception as e:
            logger.debug("plugin_loader_entry_points_failed", e=e)
            return 0

        for ep in eps:
            try:
                cls = ep.load()
                if self._is_valid_module_class(cls):
                    self.registry.register(cls, source=f"entrypoint:{ep.value}")
                else:
                    logger.warning(
                        "plugin_loader_entry_point_is_not_a_valid_basemodul",
                        name=ep.name,
                    )
            except Exception as e:
                self._errors.append({"path": ep.value, "error": str(e)})
                logger.warning(
                    "plugin_loader_failed_to_load_entry_point", name=ep.name, e=e
                )

        return len(self.registry) - before

    # ── Source 3: External dir ─────────────────────────────────────────────

    def _load_external(self, external_dir: str | None = None) -> int:
        """
        Load .py files from an external directory.
        Directory can be set via:
          1. explicit external_dir arg
          2. ARES_PLUGIN_DIR environment variable
          3. ~/.ares/plugins/ (default fallback)

        Great for:
          - Custom client-specific modules
          - Rapid prototyping without pip install
          - Private modules that shouldn't be in the repo
        """
        import os

        before = len(self.registry)

        configured_dir = external_dir or os.environ.get(self.EXTERNAL_DIR_ENV)
        plugin_dir = (
            Path(configured_dir)
            if configured_dir
            else Path.home() / ".ares" / "plugins"
        )

        # Path traversal guard - resolve to absolute path and verify it stays within
        # an allowed base (home dir or explicitly trusted locations).
        try:
            plugin_dir = plugin_dir.resolve()
        except (OSError, ValueError) as exc:
            logger.error("plugin_loader_invalid_plugin_dir_path", exc=exc)
            return 0

        _allowed_bases = [
            Path.home().resolve(),
            *self._trusted_external_roots,
            Path("/tmp").resolve(),  # noqa: S108  - sandbox staging area
        ]
        if not any(
            _is_path_within_base(plugin_dir, base) for base in _allowed_bases
        ):
            logger.error(
                f"[plugin_loader] Rejected plugin dir outside allowed locations: {plugin_dir}. "
                f"Must be under home directory or /tmp."
            )
            return 0

        if not plugin_dir.exists():
            if not configured_dir:
                logger.debug(
                    "plugin_loader_default_external_dir_missing", plugin_dir=plugin_dir
                )
                return 0
            plugin_dir.mkdir(parents=True, exist_ok=True)
            logger.debug(
                "plugin_loader_created_external_plugin_dir", plugin_dir=plugin_dir
            )
            return 0

        for py_file in sorted(plugin_dir.glob("*.py")):
            if py_file.stem.startswith("_"):
                continue
            self._load_file_module(py_file, source=f"external:{plugin_dir}")

        return len(self.registry) - before

    # ── Helpers ────────────────────────────────────────────────────────────

    def _import_and_register(self, module_path: str, source: str) -> None:
        try:
            mod = importlib.import_module(module_path)
            for _, cls in inspect.getmembers(mod, inspect.isclass):
                if self._is_valid_module_class(cls):
                    self.registry.register(cls, source=source)
        except Exception as e:
            self._errors.append({"path": module_path, "error": str(e)})
            logger.debug("plugin_loader_could_not_import", module_path=module_path, e=e)

    def _load_file_module(self, path: Path, source: str) -> None:
        """
        Load a .py file by path without needing it on sys.path.
        Security: verifies signature before executing module code.
        """
        module_name = f"ares_external.{path.stem}"

        # ── Signature verification (v1.0.0) ───────────────────────────────
        verifier = _get_signing_policy()
        if verifier:
            try:
                result = verifier.verify_file(path)
                verifier.enforce_policy(result)
                trust = result.trust_level.value
                if trust not in ("trusted", "community"):
                    logger.warning(
                        f"[plugin_loader] Loading {path.name!r} with trust={trust!r} "
                        f" -  capabilities will be restricted"
                    )
            except ValueError as e:
                self._errors.append({"path": str(path), "error": str(e)})
                logger.error("plugin_loader_refusing_to_load", name=path.name, e=e)
                return  # BLOCK: policy violation

        try:
            spec = importlib.util.spec_from_file_location(module_name, path)
            if spec is None or spec.loader is None:
                return
            mod = importlib.util.module_from_spec(spec)
            sys.modules[module_name] = mod
            spec.loader.exec_module(mod)

            for _, cls in inspect.getmembers(mod, inspect.isclass):
                if self._is_valid_module_class(cls):
                    # ── Capability enforcement (v1.0.0) ───────────────────
                    cap_violations = _enforce_capabilities(cls, source)
                    if cap_violations:
                        for v in cap_violations:
                            logger.error("plugin_loader_capability_violation", v=v)
                            self._errors.append({"path": str(path), "error": v})
                        continue  # Skip module - capability violation

                    self.registry.register(cls, source=source)

        except Exception as e:
            self._errors.append({"path": str(path), "error": str(e)})
            logger.warning(
                "plugin_loader_failed_to_load_external_plugin", name=path.name, e=e
            )

    @staticmethod
    def _is_valid_module_class(cls: Any) -> bool:
        """Check if a class is a valid ARES module (not the base class itself)."""
        from ares.modules.base import BaseModule

        return (
            inspect.isclass(cls)
            and issubclass(cls, BaseModule)
            and cls is not BaseModule
            and bool(getattr(cls, "MODULE_ID", ""))
        )