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.

fix: harden public SDK contract

Mafifrizia9b7eade3f11
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 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.py
index 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),
}
@classmethod
diff --git a/ares/modules/sdk.py b/ares/modules/sdk.py
index 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_id
cls.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 cls
return 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 = seconds
cls.DEFAULT_TIMEOUT_S = seconds
diff --git a/tests/unit/test_sdk_public_api.py b/tests/unit/test_sdk_public_api.py
index 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 pytest
import ares.sdk as sdk
from ares.core.context import ExecutionContext
+from ares.core.engine import AresEngine
from 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.asyncio
async def test_module_test_helper_available_from_public_sdk() -> None:
@sdk.module_metadata(