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(api): enforce high-noise plan authorization
Mafifrizi52bad6b0d1e3
diff --git a/ares/api/server.py b/ares/api/server.pyindex 0d1882f..7d1be84 100644--- a/ares/api/server.py+++ b/ares/api/server.py@@ -18,7 +18,7 @@ from __future__ import annotationsimport asyncioimport osimport time-from collections.abc import AsyncGenerator+from collections.abc import AsyncGenerator, Iterable, Mappingfrom contextlib import asynccontextmanagerfrom pathlib import Pathfrom typing import Any@@ -1324,6 +1324,85 @@ class PlanRunRequest(BaseModel):dry_run: bool = False+_INVALID_PLAN_MODULE_IDS_DETAIL = (+ "Invalid plan: every stage must contain a modules list of non-empty "+ "string module IDs."+)+++def _collect_plan_module_ids_for_authorization(+ plan_data: Mapping[str, Any],+) -> list[str]:+ """Validate raw plan module structure and return sorted unique IDs."""+ stages = plan_data.get("stages", [])+ if not isinstance(stages, list):+ raise HTTPException(+ status_code=422,+ detail=_INVALID_PLAN_MODULE_IDS_DETAIL,+ )++ module_ids: list[str] = []+ for stage in stages:+ if not isinstance(stage, Mapping) or "modules" not in stage:+ raise HTTPException(+ status_code=422,+ detail=_INVALID_PLAN_MODULE_IDS_DETAIL,+ )+ stage_module_ids = stage["modules"]+ if not isinstance(stage_module_ids, list):+ raise HTTPException(+ status_code=422,+ detail=_INVALID_PLAN_MODULE_IDS_DETAIL,+ )+ for module_id in stage_module_ids:+ if not isinstance(module_id, str) or not module_id.strip():+ raise HTTPException(+ status_code=422,+ detail=_INVALID_PLAN_MODULE_IDS_DETAIL,+ )+ module_ids.append(module_id)++ return sorted(set(module_ids))+++def _require_high_noise_module_access(+ module_ids: Iterable[Any],+ actor: AuthenticatedUser,+ engine: AresEngine,+) -> None:+ """Require team_lead for every registered HIGH_NOISE module."""+ from ares.modules.base import OpsecLevel++ validated_module_ids: set[str] = set()+ for module_id in module_ids:+ if not isinstance(module_id, str) or not module_id.strip():+ raise HTTPException(+ status_code=422,+ detail=_INVALID_PLAN_MODULE_IDS_DETAIL,+ )+ validated_module_ids.add(module_id)++ rejected = [+ module_id+ for module_id in sorted(validated_module_ids)+ if (+ (module_cls := engine.registry.get(module_id)) is not None+ and getattr(module_cls, "OPSEC_LEVEL", None) == OpsecLevel.HIGH_NOISE+ )+ ]+ if actor.role == "team_lead" or not rejected:+ return++ if len(rejected) == 1:+ detail = f"{rejected[0]!r} is HIGH_NOISE — team_lead only."+ else:+ detail = (+ f"{', '.join(repr(module_id) for module_id in rejected)} "+ "are HIGH_NOISE — team_lead only."+ )+ raise HTTPException(status_code=403, detail=detail)++@app.post("/modules/{module_id}/run", tags=["modules"])async def run_module(module_id: str,@@ -1335,16 +1414,11 @@ async def run_module(db: AresDatabase = Depends(get_db),) -> dict[str, Any]:"""Run module. HIGH_NOISE requires team_lead. Rate limited: 20/min."""- from ares.modules.base import OpsecLevel-if isinstance(engine, AresEngine):engine.bind_database(db)- # Use the engine's already-loaded registry — avoids rescanning disk on every request- cls = engine.registry.get(module_id)- if cls and getattr(cls, "OPSEC_LEVEL", None) == OpsecLevel.HIGH_NOISE:- if actor.role != "team_lead":- raise HTTPException(403, f"{module_id!r} is HIGH_NOISE — team_lead only.")+ # Use the engine's already-loaded registry — avoids rescanning disk on every request.+ _require_high_noise_module_access([module_id], actor, engine)# Validate params against Pydantic schemafrom pydantic import ValidationError as PydanticValidationError@@ -2351,11 +2425,14 @@ async def run_campaign_plan(from ares.core.engine import ExecutionPlan+ plan_module_ids = _collect_plan_module_ids_for_authorization(body.plan)try:plan = ExecutionPlan.from_dict(body.plan)except Exception as exc:raise HTTPException(422, f"Invalid plan: {exc}")+ _require_high_noise_module_access(plan_module_ids, actor, engine)+if body.dry_run:return engine.dry_run_plan(plan, body.global_params)diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 12e76e6..cc765dc 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -265,6 +265,11 @@ Useful for verifying remediation between assessments.Run an execution plan against the campaign.+Plans execute live by default; set `dry_run` to `true` for a preview. If any+module anywhere in the plan is classified `HIGH_NOISE`, the caller must have+the `team_lead` role. The complete plan is authorized before execution or+dry-run processing begins.+```json{"plan": [{"module_id": "ad.kerberoast", "params": {"dc": "dc01.corp.local"}}],diff --git a/tests/unit/test_api_endpoints.py b/tests/unit/test_api_endpoints.pyindex 4df693b..e4c9f3d 100644--- a/tests/unit/test_api_endpoints.py+++ b/tests/unit/test_api_endpoints.py@@ -24,6 +24,7 @@ from unittest.mock import AsyncMock, MagicMockimport httpximport pytest+from fastapi import HTTPExceptionfrom fastapi.security import OAuth2PasswordRequestForm# ── env bootstrap (before any ares import) ────────────────────────────────────@@ -1045,6 +1046,909 @@ class TestModuleSchemaEndpoint:# ── Reports safety ───────────────────────────────────────────────────────────+class TestHighNoiseAuthorizationPolicy:+ _INVALID_PLAN_DETAIL = (+ "Invalid plan: every stage must contain a modules list of non-empty "+ "string module IDs."+ )++ def setup_method(self) -> None:+ _reset_rate_limiter()++ @staticmethod+ def _module_classes() -> tuple[type, type]:+ from ares.modules.base import OpsecLevel++ class SafeModule:+ OPSEC_LEVEL = OpsecLevel.LOW++ class HighNoiseModule:+ OPSEC_LEVEL = OpsecLevel.HIGH_NOISE++ return SafeModule, HighNoiseModule++ @staticmethod+ def _actor(role: str, username: str = "operator-user") -> Any:+ from ares.api.rbac import AuthenticatedUser++ return AuthenticatedUser(username=username, role=role)++ @classmethod+ def _engine(cls, registry_items: dict[str, type | None]) -> Any:+ registry = MagicMock()+ registry.get.side_effect = registry_items.get++ def result_for(module_id: str) -> Any:+ result = SimpleNamespace(+ status="done",+ findings=[],+ error="",+ duration_ms=1.0,+ )+ result.model_dump = lambda: {+ "module_id": module_id,+ "status": "done",+ "findings": [],+ "validation_results": [],+ "raw_output": {},+ "error": "",+ "duration_ms": 1.0,+ }+ return result++ async def run_module(+ module_id: str,+ campaign: Any,+ params: dict[str, Any],+ actor_role: str = "",+ ) -> Any:+ return result_for(module_id)++ async def run_plan(+ plan: Any,+ campaign: Any,+ global_params: dict[str, Any],+ actor_role: str = "",+ ) -> dict[str, Any]:+ return {+ module_id: result_for(module_id)+ for module_id in plan.all_module_ids()+ }++ engine = SimpleNamespace(registry=registry)+ engine.run_module = AsyncMock(side_effect=run_module)+ engine.run_plan = AsyncMock(side_effect=run_plan)+ engine.dry_run_plan = MagicMock(+ return_value={+ "status": "dry_run_ok",+ "modules": [],+ "would_execute": True,+ }+ )+ return engine++ @staticmethod+ def _campaign(operator: str = "operator-user") -> dict[str, Any]:+ return {+ "id": "camp-plan-policy",+ "name": "Plan Policy",+ "client": "Internal",+ "operator": operator,+ "noise_profile": "normal",+ "status": "created",+ "scope_json": "[]",+ "targets_json": "[]",+ "notes": "",+ }++ @staticmethod+ def _plan_body(+ stages: list[tuple[str, list[str]]],+ *,+ dry_run: bool = False,+ global_params: dict[str, Any] | None = None,+ ) -> dict[str, Any]:+ return {+ "plan": {+ "stages": [+ {"name": name, "modules": modules, "params": {}}+ for name, modules in stages+ ]+ },+ "global_params": global_params or {},+ "dry_run": dry_run,+ }++ def test_shared_policy_allows_operator_for_normal_module(self) -> None:+ from ares.api.server import _require_high_noise_module_access++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})++ _require_high_noise_module_access(+ ["plugin.safe"], self._actor("operator"), engine+ )++ engine.registry.get.assert_called_once_with("plugin.safe")++ def test_shared_policy_blocks_dynamic_high_noise_module(self) -> None:+ from ares.api.server import _require_high_noise_module_access++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})++ with pytest.raises(HTTPException) as exc_info:+ _require_high_noise_module_access(+ ["plugin.dynamic-high"], self._actor("operator"), engine+ )++ assert exc_info.value.status_code == 403+ assert exc_info.value.detail == (+ "'plugin.dynamic-high' is HIGH_NOISE — team_lead only."+ )++ def test_shared_policy_allows_team_lead_for_high_noise_module(self) -> None:+ from ares.api.server import _require_high_noise_module_access++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})++ _require_high_noise_module_access(+ ["plugin.dynamic-high"], self._actor("team_lead"), engine+ )++ def test_shared_policy_delegates_unknown_module(self) -> None:+ from ares.api.server import _require_high_noise_module_access++ engine = self._engine({})++ _require_high_noise_module_access(+ ["plugin.unknown"], self._actor("operator"), engine+ )++ engine.registry.get.assert_called_once_with("plugin.unknown")++ def test_shared_policy_deduplicates_sorts_and_excludes_sensitive_values(+ self,+ ) -> None:+ from ares.api.server import _require_high_noise_module_access++ _, high_noise_module = self._module_classes()+ engine = self._engine(+ {+ "plugin.zeta-high": high_noise_module,+ "plugin.alpha-high": high_noise_module,+ }+ )++ with pytest.raises(HTTPException) as exc_info:+ _require_high_noise_module_access(+ [+ "plugin.zeta-high",+ "plugin.alpha-high",+ "plugin.zeta-high",+ ],+ self._actor("operator"),+ engine,+ )++ detail = str(exc_info.value.detail)+ assert detail == (+ "'plugin.alpha-high', 'plugin.zeta-high' "+ "are HIGH_NOISE — team_lead only."+ )+ assert [call.args[0] for call in engine.registry.get.call_args_list] == [+ "plugin.alpha-high",+ "plugin.zeta-high",+ ]+ for sensitive_marker in (+ "plan-param-marker",+ "target-marker",+ "credential-marker",+ "evidence-marker",+ ):+ assert sensitive_marker not in detail++ @pytest.mark.parametrize(+ "module_ids",+ [+ pytest.param(["plugin.safe", 7], id="mixed-string-integer"),+ pytest.param([None], id="null"),+ pytest.param([["plugin.safe"]], id="list"),+ pytest.param([{"module_id": "plugin.safe"}], id="dict"),+ pytest.param([("plugin.safe",)], id="tuple"),+ pytest.param([b"plugin.safe"], id="bytes"),+ pytest.param([""], id="empty-string"),+ pytest.param([" "], id="whitespace-only"),+ pytest.param([True], id="bool"),+ ],+ )+ def test_shared_policy_rejects_invalid_ids_before_registry_lookup(+ self, module_ids: list[Any]+ ) -> None:+ from ares.api.server import _require_high_noise_module_access++ engine = self._engine({})++ with pytest.raises(HTTPException) as exc_info:+ _require_high_noise_module_access(+ module_ids,+ self._actor("operator"),+ engine,+ )++ assert exc_info.value.status_code == 422+ assert exc_info.value.detail == self._INVALID_PLAN_DETAIL+ engine.registry.get.assert_not_called()++ @pytest.mark.parametrize(+ "plan_data",+ [+ pytest.param({"stages": [None]}, id="non-mapping-stage"),+ pytest.param({"stages": [{}]}, id="missing-modules"),+ pytest.param(+ {"stages": [{"modules": None}]},+ id="invalid-modules-collection",+ ),+ pytest.param(+ {"stages": [{"modules": [[]]}]},+ id="unhashable-module-id",+ ),+ ],+ )+ def test_plan_module_id_collector_rejects_structure_with_canonical_422(+ self, plan_data: dict[str, Any]+ ) -> None:+ from ares.api.server import _collect_plan_module_ids_for_authorization++ with pytest.raises(HTTPException) as exc_info:+ _collect_plan_module_ids_for_authorization(plan_data)++ assert exc_info.value.status_code == 422+ assert exc_info.value.detail == self._INVALID_PLAN_DETAIL++ def test_plan_module_id_collector_preserves_absent_stages_and_valid_ids(+ self,+ ) -> None:+ from ares.api.server import _collect_plan_module_ids_for_authorization++ assert _collect_plan_module_ids_for_authorization({}) == []+ module_ids = _collect_plan_module_ids_for_authorization(+ {+ "stages": [+ {+ "modules": [+ " plugin.safe ",+ "plugin.safe",+ " plugin.safe ",+ ]+ }+ ]+ }+ )++ assert module_ids == [" plugin.safe ", "plugin.safe"]++ @pytest.mark.asyncio+ async def test_single_module_operator_high_noise_denied_before_engine(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.reset_mock()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/modules/plugin.dynamic-high/run",+ json={+ "campaign_id": "camp-plan-policy",+ "params": {"target": "target-marker"},+ "dry_run": False,+ },+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 403+ assert response.json()["detail"] == (+ "'plugin.dynamic-high' is HIGH_NOISE — team_lead only."+ )+ engine.run_module.assert_not_awaited()+ db.get_campaign.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_single_module_team_lead_high_noise_reaches_engine(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign("another-operator")+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/modules/plugin.dynamic-high/run",+ json={+ "campaign_id": "camp-plan-policy",+ "params": {},+ "dry_run": False,+ },+ headers=_auth("lead-user", "team_lead"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ engine.run_module.assert_awaited_once()++ @pytest.mark.asyncio+ async def test_single_module_normal_and_unknown_modules_reach_existing_path(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ safe_response = await c.post(+ "/modules/plugin.safe/run",+ json={+ "campaign_id": "camp-plan-policy",+ "params": {},+ "dry_run": False,+ },+ headers=_auth("operator-user", "operator"),+ )+ unknown_response = await c.post(+ "/modules/plugin.unknown/run",+ json={+ "campaign_id": "camp-plan-policy",+ "params": {},+ "dry_run": False,+ },+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert safe_response.status_code == 200+ assert unknown_response.status_code == 200+ assert [call.args[0] for call in engine.run_module.await_args_list] == [+ "plugin.safe",+ "plugin.unknown",+ ]++ @pytest.mark.asyncio+ async def test_operator_safe_live_plan_reaches_engine_with_stable_response(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body([("safe", ["plugin.safe"])]),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ assert response.json() == {+ "campaign_id": "camp-plan-policy",+ "modules_run": 1,+ "results": {+ "plugin.safe": {+ "status": "done",+ "findings_count": 0,+ "error": "",+ "duration_ms": 1.0,+ }+ },+ }+ engine.run_plan.assert_awaited_once()+ assert engine.run_plan.await_args.kwargs["actor_role"] == "operator"++ @pytest.mark.parametrize(+ "stages",+ [+ [+ ("forbidden", ["plugin.dynamic-high"]),+ ("safe", ["plugin.safe"]),+ ],+ [+ ("safe", ["plugin.safe"]),+ ("forbidden", ["plugin.dynamic-high"]),+ ],+ ],+ ids=("high-noise-first", "high-noise-later"),+ )+ @pytest.mark.asyncio+ async def test_operator_high_noise_live_plan_denied_before_any_execution(+ self,+ aclient: Any,+ stages: list[tuple[str, list[str]]],+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, high_noise_module = self._module_classes()+ engine = self._engine(+ {+ "plugin.safe": safe_module,+ "plugin.dynamic-high": high_noise_module,+ }+ )+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(stages),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 403+ engine.run_plan.assert_not_awaited()+ engine.dry_run_plan.assert_not_called()++ @pytest.mark.asyncio+ async def test_team_lead_high_noise_live_plan_reaches_engine(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign("another-operator")+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("forbidden", ["plugin.dynamic-high"])]+ ),+ headers=_auth("lead-user", "team_lead"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ engine.run_plan.assert_awaited_once()++ @pytest.mark.asyncio+ async def test_duplicate_high_noise_plan_detail_is_safe_and_deterministic(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine(+ {+ "plugin.zeta-high": high_noise_module,+ "plugin.alpha-high": high_noise_module,+ }+ )+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ body = self._plan_body(+ [+ (+ "mixed",+ [+ "plugin.zeta-high",+ "plugin.alpha-high",+ "plugin.zeta-high",+ ],+ )+ ],+ global_params={+ "target": "target-marker",+ "credential": "credential-marker",+ "evidence": "evidence-marker",+ },+ )+ body["plan"]["stages"][0]["params"] = {+ "plugin.zeta-high": {"command": "plan-param-marker"}+ }+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=body,+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 403+ assert response.json()["detail"] == (+ "'plugin.alpha-high', 'plugin.zeta-high' "+ "are HIGH_NOISE — team_lead only."+ )+ for sensitive_marker in (+ "plan-param-marker",+ "target-marker",+ "credential-marker",+ "evidence-marker",+ ):+ assert sensitive_marker not in response.text+ engine.run_plan.assert_not_awaited()++ @pytest.mark.parametrize(+ "modules",+ [+ pytest.param(["plugin.safe", 7], id="mixed-string-integer"),+ pytest.param([None], id="null-entry"),+ pytest.param([["plugin.safe"]], id="list-entry"),+ pytest.param([{"module_id": "plugin.safe"}], id="dict-entry"),+ pytest.param(None, id="null-collection"),+ pytest.param(7, id="integer-collection"),+ pytest.param("plugin.safe", id="string-collection"),+ pytest.param(+ {"module_id": "plugin.safe"},+ id="dict-collection",+ ),+ pytest.param([""], id="empty-string"),+ pytest.param([" "], id="whitespace-only"),+ pytest.param([True], id="bool-entry"),+ ],+ )+ @pytest.mark.parametrize(+ "dry_run",+ [False, True],+ ids=("live", "dry-run"),+ )+ @pytest.mark.asyncio+ async def test_malformed_plan_module_ids_return_stable_422_before_policy_lookup(+ self,+ aclient: Any,+ modules: Any,+ dry_run: bool,+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json={+ "plan": {+ "stages": [+ {+ "name": "malformed",+ "modules": modules,+ "params": {},+ }+ ]+ },+ "dry_run": dry_run,+ },+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 422+ assert response.json() == {+ "code": 422,+ "detail": self._INVALID_PLAN_DETAIL,+ "type": "api_error",+ }+ engine.registry.get.assert_not_called()+ engine.run_plan.assert_not_awaited()+ engine.dry_run_plan.assert_not_called()++ @pytest.mark.parametrize(+ "plan_data",+ [+ pytest.param({"stages": [None]}, id="null-stage"),+ pytest.param({"stages": [123]}, id="integer-stage"),+ pytest.param({"stages": ["invalid"]}, id="string-stage"),+ pytest.param({"stages": [[]]}, id="list-stage"),+ pytest.param({"stages": [{}]}, id="missing-modules"),+ pytest.param(+ {+ "stages": [+ {+ "name": "safe",+ "modules": ["plugin.safe"],+ "params": {},+ },+ None,+ ]+ },+ id="malformed-later-stage",+ ),+ pytest.param(+ {"stages": "invalid-stages-collection"},+ id="invalid-stages-collection",+ ),+ ],+ )+ @pytest.mark.parametrize(+ "dry_run",+ [False, True],+ ids=("live", "dry-run"),+ )+ @pytest.mark.asyncio+ async def test_malformed_plan_structure_returns_canonical_422_before_engine(+ self,+ aclient: Any,+ plan_data: dict[str, Any],+ dry_run: bool,+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json={"plan": plan_data, "dry_run": dry_run},+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 422+ assert response.json() == {+ "code": 422,+ "detail": self._INVALID_PLAN_DETAIL,+ "type": "api_error",+ }+ assert str(plan_data) not in response.text+ engine.registry.get.assert_not_called()+ engine.run_plan.assert_not_awaited()+ engine.dry_run_plan.assert_not_called()++ @pytest.mark.asyncio+ async def test_unknown_valid_plan_module_is_delegated_to_engine(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ engine = self._engine({})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("unknown", ["plugin.unknown"])]+ ),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ engine.registry.get.assert_called_once_with("plugin.unknown")+ engine.run_plan.assert_awaited_once()+ engine.dry_run_plan.assert_not_called()++ @pytest.mark.asyncio+ async def test_operator_safe_dry_run_reaches_preview_only(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("safe", ["plugin.safe"])], dry_run=True+ ),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ assert response.json()["status"] == "dry_run_ok"+ engine.dry_run_plan.assert_called_once()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_operator_high_noise_dry_run_denied_before_preview(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("forbidden", ["plugin.dynamic-high"])],+ dry_run=True,+ ),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 403+ engine.dry_run_plan.assert_not_called()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_team_lead_high_noise_dry_run_reaches_preview(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign("another-operator")+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("forbidden", ["plugin.dynamic-high"])],+ dry_run=True,+ ),+ headers=_auth("lead-user", "team_lead"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 200+ engine.dry_run_plan.assert_called_once()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_plan_missing_campaign_precedes_policy_lookup(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = None+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/missing/run",+ json=self._plan_body(+ [("forbidden", ["plugin.dynamic-high"])]+ ),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 404+ engine.registry.get.assert_not_called()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_plan_campaign_ownership_denial_precedes_policy_lookup(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ _, high_noise_module = self._module_classes()+ engine = self._engine({"plugin.dynamic-high": high_noise_module})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign("different-owner")+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body(+ [("forbidden", ["plugin.dynamic-high"])]+ ),+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 404+ engine.registry.get.assert_not_called()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_invalid_plan_structure_remains_422_before_policy_lookup(+ self, aclient: Any+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ engine = self._engine({})+ db.get_campaign.side_effect = None+ db.get_campaign.return_value = self._campaign()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json={"plan": {"stages": [{}]}, "dry_run": False},+ headers=_auth("operator-user", "operator"),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 422+ engine.registry.get.assert_not_called()+ engine.run_plan.assert_not_awaited()++ @pytest.mark.parametrize("role", ("reporter", "recon"))+ @pytest.mark.asyncio+ async def test_plan_reporter_and_recon_access_remains_forbidden(+ self, aclient: Any, role: str+ ) -> None:+ c, db, app = aclient+ from ares.api.server import get_engine++ safe_module, _ = self._module_classes()+ engine = self._engine({"plugin.safe": safe_module})+ db.get_campaign.reset_mock()+ app.dependency_overrides[get_engine] = lambda: engine+ try:+ response = await c.post(+ "/campaigns/camp-plan-policy/run",+ json=self._plan_body([("safe", ["plugin.safe"])]),+ headers=_auth(f"{role}-user", role),+ )+ finally:+ app.dependency_overrides.pop(get_engine, None)++ assert response.status_code == 403+ db.get_campaign.assert_not_awaited()+ engine.run_plan.assert_not_awaited()++class TestModuleRunEndpoint:def setup_method(self) -> None:_reset_rate_limiter()