runbooks 0.2.5__py3-none-any.whl → 0.7.0__py3-none-any.whl

runbooks/finops/helpers.py

@@ -0,0 +1,355 @@
+import csv  # Added csv
+import json
+import os
+import re
+import sys
+import tomllib  # Built-in since Python 3.11
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import yaml
+from reportlab.lib import colors
+from reportlab.lib.pagesizes import landscape, letter
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.platypus import (
+    Flowable,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+from rich.console import Console
+
+from runbooks.finops.types import ProfileData
+
+console = Console()
+
+styles = getSampleStyleSheet()
+
+# Custom style for the footer
+audit_footer_style = ParagraphStyle(
+    name="AuditFooter",
+    parent=styles["Normal"],
+    fontSize=8,
+    textColor=colors.grey,
+    alignment=1,
+    leading=10,
+)
+
+
+def export_audit_report_to_pdf(
+    audit_data_list: List[Dict[str, str]],
+    file_name: str = "audit_report",
+    path: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Export the audit report to a PDF file.
+
+    :param audit_data_list: List of dictionaries, each representing a profile/account's audit data.
+    :param file_name: The base name of the output PDF file.
+    :param path: Optional directory where the PDF file will be saved.
+    :return: Full path of the generated PDF file or None on error.
+    """
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        base_filename = f"{file_name}_{timestamp}.pdf"
+
+        if path:
+            os.makedirs(path, exist_ok=True)
+            output_filename = os.path.join(path, base_filename)
+        else:
+            output_filename = base_filename
+
+        doc = SimpleDocTemplate(output_filename, pagesize=landscape(letter))
+        styles = getSampleStyleSheet()
+        elements: List[Flowable] = []
+
+        headers = [
+            "Profile",
+            "Account ID",
+            "Untagged Resources",
+            "Stopped EC2 Instances",
+            "Unused Volumes",
+            "Unused EIPs",
+            "Budget Alerts",
+        ]
+        table_data = [headers]
+
+        for row in audit_data_list:
+            table_data.append(
+                [
+                    row.get("profile", ""),
+                    row.get("account_id", ""),
+                    row.get("untagged_resources", ""),
+                    row.get("stopped_instances", ""),
+                    row.get("unused_volumes", ""),
+                    row.get("unused_eips", ""),
+                    row.get("budget_alerts", ""),
+                ]
+            )
+
+        table = Table(table_data, repeatRows=1)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.black),
+                    ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
+                    ("FONTNAME", (0, 0), (-1, -1), "Helvetica"),
+                    ("FONTSIZE", (0, 0), (-1, -1), 8),
+                    ("ALIGN", (0, 0), (-1, -1), "LEFT"),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("GRID", (0, 0), (-1, -1), 0.25, colors.black),
+                    ("BACKGROUND", (0, 1), (-1, -1), colors.whitesmoke),
+                ]
+            )
+        )
+
+        elements.append(Paragraph("AWS FinOps Dashboard (Audit Report)", styles["Title"]))
+        elements.append(Spacer(1, 12))
+        elements.append(table)
+        elements.append(Spacer(1, 4))
+        elements.append(
+            Paragraph(
+                "Note: This table lists untagged EC2, RDS, Lambda, ELBv2 only.",
+                audit_footer_style,
+            )
+        )
+        elements.append(Spacer(1, 2))
+        current_time_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        footer_text = (
+            f"This audit report is generated using AWS FinOps Dashboard (CLI) \u00a9 2025 on {current_time_str}"
+        )
+        elements.append(Paragraph(footer_text, audit_footer_style))
+
+        doc.build(elements)
+        return output_filename
+    except Exception as e:
+        console.print(f"[bold red]Error exporting audit report to PDF: {str(e)}[/]")
+        return None
+
+
+def clean_rich_tags(text: str) -> str:
+    """
+    Clean the rich text before writing the data to a pdf.
+
+    :param text: The rich text to clean.
+    :return: Cleaned text.
+    """
+    return re.sub(r"\[/?[a-zA-Z0-9#_]*\]", "", text)
+
+
+def export_audit_report_to_csv(
+    audit_data_list: List[Dict[str, str]],
+    file_name: str = "audit_report",
+    path: Optional[str] = None,
+) -> Optional[str]:
+    """Export the audit report to a CSV file."""
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        base_filename = f"{file_name}_{timestamp}.csv"
+        output_filename = base_filename
+        if path:
+            os.makedirs(path, exist_ok=True)
+            output_filename = os.path.join(path, base_filename)
+
+        headers = [
+            "Profile",
+            "Account ID",
+            "Untagged Resources",
+            "Stopped EC2 Instances",
+            "Unused Volumes",
+            "Unused EIPs",
+            "Budget Alerts",
+        ]
+        # Corresponding keys in the audit_data_list dictionaries
+        data_keys = [
+            "profile",
+            "account_id",
+            "untagged_resources",
+            "stopped_instances",
+            "unused_volumes",
+            "unused_eips",
+            "budget_alerts",
+        ]
+
+        with open(output_filename, "w", newline="") as csvfile:
+            writer = csv.writer(csvfile)
+            writer.writerow(headers)
+            for item in audit_data_list:
+                writer.writerow([item.get(key, "") for key in data_keys])
+        return output_filename
+    except Exception as e:
+        console.print(f"[bold red]Error exporting audit report to CSV: {str(e)}[/]")
+        return None
+
+
+def export_audit_report_to_json(
+    raw_audit_data: List[Dict[str, Any]], file_name: str = "audit_report", path: Optional[str] = None
+) -> Optional[str]:
+    """Export the audit report to a JSON file."""
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        base_filename = f"{file_name}_{timestamp}.json"
+        output_filename = base_filename
+        if path:
+            os.makedirs(path, exist_ok=True)
+            output_filename = os.path.join(path, base_filename)
+
+        with open(output_filename, "w", encoding="utf-8") as jsonfile:
+            json.dump(raw_audit_data, jsonfile, indent=4)  # Use the structured list
+        return output_filename
+    except Exception as e:
+        console.print(f"[bold red]Error exporting audit report to JSON: {str(e)}[/]")
+        return None
+
+
+def export_trend_data_to_json(
+    trend_data: List[Dict[str, Any]], file_name: str = "trend_data", path: Optional[str] = None
+) -> Optional[str]:
+    """Export trend data to a JSON file."""
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        base_filename = f"{file_name}_{timestamp}.json"
+        output_filename = base_filename
+        if path:
+            os.makedirs(path, exist_ok=True)
+            output_filename = os.path.join(path, base_filename)
+
+        with open(output_filename, "w", encoding="utf-8") as jsonfile:
+            json.dump(trend_data, jsonfile, indent=4)
+        return output_filename
+    except Exception as e:
+        console.print(f"[bold red]Error exporting trend data to JSON: {str(e)}[/]")
+        return None
+
+
+def export_cost_dashboard_to_pdf(
+    data: List[ProfileData],
+    filename: str,
+    output_dir: Optional[str] = None,
+    previous_period_dates: str = "N/A",
+    current_period_dates: str = "N/A",
+) -> Optional[str]:
+    """Export dashboard data to a PDF file."""
+    try:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        base_filename = f"{filename}_{timestamp}.pdf"
+
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+            output_filename = os.path.join(output_dir, base_filename)
+        else:
+            output_filename = base_filename
+
+        doc = SimpleDocTemplate(output_filename, pagesize=landscape(letter))
+        styles = getSampleStyleSheet()
+        elements: List[Flowable] = []
+
+        previous_period_header = f"Cost for period\n({previous_period_dates})"
+        current_period_header = f"Cost for period\n({current_period_dates})"
+
+        headers = [
+            "CLI Profile",
+            "AWS Account ID",
+            previous_period_header,
+            current_period_header,
+            "Cost By Service",
+            "Budget Status",
+            "EC2 Instances",
+        ]
+        table_data = [headers]
+
+        for row in data:
+            services_data = "\n".join([f"{service}: ${cost:.2f}" for service, cost in row["service_costs"]])
+            budgets_data = "\n".join(row["budget_info"]) if row["budget_info"] else "No budgets"
+            ec2_data_summary = "\n".join(
+                [f"{state}: {count}" for state, count in row["ec2_summary"].items() if count > 0]
+            )
+
+            table_data.append(
+                [
+                    row["profile"],
+                    row["account_id"],
+                    f"${row['last_month']:.2f}",
+                    f"${row['current_month']:.2f}",
+                    services_data or "No costs",
+                    budgets_data or "No budgets",
+                    ec2_data_summary or "No instances",
+                ]
+            )
+
+        table = Table(table_data, repeatRows=1)
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.black),
+                    ("TEXTCOLOR", (0, 0), (-1, 0), colors.whitesmoke),
+                    ("FONTNAME", (0, 0), (-1, -1), "Helvetica"),
+                    ("FONTSIZE", (0, 0), (-1, -1), 8),
+                    ("ALIGN", (0, 0), (-1, -1), "LEFT"),
+                    ("VALIGN", (0, 0), (-1, -1), "TOP"),
+                    ("GRID", (0, 0), (-1, -1), 0.25, colors.grey),
+                    ("BACKGROUND", (0, 1), (-1, -1), colors.whitesmoke),
+                ]
+            )
+        )
+
+        elements.append(Paragraph("AWS FinOps Dashboard (Cost Report)", styles["Title"]))
+        elements.append(Spacer(1, 12))
+        elements.append(table)
+        elements.append(Spacer(1, 4))
+        current_time_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        footer_text = f"This report is generated using AWS FinOps Dashboard (CLI) \u00a9 2025 on {current_time_str}"
+        elements.append(Paragraph(footer_text, audit_footer_style))
+
+        doc.build(elements)
+        return os.path.abspath(output_filename)
+    except Exception as e:
+        console.print(f"[bold red]Error exporting to PDF: {str(e)}[/]")
+        return None
+
+
+def load_config_file(file_path: str) -> Optional[Dict[str, Any]]:
+    """Load configuration from TOML, YAML, or JSON file."""
+    _, file_extension = os.path.splitext(file_path)
+    file_extension = file_extension.lower()
+
+    try:
+        with open(file_path, "rb" if file_extension == ".toml" else "r") as f:
+            if file_extension == ".toml":
+                loaded_data = tomllib.load(f)
+                if isinstance(loaded_data, dict):
+                    return loaded_data
+                console.print(f"[bold red]Error: TOML file {file_path} did not load as a dictionary.[/]")
+                return None
+            elif file_extension in [".yaml", ".yml"]:
+                loaded_data = yaml.safe_load(f)
+                if isinstance(loaded_data, dict):
+                    return loaded_data
+                console.print(f"[bold red]Error: YAML file {file_path} did not load as a dictionary.[/]")
+                return None
+            elif file_extension == ".json":
+                loaded_data = json.load(f)
+                if isinstance(loaded_data, dict):
+                    return loaded_data
+                console.print(f"[bold red]Error: JSON file {file_path} did not load as a dictionary.[/]")
+                return None
+            else:
+                console.print(f"[bold red]Error: Unsupported configuration file format: {file_extension}[/]")
+                return None
+    except FileNotFoundError:
+        console.print(f"[bold red]Error: Configuration file not found: {file_path}[/]")
+        return None
+    except tomllib.TOMLDecodeError as e:
+        console.print(f"[bold red]Error decoding TOML file {file_path}: {e}[/]")
+        return None
+    except yaml.YAMLError as e:
+        console.print(f"[bold red]Error decoding YAML file {file_path}: {e}[/]")
+        return None
+    except json.JSONDecodeError as e:
+        console.print(f"[bold red]Error decoding JSON file {file_path}: {e}[/]")
+        return None
+    except Exception as e:
+        console.print(f"[bold red]Error loading configuration file {file_path}: {e}[/]")
+        return None

runbooks/finops/main.py

@@ -0,0 +1,14 @@
+import argparse
+import sys
+from typing import Dict, List, Optional
+
+from runbooks.finops.cli import main as cli_main_entry
+
+
+def main() -> int:
+    """Entry point for the finops submodule when run directly."""
+    return cli_main_entry()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

runbooks/finops/profile_processor.py

@@ -0,0 +1,174 @@
+from collections import defaultdict
+from typing import Dict, List, Optional
+
+import boto3
+from rich.console import Console
+
+from runbooks.finops.aws_client import (
+    ec2_summary,
+    get_accessible_regions,
+)
+from runbooks.finops.cost_processor import (
+    change_in_total_cost,
+    format_budget_info,
+    format_ec2_summary,
+    get_cost_data,
+    process_service_costs,
+)
+from runbooks.finops.types import (
+    BudgetInfo,
+    CostData,
+    ProfileData,
+)
+
+console = Console()
+
+
+def process_single_profile(
+    profile: str,
+    user_regions: Optional[List[str]] = None,
+    time_range: Optional[int] = None,
+    tag: Optional[List[str]] = None,
+) -> ProfileData:
+    """Process a single AWS profile and return its data."""
+    try:
+        session = boto3.Session(profile_name=profile)
+        cost_data = get_cost_data(session, time_range, tag)
+
+        if user_regions:
+            profile_regions = user_regions
+        else:
+            profile_regions = get_accessible_regions(session)
+
+        ec2_data = ec2_summary(session, profile_regions)
+        service_costs, service_cost_data = process_service_costs(cost_data)
+        budget_info = format_budget_info(cost_data["budgets"])
+        account_id = cost_data.get("account_id", "Unknown") or "Unknown"
+        ec2_summary_text = format_ec2_summary(ec2_data)
+        percent_change_in_total_cost = change_in_total_cost(cost_data["current_month"], cost_data["last_month"])
+
+        return {
+            "profile": profile,
+            "account_id": account_id,
+            "last_month": cost_data["last_month"],
+            "current_month": cost_data["current_month"],
+            "service_costs": service_cost_data,
+            "service_costs_formatted": service_costs,
+            "budget_info": budget_info,
+            "ec2_summary": ec2_data,
+            "ec2_summary_formatted": ec2_summary_text,
+            "success": True,
+            "error": None,
+            "current_period_name": cost_data["current_period_name"],
+            "previous_period_name": cost_data["previous_period_name"],
+            "percent_change_in_total_cost": percent_change_in_total_cost,
+        }
+
+    except Exception as e:
+        return {
+            "profile": profile,
+            "account_id": "Error",
+            "last_month": 0,
+            "current_month": 0,
+            "service_costs": [],
+            "service_costs_formatted": [f"Failed to process profile: {str(e)}"],
+            "budget_info": ["N/A"],
+            "ec2_summary": {"N/A": 0},
+            "ec2_summary_formatted": ["Error"],
+            "success": False,
+            "error": str(e),
+            "current_period_name": "Current month",
+            "previous_period_name": "Last month",
+            "percent_change_in_total_cost": None,
+        }
+
+
+def process_combined_profiles(
+    account_id: str,
+    profiles: List[str],
+    user_regions: Optional[List[str]] = None,
+    time_range: Optional[int] = None,
+    tag: Optional[List[str]] = None,
+) -> ProfileData:
+    """Process multiple profiles from the same AWS account."""
+
+    primary_profile = profiles[0]
+    primary_session = boto3.Session(profile_name=primary_profile)
+
+    account_cost_data: CostData = {
+        "account_id": account_id,
+        "current_month": 0.0,
+        "last_month": 0.0,
+        "current_month_cost_by_service": [],
+        "budgets": [],
+        "current_period_name": "Current month",
+        "previous_period_name": "Last month",
+        "time_range": time_range,
+        "current_period_start": "N/A",
+        "current_period_end": "N/A",
+        "previous_period_start": "N/A",
+        "previous_period_end": "N/A",
+        "monthly_costs": None,
+    }
+
+    try:
+        # Attempt to overwrite with actual data from Cost Explorer
+        account_cost_data = get_cost_data(primary_session, time_range, tag)
+    except Exception as e:
+        console.log(f"[bold red]Error getting cost data for account {account_id}: {str(e)}[/]")
+        # account_cost_data retains its default values if an error occurs
+
+    combined_current_month = account_cost_data["current_month"]
+    combined_last_month = account_cost_data["last_month"]
+    combined_service_costs_dict: Dict[str, float] = defaultdict(float)
+
+    for group in account_cost_data["current_month_cost_by_service"]:
+        if "Keys" in group and "Metrics" in group:
+            service_name = group["Keys"][0]
+            cost_amount = float(group["Metrics"]["UnblendedCost"]["Amount"])
+            if cost_amount > 0.001:
+                combined_service_costs_dict[service_name] += cost_amount
+
+    combined_budgets = account_cost_data["budgets"]
+
+    if user_regions:
+        primary_regions = user_regions
+    else:
+        primary_regions = get_accessible_regions(primary_session)
+
+    combined_ec2 = ec2_summary(primary_session, primary_regions)
+
+    service_costs = []
+    service_cost_data = [(service, cost) for service, cost in combined_service_costs_dict.items() if cost > 0.001]
+    service_cost_data.sort(key=lambda x: x[1], reverse=True)
+
+    if not service_cost_data:
+        service_costs.append("No costs associated with this account")
+    else:
+        for service_name, cost_amount in service_cost_data:
+            service_costs.append(f"{service_name}: ${cost_amount:.2f}")
+
+    budget_info = format_budget_info(combined_budgets)
+
+    ec2_summary_text = format_ec2_summary(combined_ec2)
+
+    profile_list = ", ".join(profiles)
+
+    percent_change_in_total_cost = change_in_total_cost(combined_current_month, combined_last_month)
+
+    return {
+        "profile": profile_list,
+        "account_id": account_id,
+        "last_month": combined_last_month,
+        "current_month": combined_current_month,
+        "service_costs": service_cost_data,
+        "service_costs_formatted": service_costs,
+        "budget_info": budget_info,
+        "ec2_summary": combined_ec2,
+        "ec2_summary_formatted": ec2_summary_text,
+        "success": True,
+        "error": None,
+        "current_period_name": account_cost_data["current_period_name"],
+        "previous_period_name": account_cost_data["previous_period_name"],
+        "percent_change_in_total_cost": percent_change_in_total_cost,
+    }

runbooks/finops/types.py

@@ -0,0 +1,66 @@
+"""Type definitions for AWS FinOps Dashboard."""
+
+from typing import Dict, List, Optional, Tuple, TypedDict
+
+
+class BudgetInfo(TypedDict):
+    """Type for a budget entry."""
+
+    name: str
+    limit: float
+    actual: float
+    forecast: Optional[float]
+
+
+class CostData(TypedDict):
+    """Type for cost data returned from AWS Cost Explorer."""
+
+    account_id: Optional[str]
+    current_month: float
+    last_month: float
+    current_month_cost_by_service: List[Dict]
+    budgets: List[BudgetInfo]
+    current_period_name: str
+    previous_period_name: str
+    time_range: Optional[int]
+    current_period_start: str
+    current_period_end: str
+    previous_period_start: str
+    previous_period_end: str
+    monthly_costs: Optional[List[Tuple[str, float]]]
+
+
+class ProfileData(TypedDict):
+    """Type for processed profile data."""
+
+    profile: str
+    account_id: str
+    last_month: float
+    current_month: float
+    service_costs: List[Tuple[str, float]]
+    service_costs_formatted: List[str]
+    budget_info: List[str]
+    ec2_summary: Dict[str, int]
+    ec2_summary_formatted: List[str]
+    success: bool
+    error: Optional[str]
+    current_period_name: str
+    previous_period_name: str
+    percent_change_in_total_cost: Optional[float]
+
+
+class CLIArgs(TypedDict, total=False):
+    """Type for CLI arguments."""
+
+    profiles: Optional[List[str]]
+    regions: Optional[List[str]]
+    all: bool
+    combine: bool
+    report_name: Optional[str]
+    report_type: Optional[List[str]]
+    dir: Optional[str]
+    time_range: Optional[int]
+
+
+RegionName = str
+EC2Summary = Dict[str, int]

runbooks/finops/visualisations.py

@@ -0,0 +1,80 @@
+from decimal import ROUND_HALF_UP, Decimal, getcontext
+from typing import List, Tuple
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+# Set precision context for Decimal operations
+getcontext().prec = 6
+
+console = Console()
+
+
+def create_trend_bars(monthly_costs: List[Tuple[str, float]]) -> None:
+    """Create colorful trend bars using Rich's styling and precise Decimal math."""
+    if not monthly_costs:
+        return
+
+    table = Table(box=None, padding=(1, 1), collapse_padding=True)
+
+    table.add_column("Month", style="bright_magenta", width=10)
+    table.add_column("Cost", style="bright_cyan", justify="right", width=15)
+    table.add_column("", width=50)
+    table.add_column("MoM Change", style="bright_yellow", width=12)
+
+    max_cost = max(cost for _, cost in monthly_costs)
+    if max_cost == 0:
+        console.print("[yellow]All costs are $0.00 for this period[/]")
+        return
+
+    prev_cost = None
+
+    for month, cost in monthly_costs:
+        cost_d = Decimal(str(cost))
+        bar_length = int((cost / max_cost) * 40) if max_cost > 0 else 0
+        bar = "█" * bar_length
+
+        # Default values
+        bar_color = "blue"
+        change = ""
+
+        if prev_cost is not None:
+            prev_d = Decimal(str(prev_cost))
+
+            if prev_d < Decimal("0.01"):
+                if cost_d < Decimal("0.01"):
+                    change = "[bright_yellow]0%[/]"
+                    bar_color = "yellow"
+                else:
+                    change = "[bright_red]N/A[/]"
+                    bar_color = "bright_red"
+            else:
+                change_pct = ((cost_d - prev_d) / prev_d * Decimal("100")).quantize(
+                    Decimal("0.01"), rounding=ROUND_HALF_UP
+                )
+
+                if abs(change_pct) < Decimal("0.01"):
+                    change = "[bright_yellow]0%[/]"
+                    bar_color = "yellow"
+                elif abs(change_pct) > Decimal("999"):
+                    color = "bright_red" if change_pct > 0 else "bright_green"
+                    change = f"[{color}]{'>+' if change_pct > 0 else '-'}999%[/]"
+                    bar_color = color
+                else:
+                    color = "bright_red" if change_pct > 0 else "bright_green"
+                    sign = "+" if change_pct > 0 else ""
+                    change = f"[{color}]{sign}{change_pct}%[/]"
+                    bar_color = color
+
+        table.add_row(month, f"${cost:,.2f}", f"[{bar_color}]{bar}[/]", change)
+        prev_cost = cost
+
+    console.print(
+        Panel(
+            table,
+            title="[cyan]AWS Cost Trend Analysis[/]",
+            border_style="bright_blue",
+            padding=(1, 1),
+        )
+    )