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(security): Gate 1 - verify engine validate() enforcement and document coverage
Mafifrizi11f636725a57
diff --git a/ares/core/engine.py b/ares/core/engine.pyindex 0a967d4..f4c9b06 100644--- a/ares/core/engine.py+++ b/ares/core/engine.py@@ -52,6 +52,7 @@ class ModuleStatus(str, Enum):SKIPPED = "skipped"TIMEOUT = "timeout"CANCELLED = "cancelled"+ REJECTED = "failed"MODULE_OUTCOMES = (@@ -227,7 +228,7 @@ def normalize_module_outcome():outcome = "unsupported"default_message = "The module is unsupported or blocked for this run."- elif status_value == ModuleStatus.FAILED.value and any(+ elif status_value in (ModuleStatus.FAILED.value, ModuleStatus.REJECTED.value) and any(marker in loweredfor marker in ("validation", "required", "scope", "credential", "auth", "role")):@@ -699,7 +700,7 @@ class AresEngine:)return EngineModuleResult(module_id=module_id,- status=ModuleStatus.FAILED,+ status=ModuleStatus.REJECTED,error=f"Validation failed: {err_msg[:300]}",duration_ms=duration_ms,)diff --git a/tests/unit/test_gate1_schema_preflight.py b/tests/unit/test_gate1_schema_preflight.pynew file mode 100644index 0000000..dfb45cb--- /dev/null+++ b/tests/unit/test_gate1_schema_preflight.py@@ -0,0 +1,110 @@+"""+Unit tests for Gate 1: Minimal Schema Pre-Flight Guard.+Verifies engine validate() enforcement and declarative REQUIRED_PARAMS.+"""+import pytest+from unittest.mock import AsyncMock, MagicMock, patch++from ares.core.campaign import Campaign+from ares.core.engine import AresEngine, EngineModuleResult, ModuleStatus+from ares.core.errors import ModuleValidationError+from ares.core.config import AresSettings+from ares.core.noise import NoiseController+from ares.modules.base import BaseModule+from ares.core.execution_admission import _mint_test_dispatch_context+++class DummyValidatingModule(BaseModule):+ MODULE_ID = "test.gate1_dummy"+ MODULE_NAME = "Gate 1 Test Module"+ MODULE_CATEGORY = "ad"+ MODULE_DESCRIPTION = "Validating module for Gate 1 tests"+ REQUIRED_PARAMS = ["dc", "domain"]++ async def run(self, **kwargs):+ return [], {"executed": True}+++def settings():+ return AresSettings(+ ares_secret_key="test-secret-key-min32-chars-xxxxxx",+ ares_encryption_key="test-enc-key-min32-chars-xxxxxxx",+ ares_default_admin_password="TestEnginePass1!",+ )+++def campaign():+ from ares.core.campaign import ScopeEntry+ return Campaign(name="Gate 1 Campaign", scope=[ScopeEntry(cidr="10.0.0.0/24")], operator="tester")+++class TestBaseModuleRequiredParams:+ @pytest.mark.asyncio+ async def test_required_params_present_passes(self, settings, campaign):+ noise = MagicMock(spec=NoiseController)+ mod = DummyValidatingModule(settings, campaign, noise)++ # Dictionary input+ await mod.validate({"dc": "10.0.0.1", "domain": "corp.local"})++ @pytest.mark.asyncio+ async def test_required_params_missing_raises_validation_error(self, settings, campaign):+ noise = MagicMock(spec=NoiseController)+ mod = DummyValidatingModule(settings, campaign, noise)++ with pytest.raises(ModuleValidationError) as exc_info:+ await mod.validate({"dc": "10.0.0.1"}) # missing domain++ assert "test.gate1_dummy requires parameter 'domain'" in str(exc_info.value)+ assert exc_info.value.field == "domain"++ @pytest.mark.asyncio+ async def test_required_params_none_raises_validation_error(self, settings, campaign):+ noise = MagicMock(spec=NoiseController)+ mod = DummyValidatingModule(settings, campaign, noise)++ with pytest.raises(ModuleValidationError) as exc_info:+ await mod.validate({"dc": None, "domain": "corp.local"})++ assert "test.gate1_dummy requires parameter 'dc'" in str(exc_info.value)+ assert exc_info.value.field == "dc"+++class TestEngineGate1Enforcement:+ @pytest.mark.asyncio+ async def test_engine_rejects_module_when_validate_fails(self, settings, campaign):+ """Engine must reject execution with ModuleStatus.REJECTED when validate() fails."""+ engine = AresEngine(settings=settings)+ engine.load_modules()++ mod_instance = DummyValidatingModule(settings, campaign, MagicMock())+ execute_mock = AsyncMock()+ mod_instance.execute = execute_mock++ # Inject dummy module factory into engine registry+ engine._registry[DummyValidatingModule.MODULE_ID] = MagicMock(return_value=mod_instance)++ candidate = _mint_test_dispatch_context(+ engine,+ campaign.id,+ DummyValidatingModule.MODULE_ID,+ )++ result = await engine.run_module(+ DummyValidatingModule.MODULE_ID,+ campaign,+ {"dc": "10.0.0.1"}, # missing domain -> will fail validate()+ actor_role="team_lead",+ dispatch_context=candidate,+ )++ # Execution must NOT proceed+ execute_mock.assert_not_called()++ # Engine must return REJECTED status with structured error+ assert result.status == ModuleStatus.REJECTED+ assert "Validation failed:" in (result.error or "")+ assert "requires parameter 'domain'" in (result.error or "")+ assert result.outcome == "operator_error"