argus/README.md

Argus

AI-powered FinOps agent for AWS — Find waste, optimize costs, evaluate changes.

What is Argus?

Argus is an all-seeing eye on your AWS costs. It uses AI to:

• 🔍 Find waste — Unused resources, oversized instances, missing reservations
• 💰 Estimate impact — Cost analysis on Terraform changes before you apply
• 🤖 Auto-optimize — Generate PRs to fix inefficiencies
• 📊 Report trends — Weekly/monthly cost reports with actionable insights

Features

Standalone Mode

Run Argus on a schedule to continuously find savings:

# Weekly cost report
argus report --period weekly

# Find all optimization opportunities  
argus scan --output recommendations.md

# Auto-fix with PR
argus fix --create-pr

Atlantis Integration

Add cost analysis to your Terraform PR workflow:

# atlantis.yaml
workflows:
  default:
    plan:
      steps:
        - init
        - plan
        - run: argus evaluate --plan-file $PLANFILE

Result:

💰 Argus Cost Analysis

This PR will change your monthly spend:

  + aws_rds_cluster.main            +$680/mo
  + aws_nat_gateway.private          +$32/mo  
  - aws_instance.deprecated          -$45/mo
  ─────────────────────────────────────────
  Net Impact: +$667/mo (+15%)

  ⚠️  Suggestions:
  • Consider db.r5.large instead of xlarge (-$340/mo)
  • VPC endpoints could replace NAT for S3 traffic

GitHub Action

Use Argus as a GitHub Action:

- uses: ghndrx/argus-action@v1
  with:
    aws-role-arn: ${{ secrets.AWS_ROLE_ARN }}
    mode: evaluate  # or 'scan', 'report'

Quick Start

1. Install

# Via pip
pip install argus-finops

# Via Docker
docker pull ghcr.io/ghndrx/argus:latest

# Via GitHub Action
uses: ghndrx/argus-action@v1

2. Configure AWS Access

# Option A: IAM Role (recommended)
export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/argus

# Option B: Environment variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

3. Configure AI Provider

# AWS Bedrock (recommended)
export ARGUS_AI_PROVIDER=bedrock
export ARGUS_AI_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0

# Or OpenAI
export ARGUS_AI_PROVIDER=openai
export OPENAI_API_KEY=...

4. Run

# Generate cost report
argus report

# Scan for optimizations
argus scan

# Evaluate a Terraform plan
argus evaluate --plan-file tfplan.json

What Argus Finds

Category	Examples	Typical Savings
Unused Resources	Unattached EBS, idle load balancers, orphaned snapshots	10-20%
Oversized Instances	EC2, RDS, ElastiCache running at <20% utilization	20-40%
Missing Reservations	Steady-state workloads without RIs or Savings Plans	30-60%
Architecture Issues	NAT Gateway for S3 traffic, cross-AZ data transfer	5-15%
Storage Optimization	S3 lifecycle policies, EBS type optimization	10-30%

Configuration

# argus.yaml
scan:
  regions:
    - us-east-1
    - us-west-2
  exclude_tags:
    - Key: argus-ignore
      Value: "true"
  
thresholds:
  idle_cpu_percent: 10
  idle_days: 14
  min_savings_to_report: 10  # dollars

notifications:
  slack_webhook: https://hooks.slack.com/...
  email: finops@company.com

ai:
  provider: bedrock
  model: anthropic.claude-3-5-sonnet-20241022-v2:0

Atlantis Integration

Setup

1. Add Argus to your Atlantis server
2. Configure the workflow:

# atlantis.yaml
workflows:
  default:
    plan:
      steps:
        - init
        - plan
        - run: |
            argus evaluate \
              --plan-file $PLANFILE \
              --output-format github-comment \
              > $OUTPUT_FILE
    apply:
      steps:
        - apply

How It Works

1. Developer opens PR with Terraform changes
2. Atlantis runs terraform plan
3. Argus analyzes the plan:
   • Calculates cost delta
   • Identifies optimization opportunities
   • Checks for cost policy violations
4. Argus comments on PR with findings
5. Team reviews cost impact before merge

GitHub Action

Evaluate PR Changes

name: Argus Cost Check
on: [pull_request]

jobs:
  cost-check:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1
      
      - uses: hashicorp/setup-terraform@v3
      
      - run: terraform init && terraform plan -out=tfplan
      
      - uses: ghndrx/argus-action@v1
        with:
          mode: evaluate
          plan-file: tfplan
          comment-on-pr: true

Scheduled Cost Report

name: Weekly Cost Report
on:
  schedule:
    - cron: '0 9 * * 1'  # Monday 9am

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: ghndrx/argus-action@v1
        with:
          mode: report
          period: weekly
          slack-webhook: ${{ secrets.SLACK_WEBHOOK }}

Architecture

┌──────────────────────────────────────────────────────────────┐
│                         Argus                                 │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Scanner   │  │  Evaluator  │  │  Reporter   │          │
│  │             │  │             │  │             │          │
│  │ • AWS APIs  │  │ • TF Plans  │  │ • Markdown  │          │
│  │ • Usage     │  │ • Cost Calc │  │ • Slack     │          │
│  │ • Pricing   │  │ • AI Review │  │ • Email     │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
│         │                │                │                  │
│         └────────────────┼────────────────┘                  │
│                          │                                   │
│                   ┌──────▼──────┐                            │
│                   │  AI Engine  │                            │
│                   │  (Bedrock)  │                            │
│                   └─────────────┘                            │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Roadmap

• Cost evaluation on Terraform plans
• AWS resource scanning
• Atlantis integration
• GitHub Action
• Slack bot interface
• Multi-cloud (GCP, Azure)
• Cost anomaly detection
• Budget enforcement policies
• Recommendation auto-apply

Contributing

See CONTRIBUTING.md

License

Apache 2.0 - See LICENSE