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.

26.4 KB
Raw Blame
"""
GCP Recon & Attack Module - Production Implementation
IAM bindings, GCS buckets, service account keys, metadata server.

Authentication (automatic priority order):
  1. Service account key file - if credentials_file supplied
  2. Application Default Credentials (ADC) - env GOOGLE_APPLICATION_CREDENTIALS,
     gcloud auth, Workload Identity, or Compute Engine metadata server

Required API permissions (read-only):
  roles/viewer OR the following individual roles:
    resourcemanager.projects.getIamPolicy
    storage.buckets.list + storage.buckets.getIamPolicy
    iam.serviceAccountKeys.list
    compute.instances.list (for metadata server check)

Required optional extras:
    pip install ares-redteam[cloud]
    → google-cloud-resource-manager, google-cloud-iam, google-auth, httpx
"""
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ares.modules.base import ModuleResult


import asyncio
import datetime
from functools import partial
from typing import Any

from ares.core.logger import get_logger

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

from ares.core.campaign import Finding, Severity
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import GCPParams
from ares.sdk import (
    CircuitBreaker,
    EvidenceRecord,
    NetworkPermission,
    ProcessPermission,
    module_contract,
)

_SA_KEY_MAX_AGE_DAYS = 90   # Keys older than this are flagged
_PUBLIC_MEMBERS = frozenset({"allUsers", "allAuthenticatedUsers"})


def _get_gcp_credentials(credentials_file: str | None = None) -> "Any":
    """Return Google credentials - file or ADC."""
    if credentials_file:
        from google.oauth2 import service_account
        return service_account.Credentials.from_service_account_file(
            credentials_file,
            scopes=["https://www.googleapis.com/auth/cloud-platform.read-only"],
        )
    import google.auth
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform.read-only"]
    )
    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

    OPSEC: LOW
    MITRE: "T1526", "T1530", "T1552.005", "T1580"
    OUTPUTS:  "gcp_findings"
    """
    MODULE_ID          = "cloud.gcp"
    MODULE_NAME        = "GCP Recon & Attack"
    MODULE_CATEGORY    = "cloud"
    MODULE_DESCRIPTION = "IAM bindings, GCS misconfig, SA key audit, metadata server"
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL        = OpsecLevel.LOW
    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."""
        import importlib.util

        from ares.core.errors import ModuleValidationError

        try:
            spec = importlib.util.find_spec("google.cloud.resourcemanager")
        except (ModuleNotFoundError, ValueError):
            spec = None
        if spec is None:
            raise ModuleValidationError(
                f"{self.MODULE_ID} requires google.cloud.resourcemanager. Install with: pip install google-cloud-resource-manager",
                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, 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(
                "cloud.gcp requires GCP credentials - set project_id param or "
                "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":  # 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, 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]

        # Closed-Loop Purple Telemetry: KQL & Sigma rule synthesis
        gcp_target = project_id[:8] if project_id else "GCPProject"
        kql_query = (
            "// ARES Closed-Loop Telemetry: Detect GCP IAM Privilege Escalation & Service Account Key Creation\n"
            "// Monitors Google Cloud Audit Logs for SetIamPolicy or CreateServiceAccountKey\n"
            "GCPAuditLogs\n"
            "| where MethodName in~ (\"google.iam.admin.v1.CreateServiceAccountKey\", \"google.iam.admin.v1.SetIamPolicy\", \"google.cloud.resourcemanager.v3.Projects.SetIamPolicy\")\n"
            "| project TimeGenerated, PrincipalEmail, CallerIp, MethodName, ResourceName, Status\n"
        )
        sigma_rule = (
            f"title: GCP Service Account Key Creation & IAM Policy Modification ({gcp_target})\n"
            f"id: 0f1a2b3c-ares-gcp-{abs(hash(gcp_target)) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects creation of service account keys or modification of project IAM policies in GCP audit logs.\n"
            f"logsource:\n"
            f"  product: gcp\n"
            f"  service: gcp.audit\n"
            f"detection:\n"
            f"  selection:\n"
            f"    methodName:\n"
            f"      - 'google.iam.admin.v1.CreateServiceAccountKey'\n"
            f"      - 'google.iam.admin.v1.SetIamPolicy'\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): GCP IAM & Key Changes ({gcp_target})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting GCP service account key creation and IAM policy updates",
                    "content": {"kql": kql_query, "project": gcp_target},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): GCP IAM & Key Changes ({gcp_target})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for GCP service account key creation and IAM policy updates",
                    "content": {"sigma": sigma_rule, "project": gcp_target},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["service_account_keys_evaluated"] = True
        raw["gcp_iam_policy_bindings_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.gcp")
    async def run(self, project_id: str, credentials_file: str | None = None,
                  **kwargs: Any) -> tuple[list[Finding], dict[str, 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 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)
        except ImportError as exc:
            raise ImportError(
                "google-auth not installed. Run: pip install ares-redteam[cloud]"
            ) from exc

        loop = asyncio.get_running_loop()
        raw: dict[str, Any] = {"project_id": project_id}

        for label, fn in [
            ("iam",              partial(self._check_iam_bindings,       credentials, project_id)),
            ("gcs",              partial(self._check_gcs_buckets,        credentials, project_id)),
            ("service_accounts", partial(self._check_sa_keys,            credentials, project_id)),
        ]:
            await self.noise.rate_limiter.acquire("cloud_api")
            try:
                raw[label] = await loop.run_in_executor(None, fn)
            except Exception as exc:
                logger.warning(f"gcp_{label}_failed", error=str(exc)[:150])
                raw[label] = {"error": str(exc)[:200]}
            await self.noise.jitter.sleep()

        logger.info("gcp_recon_done", findings=len(self._findings))
        raw["gcp_findings"] = self._findings  # matches OUTPUTS
        return self._findings, raw

    # ── IAM Bindings ──────────────────────────────────────────────────────────

    def _check_iam_bindings(self, credentials: Any, project_id: str) -> dict[str, Any]:
        """
        Get project IAM policy via Google Cloud Resource Manager SDK.
        Fixed: was using requests.post directly - replaced with SDK that handles
        auth refresh automatically and is the supported stable API.
        """
        try:
            import google.auth.transport.requests as _garequests
            from google.cloud import resourcemanager_v3
            from google.oauth2 import credentials as _creds_module  # noqa: F401

            client = resourcemanager_v3.ProjectsClient(credentials=credentials)
            request = resourcemanager_v3.GetIamPolicyRequest(
                resource=f"projects/{project_id}"
            )
            policy = client.get_iam_policy(request=request)

            public_bindings: list[str] = []
            owner_bindings:  list[str] = []

            for binding in policy.bindings:
                role    = binding.role
                members = list(binding.members)
                for member in members:
                    if member in _PUBLIC_MEMBERS:
                        public_bindings.append(f"{member} → {role}")
                if role in ("roles/owner", "roles/editor"):
                    owner_bindings.extend(
                        m for m in members if m not in _PUBLIC_MEMBERS
                    )

        except ImportError:
            # Fallback to requests if google-cloud-resource-manager not installed
            import google.auth.transport.requests as _garequests
            import requests

            auth_req = _garequests.Request()
            credentials.refresh(auth_req)
            resp = requests.post(
                f"https://cloudresourcemanager.googleapis.com/v1/projects/{project_id}:getIamPolicy",
                headers={"Authorization": f"Bearer {credentials.token}"},
                json={}, timeout=20,
            )
            resp.raise_for_status()
            raw_policy = resp.json()

            public_bindings = []
            owner_bindings  = []
            for binding in raw_policy.get("bindings", []):
                role    = binding.get("role", "")
                members = binding.get("members", [])
                for member in members:
                    if member in _PUBLIC_MEMBERS:
                        public_bindings.append(f"{member} → {role}")
                if role in ("roles/owner", "roles/editor"):
                    owner_bindings.extend(m for m in members if m not in _PUBLIC_MEMBERS)

        if public_bindings:
            self.finding(
                title="GCP Project IAM Grants Access to allUsers/allAuthenticatedUsers",
                description=(
                    "The project IAM policy has bindings for 'allUsers' or "
                    "'allAuthenticatedUsers'. This grants unauthenticated or "
                    "any Google-authenticated access globally."
                ),
                severity=Severity.CRITICAL,
                mitre_technique="T1078.004",
                mitre_tactic="Initial Access",
                evidence={"public_bindings": public_bindings},
                remediation=(
                    "Remove allUsers and allAuthenticatedUsers from all IAM bindings. "
                    "Apply org policy: constraints/iam.allowedPolicyMemberDomains. "
                    "Enable Cloud Asset Inventory to monitor IAM drift."
                ),
            )

        if owner_bindings:
            self.finding(
                title=f"Multiple Project Owner/Editor Bindings ({len(owner_bindings)})",
                description=(
                    f"{len(owner_bindings)} identities have roles/owner or roles/editor "
                    "on this project. These roles allow full resource control and IAM modification."
                ),
                severity=Severity.HIGH,
                mitre_technique="T1078.004",
                mitre_tactic="Initial Access",
                evidence={"owners": owner_bindings},
                remediation=(
                    "Replace roles/owner with custom least-privilege roles. "
                    "Limit owners to ≤2 break-glass accounts. "
                    "Use Org Policy to enforce owner restrictions."
                ),
            )

        return {"public_bindings": public_bindings, "owner_bindings": owner_bindings,
                "total_bindings": len(policy.get("bindings", []))}

    # ── GCS Buckets ───────────────────────────────────────────────────────────

    def _check_gcs_buckets(self, credentials: Any, project_id: str) -> dict[str, Any]:
        """
        List all GCS buckets and check their IAM policies for public access.
        Also checks uniform bucket-level access and versioning.
        """
        import google.auth.transport.requests
        import requests

        auth_req = google.auth.transport.requests.Request()
        credentials.refresh(auth_req)
        headers  = {"Authorization": f"Bearer {credentials.token}"}
        session  = requests.Session()
        session.headers.update(headers)

        public_buckets:          list[dict[str, Any]] = []
        uniform_access_disabled: list[str]            = []
        versioning_disabled:     list[str]            = []

        # List all buckets in project
        resp = session.get(
            "https://storage.googleapis.com/storage/v1/b",
            params={"project": project_id, "maxResults": 1000},
            timeout=20,
        )
        resp.raise_for_status()
        buckets = resp.json().get("items", [])

        for bucket in buckets:
            bucket_name = bucket.get("name", "")

            # ── IAM policy ─────────────────────────────────────────────────
            try:
                iam_resp = session.get(
                    f"https://storage.googleapis.com/storage/v1/b/{bucket_name}/iam",
                    timeout=15,
                )
                iam_resp.raise_for_status()
                for binding in iam_resp.json().get("bindings", []):
                    role    = binding.get("role", "")
                    members = binding.get("members", [])
                    for member in members:
                        if member in _PUBLIC_MEMBERS:
                            public_buckets.append({
                                "bucket":    bucket_name,
                                "member":    member,
                                "role":      role,
                                "project_id": project_id,
                            })
            except Exception as exc:
                logger.debug("gcs_iam_check_skipped",
                             bucket=bucket_name, reason=str(exc)[:80])

            # ── Uniform bucket-level access ────────────────────────────────
            iamConfig = bucket.get("iamConfiguration", {})
            uba = iamConfig.get("uniformBucketLevelAccess", {})
            if not uba.get("enabled", True):
                uniform_access_disabled.append(bucket_name)

            # ── Object versioning ─────────────────────────────────────────
            versioning = bucket.get("versioning", {})
            if not versioning.get("enabled", False):
                versioning_disabled.append(bucket_name)

        if public_buckets:
            self.finding(
                title=f"Publicly Accessible GCS Buckets ({len(public_buckets)})",
                description=(
                    f"{len(public_buckets)} GCS bucket IAM binding(s) grant access to "
                    "allUsers or allAuthenticatedUsers. Data is readable without credentials."
                ),
                severity=Severity.CRITICAL,
                mitre_technique="T1530",
                mitre_tactic="Collection",
                evidence={"buckets": public_buckets[:20]},
                remediation=(
                    "Remove allUsers and allAuthenticatedUsers from all bucket IAM policies. "
                    "Apply org policy: constraints/storage.publicAccessPrevention. "
                    "Enable uniform bucket-level access to prevent ACL overrides."
                ),
            )

        if uniform_access_disabled:
            self.finding(
                title=f"GCS Buckets Without Uniform Bucket-Level Access ({len(uniform_access_disabled)})",
                description=(
                    f"{len(uniform_access_disabled)} bucket(s) have per-object ACLs enabled. "
                    "Object-level ACLs can inadvertently expose individual objects publicly."
                ),
                severity=Severity.MEDIUM,
                mitre_technique="T1530",
                mitre_tactic="Collection",
                evidence={"buckets": uniform_access_disabled[:20]},
                remediation=(
                    "Enable Uniform Bucket-Level Access on all buckets. "
                    "Migrate from per-object ACLs to bucket IAM policies."
                ),
            )

        return {
            "public_buckets":          public_buckets,
            "uniform_access_disabled": uniform_access_disabled,
            "versioning_disabled":     versioning_disabled,
            "total_buckets":           len(buckets),
        }

    # ── Service Account Keys ──────────────────────────────────────────────────

    def _check_sa_keys(self, credentials: Any, project_id: str) -> dict[str, Any]:
        """
        List all service accounts and their user-managed keys.
        Flag keys older than _SA_KEY_MAX_AGE_DAYS days.
        Also flags service accounts with owner/editor bindings.
        """
        import google.auth.transport.requests
        import requests

        auth_req = google.auth.transport.requests.Request()
        credentials.refresh(auth_req)
        headers = {"Authorization": f"Bearer {credentials.token}"}
        session = requests.Session()
        session.headers.update(headers)

        old_keys:  list[dict[str, Any]] = []
        many_keys: list[dict[str, Any]] = []   # SAs with >2 active keys

        # List ALL service accounts - paginate until nextPageToken is absent
        service_accounts: list[dict] = []
        page_token: str | None = None
        while True:
            params: dict = {"pageSize": 100}
            if page_token:
                params["pageToken"] = page_token
            sa_resp = session.get(
                f"https://iam.googleapis.com/v1/projects/{project_id}/serviceAccounts",
                params=params,
                timeout=20,
            )
            sa_resp.raise_for_status()
            body = sa_resp.json()
            service_accounts.extend(body.get("accounts", []))
            page_token = body.get("nextPageToken")
            if not page_token:
                break

        cutoff = datetime.datetime.now(datetime.UTC) - \
                 datetime.timedelta(days=_SA_KEY_MAX_AGE_DAYS)  # noqa: F841

        for sa in service_accounts:
            sa_email = sa.get("email", "")
            sa_name  = sa.get("name", "")

            # List keys - only USER_MANAGED type (system-managed keys auto-rotate)
            try:
                keys_resp = session.get(
                    f"https://iam.googleapis.com/v1/{sa_name}/keys",
                    params={"keyTypes": "USER_MANAGED"},
                    timeout=15,
                )
                keys_resp.raise_for_status()
                keys = keys_resp.json().get("keys", [])
            except Exception:
                continue

            active_keys = [k for k in keys
                           if k.get("keyType") == "USER_MANAGED"
                           and not k.get("disabled", False)]

            if len(active_keys) > 2:
                many_keys.append({
                    "service_account": sa_email,
                    "active_key_count": len(active_keys),
                })

            for key in active_keys:
                created_str = key.get("validAfterTime", "")
                if not created_str:
                    continue
                try:
                    created = datetime.datetime.fromisoformat(
                        created_str.replace("Z", "+00:00")
                    )
                    age_days = (datetime.datetime.now(datetime.UTC) - created).days
                    if age_days > _SA_KEY_MAX_AGE_DAYS:
                        old_keys.append({
                            "service_account": sa_email,
                            "key_id":          key.get("name", "").split("/")[-1],
                            "age_days":        age_days,
                            "created":         created_str,
                        })
                except (ValueError, TypeError):
                    pass

        if old_keys:
            self.finding(
                title=f"Stale Service Account Keys Found ({len(old_keys)})",
                description=(
                    f"{len(old_keys)} user-managed service account key(s) are over "
                    f"{_SA_KEY_MAX_AGE_DAYS} days old. Long-lived keys are prime targets "
                    "for theft via repository leaks, config file exposure, or insider threats."
                ),
                severity=Severity.MEDIUM,
                mitre_technique="T1552.001",
                mitre_tactic="Credential Access",
                evidence={"old_keys": old_keys[:20]},
                remediation=(
                    f"Rotate or delete SA keys older than {_SA_KEY_MAX_AGE_DAYS} days. "
                    "Prefer Workload Identity Federation over SA keys. "
                    "Scan repos with truffleHog/gitleaks for leaked keys. "
                    "Set org policy: constraints/iam.disableServiceAccountKeyCreation."
                ),
            )

        if many_keys:
            self.finding(
                title=f"Service Accounts with Excessive Active Keys ({len(many_keys)})",
                description=(
                    f"{len(many_keys)} service account(s) have more than 2 active user-managed keys. "
                    "Each extra key is an additional credential that can be stolen."
                ),
                severity=Severity.LOW,
                mitre_technique="T1552.001",
                mitre_tactic="Credential Access",
                evidence={"service_accounts": many_keys},
                remediation=(
                    "Delete unused SA keys. Keep only 1 active key per SA (2 during rotation). "
                    "Automate key rotation with Secret Manager."
                ),
            )

        return {
            "old_keys":          old_keys,
            "many_keys":         many_keys,
            "total_accounts":    len(service_accounts),
        }

    # REMOVED (MOD-064): IMDS probing belongs in post-exploitation modules
    # executed ON TARGET via remote command runner, not from operator machine.
    # Probing metadata.google.internal from operator host leaks operator IAM credentials
    # and generates false findings attributed to engagement target.
    # def _check_metadata_server(self) -> dict[str, Any]:
    #     ...