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.

feat(modules): modernize Wave 9 cloud & identity federation modules to Next-Gen Sovereign SDK v2

Mafifrizie98c4e1744be
diff --git a/ares/modules/cloud/aws.py b/ares/modules/cloud/aws.py
index 7805266..161f914 100644
--- a/ares/modules/cloud/aws.py
+++ b/ares/modules/cloud/aws.py
@@ -9,10 +9,27 @@ logger = get_logger("ares.modules.cloud.aws")
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.modules.params import AWSParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
SENSITIVE_PORTS = {22:"SSH",23:"Telnet",3389:"RDP",1433:"MSSQL",3306:"MySQL",
5432:"PostgreSQL",27017:"MongoDB",6379:"Redis",9200:"Elasticsearch"}
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.aws", failure_threshold=5),
+ params_model=AWSParams,
+)
class AWSEnumModule(BaseModule):
"""
cloud.aws — IAM enum, S3 misconfig, IMDS check, Security Group audit
@@ -26,6 +43,7 @@ class AWSEnumModule(BaseModule):
MODULE_AUTHOR = "ARES Team <[email protected]>"
OPSEC_LEVEL=OpsecLevel.LOW; REQUIRES=[]; OUTPUTS=["aws_findings"]
MITRE_TECHNIQUES=["T1526","T1530","T1552.005","T1580"]
+ PARAMS_MODEL = AWSParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
@@ -34,8 +52,15 @@ class AWSEnumModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AWSParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
# Cloud modules need AWS credentials — check at least one method available
- has_key = bool(ctx.params.get("access_key") or ctx.params.get("aws_profile"))
+ has_key = bool(pdict.get("access_key") or pdict.get("profile") or pdict.get("aws_profile"))
has_env = bool(__import__("os").environ.get("AWS_ACCESS_KEY_ID"))
if not has_key and not has_env:
raise ModuleValidationError(
@@ -50,13 +75,58 @@ class AWSEnumModule(BaseModule):
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True})
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AWSParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ raw_sec = pdict.get("secret_key")
+ if hasattr(raw_sec, "get_secret_value"):
+ secret_key = raw_sec.get_secret_value()
+ elif raw_sec is not None:
+ secret_key = str(raw_sec)
+ else:
+ secret_key = None
+
+ raw_tok = pdict.get("session_token")
+ if hasattr(raw_tok, "get_secret_value"):
+ session_token = raw_tok.get_secret_value()
+ elif raw_tok is not None:
+ session_token = str(raw_tok)
+ else:
+ session_token = None
+
findings, raw = await self.run(
- profile=ctx.params.get("profile"),
- access_key=ctx.params.get("access_key"),
- secret_key=ctx.params.get("secret_key"),
- session_token=ctx.params.get("session_token"),
- region=ctx.params.get("region", "us-east-1"),
+ profile=pdict.get("profile"),
+ access_key=pdict.get("access_key"),
+ secret_key=secret_key,
+ session_token=session_token,
+ region=pdict.get("region") or "us-east-1",
)
+
+ # Cryptographic Evidence Records with SHA-256 Merkle Provenance
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"aws-{pdict.get('region', 'us-east-1')}-{finding.mitre_technique}",
+ source_target=f"aws:{pdict.get('region', 'us-east-1')}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "aws", "recon"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
return ModuleResult(
status="success" if (findings or raw) else "partial",
findings=findings, raw=raw, module_id=self.MODULE_ID,
diff --git a/ares/modules/cloud/aws_privesc.py b/ares/modules/cloud/aws_privesc.py
index 5f5639c..6a4139d 100644
--- a/ares/modules/cloud/aws_privesc.py
+++ b/ares/modules/cloud/aws_privesc.py
@@ -18,6 +18,15 @@ from ares.core.logger import get_logger
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.modules.params import AWSPrivescParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.cloud.aws_privesc")
@@ -42,6 +51,14 @@ _PRIVESC_ACTIONS: list[tuple[str, str, str]] = [
]
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.aws_privesc", failure_threshold=5),
+ params_model=AWSPrivescParams,
+)
class AWSPrivescModule(BaseModule):
"""
cloud.aws_privesc — Enumerate current IAM permissions and identify privilege escalation paths — PassRole abuse, Assu
@@ -62,6 +79,7 @@ class AWSPrivescModule(BaseModule):
REQUIRES = []
OUTPUTS = ["aws_privesc_paths", "aws_findings"]
MITRE_TECHNIQUES = ["T1078.004", "T1548", "T1098"]
+ PARAMS_MODEL = AWSPrivescParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
@@ -70,8 +88,16 @@ class AWSPrivescModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
- has_key = bool(ctx.params.get("access_key") or
- ctx.params.get("aws_access_key") or
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AWSPrivescParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+ has_key = bool(pdict.get("access_key") or
+ pdict.get("aws_access_key") or
+ pdict.get("profile") or
__import__("os").environ.get("AWS_ACCESS_KEY_ID"))
if not has_key:
raise ModuleValidationError(
@@ -87,10 +113,62 @@ class AWSPrivescModule(BaseModule):
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})
- findings, raw = await self.run(**ctx.params)
- return ModuleResult(status="success" if (findings or raw.get("privesc_paths")) else "partial",
- findings=findings, raw=raw, module_id=self.MODULE_ID,
- execution_id=getattr(ctx, "execution_id", ""))
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AWSPrivescParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ raw_sec = pdict.get("secret_key")
+ if hasattr(raw_sec, "get_secret_value"):
+ secret_key = raw_sec.get_secret_value()
+ elif raw_sec is not None:
+ secret_key = str(raw_sec)
+ else:
+ secret_key = None
+
+ raw_tok = pdict.get("session_token")
+ if hasattr(raw_tok, "get_secret_value"):
+ session_token = raw_tok.get_secret_value()
+ elif raw_tok is not None:
+ session_token = str(raw_tok)
+ else:
+ session_token = None
+
+ findings, raw = await self.run(
+ profile=pdict.get("profile"),
+ access_key=pdict.get("access_key") or pdict.get("aws_access_key"),
+ secret_key=secret_key,
+ session_token=session_token,
+ region=pdict.get("region") or pdict.get("aws_region") or "us-east-1",
+ )
+
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"aws-privesc-{pdict.get('region', 'us-east-1')}-{finding.mitre_technique}",
+ source_target=f"aws:{pdict.get('region', 'us-east-1')}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "aws", "privesc"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
+ return ModuleResult(
+ status="success" if (findings or raw.get("privesc_paths")) else "partial",
+ findings=findings, raw=raw, module_id=self.MODULE_ID,
+ execution_id=getattr(ctx, "execution_id", ""),
+ )
@trace_module("cloud.aws_privesc")
async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
diff --git a/ares/modules/cloud/azure.py b/ares/modules/cloud/azure.py
index 7a0d118..8557d25 100644
--- a/ares/modules/cloud/azure.py
+++ b/ares/modules/cloud/azure.py
@@ -24,6 +24,15 @@ logger = get_logger("ares.modules.cloud.azure")
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.modules.params import AzureParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
_SENSITIVE_PORTS: set[int] = {22, 23, 3389, 5985, 5986, 1433, 3306, 5432,
6379, 9200, 27017, 445, 135, 2375, 2376}
@@ -37,6 +46,14 @@ def _get_credential(tenant_id=None, client_id=None, client_secret=None):
return DefaultAzureCredential()
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.azure", failure_threshold=5),
+ params_model=AzureParams,
+)
class AzureModule(BaseModule):
"""
cloud.azure — AAD enum, storage misconfig, RBAC audit, NSG rules
@@ -54,6 +71,7 @@ class AzureModule(BaseModule):
REQUIRES = []
OUTPUTS = ["azure_findings"]
MITRE_TECHNIQUES = ["T1526", "T1530", "T1580", "T1078.004"]
+ PARAMS_MODEL = AzureParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
@@ -62,8 +80,15 @@ class AzureModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
- has_cred = bool(ctx.params.get("subscription_id") or
- ctx.params.get("client_id") or
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AzureParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+ has_cred = bool(pdict.get("subscription_id") or
+ pdict.get("client_id") or
__import__("os").environ.get("AZURE_CLIENT_ID"))
if not has_cred:
raise ModuleValidationError(
@@ -79,10 +104,55 @@ class AzureModule(BaseModule):
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})
- findings, raw = await self.run(**ctx.params)
- return ModuleResult(status="success" if (findings or raw) else "partial",
- findings=findings, raw=raw, module_id=self.MODULE_ID,
- execution_id=getattr(ctx, "execution_id", ""))
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AzureParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ raw_sec = pdict.get("client_secret")
+ if hasattr(raw_sec, "get_secret_value"):
+ client_secret = raw_sec.get_secret_value()
+ elif raw_sec is not None:
+ client_secret = str(raw_sec)
+ else:
+ client_secret = None
+
+ subscription_id = pdict.get("subscription_id") or ""
+
+ findings, raw = await self.run(
+ subscription_id=subscription_id,
+ tenant_id=pdict.get("tenant_id"),
+ client_id=pdict.get("client_id"),
+ client_secret=client_secret,
+ )
+
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"azure-{subscription_id[:8]}-{finding.mitre_technique}",
+ source_target=f"azure:{subscription_id[:8]}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "azure", "recon"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
+ return ModuleResult(
+ status="success" if (findings or raw) else "partial",
+ findings=findings, raw=raw, module_id=self.MODULE_ID,
+ execution_id=getattr(ctx, "execution_id", ""),
+ )
@trace_module("cloud.azure")
async def run(self, subscription_id: str, tenant_id: str | None = None,
diff --git a/ares/modules/cloud/azure_ad.py b/ares/modules/cloud/azure_ad.py
index f4cac86..68897a6 100644
--- a/ares/modules/cloud/azure_ad.py
+++ b/ares/modules/cloud/azure_ad.py
@@ -28,6 +28,15 @@ from ares.core.campaign import Finding, Severity
from ares.core.logger import audit, get_logger
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.modules.params import AzureADParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
logger = get_logger("ares.modules.cloud.azure_ad")
@@ -46,6 +55,14 @@ _ENUM_SCOPES = [
]
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.azure_ad", failure_threshold=5),
+ params_model=AzureADParams,
+)
class AzureADModule(BaseModule):
"""
cloud.azure_ad — Azure AD / Entra ID identity attack techniques: device code flow, service principal exposure.
@@ -67,6 +84,7 @@ class AzureADModule(BaseModule):
REQUIRES = []
OUTPUTS = ["access_tokens", "azure_ad_findings"]
MITRE_TECHNIQUES = ["T1528", "T1606"]
+ PARAMS_MODEL = AzureADParams
async def validate(self, ctx: "Any") -> None:
await super().validate(ctx)
@@ -74,7 +92,14 @@ class AzureADModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
- tenant_id = ctx.params.get("tenant_id", "")
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AzureADParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+ tenant_id = pdict.get("tenant_id", "")
if not tenant_id:
raise ModuleValidationError(
"cloud.azure_ad requires 'tenant_id' — Azure AD tenant ID (UUID). "
@@ -91,16 +116,58 @@ class AzureADModule(BaseModule):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True})
- tenant_id = ctx.params.get("tenant_id", "")
- client_id = ctx.params.get("client_id", "")
- client_secret = ctx.params.get("client_secret", "")
- access_token = ctx.params.get("access_token", "")
- technique = ctx.params.get("technique", "enumerate") # enumerate|device_code|sp_audit
+ params = getattr(ctx, "params", {})
+ if isinstance(params, AzureADParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ tenant_id = pdict.get("tenant_id", "")
+ client_id = pdict.get("client_id", "")
+
+ raw_sec = pdict.get("client_secret")
+ if hasattr(raw_sec, "get_secret_value"):
+ client_secret = raw_sec.get_secret_value()
+ elif raw_sec is not None:
+ client_secret = str(raw_sec)
+ else:
+ client_secret = ""
+
+ raw_tok = pdict.get("access_token")
+ if hasattr(raw_tok, "get_secret_value"):
+ access_token = raw_tok.get_secret_value()
+ elif raw_tok is not None:
+ access_token = str(raw_tok)
+ else:
+ access_token = ""
+
+ technique = pdict.get("technique", "enumerate")
findings, raw = await self.run(
tenant_id=tenant_id, client_id=client_id, client_secret=client_secret,
access_token=access_token, technique=technique,
)
+
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"azure-ad-{str(tenant_id)[:8]}-{finding.mitre_technique}",
+ source_target=f"azure_ad:{str(tenant_id)[:8]}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "azure_ad", "identity"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
return ModuleResult(
status="success" if (findings or raw) else "partial",
findings=findings, raw=raw, module_id=self.MODULE_ID,
diff --git a/ares/modules/cloud/gcp.py b/ares/modules/cloud/gcp.py
index 9168f44..49a416f 100644
--- a/ares/modules/cloud/gcp.py
+++ b/ares/modules/cloud/gcp.py
@@ -32,6 +32,15 @@ logger = get_logger("ares.modules.cloud.gcp")
from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel
from ares.core.tracing import trace_module
+from ares.modules.params import GCPParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
_SA_KEY_MAX_AGE_DAYS = 90 # Keys older than this are flagged
_PUBLIC_MEMBERS = frozenset({"allUsers", "allAuthenticatedUsers"})
@@ -52,6 +61,14 @@ def _get_gcp_credentials(credentials_file: str | None = None) -> "Any":
return credentials
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.gcp", failure_threshold=5),
+ params_model=GCPParams,
+)
class GCPModule(BaseModule):
"""
cloud.gcp — IAM bindings, GCS misconfig, SA key audit, metadata server
@@ -69,6 +86,7 @@ class GCPModule(BaseModule):
REQUIRES = []
OUTPUTS = ["gcp_findings"]
MITRE_TECHNIQUES = ["T1526", "T1530", "T1552.005", "T1580"]
+ PARAMS_MODEL = GCPParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight param checks before any network call."""
@@ -77,8 +95,15 @@ class GCPModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
- has_cred = bool(ctx.params.get("project_id") or
- ctx.params.get("credentials_file") or
+ params = getattr(ctx, "params", {})
+ if isinstance(params, GCPParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+ has_cred = bool(pdict.get("project_id") or
+ pdict.get("credentials_file") or
__import__("os").environ.get("GOOGLE_APPLICATION_CREDENTIALS"))
if not has_cred:
raise ModuleValidationError(
@@ -94,10 +119,46 @@ class GCPModule(BaseModule):
from ares.modules.base import ModuleResult
if getattr(ctx, "dry_run", False):
return ModuleResult(status="dry_run", module_id=self.MODULE_ID, raw={"dry_run": True})
- findings, raw = await self.run(**ctx.params)
- return ModuleResult(status="success" if (findings or raw) else "partial",
- findings=findings, raw=raw, module_id=self.MODULE_ID,
- execution_id=getattr(ctx, "execution_id", ""))
+
+ params = getattr(ctx, "params", {})
+ if isinstance(params, GCPParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ project_id = pdict.get("project_id") or ""
+ credentials_file = pdict.get("credentials_file")
+
+ findings, raw = await self.run(
+ project_id=project_id,
+ credentials_file=credentials_file,
+ )
+
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"gcp-{project_id[:8]}-{finding.mitre_technique}",
+ source_target=f"gcp:{project_id[:8]}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "gcp", "recon"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
+ return ModuleResult(
+ status="success" if (findings or raw) else "partial",
+ findings=findings, raw=raw, module_id=self.MODULE_ID,
+ execution_id=getattr(ctx, "execution_id", ""),
+ )
@trace_module("cloud.gcp")
async def run(self, project_id: str, credentials_file: str | None = None,
diff --git a/ares/modules/cloud/identity_federation.py b/ares/modules/cloud/identity_federation.py
index c47ea68..17f14fb 100644
--- a/ares/modules/cloud/identity_federation.py
+++ b/ares/modules/cloud/identity_federation.py
@@ -34,6 +34,15 @@ from ares.core.campaign import Finding, Severity
from ares.modules.base import BaseModule, OpsecLevel, ModuleResult
from ares.core.tracing import trace_module
from ares.core.security import sanitize_hostname
+from ares.modules.params import CloudFederationParams
+from ares.sdk import (
+ CircuitBreaker,
+ EvidenceRecord,
+ ExecutionContext,
+ NetworkPermission,
+ ProcessPermission,
+ module_contract,
+)
if TYPE_CHECKING:
pass
@@ -41,6 +50,14 @@ if TYPE_CHECKING:
logger = get_logger("ares.modules.cloud.identity_federation")
+@module_contract(
+ permissions=[
+ NetworkPermission(ports=[80, 443], protocols=["tcp"]),
+ ProcessPermission(allow_subprocesses=False),
+ ],
+ circuit_breaker=CircuitBreaker(name="cloud.identity_federation_abuse", failure_threshold=5),
+ params_model=CloudFederationParams,
+)
class CloudIdentityFederationModule(BaseModule):
"""
cloud.identity_federation_abuse — Cross-cloud identity federation enumeration and abuse.
@@ -60,6 +77,7 @@ class CloudIdentityFederationModule(BaseModule):
OUTPUTS = ["federation_trusts", "golden_saml_paths", "oauth_tokens", "pivot_paths"]
MITRE_TECHNIQUES = ["T1606.002", "T1528", "T1550.001", "T1484.002"]
MODULE_TIMEOUT_SECONDS: int | None = 300
+ PARAMS_MODEL = CloudFederationParams
async def validate(self, ctx: "Any") -> None:
"""Pre-flight: need at least one cloud or AD credential."""
@@ -68,11 +86,18 @@ class CloudIdentityFederationModule(BaseModule):
from ares.core.errors import ModuleValidationError
if not isinstance(ctx, ExecutionContext):
return
- has_azure = bool(ctx.params.get("tenant_id") or ctx.params.get("client_id"))
- has_aws = bool(ctx.params.get("access_key") or
+ params = getattr(ctx, "params", {})
+ if isinstance(params, CloudFederationParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+ has_azure = bool(pdict.get("tenant_id") or pdict.get("client_id"))
+ has_aws = bool(pdict.get("access_key") or
__import__("os").environ.get("AWS_ACCESS_KEY_ID"))
- has_ad = bool(ctx.params.get("adfs_url") or ctx.params.get("krbtgt_hash"))
- has_google = bool(ctx.params.get("project_id") or ctx.params.get("credentials_file"))
+ has_ad = bool(pdict.get("adfs_url") or pdict.get("krbtgt_hash"))
+ has_google = bool(pdict.get("project_id") or pdict.get("credentials_file"))
if not any([has_azure, has_aws, has_ad, has_google]):
raise ModuleValidationError(
"cloud.identity_federation_abuse requires at least one credential: "
@@ -90,24 +115,81 @@ class CloudIdentityFederationModule(BaseModule):
status="dry_run", module_id=self.MODULE_ID,
raw={"dry_run": True, "mode": ctx.params.get("mode", "enumerate")},
)
- params = dict(ctx.params)
- for key in (
+ params = getattr(ctx, "params", {})
+ if isinstance(params, CloudFederationParams):
+ pdict = params.model_dump()
+ elif isinstance(params, dict):
+ pdict = dict(params)
+ else:
+ pdict = {}
+
+ raw_cs = pdict.get("client_secret")
+ if hasattr(raw_cs, "get_secret_value"):
+ client_secret = raw_cs.get_secret_value()
+ elif raw_cs is not None:
+ client_secret = str(raw_cs)
+ else:
+ client_secret = ""
+
+ raw_sk = pdict.get("secret_key")
+ if hasattr(raw_sk, "get_secret_value"):
+ secret_key = raw_sk.get_secret_value()
+ elif raw_sk is not None:
+ secret_key = str(raw_sk)
+ else:
+ secret_key = ""
+
+ raw_kt = pdict.get("krbtgt_hash")
+ if hasattr(raw_kt, "get_secret_value"):
+ krbtgt_hash = raw_kt.get_secret_value()
+ elif raw_kt is not None:
+ krbtgt_hash = str(raw_kt)
+ else:
+ krbtgt_hash = ""
+
+ tenant_id = pdict.get("tenant_id") or ""
+ client_id = pdict.get("client_id") or ""
+ access_key = pdict.get("access_key") or ""
+ adfs_url = pdict.get("adfs_url") or ""
+ domain = pdict.get("domain") or ""
+ mode = pdict.get("mode") or "enumerate"
+
+ extra = {k: v for k, v in pdict.items() if k not in (
"tenant_id", "client_id", "client_secret", "access_key", "secret_key",
"adfs_url", "krbtgt_hash", "domain", "mode",
- ):
- params.pop(key, None)
+ )}
+
findings, raw = await self.run(
- tenant_id=ctx.params.get("tenant_id", ""),
- client_id=ctx.params.get("client_id", ""),
- client_secret=ctx.params.get("client_secret", ""),
- access_key=ctx.params.get("access_key", ""),
- secret_key=ctx.params.get("secret_key", ""),
- adfs_url=ctx.params.get("adfs_url", ""),
- krbtgt_hash=ctx.params.get("krbtgt_hash", ""),
- domain=ctx.params.get("domain", ""),
- mode=ctx.params.get("mode", "enumerate"),
- **params,
+ tenant_id=tenant_id,
+ client_id=client_id,
+ client_secret=client_secret,
+ access_key=access_key,
+ secret_key=secret_key,
+ adfs_url=adfs_url,
+ krbtgt_hash=krbtgt_hash,
+ domain=domain,
+ mode=mode,
+ **extra,
)
+
+ evidence_chain: list[EvidenceRecord] = []
+ for finding in findings:
+ ev = EvidenceRecord(
+ artifact_id=f"cloud-federation-{finding.mitre_technique}",
+ source_target=f"federation:{domain or tenant_id or 'hybrid'}",
+ collected_by=self.MODULE_ID,
+ data={
+ "title": finding.title,
+ "severity": str(finding.severity),
+ "technique": finding.mitre_technique,
+ },
+ tags=["cloud", "federation", "saml", "oidc"],
+ )
+ evidence_chain.append(ev)
+
+ raw["evidence_chain"] = [e.data for e in evidence_chain]
+ raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]
+
return ModuleResult(
status="success" if findings else "partial",
findings=findings, raw=raw, module_id=self.MODULE_ID,
diff --git a/tests/unit/test_module_execute_adapters.py b/tests/unit/test_module_execute_adapters.py
index 2fb29cd..f7ccb28 100644
--- a/tests/unit/test_module_execute_adapters.py
+++ b/tests/unit/test_module_execute_adapters.py
@@ -333,6 +333,90 @@ def _ctx(params: dict[str, Any]) -> SimpleNamespace:
"auto_approve": False,
},
),
+ (
+ "ares.modules.cloud.aws",
+ "AWSEnumModule",
+ {
+ "profile": "prod",
+ "access_key": "AKIAIOSFODNN7EXAMPLE",
+ "region": "us-west-2",
+ },
+ {
+ "profile": "prod",
+ "access_key": "AKIAIOSFODNN7EXAMPLE",
+ "region": "us-west-2",
+ },
+ ),
+ (
+ "ares.modules.cloud.aws_privesc",
+ "AWSPrivescModule",
+ {
+ "profile": "prod",
+ "access_key": "AKIAIOSFODNN7EXAMPLE",
+ "region": "us-west-2",
+ },
+ {
+ "profile": "prod",
+ "access_key": "AKIAIOSFODNN7EXAMPLE",
+ "region": "us-west-2",
+ },
+ ),
+ (
+ "ares.modules.cloud.azure",
+ "AzureModule",
+ {
+ "subscription_id": "00000000-0000-0000-0000-000000000000",
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ },
+ {
+ "subscription_id": "00000000-0000-0000-0000-000000000000",
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ },
+ ),
+ (
+ "ares.modules.cloud.azure_ad",
+ "AzureADModule",
+ {
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ "technique": "enumerate",
+ },
+ {
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ "technique": "enumerate",
+ },
+ ),
+ (
+ "ares.modules.cloud.gcp",
+ "GCPModule",
+ {
+ "project_id": "corp-cloud-prod",
+ "credentials_file": "/tmp/sa.json",
+ },
+ {
+ "project_id": "corp-cloud-prod",
+ "credentials_file": "/tmp/sa.json",
+ },
+ ),
+ (
+ "ares.modules.cloud.identity_federation",
+ "CloudIdentityFederationModule",
+ {
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ "domain": "corp.local",
+ "mode": "enumerate",
+ },
+ {
+ "tenant_id": "11111111-1111-1111-1111-111111111111",
+ "client_id": "22222222-2222-2222-2222-222222222222",
+ "domain": "corp.local",
+ "mode": "enumerate",
+ },
+ ),
],
)
def test_execute_adapter_deduplicates_explicit_ctx_params(