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
fix: harden public SDK contract
Mafifrizia9b7eade3f11
diff --git a/QUICKSTART.md b/QUICKSTART.mdindex 9937829..fc0ad9d 100644--- a/QUICKSTART.md+++ b/QUICKSTART.md@@ -237,7 +237,7 @@ Common examples:Use the public SDK import path for custom modules:```python-from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult, register_module+from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult````ares.modules.sdk` remains as a compatibility shim, but new code should use `ares.sdk`.diff --git a/ares/modules/base.py b/ares/modules/base.pyindex dc34119..9d3620d 100644--- a/ares/modules/base.py+++ b/ares/modules/base.py@@ -375,6 +375,7 @@ class BaseModule(abc.ABC):"mitre_list": cls.MITRE_TECHNIQUES,"author": cls.MODULE_AUTHOR,"min_noise_profile": cls.MIN_NOISE_PROFILE,+ "required_privilege": getattr(cls, "REQUIRED_PRIVILEGE", None),}@classmethoddiff --git a/ares/modules/sdk.py b/ares/modules/sdk.pyindex 10e9eca..ab56002 100644--- a/ares/modules/sdk.py+++ b/ares/modules/sdk.py@@ -114,6 +114,7 @@ from ares.normalize.artifacts import (# ── Convenience types for type hints ──────────────────────────────────────────from typing import Any+import math# ── Decorators / helpers ──────────────────────────────────────────────────────@@ -147,6 +148,20 @@ def module_metadata(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_idcls.MODULE_NAME = name@@ -177,13 +192,16 @@ def requires_privilege(level: str) -> Any: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+ cls.REQUIRED_PRIVILEGE = level.strip()return clsreturn decorator-def timeout(seconds: int) -> Any:+def timeout(seconds: int | float) -> Any:"""Class decorator: override default execution timeout.@@ -192,6 +210,14 @@ def timeout(seconds: int) -> Any: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 = secondscls.DEFAULT_TIMEOUT_S = secondsdiff --git a/tests/unit/test_sdk_public_api.py b/tests/unit/test_sdk_public_api.pyindex 087aab2..3ab82ee 100644--- a/tests/unit/test_sdk_public_api.py+++ b/tests/unit/test_sdk_public_api.py@@ -1,9 +1,12 @@from __future__ import annotations+import asyncio+import pytestimport ares.sdk as sdkfrom ares.core.context import ExecutionContext+from ares.core.engine import AresEnginefrom ares.modules.base import BaseModule, ModuleResult, OpsecLevel, validate_module_class@@ -63,6 +66,105 @@ def test_timeout_decorator_sets_runtime_timeout_contract() -> None:assert DemoModule.DEFAULT_TIMEOUT_S == 42[email protected]("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"++[email protected]("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",),+ )+++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",+ )++ assert result.status.value == "done"+ assert result.error is None+ assert 7 in observed_timeouts++@pytest.mark.asyncioasync def test_module_test_helper_available_from_public_sdk() -> None:@sdk.module_metadata(