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.

14.2 KB
Raw Blame
"""
cloud.phantom_token - Hybrid Entra ID & Primary Refresh Token (PRT) Hijack
MITRE ATT&CK:
  T1528 - Steal Application Access Token
  T1606 - Forge Web Credentials

Autonomous adversary emulation vector for hybrid cloud environments:
  1. Inspects Windows endpoint session artifacts for Primary Refresh Token (PRT) state.
  2. Evaluates token claims (device compliance, MFA satisfaction, tenant boundaries).
  3. Brokers authenticated session requests to Microsoft Graph / Azure AD endpoints.
  4. Bypasses standard Conditional Access Policies (CAP) and legacy MFA gates.

Designed for authorized enterprise security validation within strict ARES boundaries.
"""
from __future__ import annotations

import hashlib
from typing import Any

from ares.core.campaign import Finding, Severity
from ares.core.errors import ModuleError, ModuleValidationError
from ares.core.logger import audit, get_logger
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, ModuleResult, OpsecLevel
from ares.modules.params import PhantomTokenParams
from ares.sdk import (
    CircuitBreaker,
    EvidenceRecord,
    ExecutionContext,
    NetworkPermission,
    ProcessPermission,
    module_contract,
)

logger = get_logger("ares.modules.cloud.phantom_token")


# ── 2. Enterprise Class-Based Module ──────────────────────────────────────────

@module_contract(
    permissions=[
        NetworkPermission(ports=[443], protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=CircuitBreaker(name="cloud.phantom_token", failure_threshold=5),
    params_model=PhantomTokenParams,
)
class PhantomTokenModule(BaseModule[PhantomTokenParams, ModuleResult]):
    """
    cloud.phantom_token - Hybrid Entra ID PRT extraction and cross-boundary session takeover.
    """
    MODULE_ID          = "cloud.phantom_token"
    MODULE_NAME        = "Hybrid Entra ID PRT Hijack"
    MODULE_CATEGORY    = "cloud"
    MODULE_DESCRIPTION = (
        "Simulates adversary lateral pivoting from compromised Windows workstations "
        "into Azure AD / Microsoft 365 by extracting and brokering Primary Refresh Token (PRT) sessions."
    )
    MODULE_AUTHOR      = "ARES Core Team <[email protected]>"
    OPSEC_LEVEL        = OpsecLevel.LOW
    REQUIRES           = []
    OUTPUTS            = ["cloud_sessions", "prt_artifacts", "findings"]
    MITRE_TECHNIQUES   = ["T1528", "T1606"]
    MODULE_TIMEOUT_SECONDS: int | None = 60
    PARAMS_MODEL       = PhantomTokenParams
    ENABLED            = False
    DISABLED_REASON    = (
        "module disabled: PRT hijack not implemented, synthetic token injection risk (MOD-049)"
    )

    async def assess_feasibility(self, ctx: Any) -> Any:
        from ares.modules.base import FeasibilityReport

        # MITIGATION (MOD-049): Module is temporarily disabled from execution pipeline.
        return FeasibilityReport(
            feasible=False,
            score=0.0,
            risk_level="high_noise",
            blockers=[self.DISABLED_REASON],
            recommended_alternatives=["cloud.azure_ad"],
            details={
                "disabled": True,
                "reason": self.DISABLED_REASON,
            },
        )

    async def validate(self, ctx: Any) -> None:
        # MITIGATION (MOD-049): Fail fast with explicit error before parameter checks
        raise ModuleValidationError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )

    async def execute(self, ctx: ExecutionContext[PhantomTokenParams]) -> ModuleResult:
        # MITIGATION (MOD-049): Disabled from execution pipeline to prevent fictitious findings
        # and vault contamination while final architectural decision is pending.
        raise ModuleError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )

    @trace_module("cloud.phantom_token")
    async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
        # MITIGATION (MOD-049): Disabled from execution pipeline to prevent fictitious findings
        # and vault contamination while final architectural decision is pending.
        raise ModuleError(
            self.DISABLED_REASON,
            module_id=self.MODULE_ID,
        )
        self._findings = []
        ctx = kwargs.get("ctx") or kwargs
        tenant_id = str(ctx.get("tenant_id") or ctx.get("target") or "")
        client_id = str(ctx.get("client_id") or "1fec8e78-bce4-4aaf-ab1b-1b619748b94f")
        session_cookie = ctx.get("session_cookie")
        scope = str(ctx.get("scope") or "https://graph.microsoft.com/.default")
        assessment_mode = ctx.get("assessment_mode") or "auto"
        dpop_enforced = bool(ctx.get("dpop_enforced", False))
        federation_issuer = ctx.get("federation_issuer")
        evaluate_cap_bypass = bool(ctx.get("evaluate_cap_bypass", True))
        generate_detection_rules = bool(ctx.get("generate_detection_rules", True))
        dry_run = bool(ctx.get("dry_run", False))

        mode = assessment_mode
        if mode == "auto":
            mode = "workload_identity" if federation_issuer else "prt_enclave"

        if dry_run:
            f = Finding(
                title=f"[DRY-RUN] Entra ID PRT Boundary Inspection: {tenant_id}",
                severity=Severity.INFO,
                description=(
                    f"Dry run assessment against tenant {tenant_id} with scope {scope} "
                    f"[Mode: {mode}, DPoP: {dpop_enforced}, CAE: Active]"
                ),
                mitre_technique="T1528",
                module_id=self.MODULE_ID,
                host=tenant_id,
            )
            return [f], {
                "tenant_id": tenant_id,
                "scope": scope,
                "assessment_mode": mode,
                "dry_run": True,
            }

        logger.info("phantom_token_execution_start", tenant=tenant_id, scope=scope, mode=mode)
        audit("cloud_prt_assessment", actor="operator", technique="T1528", source="ares", target=tenant_id)

        # 1. Inspect Token Claims and Hybrid Boundary
        simulated_device_id = f"dev-{hashlib.sha256(tenant_id.encode()).hexdigest()[:12]}"
        has_cookie = bool(session_cookie)
        dpop_status = "enforced" if dpop_enforced else "legacy_bearer"

        evidence = EvidenceRecord(
            artifact_id=f"ev-prt-{hashlib.sha256(tenant_id.encode()).hexdigest()[:8]}",
            source_target=tenant_id,
            collected_by=self.MODULE_ID,
            data={
                "tenant_id": tenant_id,
                "client_id": client_id,
                "device_id": simulated_device_id,
                "mfa_claim_present": True,
                "device_compliance_passed": True,
                "cookie_context_supplied": has_cookie,
                "assessment_mode": mode,
                "cae_evaluated": True,
                "dpop_status": dpop_status,
            },
            tags=["cloud", "entra_id", "prt", "token_hijack", mode],
        )

        # 2. Technique-Specific Finding Synthesis
        if mode == "workload_identity":
            issuer = federation_issuer or "https://token.actions.githubusercontent.com"
            finding = Finding(
                title=f"Entra ID Workload Identity Federation (WIF) Trust Boundary Compromise: {tenant_id}",
                severity=Severity.CRITICAL,
                description=(
                    f"Successfully validated secretless cross-boundary privilege escalation via Federated Identity Credentials (FIC) "
                    f"against tenant '{tenant_id}'. The target Service Principal trusts external OIDC authority '{issuer}' "
                    f"with overly permissive Subject matching claims, allowing unauthorized token minting without credentials."
                ),
                mitre_technique="T1528",
                mitre_tactic="Privilege Escalation",
                evidence={
                    "tenant": tenant_id,
                    "client_id": client_id,
                    "federation_issuer": issuer,
                    "evidence_hash": evidence.record_hash,
                    "cap_bypass": evaluate_cap_bypass,
                },
                remediation=(
                    "1. Pin exact Subject claims in Entra ID Federated Identity Credentials (e.g. repo:org/repo:ref:refs/heads/main). "
                    "2. Avoid wildcard or branch-level wildcards in OIDC trust definitions. "
                    "3. Restrict Service Principal roles to least-privilege Graph scopes."
                ),
                host=tenant_id,
                module_id=self.MODULE_ID,
            )
        else:
            finding = Finding(
                title=f"Entra ID Primary Refresh Token (PRT) Boundary Compromise: {tenant_id}",
                severity=Severity.CRITICAL,
                description=(
                    f"Successfully validated PRT token claim replay against tenant '{tenant_id}'. "
                    f"Adversary possessing this session artifact bypasses multi-factor authentication (MFA) "
                    f"and Conditional Access Policies (CAP) by inheriting compliant workstation identity. "
                    f"Verified Continuous Access Evaluation (CAE) tolerance and DPoP status: {dpop_status}."
                ),
                mitre_technique="T1528",
                mitre_tactic="Credential Access",
                evidence={
                    "tenant": tenant_id,
                    "client_id": client_id,
                    "device_id": simulated_device_id,
                    "evidence_hash": evidence.record_hash,
                    "cap_bypass": evaluate_cap_bypass,
                    "cae_tested": True,
                    "dpop_status": dpop_status,
                },
                remediation=(
                    "1. Enforce Phishing-Resistant MFA (FIDO2 / Windows Hello for Business) across all cloud identities. "
                    "2. Configure Continuous Access Evaluation (CAE) to immediately invalidate PRT on network location change. "
                    "3. Mandate RFC 9449 Demonstrating Proof-of-Possession (DPoP) for all high-value OAuth2 tokens. "
                    "4. Enable Entra ID Identity Protection sign-in risk policies for anomalous token replay."
                ),
                host=tenant_id,
                module_id=self.MODULE_ID,
            )

        # 3. Closed-Loop Purple Telemetry & Loot Construction
        loot_items: list[dict[str, Any]] = [
            {
                "name": f"Entra ID PRT Session: {tenant_id}",
                "loot_type": "cloud_prt_token",
                "description": f"Harvested Primary Refresh Token session context bypassing MFA/CAP for {tenant_id}",
                "content": {
                    "tenant_id": tenant_id,
                    "device_id": simulated_device_id,
                    "client_id": client_id,
                    "scope": scope,
                    "claims": ["User.Read.All", "Directory.Read.All"],
                    "mode": mode,
                },
                "tags": ["cloud", "entra_id", "prt", "token", mode],
            }
        ]

        if generate_detection_rules:
            kql_query = (
                f"// ARES Closed-Loop Telemetry: Detect Entra ID Non-Compliant Token & CAP Anomalies\n"
                f"SigninLogs\n"
                f"| where AppId =~ \"{client_id}\" or UserPrincipalName has \"{tenant_id}\"\n"
                f"| where ResultType in (50005, 53003) or ConditionalAccessStatus == \"failure\"\n"
                f"| project TimeGenerated, UserPrincipalName, AppDisplayName, IPAddress, ConditionalAccessStatus, ResultType\n"
            )
            sigma_rule = (
                f"title: Entra ID Anomalous Session Replay and CAP Bypass ({tenant_id})\n"
                f"id: a1b2c3d4-ares-entra-prt-{simulated_device_id[:8].lower()}\n"
                f"status: experimental\n"
                f"description: Detects anomalous PRT session replay with bypassed Conditional Access\n"
                f"logsource:\n"
                f"  product: azure\n"
                f"  service: signinlogs\n"
                f"detection:\n"
                f"  selection:\n"
                f"    AppId: '{client_id}'\n"
                f"    ResultType:\n"
                f"      - 50005 # Device not compliant\n"
                f"      - 53003 # Blocked by Conditional Access\n"
                f"  condition: selection\n"
                f"level: high\n"
                f"tags:\n"
                f"  - attack.credential_access\n"
                f"  - attack.t1528\n"
                f"  - attack.t1606\n"
            )
            loot_items.extend([
                {
                    "name": f"Detection Rule (KQL): Entra ID Token {tenant_id}",
                    "loot_type": "detection_rule_kql",
                    "description": "Auto-generated Microsoft Sentinel KQL query for detecting anomalous token replay",
                    "content": {"kql": kql_query, "target_tenant": tenant_id},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): Entra ID Token {tenant_id}",
                    "loot_type": "detection_rule_sigma",
                    "description": "Auto-generated Sigma YAML detection rule for Entra ID signin audit logs",
                    "content": {"sigma": sigma_rule},
                    "tags": ["detection", "sigma", "siem", "blue_team"],
                },
            ])

        raw_result = {
            "tenant_id": tenant_id,
            "device_id": simulated_device_id,
            "prt_valid": True,
            "mfa_bypassed": True,
            "cap_bypassed": evaluate_cap_bypass,
            "evidence_integrity": evidence.record_hash,
            "assessment_mode_applied": mode,
            "cae_handling_active": True,
            "dpop_status": dpop_status,
            "cloud_sessions": [
                {
                    "resource": "https://graph.microsoft.com",
                    "status": "authenticated",
                    "claims": ["User.Read.All", "Directory.Read.All"],
                }
            ],
            "loot": loot_items,
        }

        if hasattr(self, "noise") and getattr(self.noise, "jitter", None):
            await self.noise.jitter.sleep()

        return [finding], raw_result