cyntrisec 0.1.7__py3-none-any.whl

cyntrisec/__init__.py

@@ -0,0 +1,3 @@
+"""Cyntrisec - AWS capability graph analysis and attack path discovery."""
+
+__version__ = "0.1.7"

cyntrisec/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m cyntrisec."""
+
+from cyntrisec.cli.main import app
+
+if __name__ == "__main__":
+    app()

cyntrisec/aws/__init__.py

@@ -0,0 +1,6 @@
+"""AWS scanning modules."""
+
+from cyntrisec.aws.credentials import CredentialProvider
+from cyntrisec.aws.scanner import AwsScanner
+
+__all__ = ["CredentialProvider", "AwsScanner"]

cyntrisec/aws/collectors/__init__.py

@@ -0,0 +1,17 @@
+"""AWS resource collectors."""
+
+from cyntrisec.aws.collectors.ec2 import Ec2Collector
+from cyntrisec.aws.collectors.iam import IamCollector
+from cyntrisec.aws.collectors.lambda_ import LambdaCollector
+from cyntrisec.aws.collectors.network import NetworkCollector
+from cyntrisec.aws.collectors.rds import RdsCollector
+from cyntrisec.aws.collectors.s3 import S3Collector
+
+__all__ = [
+    "Ec2Collector",
+    "IamCollector",
+    "S3Collector",
+    "LambdaCollector",
+    "RdsCollector",
+    "NetworkCollector",
+]

cyntrisec/aws/collectors/ec2.py

@@ -0,0 +1,30 @@
+"""EC2 Collector - Collect EC2 instances."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+
+
+class Ec2Collector:
+    """Collect EC2 resources."""
+
+    def __init__(self, session: boto3.Session, region: str):
+        self._ec2 = session.client("ec2", region_name=region)
+        self._region = region
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all EC2 data."""
+        return {
+            "instances": self._collect_instances(),
+        }
+
+    def _collect_instances(self) -> list[dict]:
+        """Collect EC2 instances."""
+        instances = []
+        paginator = self._ec2.get_paginator("describe_instances")
+        for page in paginator.paginate():
+            for reservation in page.get("Reservations", []):
+                instances.extend(reservation.get("Instances", []))
+        return instances

cyntrisec/aws/collectors/iam.py

@@ -0,0 +1,116 @@
+"""IAM Collector - Collect IAM users, roles, policies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+
+
+class IamCollector:
+    """Collect IAM resources (global)."""
+
+    def __init__(self, session: boto3.Session):
+        self._iam = session.client("iam")
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all IAM data."""
+        return {
+            "users": self._collect_users(),
+            "roles": self._collect_roles(),
+            "policies": self._collect_policies(),
+            "instance_profiles": self._collect_instance_profiles(),
+        }
+
+    def _collect_users(self) -> list[dict]:
+        """Collect IAM users."""
+        users = []
+        paginator = self._iam.get_paginator("list_users")
+        for page in paginator.paginate():
+            users.extend(page.get("Users", []))
+        return users
+
+    def _collect_roles(self) -> list[dict]:
+        """Collect IAM roles with trust policies."""
+        roles = []
+        paginator = self._iam.get_paginator("list_roles")
+        for page in paginator.paginate():
+            for role in page.get("Roles", []):
+                role_name = role.get("RoleName")
+                if role_name:
+                    role["InlinePolicies"] = self._collect_inline_role_policies(role_name)
+                    role["AttachedPolicies"] = self._collect_attached_role_policies(role_name)
+                # Trust policy is included in list_roles
+                roles.append(role)
+        return roles
+
+    def _collect_policies(self) -> list[dict]:
+        """Collect customer-managed policies."""
+        policies = []
+        paginator = self._iam.get_paginator("list_policies")
+        for page in paginator.paginate(Scope="Local"):
+            policies.extend(page.get("Policies", []))
+        return policies
+
+    def _collect_inline_role_policies(self, role_name: str) -> list[dict]:
+        """Collect inline policy documents for a role."""
+        policies: list[dict] = []
+        paginator = self._iam.get_paginator("list_role_policies")
+        for page in paginator.paginate(RoleName=role_name):
+            for policy_name in page.get("PolicyNames", []):
+                try:
+                    response = self._iam.get_role_policy(
+                        RoleName=role_name,
+                        PolicyName=policy_name,
+                    )
+                except Exception:
+                    continue
+                policies.append(
+                    {
+                        "PolicyName": policy_name,
+                        "Document": response.get("PolicyDocument"),
+                    }
+                )
+        return policies
+
+    def _collect_attached_role_policies(self, role_name: str) -> list[dict]:
+        """Collect attached managed policy documents for a role."""
+        policies: list[dict] = []
+        paginator = self._iam.get_paginator("list_attached_role_policies")
+        for page in paginator.paginate(RoleName=role_name):
+            for policy in page.get("AttachedPolicies", []):
+                policy_arn = policy.get("PolicyArn")
+                if not policy_arn:
+                    continue
+                document = self._get_managed_policy_document(policy_arn)
+                policies.append(
+                    {
+                        "PolicyName": policy.get("PolicyName"),
+                        "PolicyArn": policy_arn,
+                        "Document": document,
+                    }
+                )
+        return policies
+
+    def _get_managed_policy_document(self, policy_arn: str) -> dict | None:
+        """Fetch the default policy document for a managed policy."""
+        try:
+            policy = self._iam.get_policy(PolicyArn=policy_arn)
+            version_id = policy.get("Policy", {}).get("DefaultVersionId")
+            if not version_id:
+                return None
+            version = self._iam.get_policy_version(
+                PolicyArn=policy_arn,
+                VersionId=version_id,
+            )
+            return version.get("PolicyVersion", {}).get("Document")
+        except Exception:
+            return None
+
+    def _collect_instance_profiles(self) -> list[dict]:
+        """Collect IAM instance profiles and attached roles."""
+        profiles = []
+        paginator = self._iam.get_paginator("list_instance_profiles")
+        for page in paginator.paginate():
+            profiles.extend(page.get("InstanceProfiles", []))
+        return profiles

cyntrisec/aws/collectors/lambda_.py

@@ -0,0 +1,45 @@
+"""Lambda Collector - Collect Lambda functions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+
+class LambdaCollector:
+    """Collect Lambda resources."""
+
+    def __init__(self, session: boto3.Session, region: str):
+        self._lambda = session.client("lambda", region_name=region)
+        self._region = region
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all Lambda data."""
+        functions = self._collect_functions()
+
+        # Enrich with policies
+        for func in functions:
+            name = func["FunctionName"]
+            func["Policy"] = self._get_function_policy(name)
+
+        return {"functions": functions}
+
+    def _collect_functions(self) -> list[dict]:
+        """List all Lambda functions."""
+        functions = []
+        paginator = self._lambda.get_paginator("list_functions")
+        for page in paginator.paginate():
+            functions.extend(page.get("Functions", []))
+        return functions
+
+    def _get_function_policy(self, function_name: str) -> dict | None:
+        """Get function resource policy."""
+        try:
+            response = self._lambda.get_policy(FunctionName=function_name)
+            return {"Policy": response.get("Policy")}
+        except ClientError as e:
+            if e.response["Error"]["Code"] == "ResourceNotFoundException":
+                return None
+            return {"Error": str(e)}

cyntrisec/aws/collectors/network.py

@@ -0,0 +1,70 @@
+"""Network Collector - Collect VPCs, subnets, security groups."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+
+
+class NetworkCollector:
+    """Collect network resources."""
+
+    def __init__(self, session: boto3.Session, region: str):
+        self._session = session
+        self._ec2 = session.client("ec2", region_name=region)
+        self._region = region
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all network data."""
+        return {
+            "vpcs": self._collect_vpcs(),
+            "subnets": self._collect_subnets(),
+            "security_groups": self._collect_security_groups(),
+            "route_tables": self._collect_route_tables(),
+            "internet_gateways": self._collect_internet_gateways(),
+            "nat_gateways": self._collect_nat_gateways(),
+            "load_balancers": self._collect_load_balancers(),
+        }
+
+    def _collect_vpcs(self) -> list[dict]:
+        """Collect VPCs."""
+        response = self._ec2.describe_vpcs()
+        return response.get("Vpcs", [])
+
+    def _collect_subnets(self) -> list[dict]:
+        """Collect subnets."""
+        response = self._ec2.describe_subnets()
+        return response.get("Subnets", [])
+
+    def _collect_security_groups(self) -> list[dict]:
+        """Collect security groups."""
+        sgs = []
+        paginator = self._ec2.get_paginator("describe_security_groups")
+        for page in paginator.paginate():
+            sgs.extend(page.get("SecurityGroups", []))
+        return sgs
+
+    def _collect_route_tables(self) -> list[dict]:
+        """Collect route tables."""
+        response = self._ec2.describe_route_tables()
+        return response.get("RouteTables", [])
+
+    def _collect_internet_gateways(self) -> list[dict]:
+        """Collect internet gateways."""
+        response = self._ec2.describe_internet_gateways()
+        return response.get("InternetGateways", [])
+
+    def _collect_nat_gateways(self) -> list[dict]:
+        """Collect NAT gateways."""
+        response = self._ec2.describe_nat_gateways()
+        return response.get("NatGateways", [])
+
+    def _collect_load_balancers(self) -> list[dict]:
+        """Collect ELBv2 load balancers."""
+        try:
+            elb = self._session.client("elbv2", region_name=self._region)
+            response = elb.describe_load_balancers()
+            return response.get("LoadBalancers", [])
+        except Exception:
+            return []

cyntrisec/aws/collectors/rds.py

@@ -0,0 +1,38 @@
+"""RDS Collector - Collect RDS instances."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+
+
+class RdsCollector:
+    """Collect RDS resources."""
+
+    def __init__(self, session: boto3.Session, region: str):
+        self._rds = session.client("rds", region_name=region)
+        self._region = region
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all RDS data."""
+        return {
+            "instances": self._collect_instances(),
+            "clusters": self._collect_clusters(),
+        }
+
+    def _collect_instances(self) -> list[dict]:
+        """Collect RDS DB instances."""
+        instances = []
+        paginator = self._rds.get_paginator("describe_db_instances")
+        for page in paginator.paginate():
+            instances.extend(page.get("DBInstances", []))
+        return instances
+
+    def _collect_clusters(self) -> list[dict]:
+        """Collect RDS Aurora clusters."""
+        clusters = []
+        paginator = self._rds.get_paginator("describe_db_clusters")
+        for page in paginator.paginate():
+            clusters.extend(page.get("DBClusters", []))
+        return clusters

cyntrisec/aws/collectors/s3.py

@@ -0,0 +1,68 @@
+"""S3 Collector - Collect S3 buckets and policies."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+
+class S3Collector:
+    """Collect S3 resources (global)."""
+
+    def __init__(self, session: boto3.Session):
+        self._s3 = session.client("s3")
+
+    def collect_all(self) -> dict[str, Any]:
+        """Collect all S3 data."""
+        buckets = self._collect_buckets()
+
+        # Enrich with policies and ACLs
+        for bucket in buckets:
+            name = bucket["Name"]
+            bucket["Policy"] = self._get_bucket_policy(name)
+            bucket["Acl"] = self._get_bucket_acl(name)
+            bucket["PublicAccessBlock"] = self._get_public_access_block(name)
+            bucket["Location"] = self._get_bucket_location(name)
+
+        return {"buckets": buckets}
+
+    def _collect_buckets(self) -> list[dict]:
+        """List all buckets."""
+        response = self._s3.list_buckets()
+        return response.get("Buckets", [])
+
+    def _get_bucket_policy(self, bucket_name: str) -> dict | None:
+        """Get bucket policy."""
+        try:
+            response = self._s3.get_bucket_policy(Bucket=bucket_name)
+            return {"Policy": response.get("Policy")}
+        except ClientError as e:
+            if e.response["Error"]["Code"] == "NoSuchBucketPolicy":
+                return None
+            return {"Error": str(e)}
+
+    def _get_bucket_acl(self, bucket_name: str) -> dict | None:
+        """Get bucket ACL."""
+        try:
+            return self._s3.get_bucket_acl(Bucket=bucket_name)
+        except ClientError:
+            return None
+
+    def _get_public_access_block(self, bucket_name: str) -> dict | None:
+        """Get public access block configuration."""
+        try:
+            response = self._s3.get_public_access_block(Bucket=bucket_name)
+            return response.get("PublicAccessBlockConfiguration")
+        except ClientError:
+            return None
+
+    def _get_bucket_location(self, bucket_name: str) -> str:
+        """Get bucket region."""
+        try:
+            response = self._s3.get_bucket_location(Bucket=bucket_name)
+            # None means us-east-1
+            return response.get("LocationConstraint") or "us-east-1"
+        except ClientError:
+            return "unknown"

cyntrisec/aws/collectors/usage.py

@@ -0,0 +1,188 @@
+"""
+Usage Collector - Collect IAM last-accessed data for waste analysis.
+
+Uses AWS IAM's generate_service_last_accessed_details API to determine
+which permissions have actually been used vs which are just granted.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class ServiceAccess:
+    """Service access record from IAM last-accessed data."""
+
+    service_name: str
+    service_namespace: str
+    last_authenticated: datetime | None = None
+    last_authenticated_entity: str | None = None
+    total_authenticated_entities: int = 0
+
+    @property
+    def is_unused(self) -> bool:
+        """Check if service was never accessed."""
+        return self.last_authenticated is None
+
+
+@dataclass
+class ActionAccess:
+    """Action-level access record."""
+
+    action_name: str
+    last_accessed: datetime | None = None
+
+    @property
+    def is_unused(self) -> bool:
+        return self.last_accessed is None
+
+
+@dataclass
+class RoleUsageReport:
+    """Usage report for an IAM role."""
+
+    role_arn: str
+    role_name: str
+    services: list[ServiceAccess] = field(default_factory=list)
+    actions: list[ActionAccess] = field(default_factory=list)
+    generated_at: datetime = field(default_factory=datetime.utcnow)
+
+    @property
+    def unused_services(self) -> list[ServiceAccess]:
+        return [s for s in self.services if s.is_unused]
+
+    @property
+    def used_services(self) -> list[ServiceAccess]:
+        return [s for s in self.services if not s.is_unused]
+
+
+class UsageCollector:
+    """
+    Collect IAM usage data using AWS Access Advisor.
+
+    The last-accessed data shows which services a role has permissions for
+    and when those permissions were last used.
+    """
+
+    def __init__(self, session):
+        """
+        Initialize with a boto3 Session.
+
+        Args:
+            session: boto3.Session with IAM permissions
+        """
+        self._session = session
+        self._iam = session.client("iam")
+
+    def get_role_usage(
+        self,
+        role_arn: str,
+        *,
+        max_wait_seconds: int = 30,
+    ) -> RoleUsageReport | None:
+        """
+        Get usage report for an IAM role.
+
+        Args:
+            role_arn: ARN of the role to analyze
+            max_wait_seconds: Maximum time to wait for report generation
+
+        Returns:
+            RoleUsageReport with service access data, or None if failed
+        """
+        role_name = role_arn.split("/")[-1]
+        log.debug("Generating last-accessed report for %s", role_name)
+
+        try:
+            # Start the report generation
+            response = self._iam.generate_service_last_accessed_details(
+                Arn=role_arn,
+                Granularity="SERVICE_LEVEL",
+            )
+            job_id = response["JobId"]
+
+            # Poll for completion
+            start_time = time.time()
+            while time.time() - start_time < max_wait_seconds:
+                result = self._iam.get_service_last_accessed_details(JobId=job_id)
+                status = result.get("JobStatus")
+
+                if status == "COMPLETED":
+                    return self._parse_report(role_arn, role_name, result)
+                elif status == "FAILED":
+                    log.warning("Last-accessed report failed for %s", role_name)
+                    return None
+
+                time.sleep(1)
+
+            log.warning("Timeout waiting for last-accessed report for %s", role_name)
+            return None
+
+        except Exception as e:
+            log.debug("Error getting usage for %s: %s", role_name, e)
+            return None
+
+    def _parse_report(
+        self,
+        role_arn: str,
+        role_name: str,
+        result: dict[str, Any],
+    ) -> RoleUsageReport:
+        """Parse the IAM last-accessed response."""
+        services = []
+
+        for svc in result.get("ServicesLastAccessed", []):
+            last_auth = svc.get("LastAuthenticated")
+            services.append(
+                ServiceAccess(
+                    service_name=svc.get("ServiceName", ""),
+                    service_namespace=svc.get("ServiceNamespace", ""),
+                    last_authenticated=last_auth,
+                    last_authenticated_entity=svc.get("LastAuthenticatedEntity"),
+                    total_authenticated_entities=svc.get("TotalAuthenticatedEntities", 0),
+                )
+            )
+
+        return RoleUsageReport(
+            role_arn=role_arn,
+            role_name=role_name,
+            services=services,
+        )
+
+    def collect_all_roles(
+        self,
+        role_arns: list[str],
+        *,
+        max_roles: int = 50,
+    ) -> list[RoleUsageReport]:
+        """
+        Collect usage reports for multiple roles.
+
+        Args:
+            role_arns: List of role ARNs to analyze
+            max_roles: Maximum number of roles to analyze (API throttling)
+
+        Returns:
+            List of usage reports
+        """
+        reports = []
+
+        for i, arn in enumerate(role_arns[:max_roles]):
+            log.info(
+                "Analyzing role %d/%d: %s",
+                i + 1,
+                min(len(role_arns), max_roles),
+                arn.split("/")[-1],
+            )
+            report = self.get_role_usage(arn)
+            if report:
+                reports.append(report)
+
+        return reports