argus-cloud-optimizer 0.2.0__py3-none-any.whl

adapters/aws/adapter.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime
+
+import boto3
+
+from adapters.aws import auth, cloudtrail, cloudwatch, cost_explorer, resource_explorer
+from adapters.base import CloudAdapter, MetricSummary, Resource
+
+
+class AWSAdapter(CloudAdapter):
+    """
+    AWS implementation of CloudAdapter.
+    Wires together Resource Explorer, CloudWatch, Cost Explorer, and CloudTrail.
+    All boto3 calls are read-only — no mutations to cloud resources.
+
+    Usage:
+        session = auth.get_session(account=account_config, region="us-east-1")
+        adapter = AWSAdapter(session)
+    """
+
+    def __init__(
+        self,
+        session: boto3.Session,
+        aggregator_region: str | None = None,
+    ) -> None:
+        self._session = session
+        self._aggregator_region: str = (
+            aggregator_region
+            or os.environ.get("RESOURCE_EXPLORER_REGION")
+            or "us-east-1"
+        )
+
+    def list_resources(self, ignore_regions: list[str] | None = None) -> list[Resource]:
+        return resource_explorer.list_resources(
+            session=self._session,
+            ignore_regions=ignore_regions,
+            aggregator_region=self._aggregator_region,
+        )
+
+    def get_metrics(
+        self,
+        resource_id: str,
+        resource_type: str,
+        days: int = 90,
+    ) -> MetricSummary:
+        return cloudwatch.get_metrics(
+            session=self._session,
+            resource_id=resource_id,
+            resource_type=resource_type,
+            days=days,
+        )
+
+    def get_cost(
+        self,
+        resource_ids: list[str],
+        days: int = 30,
+    ) -> dict[str, float]:
+        return cost_explorer.get_cost(
+            session=self._session,
+            resource_ids=resource_ids,
+            days=days,
+        )
+
+    def get_last_activity(
+        self,
+        resource_id: str,
+        resource_type: str,
+    ) -> datetime | None:
+        return cloudtrail.get_last_activity(
+            session=self._session,
+            resource_id=resource_id,
+            resource_type=resource_type,
+        )
+
+    @classmethod
+    def for_account(
+        cls,
+        account: dict | None = None,
+        region: str = "us-east-1",
+    ) -> "AWSAdapter":
+        """Convenience constructor — resolves auth and returns a ready adapter."""
+        session = auth.get_session(account=account, region=region)
+        return cls(session=session, aggregator_region=region)

adapters/aws/auth.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import boto3
+import structlog
+from botocore.exceptions import ClientError
+
+logger = structlog.get_logger(__name__)
+
+SESSION_DURATION_SECONDS = 3600  # 1 hour — short-lived, auto-expires
+
+
+def get_session(
+    account: dict | None = None,
+    region: str = "us-east-1",
+) -> boto3.Session:
+    """
+    Return an authenticated boto3 Session for the given account config.
+
+    Single-account (account is None or has no role_arn):
+        Uses the ambient credential chain — Lambda execution role in production,
+        ~/.aws/credentials profile in local dev.
+
+    Multi-account (account has role_arn):
+        Assumes the specified IAM role via STS. Credentials are temporary
+        (1 hour), scoped to read-only permissions in the target account,
+        and never stored anywhere.
+    """
+    if not account or not account.get("role_arn"):
+        logger.debug("auth_single_account", region=region)
+        return boto3.Session(region_name=region)
+
+    role_arn = account["role_arn"]
+    account_name = account.get("name", account.get("id", "unknown"))
+
+    logger.info("auth_assuming_role", account=account_name, role_arn=role_arn)
+
+    try:
+        sts = boto3.client("sts", region_name=region)
+        response = sts.assume_role(
+            RoleArn=role_arn,
+            RoleSessionName=f"ArgusScan-{account_name}",
+            DurationSeconds=SESSION_DURATION_SECONDS,
+        )
+    except ClientError as exc:
+        raise PermissionError(
+            f"Failed to assume role {role_arn} for account '{account_name}'. "
+            f"Check that the spoke IAM role exists and trusts this account. "
+            f"AWS error: {exc}"
+        ) from exc
+
+    creds = response["Credentials"]
+    return boto3.Session(
+        aws_access_key_id=creds["AccessKeyId"],
+        aws_secret_access_key=creds["SecretAccessKey"],
+        aws_session_token=creds["SessionToken"],
+        region_name=region,
+    )

adapters/aws/cloudtrail.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import boto3
+import structlog
+from botocore.exceptions import ClientError
+
+from adapters.aws.config import BOTO_TIMEOUT_CONFIG
+from adapters.aws.retry import retry_on_transient
+
+logger = structlog.get_logger(__name__)
+
+_LOOKBACK_DAYS = 90  # CloudTrail LookupEvents max window is 90 days
+
+
+def get_last_activity(
+    session: boto3.Session,
+    resource_id: str,
+    resource_type: str,
+) -> datetime | None:
+    """
+    Return the timestamp of the most recent CloudTrail event for a resource.
+    Returns None if no activity was found in the last 90 days.
+
+    Uses the resource name (extracted from ARN) as the lookup attribute
+    since CloudTrail indexes by resource name, not full ARN.
+    """
+    region = _region_from_arn(resource_id)
+    resource_name = _resource_name_from_arn(resource_id)
+    client = session.client(
+        "cloudtrail", region_name=region, config=BOTO_TIMEOUT_CONFIG
+    )
+
+    end_time = datetime.now(tz=timezone.utc)
+    start_time = end_time - timedelta(days=_LOOKBACK_DAYS)
+
+    try:
+        response = retry_on_transient(
+            client.lookup_events,
+            LookupAttributes=[
+                {"AttributeKey": "ResourceName", "AttributeValue": resource_name}
+            ],
+            StartTime=start_time,
+            EndTime=end_time,
+            MaxResults=1,
+        )
+    except ClientError as exc:
+        logger.warning(
+            "cloudtrail_lookup_failed",
+            extra={"resource_id": resource_id, "error": str(exc)},
+        )
+        return None
+
+    events = response.get("Events", [])
+    if not events:
+        return None
+
+    event_time = events[0]["EventTime"]
+    if event_time.tzinfo is None:
+        event_time = event_time.replace(tzinfo=timezone.utc)
+    return event_time  # type: ignore[no-any-return]
+
+
+def _region_from_arn(arn: str) -> str:
+    parts = arn.split(":")
+    region = parts[3] if len(parts) > 3 else ""
+    return region or "us-east-1"
+
+
+def _resource_name_from_arn(arn: str) -> str:
+    """
+    Extract the short resource name from an ARN for CloudTrail lookup.
+    CloudTrail indexes by resource name (e.g. 'i-0abc123'), not full ARN.
+    """
+    parts = arn.split(":")
+    resource_part = ":".join(parts[5:])
+
+    if "/" in resource_part:
+        return resource_part.split("/")[-1]
+    if ":" in resource_part:
+        return resource_part.split(":")[-1]
+    return resource_part