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
feat(security): CloudScopeGuard - cloud identifier scope validation (MOD-053/MOD-063)
Mafifrizi2e6d71b46b27
diff --git a/ares/core/campaign.py b/ares/core/campaign.pyindex 929c872..c575ce6 100644--- a/ares/core/campaign.py+++ b/ares/core/campaign.py@@ -11,6 +11,8 @@ from typing import Anyfrom pydantic import BaseModel, Field, PrivateAttr, field_validatorfrom netaddr import IPNetwork, AddrFormatError+from ares.core.scope import CampaignScope, CloudScope+class Severity(str, Enum):CRITICAL = "critical"@@ -130,6 +132,14 @@ class AuditEntry(BaseModel):module_id: str | None = None+class ScopeEntryList(list):+ """List of ScopeEntry items supporting .cloud_scope attribute access."""++ def __init__(self, iterable: Any = (), cloud_scope: CloudScope | None = None) -> None:+ super().__init__(iterable)+ self.cloud_scope = cloud_scope if cloud_scope is not None else CloudScope()++class Campaign(BaseModel):id: str = Field(default_factory=lambda: str(uuid.uuid4()))name: str = Field(..., min_length=1, max_length=100)@@ -150,6 +160,7 @@ class Campaign(BaseModel):result.append(clean if clean else entry.strip())return resultscope: list[ScopeEntry] = Field(default_factory=list)+ cloud_scope: CloudScope = Field(default_factory=CloudScope)status: CampaignStatus = CampaignStatus.CREATEDnoise_profile: NoiseProfile = NoiseProfile.STEALTH@@ -173,7 +184,12 @@ class Campaign(BaseModel):_scope_cache: dict[str, bool] = PrivateAttr(default_factory=dict)def model_post_init(self, __context: Any) -> None:- """Warn if operator is still the default 'unknown'."""+ """Initialize scope wrapper and warn if operator is still default 'unknown'."""+ if not isinstance(self.scope, ScopeEntryList):+ self.scope = ScopeEntryList(self.scope, cloud_scope=self.cloud_scope)+ else:+ self.scope.cloud_scope = self.cloud_scope+if self.operator == "unknown":import logging as _logging_logging.getLogger("ares.campaign").warning(diff --git a/ares/core/errors.py b/ares/core/errors.pyindex 37f2828..cd0e8f0 100644--- a/ares/core/errors.py+++ b/ares/core/errors.py@@ -366,6 +366,13 @@ class ScopeError(AresError):self.scope_cidrs = scope_cidrs or []+class ScopeViolationError(ScopeError):+ """+ Operation would target an out-of-scope host, network, or cloud identifier.+ Engine ABORTS immediately with a security audit event.+ """++class ScopeFirewallBlockError(ScopeError):"""Direct network socket or transport connection attempt to an out-of-scope hostdiff --git a/ares/core/scope.py b/ares/core/scope.pynew file mode 100644index 0000000..2dd1867--- /dev/null+++ b/ares/core/scope.py@@ -0,0 +1,51 @@+"""+ARES Campaign Scope & CloudScopeGuard+Provides declarative scope boundaries for network (CIDR/DNS) and cloud resources.+"""+from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any+++@dataclass+class CloudScope:+ """+ Authorized cloud identifiers for a campaign (CloudScopeGuard).++ Configuration semantics:+ - If a provider list is empty: all identifiers for that provider are allowed+ (unrestricted / backward compatible).+ - If a provider list is populated: only identifiers explicitly listed are allowed.+ Any other identifier triggers a ScopeViolationError.+ """+ aws_account_ids: list[str] = field(default_factory=list)+ azure_subscription_ids: list[str] = field(default_factory=list)+ azure_tenant_ids: list[str] = field(default_factory=list)+ gcp_project_ids: list[str] = field(default_factory=list)++ def is_authorized(self, identifier: str, provider: str) -> bool:+ """+ Check if the given identifier is authorized for the cloud provider.+ Returns True if unconfigured (empty list) or if identifier is in the list.+ """+ if not identifier:+ return False+ clean_id = str(identifier).strip()+ mapping = {+ "aws": self.aws_account_ids,+ "azure": self.azure_subscription_ids,+ "azure_ad": self.azure_tenant_ids,+ "gcp": self.gcp_project_ids,+ }+ authorized = mapping.get(provider, [])+ if not authorized:+ return True # Unconfigured = unrestricted (backward compatible)+ return clean_id in authorized+++@dataclass+class CampaignScope:+ """Aggregated campaign scope holding network target entries and cloud boundaries."""+ entries: list[Any] = field(default_factory=list)+ cloud_scope: CloudScope = field(default_factory=CloudScope)diff --git a/ares/modules/base.py b/ares/modules/base.pyindex cbe5adc..772be5c 100644--- a/ares/modules/base.py+++ b/ares/modules/base.py@@ -246,9 +246,35 @@ class BaseModule(abc.ABC, Generic[P, R]):from ares.core.context import ExecutionContextfrom ares.core.errors import ModuleValidationError+ if isinstance(ctx, dict):+ req_params = getattr(self.__class__, "REQUIRED_PARAMS", []) or getattr(self, "REQUIRED_PARAMS", [])+ for param in req_params:+ if param not in ctx or ctx[param] is None:+ raise ModuleValidationError(+ f"{self.MODULE_ID} requires parameter '{param}'",+ module_id=self.MODULE_ID,+ field=param,+ )+ return+if not isinstance(ctx, ExecutionContext):return # legacy context - skip validation+ req_params = getattr(self.__class__, "REQUIRED_PARAMS", []) or getattr(self, "REQUIRED_PARAMS", [])+ if req_params:+ params_dict = (+ ctx.params.model_dump()+ if hasattr(getattr(ctx, "params", None), "model_dump")+ else (getattr(ctx, "params", {}) or {})+ )+ for param in req_params:+ if param not in params_dict or params_dict[param] is None:+ raise ModuleValidationError(+ f"{self.MODULE_ID} requires parameter '{param}'",+ module_id=self.MODULE_ID,+ field=param,+ )+if getattr(self, "PARAMS_MODEL", None) is not None:from ares.sdk.params import validate_params@@ -398,6 +424,7 @@ class BaseModule(abc.ABC, Generic[P, R]):ENABLED: bool = TrueDISABLED_REASON: str = ""OPSEC_LEVEL: OpsecLevel = OpsecLevel.LOW+ REQUIRED_PARAMS: list[str] = [] # Declarative required param keys for Gate 1REQUIRES: list[str] = [] # e.g. ["domain_creds", "ldap_access"]OUTPUTS: list[str] = [] # e.g. ["spn_list", "user_list"]MITRE_TECHNIQUES: list[str] = []@@ -446,6 +473,45 @@ class BaseModule(abc.ABC, Generic[P, R]):f"Module '{self.MODULE_ID}' must implement run()")+ # ── Cloud Scope Guardrail ──────────────────────────────────────────────++ def validate_cloud_scope(self, identifier: str, provider: str) -> None:+ """+ Validate that the specified cloud identifier is authorized by the campaign's CloudScope.++ If cloud_scope is unconfigured (empty list for provider), validation passes+ (backward compatible).+ Raises ScopeViolationError if the identifier is unauthorized.+ """+ if not identifier:+ return++ from ares.core.errors import ScopeViolationError++ campaign = getattr(self, "campaign", None)+ if not campaign:+ return++ cloud_scope = getattr(campaign, "cloud_scope", None)+ if cloud_scope is None and hasattr(campaign, "scope"):+ cloud_scope = getattr(campaign.scope, "cloud_scope", None)++ if cloud_scope and not cloud_scope.is_authorized(identifier, provider):+ mapping = {+ "aws": "aws_account_ids",+ "azure": "azure_subscription_ids",+ "azure_ad": "azure_tenant_ids",+ "gcp": "gcp_project_ids",+ }+ authorized = getattr(cloud_scope, mapping.get(provider, f"{provider}_ids"), [])+ raise ScopeViolationError(+ f"Cloud {provider} identifier '{identifier}' is not "+ f"in authorized campaign scope. "+ f"Authorized: {authorized}",+ module_id=getattr(self, "MODULE_ID", ""),+ target=str(identifier),+ )+# ── Pre-request hook ───────────────────────────────────────────────────async def before_request(self, target: str, action: str = "default") -> None:diff --git a/ares/modules/cloud/__init__.py b/ares/modules/cloud/__init__.pyindex 18e8f76..663f2a2 100644--- a/ares/modules/cloud/__init__.py+++ b/ares/modules/cloud/__init__.py@@ -8,6 +8,7 @@ Direct imports from this package work but are not required.from __future__ import annotationstry:+ from ares.modules.cloud.base import BaseCloudModule # noqa: F401from ares.modules.cloud.aws import AWSEnumModule # noqa: F401from ares.modules.cloud.aws_privesc import AWSPrivescModule # noqa: F401from ares.modules.cloud.azure import AzureModule # noqa: F401@@ -17,6 +18,7 @@ except ImportError:pass # optional deps (impacket, ldap3, etc.) not installed__all__ = [+ "BaseCloudModule","AWSEnumModule","AWSPrivescModule","AzureModule",diff --git a/ares/modules/cloud/aws.py b/ares/modules/cloud/aws.pyindex 1e249b2..ea654f7 100644--- a/ares/modules/cloud/aws.py+++ b/ares/modules/cloud/aws.py@@ -80,6 +80,8 @@ class AWSEnumModule(BaseModule):"or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment variables.",module_id=self.MODULE_ID, field="access_key",)+ if pdict.get("account_id"):+ self.validate_cloud_scope(pdict.get("account_id"), "aws")async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+)."""@@ -210,8 +212,22 @@ class AWSEnumModule(BaseModule):raise AuthenticationFailed(f"AWS auth failed: {exc}", username="aws_key", module_id=self.MODULE_ID, target="aws") from excloop = asyncio.get_running_loop()raw = {"region": region}++ # Step 1: Caller identity & CloudScopeGuard validation+ try:+ identity_info = await loop.run_in_executor(None, partial(self._get_caller_identity, session))+ raw["identity"] = identity_info+ account_id = str(identity_info.get("Account", ""))+ if account_id:+ self.validate_cloud_scope(account_id, "aws")+ except Exception as exc:+ from ares.core.errors import ScopeViolationError+ if isinstance(exc, ScopeViolationError):+ raise+ logger.warning("aws_check_failed", check="identity", error=str(exc)[:100])+ raw["identity"] = {"error": str(exc)[:150]}+for label, fn in [- ("identity", partial(self._get_caller_identity, session)),("iam", partial(self._enum_iam, session)),("s3", partial(self._enum_s3, session, region)),("security_groups", partial(self._enum_security_groups, session, region)),diff --git a/ares/modules/cloud/aws_privesc.py b/ares/modules/cloud/aws_privesc.pyindex 084d527..20a20cf 100644--- a/ares/modules/cloud/aws_privesc.py+++ b/ares/modules/cloud/aws_privesc.py@@ -268,12 +268,18 @@ class AWSPrivescModule(BaseModule):# Who am I?try:identity = sts.get_caller_identity()+ account_id = str(identity.get("Account", ""))+ if account_id:+ self.validate_cloud_scope(account_id, "aws")results["current_identity"] = {"arn": identity.get("Arn", ""),"user_id": identity.get("UserId", ""),- "account": identity.get("Account", ""),+ "account": account_id,}except Exception as e:+ from ares.core.errors import ScopeViolationError+ if isinstance(e, ScopeViolationError):+ raiseresults["errors"].append(f"GetCallerIdentity: {e!s:.80}")return resultsdiff --git a/ares/modules/cloud/azure.py b/ares/modules/cloud/azure.pyindex c5a2788..7b77ee3 100644--- a/ares/modules/cloud/azure.py+++ b/ares/modules/cloud/azure.py@@ -108,6 +108,10 @@ class AzureModule(BaseModule):"AZURE_CLIENT_ID/AZURE_CLIENT_SECRET/AZURE_TENANT_ID env vars.",module_id=self.MODULE_ID, field="subscription_id",)+ if pdict.get("subscription_id"):+ self.validate_cloud_scope(pdict.get("subscription_id"), "azure")+ if pdict.get("tenant_id"):+ self.validate_cloud_scope(pdict.get("tenant_id"), "azure_ad")async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+).@@ -223,6 +227,11 @@ class AzureModule(BaseModule):# Note: before_request() intentionally not called - cloud modules use# API credentials, not host IPs. Scope check (CIDR) does not apply to# cloud API endpoints. Rate limiting and jitter are handled at the API call level.+ if subscription_id:+ self.validate_cloud_scope(subscription_id, "azure")+ if tenant_id:+ self.validate_cloud_scope(tenant_id, "azure_ad")+logger.info("azure_recon_start", subscription_id=subscription_id[:8] + "...")try:credential = _get_credential(tenant_id, client_id, client_secret)diff --git a/ares/modules/cloud/azure_ad.py b/ares/modules/cloud/azure_ad.pyindex 1f56d92..bdf64f5 100644--- a/ares/modules/cloud/azure_ad.py+++ b/ares/modules/cloud/azure_ad.py@@ -118,6 +118,7 @@ class AzureADModule(BaseModule):"Find via: az account show --query tenantId",module_id=self.MODULE_ID, field="tenant_id",)+ self.validate_cloud_scope(tenant_id, "azure_ad")async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+).@@ -243,6 +244,9 @@ class AzureADModule(BaseModule):# Note: before_request() intentionally not called - cloud modules use# API credentials, not host IPs. Scope check (CIDR) does not apply to# cloud API endpoints. Rate limiting and jitter are handled at the API call level.+ if tenant_id:+ self.validate_cloud_scope(tenant_id, "azure_ad")+logger.info("azure_ad_start", tenant=tenant_id[:8] + "...", technique=technique)audit("azure_ad_attack", actor="operator", technique="T1528",source="operator", target=f"tenant:{tenant_id[:8]}")diff --git a/ares/modules/cloud/base.py b/ares/modules/cloud/base.pynew file mode 100644index 0000000..d95e47d--- /dev/null+++ b/ares/modules/cloud/base.py@@ -0,0 +1,14 @@+"""+ARES Cloud Base Module+Base class for cloud attack and recon modules.+"""+from __future__ import annotations++from typing import Any+from ares.modules.base import BaseModule+++class BaseCloudModule(BaseModule):+ """Base class for all cloud reconnaissance and attack modules."""++ MODULE_CATEGORY = "cloud"diff --git a/ares/modules/cloud/gcp.py b/ares/modules/cloud/gcp.pyindex 430bce6..8331c23 100644--- a/ares/modules/cloud/gcp.py+++ b/ares/modules/cloud/gcp.py@@ -123,6 +123,8 @@ class GCPModule(BaseModule):"GOOGLE_APPLICATION_CREDENTIALS environment variable.",module_id=self.MODULE_ID, field="project_id",)+ if pdict.get("project_id"):+ self.validate_cloud_scope(pdict.get("project_id"), "gcp")async def execute(self, ctx: "Any") -> "ModuleResult":"""ExecutionContext-based entry point (v0.9.0+).@@ -229,6 +231,9 @@ class GCPModule(BaseModule):# Note: before_request() intentionally not called - cloud modules use# API credentials, not host IPs. Scope check (CIDR) does not apply to# cloud API endpoints. Rate limiting and jitter are handled at the API call level.+ if project_id:+ self.validate_cloud_scope(project_id, "gcp")+logger.info("gcp_recon_start", project_id=project_id)try:credentials = _get_gcp_credentials(credentials_file)diff --git a/tests/unit/test_cloud_scope_guard.py b/tests/unit/test_cloud_scope_guard.pynew file mode 100644index 0000000..3bad7d8--- /dev/null+++ b/tests/unit/test_cloud_scope_guard.py@@ -0,0 +1,181 @@+"""+Unit tests for CloudScopeGuard and CloudScope campaign validation.+Covers MOD-053 and MOD-063 architectural gap closure.+"""+import pytest+from unittest.mock import AsyncMock, MagicMock, patch++from ares.core.campaign import Campaign, Severity+from ares.core.errors import ScopeViolationError+from ares.core.scope import CloudScope, CampaignScope+from ares.modules.base import BaseModule, OpsecLevel+from ares.core.config import AresSettings+from ares.core.noise import NoiseController+++class DummyCloudModule(BaseModule):+ MODULE_ID = "test.cloud"+ MODULE_NAME = "Test Cloud Module"+ MODULE_CATEGORY = "cloud"+ MODULE_DESCRIPTION = "Dummy cloud module for unit tests"+++def dummy_settings():+ return AresSettings()+++def dummy_noise():+ return MagicMock(spec=NoiseController)+++class TestCloudScopeDataclass:+ def test_unconfigured_provider_is_permissive(self):+ """When an identifier list is empty, any identifier is authorized (backward compatible)."""+ scope = CloudScope()+ assert scope.is_authorized("123456789012", "aws") is True+ assert scope.is_authorized("sub-uuid-1", "azure") is True+ assert scope.is_authorized("tenant-uuid-1", "azure_ad") is True+ assert scope.is_authorized("my-gcp-project", "gcp") is True++ def test_empty_or_blank_identifier_is_rejected(self):+ scope = CloudScope(aws_account_ids=["123456789012"])+ assert scope.is_authorized("", "aws") is False+ assert scope.is_authorized(" ", "aws") is False++ def test_configured_provider_enforces_whitelist(self):+ scope = CloudScope(+ aws_account_ids=["111122223333", "444455556666"],+ azure_subscription_ids=["sub-alpha", "sub-beta"],+ azure_tenant_ids=["tenant-corp-1"],+ gcp_project_ids=["prod-security-01"],+ )+ # Authorized+ assert scope.is_authorized("111122223333", "aws") is True+ assert scope.is_authorized("444455556666", "aws") is True+ assert scope.is_authorized("sub-alpha", "azure") is True+ assert scope.is_authorized("tenant-corp-1", "azure_ad") is True+ assert scope.is_authorized("prod-security-01", "gcp") is True++ # Unauthorized+ assert scope.is_authorized("999999999999", "aws") is False+ assert scope.is_authorized("sub-rogue", "azure") is False+ assert scope.is_authorized("tenant-attacker", "azure_ad") is False+ assert scope.is_authorized("victim-project", "gcp") is False+++class TestCampaignCloudScopeIntegration:+ def test_campaign_default_cloud_scope(self):+ campaign = Campaign(name="Test Campaign")+ assert isinstance(campaign.cloud_scope, CloudScope)+ assert campaign.cloud_scope.aws_account_ids == []+ # Test .scope.cloud_scope proxy compatibility+ assert hasattr(campaign.scope, "cloud_scope")+ assert campaign.scope.cloud_scope is campaign.cloud_scope++ def test_campaign_custom_cloud_scope(self):+ cloud_scope = CloudScope(aws_account_ids=["123456789012"])+ campaign = Campaign(name="SecOps AWS", cloud_scope=cloud_scope)+ assert campaign.cloud_scope.aws_account_ids == ["123456789012"]+ assert campaign.scope.cloud_scope.aws_account_ids == ["123456789012"]+++class TestBaseModuleCloudScopeValidation:+ def test_validate_cloud_scope_unconfigured_passes(self, dummy_settings, dummy_noise):+ campaign = Campaign(name="Unrestricted Campaign")+ module = DummyCloudModule(dummy_settings, campaign, dummy_noise)++ # Should pass without raising+ module.validate_cloud_scope("123456789012", "aws")+ module.validate_cloud_scope("sub-id", "azure")+ module.validate_cloud_scope("tenant-id", "azure_ad")+ module.validate_cloud_scope("project-id", "gcp")++ def test_validate_cloud_scope_authorized_passes(self, dummy_settings, dummy_noise):+ cloud_scope = CloudScope(+ aws_account_ids=["123456789012"],+ azure_subscription_ids=["sub-allowed"],+ )+ campaign = Campaign(name="Restricted Campaign", cloud_scope=cloud_scope)+ module = DummyCloudModule(dummy_settings, campaign, dummy_noise)++ module.validate_cloud_scope("123456789012", "aws")+ module.validate_cloud_scope("sub-allowed", "azure")++ def test_validate_cloud_scope_unauthorized_raises_scope_violation(self, dummy_settings, dummy_noise):+ cloud_scope = CloudScope(+ aws_account_ids=["123456789012"],+ azure_subscription_ids=["sub-allowed"],+ azure_tenant_ids=["tenant-allowed"],+ gcp_project_ids=["proj-allowed"],+ )+ campaign = Campaign(name="Restricted Campaign", cloud_scope=cloud_scope)+ module = DummyCloudModule(dummy_settings, campaign, dummy_noise)++ with pytest.raises(ScopeViolationError) as exc_aws:+ module.validate_cloud_scope("999999999999", "aws")+ assert "Cloud aws identifier '999999999999' is not in authorized campaign scope" in str(exc_aws.value)++ with pytest.raises(ScopeViolationError) as exc_azure:+ module.validate_cloud_scope("sub-unauthorized", "azure")+ assert "Cloud azure identifier" in str(exc_azure.value)++ with pytest.raises(ScopeViolationError) as exc_tenant:+ module.validate_cloud_scope("tenant-unauthorized", "azure_ad")+ assert "Cloud azure_ad identifier" in str(exc_tenant.value)++ with pytest.raises(ScopeViolationError) as exc_gcp:+ module.validate_cloud_scope("proj-unauthorized", "gcp")+ assert "Cloud gcp identifier" in str(exc_gcp.value)+++class TestCloudModulesEnforcement:+ async def test_aws_recon_scope_enforcement(self, dummy_settings, dummy_noise):+ from ares.modules.cloud.aws import AWSEnumModule++ cloud_scope = CloudScope(aws_account_ids=["111111111111"])+ campaign = Campaign(name="AWS Restricted", cloud_scope=cloud_scope)+ mod = AWSEnumModule(dummy_settings, campaign, dummy_noise)++ # Mock session & STS to return an unauthorized account ID+ mock_sts = MagicMock()+ mock_sts.get_caller_identity.return_value = {"Account": "999999999999", "Arn": "arn:aws:iam::999999999999:user/test"}+ mock_session = MagicMock()+ mock_session.client.return_value = mock_sts++ with patch.object(mod, "_make_session", return_value=mock_session):+ with pytest.raises(ScopeViolationError):+ await mod.run(access_key="fake", secret_key="fake")++ async def test_azure_recon_scope_enforcement(self, dummy_settings, dummy_noise):+ from ares.modules.cloud.azure import AzureModule++ cloud_scope = CloudScope(azure_subscription_ids=["sub-authorized"])+ campaign = Campaign(name="Azure Restricted", cloud_scope=cloud_scope)+ mod = AzureModule(dummy_settings, campaign, dummy_noise)++ # Unauthorized subscription ID must raise ScopeViolationError+ with pytest.raises(ScopeViolationError):+ await mod.run(subscription_id="sub-unauthorized")++ async def test_azure_ad_scope_enforcement(self, dummy_settings, dummy_noise):+ from ares.modules.cloud.azure_ad import AzureADModule++ cloud_scope = CloudScope(azure_tenant_ids=["tenant-corp-uuid"])+ campaign = Campaign(name="Entra Restricted", cloud_scope=cloud_scope)+ mod = AzureADModule(dummy_settings, campaign, dummy_noise)++ with pytest.raises(ScopeViolationError):+ await mod.run(tenant_id="tenant-attacker-uuid")++ async def test_gcp_recon_scope_enforcement(self, dummy_settings, dummy_noise):+ from ares.modules.cloud.gcp import GCPModule++ cloud_scope = CloudScope(gcp_project_ids=["gcp-corp-project"])+ campaign = Campaign(name="GCP Restricted", cloud_scope=cloud_scope)+ mod = GCPModule(dummy_settings, campaign, dummy_noise)++ with pytest.raises(ScopeViolationError):+ await mod.run(project_id="gcp-rogue-project")