cyntrisec 0.1.7__py3-none-any.whl

cyntrisec/cli/setup.py

@@ -0,0 +1,260 @@
+"""
+Setup Commands - Generate IAM roles and configuration.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from cyntrisec.cli.errors import EXIT_CODE_MAP, CyntriError, ErrorCode, handle_errors
+from cyntrisec.cli.output import emit_agent_or_json, resolve_format, suggested_actions
+from cyntrisec.cli.schemas import SetupIamResponse
+
+setup_app = typer.Typer(help="Setup commands")
+
+
+@setup_app.command("iam")
+@handle_errors
+def setup_iam(
+    account_id: str = typer.Argument(
+        ...,
+        help="AWS account ID (12 digits)",
+    ),
+    role_name: str = typer.Option(
+        "CyntrisecReadOnly",
+        "--role-name",
+        "-n",
+        help="Name for the IAM role",
+    ),
+    external_id: str | None = typer.Option(
+        None,
+        "--external-id",
+        "-e",
+        help="External ID for extra security",
+    ),
+    format: str = typer.Option(
+        "terraform",
+        "--format",
+        "-f",
+        help="Output format: terraform, cloudformation, policy",
+    ),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Output file (default: stdout)",
+    ),
+    output_format: str | None = typer.Option(
+        None,
+        "--output-format",
+        help="Render format: text, json, agent (defaults to json when piped)",
+    ),
+):
+    """
+    Generate IAM role for AWS scanning.
+
+    Creates a read-only IAM role that Cyntrisec can assume.
+
+    Examples:
+
+        cyntrisec setup iam 123456789012 --output role.tf
+
+        cyntrisec setup iam 123456789012 --format policy
+
+        cyntrisec setup iam 123456789012 --external-id my-id --format cloudformation
+    """
+    # Validate
+    if not account_id.isdigit() or len(account_id) != 12:
+        raise CyntriError(
+            error_code=ErrorCode.INVALID_QUERY,
+            message="Account ID must be exactly 12 digits",
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+
+    resolved_output_format = resolve_format(
+        output_format,
+        default_tty="text",
+        allowed=["text", "json", "agent"],
+    )
+
+    # Read-only policy
+    policy = {
+        "Version": "2012-10-17",
+        "Statement": [
+            {
+                "Sid": "CyntrisecReadOnly",
+                "Effect": "Allow",
+                "Action": [
+                    "ec2:Describe*",
+                    "iam:Get*",
+                    "iam:List*",
+                    "s3:GetBucketAcl",
+                    "s3:GetBucketPolicy",
+                    "s3:GetBucketPolicyStatus",
+                    "s3:GetBucketPublicAccessBlock",
+                    "s3:GetBucketLocation",
+                    "s3:ListBucket",
+                    "s3:ListAllMyBuckets",
+                    "lambda:GetFunction",
+                    "lambda:GetFunctionConfiguration",
+                    "lambda:GetPolicy",
+                    "lambda:ListFunctions",
+                    "rds:Describe*",
+                    "elasticloadbalancing:Describe*",
+                    "route53:List*",
+                    "route53:Get*",
+                    "cloudfront:Get*",
+                    "cloudfront:List*",
+                    "apigateway:GET",
+                    "sts:GetCallerIdentity",
+                ],
+                "Resource": "*",
+            }
+        ],
+    }
+
+    if format == "terraform":
+        result = _gen_terraform(account_id, role_name, external_id, policy)
+    elif format == "cloudformation":
+        result = _gen_cloudformation(role_name, external_id, policy)
+    elif format == "policy":
+        result = json.dumps(policy, indent=2)
+    else:
+        raise CyntriError(
+            error_code=ErrorCode.INVALID_QUERY,
+            message=f"Unknown format: {format}",
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+
+    payload = {
+        "account_id": account_id,
+        "role_name": role_name,
+        "external_id": external_id,
+        "template_format": format,
+        "template": result,
+    }
+
+    if output:
+        output.write_text(result)
+        payload["output_path"] = str(output)
+        typer.echo(f"Written to {output}", err=True)
+    elif resolved_output_format == "text":
+        typer.echo(result)
+
+    if resolved_output_format in {"json", "agent"}:
+        actions = suggested_actions(
+            [
+                (
+                    f"cyntrisec validate-role --role-arn arn:aws:iam::{account_id}:role/{role_name}",
+                    "Verify trust and permissions",
+                ),
+                ("cyntrisec scan --role-arn <role_arn>", "Kick off the first scan"),
+            ]
+        )
+        emit_agent_or_json(
+            resolved_output_format,
+            payload,
+            suggested=actions,
+            schema=SetupIamResponse,
+        )
+
+
+def _gen_terraform(account_id: str, role_name: str, external_id: str | None, policy: dict) -> str:
+    """Generate Terraform configuration."""
+    safe_name = role_name.lower().replace("-", "_")
+
+    # Build assume role policy with proper Condition structure inside jsonencode
+    assume_statement = {
+        "Effect": "Allow",
+        "Principal": {"AWS": f"arn:aws:iam::{account_id}:root"},
+        "Action": "sts:AssumeRole",
+    }
+    if external_id:
+        assume_statement["Condition"] = {
+            "StringEquals": {"sts:ExternalId": external_id}
+        }
+
+    assume_policy = {
+        "Version": "2012-10-17",
+        "Statement": [assume_statement],
+    }
+
+    # Format JSON for HCL embedding
+    assume_policy_json = json.dumps(assume_policy, indent=4)
+    policy_json = json.dumps(policy, indent=4)
+
+    return f'''# Cyntrisec Read-Only IAM Role
+# Usage: cyntrisec scan --role-arn <output.role_arn>{f" --external-id {external_id}" if external_id else ""}
+
+resource "aws_iam_role" "{safe_name}" {{
+  name = "{role_name}"
+
+  assume_role_policy = jsonencode({assume_policy_json})
+
+  tags = {{
+    Purpose   = "Cyntrisec"
+    ManagedBy = "terraform"
+    ReadOnly  = "true"
+  }}
+}}
+
+resource "aws_iam_role_policy" "{safe_name}_policy" {{
+  name   = "{role_name}Policy"
+  role   = aws_iam_role.{safe_name}.id
+  policy = jsonencode({policy_json})
+}}
+
+output "role_arn" {{
+  value = aws_iam_role.{safe_name}.arn
+}}
+'''
+
+
+def _gen_cloudformation(role_name: str, external_id: str | None, policy: dict) -> str:
+    """Generate CloudFormation template."""
+    cond = ""
+    if external_id:
+        cond = f'''
+            Condition:
+              StringEquals:
+                sts:ExternalId: "{external_id}"'''
+
+    policy_yaml = json.dumps(policy, indent=8).replace("\n", "\n        ")
+
+    return f"""AWSTemplateFormatVersion: "2010-09-09"
+Description: Cyntrisec Read-Only IAM Role
+
+Resources:
+  CyntrisecRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: {role_name}
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          - Effect: Allow
+            Principal:
+              AWS: !Sub "arn:aws:iam::${{AWS::AccountId}}:root"
+            Action: sts:AssumeRole{cond}
+      Tags:
+        - Key: Purpose
+          Value: Cyntrisec
+        - Key: ReadOnly
+          Value: "true"
+
+  CyntrisecPolicy:
+    Type: AWS::IAM::Policy
+    Properties:
+      PolicyName: {role_name}Policy
+      Roles: [!Ref CyntrisecRole]
+      PolicyDocument: {policy_yaml}
+
+Outputs:
+  RoleArn:
+    Value: !GetAtt CyntrisecRole.Arn
+    Export:
+      Name: CyntrisecRoleArn
+"""

cyntrisec/cli/validate.py

@@ -0,0 +1,101 @@
+"""
+Validate Role Command - Check AWS role trust without running a full scan.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from cyntrisec.cli.errors import EXIT_CODE_MAP, CyntriError, ErrorCode, handle_errors
+from cyntrisec.cli.output import emit_agent_or_json, resolve_format, suggested_actions
+from cyntrisec.cli.schemas import ValidateRoleResponse
+
+
+@handle_errors
+def validate_role_cmd(
+    role_arn: str = typer.Option(
+        ...,
+        "--role-arn",
+        "-r",
+        help="AWS IAM role ARN to validate",
+    ),
+    external_id: str | None = typer.Option(
+        None,
+        "--external-id",
+        "-e",
+        help="External ID for role assumption",
+    ),
+    profile: str | None = typer.Option(
+        None,
+        "--profile",
+        "-p",
+        help="AWS CLI profile for base credentials",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON",
+    ),
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="Output format: text, json, agent (defaults to json when piped)",
+    ),
+):
+    """
+    Validate that an IAM role can be assumed.
+
+    Performs STS AssumeRole + GetCallerIdentity to verify trust.
+    Useful for testing role configuration before running a full scan.
+
+    Examples:
+
+        cyntrisec validate-role --role-arn arn:aws:iam::123456789012:role/ReadOnly
+
+        cyntrisec validate-role -r arn:aws:iam::123456789012:role/ReadOnly --json
+    """
+    from cyntrisec.aws.credentials import CredentialProvider
+
+    typer.echo(f"Validating role: {role_arn}", err=True)
+    resolved_format = resolve_format(
+        "json" if json_output and format is None else format,
+        default_tty="text",
+        allowed=["text", "json", "agent"],
+    )
+
+    creds = CredentialProvider(profile=profile)
+    try:
+        session = creds.assume_role(role_arn, external_id=external_id)
+    except PermissionError as e:
+        raise CyntriError(
+            error_code=ErrorCode.AWS_ACCESS_DENIED,
+            message=str(e),
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+    identity = session.client("sts").get_caller_identity()
+
+    result = {
+        "success": True,
+        "role_arn": role_arn,
+        "account": identity.get("Account"),
+        "arn": identity.get("Arn"),
+        "user_id": identity.get("UserId"),
+    }
+
+    if resolved_format in {"json", "agent"}:
+        actions = suggested_actions(
+            [
+                (f"cyntrisec scan --role-arn {role_arn}", "Start a scan with the validated role"),
+                ("cyntrisec report --format json", "Export results for audit"),
+            ]
+        )
+        emit_agent_or_json(resolved_format, result, suggested=actions, schema=ValidateRoleResponse)
+    else:
+        typer.echo("", err=True)
+        typer.echo("Role validation successful!", err=True)
+        typer.echo(f"  Account: {identity['Account']}", err=True)
+        typer.echo(f"  ARN: {identity['Arn']}", err=True)
+        typer.echo(f"  UserId: {identity['UserId']}", err=True)
+
+    raise typer.Exit(0)

cyntrisec/cli/waste.py

@@ -0,0 +1,323 @@
+"""
+waste command - Find unused IAM capabilities for blast radius reduction.
+
+Usage:
+    cyntrisec waste [OPTIONS]
+
+Examples:
+    cyntrisec waste                   # Analyze using scan data (no AWS calls)
+    cyntrisec waste --live            # Fetch live usage data from AWS
+    cyntrisec waste --days 90         # Consider unused if not accessed in 90 days
+    cyntrisec waste --format json     # Machine-readable output
+"""
+
+from __future__ import annotations
+
+import logging
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from cyntrisec.cli.errors import EXIT_CODE_MAP, CyntriError, ErrorCode, handle_errors
+from cyntrisec.cli.output import (
+    build_artifact_paths,
+    emit_agent_or_json,
+    resolve_format,
+    suggested_actions,
+)
+from cyntrisec.cli.schemas import WasteResponse
+from cyntrisec.core.cost_estimator import CostEstimator
+from cyntrisec.core.waste import WasteAnalyzer
+from cyntrisec.storage import FileSystemStorage
+
+console = Console()
+status_console = Console(stderr=True)
+log = logging.getLogger(__name__)
+
+
+@handle_errors
+def waste_cmd(
+    days: int = typer.Option(
+        90,
+        "--days",
+        "-d",
+        help="Days threshold for considering a permission unused",
+    ),
+    live: bool = typer.Option(
+        False,
+        "--live",
+        "-l",
+        help="Fetch live usage data from AWS (requires IAM permissions)",
+    ),
+    role_arn: str | None = typer.Option(
+        None,
+        "--role-arn",
+        "-r",
+        help="AWS role to assume for live analysis",
+    ),
+    external_id: str | None = typer.Option(
+        None,
+        "--external-id",
+        "-e",
+        help="External ID for role assumption",
+    ),
+    format: str | None = typer.Option(
+        None,
+        "--format",
+        "-f",
+        help="Output format: table, json, agent (defaults to json when piped)",
+    ),
+    cost_source: str = typer.Option(
+        "estimate",
+        "--cost-source",
+        help="Cost data source: estimate (static), pricing-api, cost-explorer",
+    ),
+    max_roles: int = typer.Option(
+        20,
+        "--max-roles",
+        help="Maximum number of roles to analyze (API throttling)",
+    ),
+    snapshot_id: str | None = typer.Option(
+        None,
+        "--snapshot",
+        "-s",
+        help="Snapshot UUID (default: latest; scan_id accepted)",
+    ),
+):
+    """
+    Analyze IAM roles for unused permissions (blast radius reduction).
+
+    Compares granted permissions against actual usage to identify
+    opportunities to reduce attack surface.
+
+    Without --live, uses heuristic analysis of scan data.
+    With --live, fetches actual usage data from AWS IAM Access Advisor.
+    """
+    output_format = resolve_format(
+        format,
+        default_tty="table",
+        allowed=["table", "json", "agent"],
+    )
+
+    storage = FileSystemStorage()
+    assets = storage.get_assets(snapshot_id)
+    snapshot = storage.get_snapshot(snapshot_id)
+
+    if not assets or not snapshot:
+        raise CyntriError(
+            error_code=ErrorCode.SNAPSHOT_NOT_FOUND,
+            message="No scan data found. Run 'cyntrisec scan' first.",
+            exit_code=EXIT_CODE_MAP["usage"],
+        )
+
+    analyzer = WasteAnalyzer(days_threshold=days)
+    usage_reports = None
+
+    if live:
+        # Fetch real usage data from AWS
+        live_console = console if output_format == "table" else status_console
+        usage_reports = _collect_live_usage(
+            assets,
+            role_arn,
+            external_id,
+            max_roles,
+            status_console=live_console,
+        )
+
+    # Run analysis
+    report = analyzer.analyze_from_assets(assets, usage_reports)
+
+    if output_format in {"json", "agent"}:
+        cost_estimator = CostEstimator(source=cost_source)
+        payload = _build_payload(report, snapshot, days, cost_estimator, assets)
+        actions = suggested_actions(
+            [
+                (
+                    f"cyntrisec comply --snapshot {snapshot.id} --format agent",
+                    "Connect unused permissions to compliance gaps",
+                ),
+                (
+                    f"cyntrisec cuts --snapshot {snapshot.id}",
+                    "Prioritize fixes that remove risky unused permissions",
+                ),
+            ]
+        )
+        emit_agent_or_json(
+            output_format,
+            payload,
+            suggested=actions,
+            artifact_paths=build_artifact_paths(storage, snapshot_id),
+            schema=WasteResponse,
+        )
+    else:
+        _output_table(report, snapshot, days)
+
+
+def _collect_live_usage(assets, role_arn, external_id, max_roles, *, status_console):
+    """Collect live usage data from AWS."""
+    from cyntrisec.aws import CredentialProvider
+    from cyntrisec.aws.collectors.usage import UsageCollector
+
+    status_console.print("[cyan]Fetching live usage data from AWS...[/cyan]")
+
+    provider = CredentialProvider()
+    if role_arn:
+        session = provider.assume_role(role_arn, external_id=external_id)
+    else:
+        session = provider.default_session()
+
+    collector = UsageCollector(session)
+
+    # Get IAM role ARNs from assets
+    role_arns = [a.arn for a in assets if a.asset_type == "iam:role" and a.arn]
+
+    if not role_arns:
+        status_console.print("[yellow]No IAM roles found in scan data.[/yellow]")
+        return []
+
+    status_console.print(f"[dim]Analyzing {min(len(role_arns), max_roles)} roles...[/dim]")
+    return collector.collect_all_roles(role_arns, max_roles=max_roles)
+
+
+def _output_table(report, snapshot, days):
+    """Display results as a rich table."""
+    console.print()
+
+    # Summary panel
+    reduction_pct = report.blast_radius_reduction * 100
+    console.print(
+        Panel(
+            f"[bold]Unused Permissions Analysis[/bold]\n"
+            f"Account: {snapshot.aws_account_id if snapshot else 'unknown'}\n"
+            f"Threshold: {days} days\n"
+            f"Unused: {report.total_unused} / {report.total_permissions} permissions\n"
+            f"Blast Radius Reduction: [green]{reduction_pct:.0f}%[/green]",
+            title="cyntrisec waste",
+            border_style="yellow",
+        )
+    )
+    console.print()
+
+    if not report.role_reports:
+        console.print("[green]No obvious waste found.[/green]")
+        console.print("[dim]Run with --live for detailed IAM Access Advisor analysis.[/dim]")
+        return
+
+    # Table per role with findings
+    for role_report in report.role_reports:
+        if not role_report.unused_capabilities:
+            continue
+
+        table = Table(
+            title=f"Role: {role_report.role_name}",
+            box=box.ROUNDED,
+            show_header=True,
+            header_style="bold yellow",
+        )
+        table.add_column("Risk", style="bold", width=8)
+        table.add_column("Service", width=25)
+        table.add_column("Status", width=20)
+        table.add_column("Recommendation", min_width=30)
+
+        for cap in role_report.unused_capabilities:
+            risk_style = {
+                "critical": "red bold",
+                "high": "red",
+                "medium": "yellow",
+                "low": "dim",
+            }.get(cap.risk_level, "white")
+
+            if cap.days_unused is None:
+                status = "[red]Never used[/red]"
+            else:
+                status = f"[yellow]{cap.days_unused} days[/yellow]"
+
+            table.add_row(
+                f"[{risk_style}]{cap.risk_level.upper()}[/]",
+                cap.service_name,
+                status,
+                cap.recommendation,
+            )
+
+        console.print(table)
+        console.print()
+
+    # Summary
+    console.print(
+        f"[yellow]Remove {report.total_unused} unused permissions to reduce "
+        f"blast radius by {reduction_pct:.0f}%[/yellow]"
+    )
+
+
+def _build_payload(report, snapshot, days, cost_estimator=None, assets=None):
+    """Build structured output with optional cost estimates."""
+    # Build asset lookup for cost estimation
+    asset_lookup = {a.id: a for a in assets} if assets else {}
+
+    return {
+        "snapshot_id": str(snapshot.id) if snapshot else None,
+        "account_id": snapshot.aws_account_id if snapshot else None,
+        "days_threshold": days,
+        "total_permissions": report.total_permissions,
+        "total_unused": report.total_unused,
+        "blast_radius_reduction": report.blast_radius_reduction,
+        "roles": [
+            {
+                "role_arn": r.role_arn,
+                "role_name": r.role_name,
+                "total_services": r.total_services,
+                "unused_services": r.unused_services,
+                "reduction": r.blast_radius_reduction,
+                "unused_capabilities": [
+                    _build_capability_dict(c, r, cost_estimator, asset_lookup)
+                    for c in r.unused_capabilities
+                ],
+            }
+            for r in report.role_reports
+        ],
+    }
+
+
+def _build_capability_dict(c, role_report, cost_estimator, asset_lookup):
+    """Build capability dict with optional cost estimate."""
+    result = {
+        "service": c.service,
+        "service_name": c.service_name,
+        "days_unused": c.days_unused,
+        "risk_level": c.risk_level,
+        "recommendation": c.recommendation,
+    }
+
+    if cost_estimator:
+        estimate = _estimate_service_cost(c.service, asset_lookup, cost_estimator)
+        if estimate:
+            result["monthly_cost_usd_estimate"] = float(estimate.monthly_cost_usd_estimate)
+            result["cost_source"] = estimate.cost_source
+            result["confidence"] = estimate.confidence
+            result["assumptions"] = estimate.assumptions
+        else:
+            result["monthly_cost_usd_estimate"] = None
+            result["cost_source"] = cost_estimator.source
+            result["confidence"] = "unknown"
+            result["assumptions"] = ["No cost estimate available for this service"]
+
+    return result
+
+
+def _estimate_service_cost(service: str, asset_lookup: dict, cost_estimator: CostEstimator):
+    """Estimate cost for a service by inspecting matching assets."""
+    if not service or service in {"*", "unknown"}:
+        return None
+    best = None
+    for asset in asset_lookup.values():
+        if not asset.asset_type.startswith(f"{service}:"):
+            continue
+        estimate = cost_estimator.estimate(asset)
+        if not estimate:
+            continue
+        if not best or estimate.monthly_cost_usd_estimate > best.monthly_cost_usd_estimate:
+            best = estimate
+    return best