argus-cloud-optimizer 0.6.1

Argus — AI Cloud Detective for AWS, GCP, and Azure.

Argus is an open-source AI Cloud Detective — it hunts idle and wasted cloud resources across AWS, GCP, and Azure (stopped EC2 instances, unattached EBS volumes, orphaned Elastic IPs, underutilized RDS databases) and delivers a prioritized, AI-reasoned report to Slack every week. No rules. No thresholds. Just reasoning.

Argus — AWS Waste Report (2026-06-24)

💸 $1,432.85/month estimated waste
📊 6 idle resources across 1 account

Six resources were identified as idle or over-provisioned. The RDS instance
accounts for 87% of waste and should be right-sized immediately.

─────────────────────────────────────
Top findings
🔴 db-analytics-01  · RDS         · $1,240.00/mo
🔴 cache-prod-001   · ElastiCache  ·   $142.00/mo
🔴 i-0abc123def     · EC2          ·    $28.40/mo
🟡 nat-0def456      · NAT Gateway  ·    $10.80/mo
🟡 vol-orphan       · EBS          ·     $8.00/mo
⚪ +1 more finding in the full report

[ 📄 Full report (HTML) ]  [ vamshisiddarth/argus ]

🆕 What's new in v0.6.0

Breaking: scheduled scans now create Jira tickets only when REMEDIATION_ENABLED=true (default false). If you ran v0.5.0 with Jira configured, set it to keep tickets flowing. argus policies apply --confirm is unaffected.

• Dry runs never touch Jira — DRY_RUN=true / --dry-run previously still created real tickets when Jira was configured.
• One summary log line per remediation run, with error_type on failures.
• ARGUS_POLICY_DIR is read by both the CLI and scheduled scans (ARGUS_POLICIES_DIR still accepted).

Full changelog → · Project status →

v0.5.0

Remediation is now first-class. Argus goes beyond reporting — it generates Jira tickets, suggests exact resize targets, and tracks acceptance rates.

• Policy engine — YAML-driven policies match AI findings and generate prioritised ChangeProposal objects (weight-ordered, one proposal per resource per scan). Ships with 13 real-world policies across AWS, GCP, and Azure.
• Jira integration — idempotent ticket creation with ADF-structured descriptions (metrics table, runbook code block, snapshot fingerprint for diff-on-update). Dedup via deterministic label; diff-comment on re-scan.
• Rightsizing recommendations — resize and reduce_nodes proposals now include a specific target tier or node count derived from observed CPU% (e.g., "Recommend db.t3.small — observed CPU ~8%").
• Acceptance rate monitoring — argus policies stats reads the append-only audit log and prints per-policy proposal counts, Jira new/update splits, and cloud breakdown.
• JSONL audit log — every apply --confirm appends a line to local_reports/audit.jsonl mapping proposal_id → jira_key → jira_url.
• 1756 tests — all pass offline, no cloud credentials needed.

Full changelog →

What it does

Every week (or on demand), Argus:

1. Discovers every resource in your cloud account using AWS Resource Explorer / GCP Asset Inventory / Azure Resource Graph
2. Analyzes each candidate — CloudWatch/Cloud Monitoring/Azure Monitor metrics, Cost Explorer/BigQuery/Cost Management cost data, and CloudTrail/Audit Log/Activity Log last-activity timestamps
3. Reasons about idleness using Claude (via AWS Bedrock, Anthropic API, or Vertex AI) — no hardcoded thresholds
4. Reports a compact digest (Slack, Microsoft Teams, or generic webhook) with top findings and a link to a full self-contained HTML report

The Full report button links to a self-contained HTML file (S3 / GCS / Azure Blob) with a filterable/sortable table and expandable AI reasoning per finding. Works offline, no login required.

See realistic examples: sample-report-aws.json · sample-report-gcp.json · sample-report-azure.json — 5 findings each with AI-written reasoning, metrics, and cost data.

Remediation

Argus stays strictly read-only — it never mutates a resource. Instead, the policy engine turns AI findings into prioritised Jira tickets that a human reviews and acts on.

How it works

argus scan → scan_report.json
               │
               ▼
argus policies plan --report scan_report.json
               │
               ├── evaluates policies in config/policies/ (13 bundled — weight-ordered, first-match-wins)
               ├── applies two-tier conditions: cost/priority/idle-days + metric thresholds
               ├── computes rightsizing target (e.g. "Recommend db.t3.small — CPU ~8%")
               └── prints proposal table with total savings estimate
               │
               ▼  (add --confirm to create tickets)
argus policies apply --report scan_report.json --confirm
               │
               ├── creates Jira ticket per proposal (idempotent — dedup via label)
               ├── diff-comments on re-scan if finding changed
               ├── appends line to local_reports/audit.jsonl
               └── prints per-ticket status

argus policies stats   # acceptance rate per policy from audit log

To create tickets automatically after every scheduled scan (Lambda, Cloud Run, Azure Function), set REMEDIATION_ENABLED=true. It is off by default; apply --confirm above works without it.

Bundled policies (13)

Each policy also has AI-priority and metric conditions; see Policies for the full table.

All policies skip resources tagged environment: prod (or production) and resources tagged argus-exempt: "true" — either tag on its own is enough. Add your own in config/policies/ — see CONTRIBUTING.md.

Safety guarantees

• IAM — read-only roles; write APIs are unavailable even with creds attached
• Code — no cloud SDK write calls anywhere in the codebase
• CLI gate — apply is a dry-run by default; --confirm is required to create tickets
• Human gate — runbook is printed in the Jira ticket; Argus never executes it

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Agent Loop (ReAct)                   │
│   Think → Call Tool → Observe → Think → Submit          │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┴────────────┐
        ▼                         ▼
  CloudAdapter               AIProvider
  (AWS / GCP / Azure)        (Bedrock / Anthropic / Vertex)
        │
   ┌────┴──────────────────┐
   │  list_resources       │  Resource Explorer / Asset Inventory / Resource Graph
   │  get_metrics          │  CloudWatch / Cloud Monitoring / Azure Monitor
   │  get_cost             │  Cost Explorer / BigQuery / Cost Management
   │  get_last_activity    │  CloudTrail / Audit Logs / Activity Log
   └───────────────────────┘

Design principle: Same brain. Different hands. Different home.

• Brain = agent loop + AI reasoning (core/) — pure Python, zero cloud imports
• Hands = cloud adapters (adapters/) — swappable per cloud
• Home = entrypoints (entrypoints/) — Lambda / Cloud Run / Azure Function

Quick start

Option A — Docker (fastest)

docker build --build-arg CLOUD=aws -t argus .

docker run --rm \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e DRY_RUN=true \
  -v ~/.aws:/root/.aws:ro \
  argus --cloud aws --run-now --dry-run

Option B — Install from PyPI

Prerequisites

• Python 3.11+
• Cloud credentials configured (see below)
• An Anthropic API key or cloud-native AI access (Bedrock / Vertex AI / Azure OpenAI)

pip install argus-cloud-optimizer
argus --version   # argus 0.6.0
argus --help

One package — all three clouds included. No extras needed. --cloud auto-detects from your environment (GCP_PROJECT_ID / AZURE_SUBSCRIPTION_IDS / AWS credentials), or specify explicitly.

Verified 2026-06-24: pip install argus-cloud-optimizer && argus --version works on a clean Python 3.11/3.12/3.13 venv with no project files.

AWS:

export AI_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export DRY_RUN=true
argus scan --cloud aws --dry-run
# or just: argus scan  (auto-detects from AWS_PROFILE / AWS_ACCESS_KEY_ID)

Enable Resource Explorer with an aggregator index in us-east-1 (or set RESOURCE_EXPLORER_REGION).

GCP:

export GCP_PROJECT_ID=my-project-123
export AI_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export DRY_RUN=true
argus scan --cloud gcp --dry-run
# or just: argus scan  (auto-detects from GCP_PROJECT_ID)

Requires BigQuery billing export enabled for cost data.

Azure:

export AZURE_SUBSCRIPTION_IDS=sub-id-1,sub-id-2
export AI_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
export DRY_RUN=true
argus scan --cloud azure --dry-run
# or just: argus scan  (auto-detects from AZURE_SUBSCRIPTION_IDS)

Option C — Clone and develop

git clone https://github.com/vamshisiddarth/argus.git
cd argus
pip install -e ".[all,dev]"
cp .env.example .env                       # edit with your values
argus --cloud aws --run-now

Interactive Chat Mode

Ask questions about your cloud infrastructure in natural language:

pip install argus-cloud-optimizer[chat]   # optional: adds rich formatting
argus chat --cloud aws --ai-provider anthropic   # explicit cloud
argus chat                                       # auto-detects cloud

Argus v0.6.0 — AI Cloud Detective
Cloud: AWS  |  Accounts: prod (123456789012)  |  Budget: $1.00/session
Tip: end a line with \ to continue on the next line.
Type your question, or /help for commands.

argus> What's costing the most and not doing anything?

  → Scanning resources
  → Fetching cost data

Argus: Three idle resources account for $73.30/mo in waste:
  • nat-0abc123 (NAT Gateway, us-east-1) — $32.50/mo — 847 bytes in 90 days, delete it
  • db-prod-replica (RDS, us-west-2) — $28.80/mo — zero connections, read replica with no readers
  • vol-0def456 (EBS, us-east-1) — $12.00/mo — unattached since 2026-03-15

[this turn: 2,847 in / 412 out, $0.0147 | session: 2,847 in / 412 out, $0.0147 / $1.00 budget]

argus> Is the RDS replica definitely safe to delete?

  → Fetching metrics: db-prod-replica
  → Checking last activity: db-prod-replica

Argus: Yes. db-prod-replica is confirmed idle — CPU avg 0.1%, DatabaseConnections avg 0,
last activity 2026-03-21 (93 days ago). The primary db-prod is fully active; this replica
has no readers. Safe to snapshot and delete. Saves $28.80/mo.

[this turn: 1,923 in / 187 out, $0.0089 | session: 4,770 in / 599 out, $0.0236 / $1.00 budget]

argus> What would our total monthly bill look like after cleaning all three up?

Argus: Current waste: $73.30/mo across the three resources. Deleting all three saves
$879.60/year. Your remaining infrastructure cost is unchanged — none of these have
active dependencies based on metrics and activity logs.

[this turn: 1,102 in / 98 out, $0.0047 | session: 5,872 in / 697 out, $0.0283 / $1.00 budget]

argus> /summary
Summarizing conversation...
Done — earlier turns condensed into context.

argus> Remind me which one had the highest monthly cost?

Argus: nat-0abc123 (NAT Gateway, us-east-1) at $32.50/mo — negligible traffic over 90 days.

Available REPL commands: /help, /scan, /cost, /clear, /summary, /quit

CLI Options

argus scan [--cloud aws|gcp|azure] [options]    # full batch scan
argus chat [--cloud aws|gcp|azure] [options]    # interactive Q&A
argus --run-now --cloud aws [options]           # backward compat

  --cloud CLOUD              Cloud provider (auto-detected from env vars if omitted)
  -V, --version              Show version and exit
  --dry-run                  Print notification payload instead of posting
  --ignore-regions REGIONS   Comma-separated regions to skip (e.g. ap-east-1,me-south-1)
  --ai-provider PROVIDER     anthropic | bedrock | vertexai | azure_openai (default: anthropic)
  --accounts PATH            Path to accounts.yaml for multi-account/project/subscription mode
  --max-resources N          Maximum resources to analyze per scan (default: 200)
  --lookback-days DAYS       Metrics lookback window in days (default: 90, use 14 for faster local dev)
  --llm-budget USD           Cost budget per scan/session (default: $2.00 scan, $1.00 chat)

Deploy to AWS Lambda

Uses AWS SAM — handles packaging and upload automatically. No S3 bucket needed.

Single account

make deploy-aws
# or manually:
cd deploy/aws/single-account
sam build && sam deploy --guided

sam deploy --guided walks you through parameters (Slack webhook, region, AI provider) and saves them to samconfig.toml for future deploys. Subsequent deploys are just sam deploy.

The stack creates:

• Lambda function (runs weekly via EventBridge)
• IAM role with least-privilege read-only permissions
• S3 bucket for full JSON report storage (90-day retention)

Multi-account

Hub account (runs Argus):

make deploy-aws-multi
# or manually:
cd deploy/aws/multi-account/hub
sam build && sam deploy --guided

Each spoke account (read-only IAM role only — no Lambda):

aws cloudformation deploy \
  --template-file deploy/aws/multi-account/spoke-role.yaml \
  --stack-name Argus-Spoke \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides HubAccountId=<hub-account-id>

The hub stack output includes the HubRoleArn — use it as the HubRoleArn parameter for spoke deployments.

Deploy to GCP (Cloud Run)

# Authenticate
gcloud auth application-default login

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Deploy
bash deploy/gcp/deploy.sh

Requires: Cloud Run API, Cloud Scheduler API, BigQuery billing export enabled.

Deploy to Azure (Function App)

# Authenticate
az login

# Deploy
az deployment group create \
  --resource-group Argus-RG \
  --template-file deploy/azure/function-app.bicep \
  --parameters subscriptionIds="sub-id-1,sub-id-2" \
               slackWebhookUrl="https://hooks.slack.com/services/..."

AI providers

Set AI_PROVIDER=anthropic|bedrock|vertexai|azure_openai in .env or the deployment environment. Use AI_MODEL to override the model for any provider, and AI_TEMPERATURE to control creativity (default: 0.0).

Multi-account / multi-project setup

Create accounts.yaml with the key matching your cloud:

AWS (hub/spoke with STS AssumeRole):

mode: multi

accounts:
  - id: "111122223333"
    name: dev
    role_arn: arn:aws:iam::111122223333:role/ArgusSpokeRole
  - id: "444455556666"
    name: prod
    role_arn: arn:aws:iam::444455556666:role/ArgusSpokeRole

GCP (one scan per project, ADC handles auth):

mode: multi

projects:
  - id: my-project-dev
    name: dev
  - id: my-project-prod
    name: production

Or set GCP_PROJECT_IDS=my-project-dev,my-project-prod instead.

Azure (cross-subscription via Resource Graph):

mode: multi

subscriptions:
  - id: "aaaabbbb-cccc-dddd-eeee-ffffffffffff"
    name: dev
  - id: "11112222-3333-4444-5555-666677778888"
    name: production

Or set AZURE_SUBSCRIPTION_IDS=sub-1,sub-2 instead.

Then run:

argus scan --cloud aws --accounts accounts.yaml
argus scan --cloud gcp --accounts accounts.yaml
argus scan --cloud azure --accounts accounts.yaml

IAM permissions (AWS)

Argus needs read-only access. The Lambda execution role requires:

resource-explorer-2:Search
resource-explorer-2:GetView
cloudwatch:GetMetricData
ce:GetCostAndUsage
ce:GetCostAndUsageWithResources
cloudtrail:LookupEvents
bedrock:InvokeModel          # only if AI_PROVIDER=bedrock
sts:AssumeRole               # only for multi-account mode
s3:PutObject                 # only if REPORT_S3_BUCKET is set

No write permissions are ever requested.

Cost Explorer note: GetCostAndUsageWithResources requires resource-level cost allocation to be enabled in AWS Cost Management → Preferences → Resource-level data. If not enabled, Argus logs a warning and continues — cost fields will show $0.00.

IAM permissions (GCP)

Argus needs read-only access. The service account (argus-sa@PROJECT.iam.gserviceaccount.com) requires:

cloudasset.assets.listAssets        # list all resources (Asset Inventory API)
monitoring.timeSeries.list          # read CPU / memory / request metrics
monitoring.metricDescriptors.list   # discover available metric types
logging.logEntries.list             # read Cloud Audit Logs for last-activity timestamps
bigquery.jobs.create                # only if BILLING_BQ_TABLE is set
bigquery.tables.getData             # only if BILLING_BQ_TABLE is set
aiplatform.endpoints.predict        # only if AI_PROVIDER=vertexai (default)
storage.objects.create              # only if REPORT_GCS_BUCKET is set
storage.objects.get                 # only if REPORT_GCS_BUCKET is set
iam.serviceAccounts.signBlob        # only if REPORT_GCS_BUCKET is set

No write permissions are ever requested.

The deploy script binds roles/cloudasset.viewer, roles/monitoring.viewer, and roles/logging.viewer automatically. For a tighter permission surface, create a custom role using only the exact permissions above — see GCP deployment docs for the one-command setup.

BigQuery note: without BILLING_BQ_TABLE, cost fields show $0.00 — resource discovery and idleness detection still work via metrics and audit logs.

IAM permissions (Azure)

Argus needs read-only access. The Managed Identity requires:

Microsoft.ResourceGraph/resources/action                              # list all resources (Resource Graph KQL)
Microsoft.Insights/metrics/read                                       # read CPU / memory / request metrics
Microsoft.Insights/metricDefinitions/read                             # discover available metric types
Microsoft.Insights/eventtypes/management/values/read                  # Activity Log fallback for last-activity
Microsoft.CostManagement/query/action                                 # run cost queries
Microsoft.CostManagement/*/read                                       # read cost data
Microsoft.OperationalInsights/workspaces/query/read                   # only if logAnalyticsWorkspaceId is set
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write # only if reportStorageAccount is set
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read  # only if reportStorageAccount is set

No write permissions are ever requested.

The built-in Reader + Cost Management Reader roles cover all required actions per subscription. For a tighter permission surface, create a custom role using only the exact actions above — see Azure deployment docs for the one-command setup.

Cost Management note: Reader covers */read but cost queries use a query/action verb. Cost Management Reader must be added separately — without it, cost fields show $0.00.

Limitations & known issues

Before you invest time deploying Argus, know what it can't do yet:

Multi-cloud maturity

AWS has the richest experience — it was developed first, has the most resource types with curated metric mappings, and has a mature multi-account hub/spoke deployment model. GCP and Azure are fully functional but the AWS adapter has been battle-tested more extensively. Cost data depth also varies: AWS Cost Explorer with resource-level allocation is the most reliable, GCP requires BigQuery billing export to be configured, and Azure Cost Management depends on subscription-level access. All three clouds have dynamic metric fallback for unmapped resource types, so even uncurated types get some signal.

Multi-cloud parity

Running tests

make test                  # unit tests only (528 tests, no cloud creds needed)
make test-integration      # integration tests (32 tests — adapter contracts, report schema)
make test-all              # everything (560 tests)

Tests use unittest.mock throughout — no real AWS/GCP/Azure calls are made.

Project structure

argus/
├── core/                  # Pure Python — no cloud imports
│   ├── agent/loop.py      # ReAct agent loop
│   ├── agent/prompts.py   # System prompt + tool schemas
│   ├── models/finding.py  # ResourceFinding dataclass
│   ├── remediation/       # Policy engine — models, loader, validator, engine, audit, rightsizing
│   └── reports/           # Report generator, multi-cloud merge, export, notifications
├── adapters/
│   ├── base.py            # CloudAdapter abstract class
│   ├── aws/               # AWS adapter (Resource Explorer, CloudWatch, Cost Explorer, CloudTrail)
│   ├── gcp/               # GCP adapter (Asset Inventory, Cloud Monitoring, BigQuery, Audit Logs)
│   └── azure/             # Azure adapter (Resource Graph, Monitor, Cost Management, Activity Log)
├── ai/
│   ├── base.py            # AIProvider abstract class
│   ├── anthropic.py       # Anthropic API (local dev / universal fallback)
│   ├── bedrock.py         # AWS Bedrock (Converse API)
│   ├── vertexai.py        # Vertex AI / Gemini (GCP)
│   └── azure_openai.py    # Azure OpenAI / GPT-4o (Azure)
├── integrations/
│   └── jira/              # Ticket lifecycle: create, dedup, diff-comment, ADF formatter, webhook
├── config/policies/       # 13 bundled YAML policies (AWS / GCP / Azure)
├── config/policies.example/  # 3 annotated starter templates — copy here to begin
├── entrypoints/
│   ├── cli.py             # argus scan / chat / policies validate|plan|apply|stats|docs
│   ├── aws_lambda.py      # AWS Lambda handler
│   ├── gcp_cloudrun.py    # GCP Cloud Run Job handler
│   └── azure_function.py  # Azure Function timer trigger
├── deploy/
│   ├── aws/               # CloudFormation templates
│   ├── gcp/               # Cloud Run + Scheduler deploy script
│   └── azure/             # Bicep templates
└── tests/                 # 1756 tests, all pass offline

Contributing

See CONTRIBUTING.md.

License

MIT