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.

9.3 KB
Raw Blame
from __future__ import annotations

import asyncio

import pytest

import ares.sdk as sdk
from ares.core.context import ExecutionContext
from ares.core.engine import AresEngine
from ares.core.execution_admission import _mint_test_dispatch_context
from ares.modules.base import BaseModule, ModuleResult, OpsecLevel, validate_module_class


def test_public_sdk_re_exports_core_contracts() -> None:
    assert sdk.BaseModule is BaseModule
    assert sdk.ExecutionContext is ExecutionContext
    assert sdk.ModuleResult is ModuleResult
    assert sdk.OpsecLevel is OpsecLevel
    assert sdk.validate_module_class is validate_module_class


def test_public_sdk_all_contains_author_symbols() -> None:
    for symbol in (
        "BaseModule",
        "ExecutionContext",
        "ModuleResult",
        "ModuleTestHelper",
        "Finding",
        "Severity",
        "module_metadata",
        "requires_privilege",
        "timeout",
        "ModuleValidationError",
    ):
        assert symbol in sdk.__all__
        assert hasattr(sdk, symbol)


def test_module_metadata_decorator_available_from_public_sdk() -> None:
    @sdk.module_metadata(
        module_id="demo.example",
        name="Demo Example",
        category="network",
        description="SDK import smoke test",
        author="ARES",
        opsec=sdk.OpsecLevel.LOW,
        requires=["target"],
        outputs=["finding"],
        mitre=["T1592.002"],
    )
    class DemoModule(sdk.BaseModule):
        async def run(self, **kwargs):
            return [], {"ok": True}

    assert DemoModule.MODULE_ID == "demo.example"
    assert DemoModule.metadata()["id"] == "demo.example"
    assert sdk.validate_module_class(DemoModule) == []


def test_timeout_decorator_sets_runtime_timeout_contract() -> None:
    @sdk.timeout(42)
    class DemoModule(sdk.BaseModule):
        async def run(self, **kwargs):
            return [], {"ok": True}

    assert DemoModule.MODULE_TIMEOUT_SECONDS == 42
    assert DemoModule.DEFAULT_TIMEOUT_S == 42


@pytest.mark.parametrize("invalid_seconds", [0, -1, True, False, float("nan"), float("inf"), "60"])
def test_timeout_decorator_rejects_invalid_values(invalid_seconds) -> None:
    with pytest.raises(ValueError, match="positive finite number"):
        sdk.timeout(invalid_seconds)


def test_requires_privilege_sets_sdk_metadata() -> None:
    @sdk.requires_privilege(" domain_admin ")
    class DemoModule(sdk.BaseModule):
        async def run(self, **kwargs):
            return [], {"ok": True}

    assert DemoModule.REQUIRED_PRIVILEGE == "domain_admin"
    assert DemoModule.metadata()["required_privilege"] == "domain_admin"


@pytest.mark.parametrize("invalid_level", ["", "   ", None, 123])
def test_requires_privilege_rejects_invalid_values(invalid_level) -> None:
    with pytest.raises(ValueError, match="non-empty string"):
        sdk.requires_privilege(invalid_level)


def test_module_metadata_rejects_invalid_sdk_metadata() -> None:
    with pytest.raises(ValueError, match="category"):
        sdk.module_metadata(
            module_id="demo.invalid",
            name="Demo Invalid",
            category=" ",
            description="Bad category",
        )

    with pytest.raises(ValueError, match="opsec"):
        sdk.module_metadata(
            module_id="demo.invalid",
            name="Demo Invalid",
            category="network",
            description="Bad opsec",
            opsec="not-a-level",
        )

    with pytest.raises(ValueError, match="requires"):
        sdk.module_metadata(
            module_id="demo.invalid",
            name="Demo Invalid",
            category="network",
            description="Bad requires",
            requires=("target",),
        )


@pytest.mark.asyncio
async def test_runtime_uses_module_timeout_contract(monkeypatch) -> None:
    @sdk.module_metadata(
        module_id="demo.timeout",
        name="Demo Timeout",
        category="network",
        description="Runtime timeout contract test",
    )
    @sdk.timeout(7)
    class DemoModule(sdk.BaseModule):
        async def execute(self, ctx: sdk.ExecutionContext) -> sdk.ModuleResult:
            return sdk.ModuleResult(status="success", module_id=self.MODULE_ID)

        async def run(self, **kwargs):
            return [], {"ok": True}

    observed_timeouts: list[int | float] = []
    original_wait_for = asyncio.wait_for

    async def capture_wait_for(awaitable, timeout=None):
        observed_timeouts.append(timeout)
        return await original_wait_for(awaitable, timeout)

    class Registry:
        def __contains__(self, module_id):
            return module_id == "demo.timeout"

        def get(self, module_id):
            assert module_id == "demo.timeout"
            return DemoModule

    monkeypatch.setattr(asyncio, "wait_for", capture_wait_for)
    engine = AresEngine()
    engine._registry = Registry()
    helper = sdk.ModuleTestHelper(DemoModule, scope_cidrs=["127.0.0.1/32"])

    result = await engine.run_module(
        "demo.timeout",
        campaign=helper.campaign,
        params={"target": "127.0.0.1"},
        timeout_seconds=120,
        actor_role="team_lead",
        dispatch_context=_mint_test_dispatch_context(engine, helper.campaign.id, "demo.timeout"),
    )

    assert result.status.value == "done"
    assert result.error is None
    assert 7 in observed_timeouts


@pytest.mark.asyncio
async def test_runtime_retries_use_module_timeout_contract(monkeypatch) -> None:
    @sdk.module_metadata(
        module_id="demo.retry_timeout",
        name="Demo Retry Timeout",
        category="network",
        description="Runtime retry timeout contract test",
    )
    @sdk.timeout(7)
    class DemoModule(sdk.BaseModule):
        execute_calls = 0

        async def execute(self, ctx: sdk.ExecutionContext) -> sdk.ModuleResult:
            type(self).execute_calls += 1
            if type(self).execute_calls == 1:
                raise TimeoutError
            return sdk.ModuleResult(status="success", module_id=self.MODULE_ID)

        async def run(self, **kwargs):
            return [], {"ok": True}

    observed_timeouts: list[int | float | None] = []
    original_wait_for = asyncio.wait_for

    async def capture_wait_for(awaitable, timeout=None):
        observed_timeouts.append(timeout)
        return await original_wait_for(awaitable, timeout)

    async def no_sleep(_delay):
        return None

    class Registry:
        def __contains__(self, module_id):
            return module_id == "demo.retry_timeout"

        def get(self, module_id):
            assert module_id == "demo.retry_timeout"
            return DemoModule

    monkeypatch.setattr(asyncio, "wait_for", capture_wait_for)
    monkeypatch.setattr(asyncio, "sleep", no_sleep)
    engine = AresEngine()
    engine._registry = Registry()
    helper = sdk.ModuleTestHelper(DemoModule, scope_cidrs=["127.0.0.1/32"])

    result = await engine.run_module(
        "demo.retry_timeout",
        campaign=helper.campaign,
        params={"target": "127.0.0.1"},
        timeout_seconds=120,
        actor_role="team_lead",
        dispatch_context=_mint_test_dispatch_context(
            engine, helper.campaign.id, "demo.retry_timeout"
        ),
    )

    assert result.status.value == "timeout"
    assert DemoModule.execute_calls == 1
    assert observed_timeouts == [10, 7]


@pytest.mark.asyncio
async def test_module_test_helper_available_from_public_sdk() -> None:
    @sdk.module_metadata(
        module_id="demo.helper",
        name="Demo Helper",
        category="network",
        description="SDK helper smoke test",
    )
    class DemoModule(sdk.BaseModule):
        execute_calls = 0

        async def execute(self, ctx: sdk.ExecutionContext) -> sdk.ModuleResult:
            type(self).execute_calls += 1
            return sdk.ModuleResult(
                status="dry_run" if ctx.dry_run else "success",
                module_id=self.MODULE_ID,
                raw={"target": ctx.target},
            )

        async def run(self, **kwargs):
            return [], {"ok": True}

    helper = sdk.ModuleTestHelper(DemoModule, scope_cidrs=["127.0.0.1/32"])
    result = await helper.run_full(target="127.0.0.1", dry_run=True)

    assert result.status == "preview_only"
    assert result.module_id == "demo.helper"
    assert result.raw["target"] == "127.0.0.1"
    assert result.raw["would_execute"] is False
    assert DemoModule.execute_calls == 0


@pytest.mark.parametrize("entrypoint", ["run", "run-full"])
@pytest.mark.asyncio
async def test_module_test_helper_is_preview_only(entrypoint: str) -> None:
    class PreviewProbe(sdk.BaseModule):
        MODULE_ID = "test.sdk_preview"
        MODULE_NAME = "SDK preview probe"
        MODULE_CATEGORY = "test"
        MODULE_DESCRIPTION = "Proves the public SDK cannot dispatch"
        execute_calls = 0

        async def execute(self, ctx: sdk.ExecutionContext) -> sdk.ModuleResult:
            type(self).execute_calls += 1
            return sdk.ModuleResult(status="success", module_id=self.MODULE_ID)

        async def run(self, **kwargs):
            type(self).execute_calls += 1
            return [], {}

    helper = sdk.ModuleTestHelper(PreviewProbe)
    if entrypoint == "run":
        result = await helper.run(helper.make_context())
    else:
        result = await helper.run_full()
    assert result.status == "preview_only"
    assert result.raw["would_execute"] is False
    assert PreviewProbe.execute_calls == 0