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): disable ghost_forge module - fake implementation (MOD-005)
Mafifrizi32f2be3cf94f
diff --git a/ares/api/server.py b/ares/api/server.pyindex 1b8a358..e0a23e1 100644--- a/ares/api/server.py+++ b/ares/api/server.py@@ -2479,6 +2479,12 @@ async def run_module(if not campaign:raise HTTPException(404, "Campaign not found")+ if hasattr(engine, "registry"):+ is_disabled = getattr(engine.registry, "is_disabled", None)+ if callable(is_disabled) and is_disabled(module_id) is True:+ reason = getattr(engine.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"+ raise HTTPException(status_code=400, detail=reason)+raw_params = dict(body.params)# Validate params against Pydantic schemadiff --git a/ares/cli/typer_main.py b/ares/cli/typer_main.pyindex e7794b5..cdbb204 100644--- a/ares/cli/typer_main.py+++ b/ares/cli/typer_main.py@@ -557,6 +557,8 @@ def module_list(rows = []for mod_id, mod_cls in sorted(registry._registry.items()):+ if getattr(mod_cls, "ENABLED", True) is False or registry.is_disabled(mod_id):+ continuemeta = mod_cls.metadata()if category and meta.get("category") != category:continuediff --git a/ares/core/engine.py b/ares/core/engine.pyindex 04789d2..8f757fa 100644--- a/ares/core/engine.py+++ b/ares/core/engine.py@@ -559,6 +559,15 @@ class AresEngine:)runtime_state = await self.ensure_campaign_runtime(campaign)+ is_disabled = getattr(self.registry, "is_disabled", None)+ if callable(is_disabled) and is_disabled(module_id) is True:+ reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"+ return EngineModuleResult(+ module_id=module_id,+ status=ModuleStatus.FAILED,+ error=reason,+ )+if module_id not in self.registry:return EngineModuleResult(module_id=module_id,@@ -1124,6 +1133,20 @@ class AresEngine:raw_params = params or {}cls = self.registry.get(module_id)summary = redact_module_params(module_id, raw_params)+ is_disabled = getattr(self.registry, "is_disabled", None)+ if callable(is_disabled) and is_disabled(module_id) is True:+ reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"+ return {+ "dry_run": True,+ "status": "disabled",+ "module_id": module_id,+ "validated_params_summary": summary,+ "missing_params": list(missing_params or []),+ "missing_dependencies": [],+ "would_execute": False,+ "warnings": [reason],+ "operator_next_steps": [reason],+ }if cls is None:return {"dry_run": True,@@ -1197,6 +1220,16 @@ class AresEngine:"""from ares.modules.base import FeasibilityReport+ is_disabled = getattr(self.registry, "is_disabled", None)+ if callable(is_disabled) and is_disabled(module_id) is True:+ reason = getattr(self.registry, "get_disabled_reason", lambda _: None)(module_id) or "module disabled: implementation incomplete, see MOD-005"+ return FeasibilityReport(+ feasible=False,+ score=0.0,+ risk_level="high_noise",+ blockers=[reason],+ )+if module_id not in self.registry:return FeasibilityReport(feasible=False,diff --git a/ares/core/execution_chains.py b/ares/core/execution_chains.pyindex 3c3dae9..2cb3059 100644--- a/ares/core/execution_chains.py+++ b/ares/core/execution_chains.py@@ -99,7 +99,7 @@ MODULE_EXECUTION_CHAINS: Final[tuple[ExecutionChain, ...]] = ({"order": 2,"title": "Review access and identity exposure",- "module_ids": ["ad.enum_acl", "ad.adcs", "ad.ghost_forge", "ad.laps_enum"],+ "module_ids": ["ad.enum_acl", "ad.adcs", "ad.laps_enum"],"purpose": "Check delegated access, certificate services, and password-management exposure.","required_inputs": ["dc", "domain", "username", "password"],"uses_previous_output": True,diff --git a/ares/core/plugin/loader.py b/ares/core/plugin/loader.pyindex d9e5cb5..48077f6 100644--- a/ares/core/plugin/loader.py+++ b/ares/core/plugin/loader.py@@ -106,14 +106,20 @@ class ModuleRegistry:def __init__(self) -> None:self._registry: dict[str, type[BaseModule]] = {}+ self._disabled: dict[str, type[BaseModule]] = {}self._sources: dict[str, str] = ({}) # module_id → source (builtin/entrypoint/external)def register(self, cls: type[BaseModule], source: str = "builtin") -> None:- mid = cls.MODULE_ID+ mid = getattr(cls, "MODULE_ID", "")if not mid:return+ if getattr(cls, "ENABLED", True) is False:+ self._disabled[mid] = cls+ self._sources[mid] = source+ logger.info("registry_disabled_module", mid=mid, source=source)+ returnif mid in self._registry:existing_source = self._sources.get(mid, "unknown")logger.debug(@@ -127,18 +133,45 @@ class ModuleRegistry:self._sources[mid] = sourcelogger.debug("registry_registered_from", mid=mid, source=source)+ def is_disabled(self, module_id: str) -> bool:+ if module_id in self._disabled:+ return True+ cls = self._registry.get(module_id)+ if cls is not None and getattr(cls, "ENABLED", True) is False:+ return True+ return False++ def get_disabled_reason(self, module_id: str) -> str | None:+ cls = self._disabled.get(module_id) or self._registry.get(module_id)+ if cls is not None:+ return getattr(cls, "DISABLED_REASON", "") or "module disabled"+ return None+def get(self, module_id: str) -> type[BaseModule] | None:return self._registry.get(module_id)+ def get_disabled(self, module_id: str) -> type[BaseModule] | None:+ return self._disabled.get(module_id)+def __setitem__(self, module_id: str, cls: type[BaseModule]) -> None:- self._registry[module_id] = cls+ if getattr(cls, "ENABLED", True) is False:+ self._disabled[module_id] = cls+ else:+ self._registry[module_id] = clsdef all(self) -> list[type[BaseModule]]:- return list(self._registry.values())+ return [+ cls for mid, cls in self._registry.items()+ if getattr(cls, "ENABLED", True) is not False and mid not in self._disabled+ ]def by_category(self, category: str) -> list[type[BaseModule]]:return [- cls for cls in self._registry.values() if cls.MODULE_CATEGORY == category+ cls+ for mid, cls in self._registry.items()+ if cls.MODULE_CATEGORY == category+ and getattr(cls, "ENABLED", True) is not False+ and mid not in self._disabled]def list_metadata(self) -> list[dict[str, Any]]:@@ -151,6 +184,8 @@ class ModuleRegistry:"""result = []for mid, cls in sorted(self._registry.items()):+ if getattr(cls, "ENABLED", True) is False or mid in self._disabled:+ continuetry:# BaseModule.metadata() returns the canonical dict including# opsec_level, requires, outputs, mitre_list, min_noise_profile@@ -179,7 +214,7 @@ class ModuleRegistry:return len(self._registry)def __contains__(self, module_id: str) -> bool:- return module_id in self._registry+ return module_id in self._registry and not self.is_disabled(module_id)# ── Loader ────────────────────────────────────────────────────────────────────diff --git a/ares/modules/ad/ghost_forge.py b/ares/modules/ad/ghost_forge.pyindex 4849262..a40590e 100644--- a/ares/modules/ad/ghost_forge.py+++ b/ares/modules/ad/ghost_forge.py@@ -20,6 +20,7 @@ import hashlibfrom typing import Anyfrom ares.core.campaign import Finding, Severity+from ares.core.errors import ModuleError, ModuleValidationErrorfrom ares.core.logger import audit, get_loggerfrom ares.core.security import sanitize_hostname, sanitize_ldapfrom ares.core.tracing import trace_module@@ -65,123 +66,48 @@ class GhostForgeModule(BaseModule[GhostForgeParams, ModuleResult]):MITRE_TECHNIQUES = ["T1649", "T1558"]MODULE_TIMEOUT_SECONDS: int | None = 120PARAMS_MODEL = GhostForgeParams+ ENABLED = False+ DISABLED_REASON = "module disabled: implementation incomplete, see MOD-005"async def assess_feasibility(self, ctx: Any) -> Any:from ares.modules.base import FeasibilityReport- blockers: list[str] = []- score = 1.0- risk = "medium"-- p = getattr(ctx, "params", {})- dc = getattr(ctx, "target", "") or (p.get("dc") if isinstance(p, dict) else getattr(p, "dc", ""))- if not dc:- blockers.append("No Domain Controller (dc) specified for PKINIT exchange")- score -= 0.4-- ca = (p.get("ca_server") if isinstance(p, dict) else getattr(p, "ca_server", ""))- if not ca:- blockers.append("No CA server specified for certificate enrollment")- score -= 0.4-- technique = (p.get("target_technique") if isinstance(p, dict) else getattr(p, "target_technique", "auto")) or "auto"- policy_oid = (p.get("policy_oid") if isinstance(p, dict) else getattr(p, "policy_oid", None))- if technique == "esc13" and not policy_oid:- blockers.append("ESC13 evaluation requires 'policy_oid' to map to target group")- score -= 0.3+ # MITIGATION (MOD-005): Module is temporarily disabled from execution pipeline.return FeasibilityReport(- feasible=len(blockers) == 0 and score >= 0.5,- score=max(0.0, min(1.0, score)),- risk_level=risk,- blockers=blockers,+ feasible=False,+ score=0.0,+ risk_level="high_noise",+ blockers=["module disabled: implementation incomplete, see MOD-005"],recommended_alternatives=["ad.adcs"],details={- "dc_specified": bool(dc),- "ca_specified": bool(ca),- "target_technique": technique,- "strong_mapping_ready": True,+ "disabled": True,+ "reason": "module disabled: implementation incomplete, see MOD-005",},)async def validate(self, ctx: Any) -> None:- from ares.core.context import ExecutionContext- from ares.core.errors import ModuleValidationError- if not isinstance(ctx, ExecutionContext):- return- p = getattr(ctx, "params", {})- dc = (p.get("dc") if isinstance(p, dict) else getattr(p, "dc", None)) or getattr(ctx, "target", "")- ca = p.get("ca_server") if isinstance(p, dict) else getattr(p, "ca_server", None)- user = p.get("username") if isinstance(p, dict) else getattr(p, "username", None)- if not dc:- raise ModuleValidationError("ad.ghost_forge requires 'dc'.", module_id=self.MODULE_ID, field="dc")- if not ca:- raise ModuleValidationError("ad.ghost_forge requires 'ca_server'.", module_id=self.MODULE_ID, field="ca_server")- if not user:- raise ModuleValidationError("ad.ghost_forge requires 'username'.", module_id=self.MODULE_ID, field="username")- await super().validate(ctx)+ # MITIGATION (MOD-005): Fail fast with explicit error before parameter checks+ raise ModuleValidationError(+ "module disabled: implementation incomplete, see MOD-005",+ module_id=self.MODULE_ID,+ )async def execute(self, ctx: ExecutionContext[GhostForgeParams]) -> ModuleResult:- if isinstance(ctx.params, GhostForgeParams):- p = ctx.params- elif isinstance(ctx.params, dict):- p = GhostForgeParams.model_validate(ctx.params)- else:- p = GhostForgeParams()-- kwargs = p.model_dump()- kwargs["dry_run"] = getattr(ctx, "dry_run", False)- if getattr(ctx, "target", None) and not kwargs.get("dc"):- kwargs["dc"] = ctx.target-- findings, raw = await self.run(**kwargs)-- if getattr(ctx, "dry_run", False):- if findings and hasattr(ctx, "emit_finding"):- f = findings[0]- ctx.emit_finding(- title=f.title,- severity=f.severity,- description=f.description,- mitre_technique=f.mitre_technique,- )- return ModuleResult(- status="dry_run",- module_id=self.MODULE_ID,- raw=raw,- )-- if findings and hasattr(ctx, "emit_finding"):- f = findings[0]- ctx.emit_finding(- title=f.title,- severity=f.severity,- description=f.description,- mitre_technique=f.mitre_technique,- mitre_tactic=f.mitre_tactic,- evidence=f.evidence,- remediation=f.remediation,- )-- target_account = raw.get("impersonated_user", "Administrator")- cert_thumbprint = raw.get("certificate_thumbprint", "")- if hasattr(ctx, "record_credential"):- ctx.record_credential(- username=target_account,- secret=f"TGT_PKINIT_{cert_thumbprint[:16]}",- domain=p.domain,- cred_type="ticket",- )-- return ModuleResult(- status="success",- findings=findings,- raw=raw,+ # MITIGATION (MOD-005): Disabled from execution pipeline to prevent fictitious findings+ # and vault contamination while final architectural decision is pending.+ raise ModuleError(+ "module disabled: implementation incomplete, see MOD-005",module_id=self.MODULE_ID,- execution_id=getattr(ctx, "execution_id", ""),)@trace_module("ad.ghost_forge")async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:+ # MITIGATION (MOD-005): Disabled from execution pipeline to prevent fictitious findings+ # and vault contamination while final architectural decision is pending.+ raise ModuleError(+ "module disabled: implementation incomplete, see MOD-005",+ module_id=self.MODULE_ID,+ )self._findings = []ctx = kwargs.get("ctx") or kwargsdc = str(ctx.get("dc") or ctx.get("target") or "")diff --git a/ares/modules/base.py b/ares/modules/base.pyindex fd240e6..cbe5adc 100644--- a/ares/modules/base.py+++ b/ares/modules/base.py@@ -132,6 +132,7 @@ def normalize_module_metadata(metadata.setdefault("safe_error_categories", list(MODULE_SAFE_ERROR_CATEGORIES))+ metadata.setdefault("enabled", bool(getattr(cls, "ENABLED", True)))metadata["param_schema"] = schemareturn metadata@@ -394,6 +395,8 @@ class BaseModule(abc.ABC, Generic[P, R]):MODULE_DESCRIPTION: str = ""# ── Optional metadata ──────────────────────────────────────────────────+ ENABLED: bool = True+ DISABLED_REASON: str = ""OPSEC_LEVEL: OpsecLevel = OpsecLevel.LOWREQUIRES: list[str] = [] # e.g. ["domain_creds", "ldap_access"]OUTPUTS: list[str] = [] # e.g. ["spn_list", "user_list"]diff --git a/tests/unit/test_api_endpoints.py b/tests/unit/test_api_endpoints.pyindex 6e79361..f54c9c3 100644--- a/tests/unit/test_api_endpoints.py+++ b/tests/unit/test_api_endpoints.py@@ -1728,6 +1728,46 @@ class TestModuleSchemaEndpoint:assert field in moduleassert module["dry_run_supported"] is True+ @pytest.mark.asyncio+ async def test_disabled_ghost_forge_module_rejected_via_api(+ self, aclient: Any+ ) -> None:+ from ares.api.server import app, get_engine+ from ares.core.campaign import Campaign, ScopeEntry+ from ares.core.engine import AresEngine+ c, db, _ = aclient+ db.is_access_token_revoked.return_value = False+ campaign = Campaign(name="Disabled Test", client="Client", scope=[ScopeEntry(cidr="10.0.0.0/24")])+ db.get_campaign.return_value = campaign++ real_engine = AresEngine()+ real_engine.load_modules()+ app.dependency_overrides[get_engine] = lambda: real_engine+ try:+ # 1. Verify ad.ghost_forge does NOT appear in GET /modules+ res = await c.get("/modules", headers=_auth("admin", "team_lead"))+ assert res.status_code == 200+ module_ids = [m["id"] for m in res.json()]+ assert "ad.ghost_forge" not in module_ids++ # 2. Verify POST /modules/ad.ghost_forge/run is rejected with explicit 400 error+ res_run = await c.post(+ "/modules/ad.ghost_forge/run",+ json={+ "campaign_id": campaign.id,+ "target": "10.0.0.1",+ "params": {"dc": "10.0.0.1", "username": "admin", "password": "Password123!"},+ },+ headers={+ **_auth("admin", "team_lead"),+ "X-Idempotency-Key": "00000000-0000-4000-8000-000000000001",+ },+ )+ assert res_run.status_code == 400+ assert "module disabled: implementation incomplete, see MOD-005" in res_run.json()["detail"]+ finally:+ app.dependency_overrides.pop(get_engine, None)+@pytest.mark.asyncio # type: ignore[untyped-decorator]async def test_execution_chains_are_available_with_module_metadata(self, aclient: Anydiff --git a/tests/unit/test_staged_modules.py b/tests/unit/test_staged_modules.pyindex dc80937..8ff3313 100644--- a/tests/unit/test_staged_modules.py+++ b/tests/unit/test_staged_modules.py@@ -56,10 +56,28 @@ class TestPhantomTokenModule:class TestGhostForgeModule:def test_module_attributes(self):assert GhostForgeModule.MODULE_ID == "ad.ghost_forge"+ assert GhostForgeModule.ENABLED is False+ assert GhostForgeModule.DISABLED_REASON == "module disabled: implementation incomplete, see MOD-005"assert "T1649" in GhostForgeModule.MITRE_TECHNIQUESassert "T1558" in GhostForgeModule.MITRE_TECHNIQUES- def test_dry_run_execution(self):+ def test_direct_run_raises_disabled_error(self):+ from ares.core.errors import ModuleError+ mod, _ = _make_module(GhostForgeModule)+ with pytest.raises(ModuleError) as exc_info:+ _run(mod.run(+ dc="10.10.10.1",+ domain="CORP.LOCAL",+ ca_server="ca.corp.local",+ ca_name="CORP-CA",+ impersonate_user="Administrator",+ username="audit_operator",+ password="SecretPassword123!",+ ))+ assert "module disabled: implementation incomplete, see MOD-005" in str(exc_info.value)++ def test_execute_raises_disabled_error(self):+ from ares.core.errors import ModuleErrormod, _ = _make_module(GhostForgeModule)ctx = _mock_ctx(params={"dc": "10.10.10.1",@@ -69,52 +87,34 @@ class TestGhostForgeModule:"username": "audit_operator","password": "SecretPassword123!",})- ctx.dry_run = True- res = _run(mod.execute(ctx))- assert res.status == "dry_run"- assert res.module_id == "ad.ghost_forge"- assert res.raw.get("dc") == "10.10.10.1"+ with pytest.raises(ModuleError) as exc_info:+ _run(mod.execute(ctx))+ assert "module disabled: implementation incomplete, see MOD-005" in str(exc_info.value)- def test_live_execution_findings(self):+ def test_validate_raises_disabled_error(self):+ from ares.core.errors import ModuleValidationErrormod, _ = _make_module(GhostForgeModule)ctx = _mock_ctx(params={"dc": "10.10.10.1","domain": "CORP.LOCAL","ca_server": "ca.corp.local","ca_name": "CORP-CA",- "impersonate_user": "Administrator","username": "audit_operator","password": "SecretPassword123!",- "perform_pkinit": True,})- ctx.dry_run = False- res = _run(mod.execute(ctx))- assert res.status == "success"- assert len(res.findings) >= 1- assert res.findings[0].mitre_technique == "T1649"- assert res.raw.get("pkinit_success") is True+ with pytest.raises(ModuleValidationError) as exc_info:+ _run(mod.validate(ctx))+ assert "module disabled: implementation incomplete, see MOD-005" in str(exc_info.value)- def test_direct_run_method(self):+ def test_assess_feasibility_reports_disabled(self):mod, _ = _make_module(GhostForgeModule)- findings, raw = _run(mod.run(- dc="10.10.10.1",- domain="CORP.LOCAL",- ca_server="ca.corp.local",- ca_name="CORP-CA",- impersonate_user="Administrator",- username="audit_operator",- password="SecretPassword123!",- perform_pkinit=True,- dry_run=False,- ))- assert len(findings) == 1- assert findings[0].mitre_technique == "T1649"- assert raw.get("pkinit_success") is True- assert raw.get("dc") == "10.10.10.1"-+ ctx = _mock_ctx(params={"dc": "10.10.10.1"})+ report = _run(mod.assess_feasibility(ctx))+ assert report.feasible is False+ assert any("MOD-005" in b for b in report.blockers)@pytest.mark.asyncio- async def test_engine_persists_loot_from_module_output(self, tmp_path):+ async def test_engine_run_module_fails_with_disabled_error(self, tmp_path):from ares.core.campaign import Campaign, ScopeEntryfrom ares.core.engine import AresEnginefrom ares.db.database import AresDatabase@@ -124,7 +124,7 @@ class TestGhostForgeModule:campaign = Campaign(name="Loot Test", client="Client", scope=[ScopeEntry(cidr="10.10.10.0/24")], operator="operator")await db.save_campaign(campaign)- from ares.core.execution_admission import _mint_test_dispatch_context, mark_terminal_committed+ from ares.core.execution_admission import _mint_test_dispatch_contextengine = AresEngine(db=db)mod, _ = _make_module(GhostForgeModule)@@ -144,39 +144,22 @@ class TestGhostForgeModule:},dispatch_context=dispatch_ctx,)- assert str(result.status) in ("success", "done", "ModuleStatus.DONE")- mark_terminal_committed(dispatch_ctx)- await engine._finalize_committed_module_result(campaign, "ad.ghost_forge", result, dispatch_ctx)+ assert str(result.status) in ("failed", "ModuleStatus.FAILED")+ assert "module disabled: implementation incomplete, see MOD-005" in (result.error or "")loots = await db.get_loot(campaign.id)- assert len(loots) >= 1- assert any("TGT" in l["name"] for l in loots)- assert any("KQL" in l["name"] for l in loots)- assert any("Sigma" in l["name"] for l in loots)+ assert len(loots) == 0await db.close()- def test_ghost_forge_esc13_and_strong_mapping(self):- mod, _ = _make_module(GhostForgeModule)- ctx = _mock_ctx(params={- "dc": "10.10.10.1",- "domain": "CORP.LOCAL",- "ca_server": "ca.corp.local",- "ca_name": "CORP-CA",- "username": "audit_operator",- "password": "SecretPassword123!",- "target_technique": "esc13",- "policy_oid": "1.3.6.1.4.1.311.99.1.13",- "enforcement_mode_check": True,- "generate_detection_rules": True,- })- ctx.dry_run = False- res = _run(mod.execute(ctx))- assert res.status == "success"- assert len(res.findings) >= 1- assert "ESC13" in res.findings[0].title- assert res.raw.get("technique_applied") == "esc13"- assert res.raw.get("kb5014754_compliant") is True- assert any(l["loot_type"] == "detection_rule_kql" for l in res.raw["loot"])- assert any(l["loot_type"] == "detection_rule_sigma" for l in res.raw["loot"])+ def test_registry_excludes_ghost_forge_from_listings(self):+ from ares.core.plugin.loader import PluginLoader+ loader = PluginLoader()+ loader._load_builtin()+ assert "ad.ghost_forge" not in [m["id"] for m in loader.registry.list_metadata()]+ assert "ad.ghost_forge" not in [cls.MODULE_ID for cls in loader.registry.all()]+ assert "ad.ghost_forge" not in [cls.MODULE_ID for cls in loader.registry.by_category("ad")]+ assert loader.registry.is_disabled("ad.ghost_forge") is True+ assert loader.registry.get_disabled_reason("ad.ghost_forge") == "module disabled: implementation incomplete, see MOD-005"+ assert "ad.ghost_forge" not in loader.registrydef test_phantom_token_workload_identity_and_detection(self):mod, _ = _make_module(PhantomTokenModule)