finops-guard 0.1.0

Automated, Developer-First Local Cloud Cost Tracing & Linting

FinOps-Guard 💲🛡️

Automated, Developer-First Local Cloud Cost Tracing & Linting

FinOps-Guard acts as a "linter" for cloud costs and efficiency, running locally on developers' machines or within CI/CD pipelines. It bridges the gap between infrastructure configuration (Terraform) and application code efficiency (Python/JS/TS) to predict cost anomalies before they hit production.

---

🚀 Key Features

• Static Cost Estimation: Parse Terraform configurations locally and map them against cached, offline pricing datasets (pricing_db.json) to show the monthly dollar impact right in the terminal. No cloud API access or terraform credentials required!
• Code-to-Cloud Tracing: Analyze application source code statically (using AST parsing for Python and token-based heuristics for JavaScript/TypeScript) to detect inefficient loops containing synchronous API calls or cloud SDK invocations.
• FinOps Commit Hooks: Interactively prompt developers during git commit if changes exceed a cost threshold (e.g. $100/mo), preventing accidental expensive configurations from reaching staging or production.

---

🗺️ High-Level Launch Architecture

To bridge developer tools with commercial platforms, FinOps-Guard operates on a hybrid model:

• Free CLI / Hooks: Runs locally or in CI pipelines.
• SaaS / Self-Hosted Ingestion: Aggregates reports for dashboard visibility, billing reconciliation, and license-based policy enforcement.

---

📂 Project Structure

finopsguard/
├── finops_guard/
│   ├── __init__.py
│   ├── cli.py             # CLI command orchestrator (lint, trace, hook)
│   ├── iac_parser.py      # Local HCL resource block and JSON plan parser
│   ├── cost_estimator.py  # Mapping resource metrics to pricing configurations
│   ├── code_tracer.py     # AST-based static analyzer for loop-bound API calls
│   ├── pre_commit.py      # Git hook integration logic
│   └── data/
│       └── pricing_db.json # Offline cache of AWS & GCP pricing rates
├── examples/
│   ├── terraform/         # Sample IaC configs with expensive DB/compute resources
│   └── app/               # Sample application script with synchronous loops
├── tests/                 # Comprehensive unit test suite
│   ├── test_iac_parser.py
│   ├── test_cost_estimator.py
│   └── test_code_tracer.py
├── pyproject.toml         # Packaging file (setuptools metadata)
└── ROADMAP.md             # Monetization strategies, extensions, and growth steps

---

💻 Installation

Install the package in editable mode locally:

pip install -e .

---

🛠️ Usage

1. Estimating Infrastructure Costs (Linting)

Run the static cost estimator on a Terraform directory or a single .tf/plan.json file:

finops-guard lint examples/terraform

Output includes a detailed table of predicted monthly costs, service breakdowns, and annual projections.

2. Tracing Application Code (Code-to-Cloud Tracing)

Scan codebases for costly synchronous network calls or cloud API calls nested in loops:

finops-guard trace examples/app

Flags synchronous requests inside loop blocks with nesting details and code snippets.

3. Setting Up pre-commit Hooks

Add FinOps-Guard directly to your git pre-commit workflow. You can run the hook check manually:

finops-guard hook examples/terraform --threshold 100 --strict

To configure it as a Git pre-commit hook automatically:

1. Create or edit .git/hooks/pre-commit in your git repository.
2. Add the following line:

   finops-guard hook . --threshold 100
   

3. Make the hook executable: chmod +x .git/hooks/pre-commit.

---

🧪 Testing

Run the automated test suite with Python's built-in unittest module:

python -m unittest discover -s tests