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.

4.8 KB
Raw Blame
"""Declarative Module Contract System for ARES SDK.

Allows authors to declare permissions, circuit breakers, idempotency, and security
invariants in a clean, unified Python decorator (@module_contract).
"""
from __future__ import annotations

import functools
from collections.abc import Callable
from typing import Any, TypeVar

from ares.core.context import ExecutionContext
from ares.modules.base import ModuleResult
from ares.sdk.pipeline.base import ExecutionPipeline
from ares.sdk.pipeline.interceptors import (
    AdaptiveNoiseInterceptor,
    AuditProvenanceInterceptor,
    ScopeEnforcementInterceptor,
    SecretSanitizationInterceptor,
)
from ares.sdk.resilience.circuit_breaker import CircuitBreaker
from ares.sdk.security.permissions import CapabilitySandbox, SecurityPermission

M = TypeVar("M")


def module_contract(
    *,
    permissions: list[SecurityPermission] | None = None,
    circuit_breaker: CircuitBreaker | None = None,
    params_model: Any = None,
    idempotency: str = "idempotent",
    compensation: str = "not_applicable",
    interceptors: list[Any] | None = None,
) -> Callable[[type[M]], type[M]]:
    """Class decorator for declaring enterprise security and governance contracts."""

    def decorator(cls: type[M]) -> type[M]:
        declared_perms = list(permissions or [])
        cls.PERMISSIONS = declared_perms  # type: ignore[attr-defined]
        cls.CIRCUIT_BREAKER = circuit_breaker  # type: ignore[attr-defined]
        cls.IDEMPOTENCY = idempotency  # type: ignore[attr-defined]
        cls.COMPENSATION = compensation  # type: ignore[attr-defined]

        if params_model is not None:
            cls.PARAMS_MODEL = params_model  # type: ignore[attr-defined]

        # Assemble the default execution pipeline
        pipeline = ExecutionPipeline()
        pipeline.add_interceptor(ScopeEnforcementInterceptor())
        pipeline.add_interceptor(AdaptiveNoiseInterceptor())
        if interceptors:
            for ic in interceptors:
                pipeline.add_interceptor(ic)
        # SecretSanitizationInterceptor is disabled by default in operational pipelines
        # so Red Team operators receive real findings and verification evidence without censorship.
        pipeline.add_interceptor(SecretSanitizationInterceptor(enabled=False))
        pipeline.add_interceptor(AuditProvenanceInterceptor())
        cls.EXECUTION_PIPELINE = pipeline  # type: ignore[attr-defined]

        # Wrap execute() to automatically enforce permissions, circuit breaker, and pipeline
        original_execute = getattr(cls, "execute", None)
        if original_execute is not None:
            @functools.wraps(original_execute)
            async def wrapped_execute(self: Any, ctx: ExecutionContext) -> ModuleResult:
                # 1. Enforce Circuit Breaker (if configured)
                cb: CircuitBreaker | None = getattr(self, "CIRCUIT_BREAKER", None)
                if cb is not None:
                    cb.allow_execution()

                # 2. Enforce Capability Sandbox against parameters
                perms: list[SecurityPermission] = getattr(self, "PERMISSIONS", [])
                if perms:
                    raw_params = ctx.params.model_dump() if hasattr(ctx.params, "model_dump") else (ctx.params or {})
                    CapabilitySandbox.verify(perms, raw_params, ctx)

                # 3. Execute through the Interceptor Pipeline
                pipe: ExecutionPipeline = getattr(self, "EXECUTION_PIPELINE", pipeline)

                async def _inner_exec(c: ExecutionContext) -> ModuleResult:
                    try:
                        res = await original_execute(self, c)
                        if cb is not None:
                            from ares.sdk.resilience.circuit_breaker import (
                                CircuitBreakerState,
                                LockoutCircuitBreaker,
                            )
                            if isinstance(cb, LockoutCircuitBreaker):
                                raw_res = getattr(res, "raw", {}) or {}
                                for acc in raw_res.get("locked_accounts", []):
                                    cb._trip_for_account(acc, "Module result reported account lockout")
                                if raw_res.get("lockout_detected") and cb.state != CircuitBreakerState.OPEN:
                                    cb._trip_for_account("unknown", "Module result reported lockout detected")
                            if cb.state != CircuitBreakerState.OPEN:
                                cb.record_success()
                        return res
                    except Exception as exc:
                        if cb is not None:
                            cb.record_failure(exc)
                        raise

                return await pipe.run(self, ctx, _inner_exec)

            cls.execute = wrapped_execute

        return cls

    return decorator