argus/README.md

# Argus

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

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

## 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:

```bash
# 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:

```yaml
# 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:

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

## Quick Start

### 1. Install

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```yaml
# 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:

```yaml
# 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

```yaml
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

```yaml
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

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

Apache 2.0 - See [LICENSE](LICENSE)