cloud-finops-agent

Evidence-based cloud cost optimization. Deterministic checks. Real production metrics. Canary deployments with automated rollback.

---

What is this? (30 seconds)

Every cloud platform tells you to resize your instances. None of them prove it's safe.

The trust gap: AWS Trusted Advisor says "this instance is oversized." Your team says "last time we resized, latency spiked and we rolled back at 2am." The recommendation sits in a backlog for 6 months. Repeat across 200 accounts.

cloud-finops-agent closes the gap with a tiered evidence model:

Tier	What it does	Trust level	Example
Tier 0	Deterministic rules — mathematically guaranteed safe	Ship immediately	Delete unattached EBS volumes
Tier 1	Statistical analysis — high confidence from metrics	Review, then ship	Instance at 18% CPU for 14 days → rightsize
Tier 2	Canary validation — prove it in production with automated rollback	Validated safe	Resize 1 of 3 targets, monitor 60min, auto-rollback on regression

The result: instead of "you should do this," you get "we proved this works — here's the evidence."

---

How is this different?

Capability	Trusted Advisor	Compute Optimizer	CloudHealth	Infracost	Kubecost	cloud-finops-agent
Proves safety before acting	❌ Suggests only	❌ Suggests only	❌ Suggests only	❌ Cost estimation	❌ K8s only	✅ Tiered validation with evidence
Production canary with rollback	❌	❌	❌	❌	❌	✅ Weighted traffic + SLO gate
Works without vendor lock-in	AWS only	AWS only	Multi (paid SaaS)	IaC only	K8s only	✅ Open source, FOCUS data model (multi-cloud on roadmap)
Understands workload context	❌ Generic thresholds	Partial (CPU/memory)	Partial	❌ Static	❌ Container only	✅ Buffer-cache trap, CPU-bound Lambda guard
Deterministic vs empirical separation	❌ Mixed signals	❌ All probabilistic	❌	❌	❌	✅ Tier 0 (guaranteed) vs Tier 1 (statistical)
IaC-anchored findings (SARIF)	❌ Console only	❌ Console only	❌ Dashboard	✅ PR comments	❌	✅ SARIF in GitHub Code Scanning
Agent-native (AI assistant UX)	❌	❌	❌	❌	❌	✅ Skills for Kiro/Claude/Codex
Fail-closed safety model	N/A	N/A	N/A	N/A	N/A	✅ OIDC + tag-gated + auto-rollback

The core difference: Every other tool stops at "you should do this." cloud-finops-agent goes to "we proved this works — here's the evidence, and if it didn't work, we rolled back automatically."

---

Architecture

graph TB
    subgraph "Agent Skills"
        Setup["/setup"]
        Discover["/discover"]
        Recommend["/recommend"]
        Validate["/validate"]
        Investigate["/investigate"]
        Digest["/digest"]
    end

    subgraph "Model-Invoked"
        Grilling["grilling"]
        Risk["risk-assessment"]
    end

    subgraph "AWS Data Sources"
        FOCUS["FOCUS/CUR Table"]
        CW["CloudWatch Metrics"]
        CT["CloudTrail Events"]
        CE["Cost Explorer"]
    end

    subgraph "Validation Infrastructure"
        GHA["GitHub Actions"]
        Canary["Canary Workflow"]
        Evidence["evidence/ directory"]
    end

    Setup --> Config["finops-config.yaml"]
    Discover --> FOCUS
    Discover --> CW
    Discover --> Risk
    Investigate --> CT
    Investigate --> FOCUS
    Validate --> GHA
    GHA --> Canary
    Canary --> CW
    Canary --> Evidence
    Recommend --> Risk
    Grilling -.-> Discover
    Grilling -.-> Validate
    Grilling -.-> Investigate
    Digest --> Evidence
    Digest --> FOCUS

Loading

---

Quickstart

Try it in 30 seconds (no AWS account needed)

The full pipeline runs offline against bundled sample data:

git clone https://github.com/prmaddi6233/cloud-finops-agent.git
cd cloud-finops-agent
pip install -e .

finops scan --input examples/sample-resources.json        # Tier 0: $156.80/mo found
finops analyze --input examples/sample-analyze-contexts.json  # Tier 1: verdicts + evidence
finops report                                             # Ranked savings report

You get a findings table, per-resource evidence JSON in evidence/, and a finops-report.md with total monthly savings, top opportunities, and the SAFE findings queued as canary candidates.

Run it against your accounts

# 1. Configure accounts and discovery roles
#    Edit finops-config.yaml, or walk through it with:
/setup

# 2. Validate the config
finops validate-config

# 3. Scan live (assumes the per-account FinOpsDiscovery role, read-only)
finops scan

# 4. Analyze RDS + Lambda against 14 days of CloudWatch metrics
finops analyze

# 5. Build the report
finops report

# 6. Validate a SAFE finding with a production canary
/validate

Prerequisites (live mode only):

• Python 3.11+
• AWS credentials with read access (see Trust Model)
• FOCUS or CUR 2.0 table in Athena (for cost-data skills)

---

Current Status

Capability	Status
Tier 0 scan — 5 deterministic rules (gp2→gp3, orphaned EBS, idle EC2, empty NAT, unassociated EIP)	✅ Working (live + offline)
Cross-account resource collector (STS assume-role, read-only)	✅ Working
Tier 1 analyze — RDS rightsize + Lambda cost-optimal memory	✅ Working (live + offline)
Evidence records written per analysis (evidence/*.json)	✅ Working
finops report — ranked savings report with canary candidates	✅ Working
SARIF emission with IaC-anchored findings	✅ Working
Tier 2 canary pipeline (GitHub Actions, OIDC, SLO gate, auto-rollback)	✅ Built, needs your AWS setup
FOCUS/Athena cost-data queries	🔜 Roadmap (Wave 2)
Multi-cloud (Azure/GCP)	🔜 Roadmap (Wave 2)

---

What a First Scan Looks Like

Every number below is reproducible from the bundled sample data — run it yourself:

pip install -e .
finops scan --input examples/sample-resources.json
finops analyze --input examples/sample-analyze-contexts.json
finops report

Output (verbatim):

Total identified savings: $563.23/month
  Tier 0 (ship now):        $156.80 (8 findings)
  Tier 1 SAFE (validate):   $406.43 (2 candidates)
  Report: finops-report.md

The sample data deliberately exercises the judgment calls that naive rightsizers get wrong:

• A db.r6g.2xlarge at 12% CPU → SAFE to step down ($379.60/month), because the working set fits the target's buffer cache
• A db.r6g.xlarge at 10% CPU → REVIEW, because downsizing would evict the buffer cache (the "free memory" is doing work)
• A 3008 MB Lambda at 20% memory → REVIEW, because it's CPU-bound — cutting memory would slow it down without saving money
• A Lambda without Lambda Insights → INSUFFICIENT_DATA, because the tool refuses to guess

Low CPU alone is never the answer — that's the point.

---

Skills Reference

User-Invoked

Skill	Trigger	What it does
/setup	"configure", "get started"	Walk through 5-phase config generation → finops-config.yaml
/discover	"find savings", "scan for waste"	Run Tier 0 rules + Tier 1 statistical analysis → prioritized findings
/recommend	"create tickets", "what should we do"	Format findings as ticket-ready actions with $, risk, owner, rollback
/validate	"prove it", "canary test"	Dispatch Tier 2 canary via GitHub Actions, auto-rollback on regression
/investigate	"why did spend spike?"	Root-cause a cost anomaly → Slack message + ticket + executive summary
/digest	"CFO update", "executive summary"	One-paragraph, CFO-grade summary on any FinOps topic

Model-Invoked (automatic)

Skill	When	What it does
grilling	Before any action skill	Asks ≤3 clarifying questions to resolve unknowns
risk-assessment	Before any recommendation or validation	Scores blast_radius × reversibility × dependency_count → LOW/MEDIUM/HIGH/CRITICAL

---

Tiered Validation Model

	Tier 0 — Deterministic	Tier 1 — Statistical	Tier 2 — Canary
Method	Rule-based (if X then Y)	Metric analysis (p95 over N days)	Production canary deployment
Confidence	100%	85-99%	Validated
Risk	Zero (guaranteed safe)	Low (needs review)	Mitigated (auto-rollback)
Speed	Immediate	Same day	30-240 minutes
Examples	Unattached volumes, idle EIPs, stopped instances	Oversized EC2/RDS/Lambda, gp2→gp3	Rightsize with traffic, memory reduction
Approval	None needed	Team lead	Maintenance window
Evidence	Rule match	CloudWatch metrics snapshot	Before/after metrics + canary duration

---

Trust Model

How credentials work

cloud-finops-agent is a read-first, act-with-proof system:

1. Discovery (read-only): Uses a cross-account read role to query Cost Explorer, CloudWatch, and CloudTrail. No write permissions needed.
2. Validation (scoped write): Canary workflows run via GitHub Actions with OIDC federation. Write permissions are scoped to the specific resource being validated.
3. Tag-gating: The agent only acts on resources tagged with your configured gate tag (e.g., finops:managed=true). Untagged resources are invisible.

Authentication methods (in order of preference)

Method	Security	Setup effort
OIDC federation	Best — no long-lived credentials	Medium (one-time GitHub ↔ AWS trust)
IAM cross-account roles	Good — rotatable, auditable	Low
Access keys	Discouraged — static secrets	Lowest (but don't)

Permission boundary

All agent roles should be constrained by a permission boundary that explicitly denies:

• iam:* (no privilege escalation)
• organizations:* (no org-level changes)
• Resource deletion outside of validated Tier 0 rules

---

Architecture Decision Records

ADR	Decision	Rationale
ADR-001	No sandbox benchmarks	Production traffic patterns can't be replicated. Canary on real infra with rollback is safer than testing in a synthetic environment that doesn't match.
ADR-002	Agent, not control plane	This is an advisory + validation layer, not an autonomous optimizer. Humans approve, agent proves. Avoids "the AI deleted my database" failure mode.
ADR-003	Tiered validation model	Single confidence threshold doesn't work. A guaranteed-safe deletion is fundamentally different from a statistical sizing recommendation. Tiers make trust explicit.

---

Sample Evidence Output

After a successful Tier 2 validation:

# evidence/T1-001-i-ghi789-2024-01-15.yaml
finding_id: "T1-001-i-ghi789"
validation_date: "2024-01-15T14:30:00Z"
duration_minutes: 60
result: "PASS"

resource:
  id: "i-ghi789"
  type: "ec2_instance"
  account: "production (123456789012)"
  region: "us-east-1"

change:
  from: "m5.xlarge"
  to: "m5.large"
  monthly_savings: 340

baseline_metrics:
  cpu_p95: 18.2
  latency_p99_ms: 42
  error_rate: 0.01

canary_metrics:
  cpu_p95: 34.1
  latency_p99_ms: 44
  error_rate: 0.01

assessment:
  cpu_headroom: "65.9% remaining"
  latency_impact: "+4.7% (within 5% threshold)"
  error_impact: "no change"

confidence: 0.94
recommendation: "PROCEED — validated safe with production traffic"

This evidence file is what separates "you should resize" from "we proved resizing is safe."

---

Wave 2 Roadmap

• Multi-cloud support — Azure + GCP via FOCUS normalization
• Commitment optimizer — RI/SP purchase recommendations with coverage simulation
• Anomaly auto-detection — Proactive alerts before humans notice spend spikes
• Team dashboards — Self-serve cost views per team with validated savings tracking
• Slack bot integration — /finops discover directly in Slack
• Terraform integration — Auto-generate IaC changes for validated findings
• Historical evidence index — Track validation success rate per resource type
• Custom rule engine — User-defined Tier 0 rules via YAML DSL

---

Positioning

Every cloud platform has optimization recommendations. Zero platforms prove they're safe.

cloud-finops-agent is the evidence layer between "you should do this" and "we proved this works."

Traditional tools tell you what to do. This agent tells you what to do, calculates the risk, validates it against production traffic, auto-rolls back if anything regresses, and produces auditable evidence that the change is safe. Then it formats the ticket.

The difference between a recommendation and a validated recommendation is the difference between a 6-month backlog item and a same-sprint ship.

---

Contributing

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check . && ruff format --check .

# Type check
mypy engine/ --strict

---

License

MIT — see LICENSE.

---

Built by Pradeep Maddi • Built with Kiro