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.

13.5 KB
Raw Blame
"""
ARES Module SDK
One-stop import for community module authors.
Provides all base classes, helpers, and type definitions needed
to write a compliant ARES module.

Quick start:
    from ares.sdk import (
        BaseModule, ExecutionContext, ModuleResult,
        Finding, Severity, OpsecLevel,
        module_metadata, requires_privilege, timeout,
    )

    class MyModule(BaseModule):
        MODULE_ID          = "corp.my_attack"
        MODULE_NAME        = "My Attack Module"
        MODULE_CATEGORY    = "ad"
        MODULE_DESCRIPTION = "Does something interesting"
        MODULE_AUTHOR      = "[email protected]"
        OPSEC_LEVEL        = OpsecLevel.LOW
        REQUIRES           = ["domain_creds"]
        OUTPUTS            = ["credential"]
        MITRE_TECHNIQUES   = ["T1558.003"]

        async def validate(self, ctx: ExecutionContext) -> None:
            ctx.require("target", "domain")
            if not ctx.params.get("dc"):
                raise ModuleValidationError(
                    "Missing required param: dc",
                    module_id=self.MODULE_ID, field="dc"
                )

        async def execute(self, ctx: ExecutionContext) -> ModuleResult:
            if ctx.dry_run:
                return ModuleResult(status="dry_run", module_id=self.MODULE_ID)

            await self.before_request(ctx.target)
            # ... do attack work ...
            f = self.finding(
                title       = "Something found",
                description = "Details",
                severity    = Severity.HIGH,
                mitre_technique = "T1558.003",
                host        = ctx.target,
            )
            return ModuleResult(
                status   = "success",
                findings = [f],
                module_id = self.MODULE_ID,
            )

        async def run(self, **kwargs):
            # Legacy interface - prefer execute(ctx) instead
            ctx = ExecutionContext.for_test(**kwargs)
            result = await self.execute(ctx)
            return result.findings, result.raw
"""

from __future__ import annotations

import math

# ── Convenience types for type hints ──────────────────────────────────────────
from typing import Any

# ── Campaign types ─────────────────────────────────────────────────────────────
from ares.core.campaign import Finding, Severity

# ── Context ────────────────────────────────────────────────────────────────────
from ares.core.context import ExecutionContext

# ── Errors ────────────────────────────────────────────────────────────────────
from ares.core.errors import (
    AccountLocked,
    AresError,
    AuthenticationFailed,
    ConnectionRefused,
    ConnectionTimeout,
    CredentialError,
    CredentialExpired,
    DetectionSignal,
    ExecutionError,
    HoneypotDetected,
    HostUnreachable,
    InsufficientPrivilege,
    InvalidContext,
    ModuleError,
    ModuleExecutionError,
    ModuleTimeoutError,
    ModuleValidationError,
    NetworkError,
    NoCredentialsAvailable,
    OpsecError,
    SandboxError,
    ScopeError,
)

# ── Logging ───────────────────────────────────────────────────────────────────
from ares.core.logger import get_logger

# ── Core base ──────────────────────────────────────────────────────────────────
from ares.modules.base import (
    BaseModule,
    ModuleResult,
    OpsecLevel,
    validate_module_class,
)

# ── Normalize ─────────────────────────────────────────────────────────────────
from ares.normalize.artifacts import (
    ArtifactStore,
    CredentialArtifact,
    HashArtifact,
    HostArtifact,
    PermissionArtifact,
    UserArtifact,
)

# ── MITRE ─────────────────────────────────────────────────────────────────────
from ares.technique.library import TechniqueLibrary, TechniqueMapper

# ── Decorators / helpers ──────────────────────────────────────────────────────


def module_metadata(
    module_id: str,
    name: str,
    category: str,
    description: str,
    author: str = "Community",
    opsec: OpsecLevel = OpsecLevel.LOW,
    requires: list[str] | None = None,
    outputs: list[str] | None = None,
    mitre: list[str] | None = None,
) -> Any:
    """
    Class decorator to set all module metadata cleanly.

    Usage:
        @module_metadata(
            module_id   = "corp.my_module",
            name        = "My Module",
            category    = "ad",
            description = "Does X",
            author      = "[email protected]",
            opsec       = OpsecLevel.LOW,
            requires    = ["domain_creds"],
            outputs     = ["user_list"],
            mitre       = ["T1087.002"],
        )
        class MyModule(BaseModule):
            ...
    """
    if not isinstance(category, str) or not category.strip():
        raise ValueError("module_metadata category must be a non-empty string")
    if not isinstance(opsec, OpsecLevel) and str(opsec) not in {
        level.value for level in OpsecLevel
    }:
        raise ValueError("module_metadata opsec must be an OpsecLevel or valid opsec level string")
    for field_name, value in (
        ("requires", requires),
        ("outputs", outputs),
        ("mitre", mitre),
    ):
        if value is None:
            continue
        if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
            raise ValueError(f"module_metadata {field_name} must be a list of strings")

    def decorator(cls: type) -> type:
        cls.MODULE_ID = module_id
        cls.MODULE_NAME = name
        cls.MODULE_CATEGORY = category
        cls.MODULE_DESCRIPTION = description
        cls.MODULE_AUTHOR = author
        cls.OPSEC_LEVEL = opsec
        cls.REQUIRES = requires or []
        cls.OUTPUTS = outputs or []
        cls.MITRE_TECHNIQUES = mitre or []

        errors = validate_module_class(cls)
        if errors:
            raise ValueError(f"Module class {cls.__name__!r} has validation errors: {errors}")
        return cls

    return decorator


def requires_privilege(level: str) -> Any:
    """
    Class decorator: declare minimum privilege required by this module.
    Engine will suggest privilege escalation if current level is insufficient.

    Usage:
        @requires_privilege("domain_admin")
        class DCSyncModule(BaseModule):
            ...
    """
    if not isinstance(level, str) or not level.strip():
        raise ValueError("requires_privilege level must be a non-empty string")

    def decorator(cls: type) -> type:
        cls.REQUIRED_PRIVILEGE = level.strip()
        return cls

    return decorator


def timeout(seconds: int | float) -> Any:
    """
    Class decorator: override default execution timeout.

    Usage:
        @timeout(60)
        class FastModule(BaseModule):
            ...
    """
    if (
        isinstance(seconds, bool)
        or not isinstance(seconds, (int, float))
        or not math.isfinite(seconds)
        or seconds <= 0
    ):
        raise ValueError("timeout seconds must be a positive finite number")

    def decorator(cls: type) -> type:
        cls.MODULE_TIMEOUT_SECONDS = seconds
        cls.DEFAULT_TIMEOUT_S = seconds
        return cls

    return decorator


# ── TestHelper - makes unit testing modules trivial ───────────────────────────


class ModuleTestHelper:
    """
    Static preview helper for module metadata and request-shape tests.

    C-LIVE-v1 intentionally does not execute module code through the public
    SDK.  Effectful tests use the sealed coordinator's private test seam.

    Usage:
        helper  = ModuleTestHelper(KerberoastModule)
        ctx     = helper.make_context(target="dc01", domain="CORP")
        result  = await helper.run(ctx)
        assert result.success
    """

    def __init__(self, module_class: type, scope_cidrs: list[str] | None = None) -> None:
        from ares.core.campaign import Campaign, NoiseProfile, ScopeEntry
        from ares.core.config import AresSettings
        from ares.core.noise import NoiseController

        self.module_class = module_class
        self.settings = AresSettings()
        # NOTE: scope defaults to 0.0.0.0/0 for test harness.
        # Override via ModuleTestHelper(scope_cidrs=[...]) in integration tests.
        _scope = [ScopeEntry(cidr=s) for s in (scope_cidrs or ["0.0.0.0/0"])]
        self.campaign = Campaign(
            name="test-campaign",
            client="test",
            scope=_scope,
            noise_profile=NoiseProfile.NORMAL,
            operator="test",
        )
        self.noise = NoiseController(self.campaign)
        self.module = module_class(
            settings=self.settings,
            campaign=self.campaign,
            noise=self.noise,
        )

    def make_context(
        self,
        target: str = "10.0.0.1",
        domain: str = "",
        params: dict[str, Any] | None = None,
        dry_run: bool = True,
        **kwargs: Any,
    ) -> ExecutionContext:
        """Build a test context for this module."""
        context_params = {**(params or {}), **kwargs}
        if dry_run:
            for requirement in getattr(self.module_class, "REQUIRES", []):
                if requirement in {"credentials", "domain_creds", "domain_admin_creds"}:
                    context_params.setdefault(requirement, True)

        return ExecutionContext.build(
            campaign=self.campaign,
            target=target,
            module_id=self.module_class.MODULE_ID,
            domain=domain,
            params=context_params,
            dry_run=dry_run,
        )

    async def validate(self, ctx: ExecutionContext) -> None:
        """Validate the preview envelope without invoking module code."""
        if not isinstance(ctx, ExecutionContext):
            raise TypeError("SDK preview requires an ExecutionContext")

    async def run(self, ctx: ExecutionContext) -> ModuleResult:
        """Return a static preview; never call validate(), execute(), or run()."""
        if not isinstance(ctx, ExecutionContext):
            raise TypeError("SDK preview requires an ExecutionContext")
        return ModuleResult(
            status="preview_only",
            module_id=self.module_class.MODULE_ID,
            raw={
                "preview": True,
                "would_execute": False,
                "target": ctx.target,
                "module_id": self.module_class.MODULE_ID,
            },
        )

    async def run_full(
        self,
        target: str = "10.0.0.1",
        domain: str = "",
        params: dict[str, Any] | None = None,
        dry_run: bool = True,
    ) -> ModuleResult:
        """One-liner static preview; ``dry_run=False`` is rejected."""
        if dry_run is not True:
            raise PermissionError("public SDK helpers are preview-only")
        ctx = self.make_context(target=target, domain=domain, params=params, dry_run=dry_run)
        return await self.run(ctx)

    def report(self, result: ModuleResult) -> dict[str, Any]:
        """Generate report dict for this result."""
        return self.module.report(result)

    def metadata(self) -> dict[str, Any]:
        """Return module metadata."""
        return self.module_class.metadata()

    def validate_class(self) -> list[str]:
        """Validate module class has all required attributes. Returns errors."""
        return validate_module_class(self.module_class)


# ── Public API surface ────────────────────────────────────────────────────────
__all__ = [
    # Base
    "BaseModule",
    "ModuleResult",
    "OpsecLevel",
    "validate_module_class",
    # Context
    "ExecutionContext",
    # Errors
    "AresError",
    "ModuleError",
    "ModuleExecutionError",
    "ModuleValidationError",
    "ModuleTimeoutError",
    "NetworkError",
    "ConnectionRefused",
    "ConnectionTimeout",
    "HostUnreachable",
    "CredentialError",
    "AuthenticationFailed",
    "AccountLocked",
    "CredentialExpired",
    "NoCredentialsAvailable",
    "ExecutionError",
    "SandboxError",
    "ScopeError",
    "OpsecError",
    "DetectionSignal",
    "HoneypotDetected",
    "InsufficientPrivilege",
    "InvalidContext",
    # Campaign types
    "Finding",
    "Severity",
    # Logging
    "get_logger",
    # MITRE
    "TechniqueLibrary",
    "TechniqueMapper",
    # Normalize
    "ArtifactStore",
    "HostArtifact",
    "UserArtifact",
    "CredentialArtifact",
    "HashArtifact",
    "PermissionArtifact",
    # Decorators
    "module_metadata",
    "requires_privilege",
    "timeout",
    # Testing
    "ModuleTestHelper",
]