ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
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