FinOps Alert CLI

⚠️ SECURITY NOTICE — SANITIZATION IN PROGRESS

This tool is currently running in a production environment to audit the hybrid infrastructure of a confidential client’s portfolio within the IT industry.

The source code still contains:

• Hardcoded internal Slack webhook URLs
• Organization-specific API constraints

These elements are being abstracted into a generic configuration model
(e.g. .env.example) prior to public release.

Estimated public release: Q1 2026

---

📖 Overview

FinOps Alert CLI is a lightweight, type-safe governance tool designed to monitor the Management Plane (Hetzner) of a hybrid cloud architecture.

While the Production Plane on Oracle Cloud Infrastructure (OCI) benefits from fixed or free-tier pricing, the Management Plane on Hetzner is billed hourly. This tool acts as an automated financial auditor, detecting zombie resources before they silently drain the budget.

---

❗ The Problem

Uncontrolled management infrastructure introduces financial blind spots:

• Orphaned Volumes
  Storage volumes left behind after staging environments are destroyed
• Unused IPs
  Floating IPs reserved but not attached to any server
• Cost Drift
  Gradual monthly spend increases that evade manual reviews

---

✅ The Solution

A cron-driven CLI that enforces governance as code:

1. Query the Hetzner Cloud API
2. Apply FinOps heuristics (zombie detection)
3. Calculate real-time run-rate
4. Dispatch alerts to Slack or Discord when thresholds are breached

---

⚙️ Execution Flow

The tool runs daily at 09:00 UTC inside a Docker container within the Management Swarm.

graph LR
    Cron[Cron Job] --> CLI[FinOps CLI]
    CLI -->|Query| API[Hetzner API]
    API -->|JSON| CLI
    CLI -->|Validate| Pydantic[Pydantic Models]
    Pydantic -->|Analyze| Logic{Audit Logic}
    Logic -->|Healthy| Log[Silent Log]
    Logic -->|Anomaly| Slack[Slack Alert]

Loading

---

🛠️ Development Roadmap

This roadmap tracks the evolution from a simple script to a production-grade CLI.

Phase 1 — Core Logic (Python) ✅

• Python 3.11 environment with Poetry
• Hetzner API integration via hcloud
• Initial server enumeration logic

Phase 2 — Data Modeling (Pydantic) ✅

• Replace raw dictionaries with typed Pydantic models
• Implement Decimal-based cost modeling
• Map Hetzner regions (Ashburn vs. Nuremberg) to pricing tiers

Phase 3 — CLI Experience (Typer) ✅

• Integrate Typer for argument parsing

• Implement commands:

  • audit
  • forecast
  • cleanup-dry-run

• Add --json output for observability pipelines

Phase 4 — Notifications ✅

• Slack & Gmail webhook adapter
• Rich message formatting (severity indicators)
• Zombie detection (unattached volumes)

Phase 5 — Open Source Preparation 🚧 (Current Stage)

• Externalize configuration (ENV / YAML)
• Optimize Dockerfile (multi-stage build)
• Write contribution guidelines
• Publish to GitHub
• Publish to PyPI

---

💻 Code Architecture

The project prioritizes type safety to prevent financial miscalculations.

---

Data Models (models.py)

All API responses are validated before any financial logic is applied.

from pydantic import BaseModel
from decimal import Decimal
from typing import Optional

class ResourceCost(BaseModel):
    resource_id: int
    name: str
    resource_type: str  # server | volume | floating_ip
    monthly_price: Decimal
    attached_to: Optional[int] = None

    @property
    def is_zombie(self) -> bool:
        """
        A resource is considered a zombie if it incurs cost
        without providing utility.
        """
        return self.resource_type == "volume" and self.attached_to is None

---

Audit Logic (audit.py)

The auditor computes the total run-rate and compares it against a defined threshold.

from decimal import Decimal

def check_budget(threshold: Decimal = Decimal("20.00")):
    total_spend = calculator.get_total_run_rate()

    if total_spend > threshold:
        slack_client.send_alert(
            title="💸 Budget Breach Detected",
            message=(
                f"Current run-rate is €{total_spend}, "
                f"exceeding the limit of €{threshold}."
            ),
            color="#FF0000",  # Red
        )

---

📦 Technology Stack

Component	Technology	Rationale
Language	Python 3.11	Modern syntax, strong typing
CLI Framework	Typer	Excellent DX, auto-generated help
Validation	Pydantic	Strict schema enforcement
Container	Docker (Alpine)	Minimal footprint (~50 MB image)

---

📬 Contact

Maintained by: Miguel Lozano — Cloud Infrastructure Engineer

• Website: developmi.com
• Role: This tool safeguards the financial integrity of a confidential client’s portfolio within the IT industry.
• Inquiries: Please reach out via LinkedIn for architecture consulting

---

© 2025 Miguel Lozano. All rights reserved.