FinOpsGuard

MCP agent providing cost-aware guardrails for IaC in CI/CD with advanced policy enforcement.

Overview

• Cost Analysis: Analyzes IaC changes and provides accurate cost projections
• Policy Engine: Enforces budget rules and resource constraints with blocking/advisory modes
• Multi-Cloud Support: AWS, GCP, and Azure pricing adapters with support for multiple resource types
• CI/CD Integration: Seamless integration with GitHub/GitLab CI for automated cost governance
• FastAPI Server: Modern Python API with auto-generated OpenAPI documentation

Current Status (MVP+ Complete) ✅

Core MCP Endpoints

• POST /mcp/checkCostImpact - Cost analysis with integrated policy evaluation
• POST /mcp/evaluatePolicy - Dedicated policy evaluation with blocking mode
• POST /mcp/suggestOptimizations - Cost optimization recommendations
• POST /mcp/getPriceCatalog - Cloud pricing information
• POST /mcp/listRecentAnalyses - Historical analysis tracking
• GET /healthz - Health check endpoint
• GET /metrics - Prometheus metrics

Policy Management API

• GET /mcp/policies - List all policies
• GET /mcp/policies/{id} - Get specific policy
• POST /mcp/policies - Create new policy
• PUT /mcp/policies/{id} - Update existing policy
• DELETE /mcp/policies/{id} - Delete policy

Usage Integration API

• GET /usage/availability - Check cloud provider availability
• POST /usage/resource - Get resource metrics (CloudWatch, Cloud Monitoring, Azure Monitor)
• POST /usage/cost - Get historical cost data (Cost Explorer, Cloud Billing, Cost Management)
• POST /usage/summary - Generate comprehensive usage summary
• GET /usage/example/{provider} - Get example usage data
• DELETE /usage/cache - Clear usage data cache

Webhook Management API

• GET /webhooks - List all webhook configurations
• POST /webhooks - Create new webhook configuration
• GET /webhooks/{id} - Get specific webhook configuration
• PUT /webhooks/{id} - Update webhook configuration
• DELETE /webhooks/{id} - Delete webhook configuration
• GET /webhooks/{id}/deliveries - List webhook delivery attempts
• GET /webhooks/stats - Get webhook delivery statistics

Admin UI

• GET / - Modern web interface for policy and analysis management
• Dashboard: Real-time metrics and activity overview
• Policy Management: Visual policy builder with rule editor
• Analysis History: Detailed cost analysis results and trends
• Settings: Configuration management and system settings

CI/CD Integration

• GitHub Actions: Ready-to-use workflow for automated cost checking
• GitLab CI: Reusable job template for GitLab pipelines
• CLI Tool: Command-line interface for any CI/CD platform
• Universal Script: Cross-platform bash script for CI/CD integration
• PR/MR Comments: Automated posting of cost analysis results

Features

• ✅ Terraform Parser: Modular HCL parsing with 60+ resource types across AWS (24), GCP (18), and Azure (18)
• ✅ Ansible Parser: Comprehensive YAML parsing with 58+ module types across AWS (20), GCP (18), and Azure (20)
• ✅ Cost Simulation: Accurate monthly/weekly cost projections for multi-cloud infrastructure
• ✅ Policy Engine: Budget and rule-based policies with DSL support
• ✅ Blocking Mode: Policy violations can block deployments
• ✅ Real-time Pricing: Live pricing APIs for AWS, GCP, and Azure with intelligent fallback
• ✅ Usage Integration: Historical usage data from CloudWatch, Cloud Monitoring, and Azure Monitor
  • AWS: CloudWatch metrics and Cost Explorer for actual resource usage and billing
  • GCP: Cloud Monitoring metrics and BigQuery billing export for usage analytics
  • Azure: Azure Monitor metrics and Cost Management for cost and usage tracking
• ✅ Webhooks: Event-driven notifications for cost anomalies and policy changes
  • Cost Anomalies: Automatic alerts for budget violations, cost spikes, and high-cost resources
  • Policy Events: Notifications for policy creation, updates, and deletions
  • Retry Logic: Robust delivery with configurable retry attempts and timeouts
  • HMAC Signatures: Secure webhook verification with cryptographic signatures
  • Background Processing: Asynchronous delivery with proper error handling
• ✅ Authentication: API keys, JWT tokens, OAuth2 (GitHub/Google/Azure), mTLS support
• ✅ RBAC: Role-based access control (admin, user, viewer, api)
• ✅ PostgreSQL Storage: Persistent policies and analysis history
• ✅ Redis Caching: Intelligent caching for pricing data and analysis results with automatic TTL management
• ✅ Multi-Cloud Support:
  • AWS: EC2, RDS, EKS, ElastiCache, DynamoDB, Redshift, OpenSearch, Load Balancers
  • GCP: Compute Engine, Cloud SQL, GKE, Cloud Run, Cloud Functions, Load Balancers, Redis, BigQuery
  • Azure: Virtual Machines, SQL Database, Storage, AKS, App Service, Functions, Load Balancer, Redis, Cosmos DB
• ✅ Auto-generated OpenAPI: Complete API documentation at /docs
• ✅ Admin UI: Modern web interface for management and monitoring
• ✅ CI/CD Integration: Seamless integration with GitHub Actions and GitLab CI

Repo Structure

src/finopsguard/
  api/                 # FastAPI server and MCP endpoints
  adapters/
    pricing/           # Cloud pricing adapters (static + live APIs for AWS/GCP/Azure)
    usage/             # Historical usage adapters (CloudWatch, Monitoring, Cost Management)
  auth/                # Authentication & authorization (API keys, JWT, OAuth2, mTLS)
  audit/               # Audit logging and compliance reporting
  cache/               # Redis caching layer (pricing, analysis, policies)
  database/            # PostgreSQL persistent storage (policies, analyses, audit logs)
  engine/              # Cost simulation and policy evaluation
  parsers/             # Infrastructure parsers (Terraform HCL + Ansible YAML)
    terraform.py       # Terraform orchestrator (93 lines)
    aws_tf_parser.py   # AWS Terraform parsing (24 types)
    gcp_tf_parser.py   # GCP Terraform parsing (18 types)
    azure_tf_parser.py # Azure Terraform parsing (18 types)
    ansible.py         # Ansible orchestrator (210 lines)
    aws_ansible_parser.py   # AWS Ansible parsing (20 types)
    gcp_ansible_parser.py   # GCP Ansible parsing (18 types)
    azure_ansible_parser.py # Azure Ansible parsing (20 types)
  storage/             # Hybrid storage (in-memory + database)
  types/               # Pydantic models and policy definitions
  webhooks/            # Webhook system for event-driven notifications
    storage.py         # Webhook configuration storage
    delivery.py        # Webhook delivery service with retry logic
    events.py          # Event generation and cost anomaly detection
    tasks.py           # Background task processing
  integrations/        # CI/CD integration helpers
    github/            # GitHub Actions and PR commenting
    gitlab/            # GitLab CI and MR commenting
  cli/                 # Command-line interface tools
  metrics/             # Prometheus metrics
  
tests/
  unit/                # Unit tests (260+ tests: auth, cache, database, pricing, policies, usage, parsers, audit, webhooks)
  integration/         # Integration tests (25+ tests)

examples/              # Example scripts and infrastructure definitions
  usage_integration_example.py  # Complete usage integration examples
  aws-infrastructure.tf         # AWS Terraform example
  gcp-infrastructure.tf         # GCP Terraform example
  azure-infrastructure.tf       # Azure Terraform example
  aws-infrastructure.yml        # AWS Ansible example
  gcp-infrastructure.yml        # GCP Ansible example
  azure-infrastructure.yml      # Azure Ansible example

static/                # Admin UI static files
  css/                 # Stylesheets
  js/                  # JavaScript application
  assets/              # Images and other assets

scripts/               # CI/CD integration scripts
  finopsguard-cicd.sh  # Universal CI/CD integration script

examples/              # Example configurations and templates
  .github/
    workflows/         # GitHub Actions workflow examples
      finopsguard-check.yml
      finopsguard-pr-comment.yml
  .gitlab/
    ci-templates/      # GitLab CI job template examples
      finopsguard.yml
    ci-example.yml     # Example GitLab CI configuration

docs/
  requirements.md      # Detailed requirements and specifications
  architecture.md      # System architecture documentation
  cicd-integration.md  # CI/CD integration guide
  deployment.md        # Deployment guide (Docker Compose & Kubernetes)
  integrations.md      # MCP agent integration examples (12+ platforms)
  database.md          # PostgreSQL configuration and management
  authentication.md    # Authentication & authorization guide (API keys, JWT, OAuth2, mTLS)
  pricing.md           # Real-time and static pricing configuration
  usage-integration.md # Usage integration guide (CloudWatch, Cloud Monitoring, Cost Management)
  terraform-parsing.md # Terraform HCL parsing guide
  ansible-parsing.md   # Ansible YAML parsing guide

deploy/
  kubernetes/          # Kubernetes manifests
  prometheus/          # Prometheus configuration
  grafana/            # Grafana dashboards and datasources
  QUICK_START.md      # Quick deployment guide

Quick Start

Prerequisites

• Python 3.11+
• pip

Install Dependencies

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Run Development Server

# Set Python path and run
PYTHONPATH=src python -m finopsguard.main

# Server will be available at http://localhost:8080

Verify Installation

# Health check
curl -sS http://loca