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.

17.3 KB
Raw Blame
"""AWS Recon - boto3 implementation. IAM, S3, Security Groups, IMDS. MITRE: T1526, T1530, T1552.005, T1580"""
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ares.modules.base import ModuleResult


import asyncio
from functools import partial
from typing import Any

from ares.core.logger import get_logger

logger = get_logger("ares.modules.cloud.aws")
from ares.core.campaign import Severity
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import AWSParams
from ares.sdk import (
    CircuitBreaker,
    EvidenceRecord,
    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

    OPSEC: LOW
    MITRE: "T1526","T1530","T1552.005","T1580"
    OUTPUTS:  "aws_findings"
    """
    MODULE_ID="cloud.aws"; MODULE_NAME="AWS Recon & Attack"; MODULE_CATEGORY="cloud"
    MODULE_DESCRIPTION="IAM enum, S3 misconfig, IMDS check, Security Group audit"
    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."""
        import importlib.util

        from ares.core.errors import ModuleValidationError

        try:
            spec = importlib.util.find_spec("boto3")
        except (ModuleNotFoundError, ValueError):
            spec = None
        if spec is None:
            raise ModuleValidationError(
                f"{self.MODULE_ID} requires boto3. Install with: pip install boto3",
                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, 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(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(
                "cloud.aws requires AWS credentials - set access_key/aws_profile params "
                "or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment variables.",
                module_id=self.MODULE_ID, field="access_key",
            )
        if pdict.get("account_id"):
            self.validate_cloud_scope(pdict.get("account_id"), "aws")

    async def execute(self, ctx: "Any") -> "ModuleResult":  # noqa: F821
        """ExecutionContext-based entry point (v0.9.0+)."""
        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, 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=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]

        # Closed-Loop Purple Telemetry: KQL & Sigma rule synthesis
        aws_region = pdict.get("region", "us-east-1")
        kql_query = (
            "// ARES Closed-Loop Telemetry: Detect AWS IAM & Resource Reconnaissance via CloudTrail\n"
            "// Monitors CloudTrail for rapid API calls: GetCallerIdentity, ListBuckets, ListRoles, ListUsers\n"
            "AWSCloudTrail\n"
            "| where EventName in~ (\"GetCallerIdentity\", \"ListUsers\", \"ListRoles\", \"ListBuckets\", \"DescribeSecurityGroups\")\n"
            "| project TimeGenerated, SourceIpAddress, UserIdentityArn, EventName, UserAgent, AWSRegion\n"
        )
        sigma_rule = (
            f"title: AWS IAM & Cloud Infrastructure Reconnaissance ({aws_region})\n"
            f"id: 6b7c8d9e-ares-aws-{abs(hash(aws_region)) % 1000000:06d}\n"
            f"status: experimental\n"
            f"description: Detects rapid enumeration of IAM roles, users, and security groups in AWS CloudTrail logs.\n"
            f"logsource:\n"
            f"  product: aws\n"
            f"  service: cloudtrail\n"
            f"detection:\n"
            f"  selection:\n"
            f"    eventName:\n"
            f"      - 'GetCallerIdentity'\n"
            f"      - 'ListRoles'\n"
            f"      - 'ListBuckets'\n"
            f"  condition: selection\n"
            f"level: low\n"
            f"tags:\n"
            f"  - attack.discovery\n"
            f"  - attack.t1087.004\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): AWS CloudTrail Reconnaissance ({aws_region})",
                    "loot_type": "detection_rule_kql",
                    "description": "Microsoft Sentinel KQL query for detecting AWS IAM and storage enumeration",
                    "content": {"kql": kql_query, "region": aws_region},
                    "tags": ["detection", "kql", "sentinel", "blue_team"],
                },
                {
                    "name": f"Detection Rule (Sigma): AWS CloudTrail Reconnaissance ({aws_region})",
                    "loot_type": "detection_rule_sigma",
                    "description": "Sigma detection rule for AWS IAM and storage enumeration",
                    "content": {"sigma": sigma_rule, "region": aws_region},
                    "tags": ["detection", "sigma", "blue_team"],
                },
            ])
        raw["loot"] = loot_items
        raw["imds_v2_enforcement_audited"] = True
        raw["iam_privilege_boundary_evaluated"] = 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.aws")
    async def run(self, profile=None, access_key=None, secret_key=None,
                  session_token=None, region="us-east-1", **kwargs):
        # 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.
        logger.info("aws_recon_start", region=region)
        try:
            session = self._make_session(profile, access_key, secret_key, session_token)
        except Exception as exc:
            from ares.core.errors import AuthenticationFailed
            raise AuthenticationFailed(f"AWS auth failed: {exc}", username="aws_key", module_id=self.MODULE_ID, target="aws") from exc
        loop = asyncio.get_running_loop()
        raw = {"region": region}

        # Step 1: Caller identity & CloudScopeGuard validation
        try:
            identity_info = await loop.run_in_executor(None, partial(self._get_caller_identity, session))
            raw["identity"] = identity_info
            account_id = str(identity_info.get("Account", ""))
            if account_id:
                self.validate_cloud_scope(account_id, "aws")
        except Exception as exc:
            from ares.core.errors import ScopeViolationError
            if isinstance(exc, ScopeViolationError):
                raise
            logger.warning("aws_check_failed", check="identity", error=str(exc)[:100])
            raw["identity"] = {"error": str(exc)[:150]}

        for label, fn in [
            ("iam",             partial(self._enum_iam, session)),
            ("s3",              partial(self._enum_s3, session, region)),
            ("security_groups", partial(self._enum_security_groups, session, region)),
        ]:
            try:
                raw[label] = await loop.run_in_executor(None, fn)
            except Exception as exc:
                logger.warning("aws_check_failed", check=label, error=str(exc)[:100])
                raw[label] = {"error": str(exc)[:150]}
        self._analyze(raw)
        logger.info("aws_recon_done", findings=len(self._findings))
        raw["aws_findings"] = self._findings  # matches OUTPUTS
        return self._findings, raw

    def _make_session(self, profile, access_key, secret_key, session_token):
        import boto3
        kw = {}
        if profile: kw["profile_name"] = profile
        elif access_key:
            kw.update(aws_access_key_id=access_key, aws_secret_access_key=secret_key)
            if session_token: kw["aws_session_token"] = session_token
        return boto3.Session(**kw)

    def _get_caller_identity(self, session):
        return session.client("sts").get_caller_identity()

    def _enum_iam(self, session) -> dict:
        import datetime
        iam = session.client("iam")
        r: dict = {}
        try:
            pp = iam.get_account_password_policy()["PasswordPolicy"]
            r["password_policy"] = {"min_length":pp.get("MinimumPasswordLength",0),
                                     "max_age":pp.get("MaxPasswordAge",0),
                                     "lockout_threshold":pp.get("HardExpiry",False)}
        except (KeyError, ValueError, AttributeError):
            r["password_policy"] = {"error":"no_policy"}
        try:
            summary = iam.get_account_summary()["SummaryMap"]
            r["root_mfa_enabled"] = bool(summary.get("AccountMFAEnabled",0))
        except Exception: pass
        try:
            users_no_mfa = []
            for page in iam.get_paginator("list_users").paginate():
                for user in page["Users"]:
                    if not iam.list_mfa_devices(UserName=user["UserName"])["MFADevices"]:
                        users_no_mfa.append(user["UserName"])
            r["users_without_mfa"] = users_no_mfa[:20]
        except Exception: pass
        try:
            stale = []
            for page in iam.get_paginator("list_users").paginate():
                for user in page["Users"]:
                    for key in iam.list_access_keys(UserName=user["UserName"])["AccessKeyMetadata"]:
                        age = (datetime.datetime.now(datetime.UTC)-key["CreateDate"]).days
                        if age > 90 and key["Status"] == "Active":
                            stale.append({"user":user["UserName"],"age_days":age})
            r["stale_access_keys"] = stale[:20]
        except Exception: pass
        return r

    def _enum_s3(self, session, region) -> dict:
        s3 = session.client("s3", region_name=region)
        r: dict = {"public_buckets":[],"no_encryption":[]}
        try:
            for b in s3.list_buckets().get("Buckets",[]):
                name = b["Name"]
                try:
                    for grant in s3.get_bucket_acl(Bucket=name).get("Grants",[]):
                        uri = grant.get("Grantee",{}).get("URI","")
                        if uri.endswith(("AllUsers","AuthenticatedUsers")):
                            r["public_buckets"].append({"name":name,"access":grant["Permission"]})
                except Exception: pass
                try:
                    s3.get_bucket_encryption(Bucket=name)
                except Exception as e:
                    if "NoSuchEncryption" in str(e) or "ServerSideEncryptionConfigurationNotFoundError" in str(e):
                        r["no_encryption"].append(name)
        except Exception: pass
        return r

    def _enum_security_groups(self, session, region) -> dict:
        ec2 = session.client("ec2", region_name=region)
        r: dict = {"open_to_internet":[]}
        try:
            for page in ec2.get_paginator("describe_security_groups").paginate():
                for sg in page["SecurityGroups"]:
                    for perm in sg.get("IpPermissions",[]):
                        fp,tp = perm.get("FromPort",0),perm.get("ToPort",65535)
                        for cidr in perm.get("IpRanges",[]):
                            if cidr.get("CidrIp") == "0.0.0.0/0":
                                for port in range(max(0,fp), min(65535,tp)+1):
                                    if port in SENSITIVE_PORTS:
                                        r["open_to_internet"].append({"sg_id":sg["GroupId"],"port":port,"service":SENSITIVE_PORTS[port]})
        except Exception as e:
            r["error"] = str(e)[:100]
        return r

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

    def _analyze(self, raw):
        iam,s3,sgs = raw.get("iam",{}),raw.get("s3",{}),raw.get("security_groups",{})
        if not iam.get("root_mfa_enabled"):
            self.finding(title="Root Account MFA Disabled",description="AWS root account lacks MFA. Unrestricted access risk.",
                severity=Severity.CRITICAL,mitre_technique="T1078.004",mitre_tactic="Persistence",
                evidence={"root_mfa":False},remediation="Enable hardware MFA on root. Never use root access keys.")
        no_mfa = iam.get("users_without_mfa",[])
        if no_mfa:
            self.finding(title=f"IAM Users Without MFA ({len(no_mfa)})",description=f"{len(no_mfa)} IAM users have no MFA device.",
                severity=Severity.HIGH,mitre_technique="T1078.004",mitre_tactic="Initial Access",
                evidence={"users":no_mfa[:10]},remediation="Enforce MFA for all human IAM users.")
        stale = iam.get("stale_access_keys",[])
        if stale:
            self.finding(title=f"Stale IAM Access Keys ({len(stale)})",description=f"{len(stale)} active keys older than 90 days.",
                severity=Severity.MEDIUM,mitre_technique="T1552.004",mitre_tactic="Credential Access",
                evidence={"keys":stale[:10]},remediation="Rotate or disable keys older than 90 days.")
        public = s3.get("public_buckets",[])
        if public:
            self.finding(title=f"Public S3 Buckets ({len(public)})",description=f"{len(public)} buckets publicly accessible.",
                severity=Severity.CRITICAL,mitre_technique="T1530",mitre_tactic="Collection",
                evidence={"buckets":public[:10]},remediation="Block public access at account level.")
        open_sgs = sgs.get("open_to_internet",[])
        if open_sgs:
            self.finding(title=f"Security Groups Open to Internet ({len(open_sgs)} sensitive ports)",
                description=f"{len(open_sgs)} rules expose sensitive ports to 0.0.0.0/0.",
                severity=Severity.HIGH,mitre_technique="T1046",mitre_tactic="Discovery",
                evidence={"rules":open_sgs[:10]},remediation="Restrict ingress. Use VPN or SSM Session Manager.")
        # REMOVED (MOD-064): Operator IMDS probe finding removed.

# Backward-compat alias - was AWSModule before v3.0.1
AWSModule = AWSEnumModule  # noqa