# StackSage

**Scan your AWS account for cost waste and security gaps — in 5 minutes, nothing leaves your machine.**

[![PyPI version](https://badge.fury.io/py/stacksage.svg)](https://pypi.org/project/stacksage/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org)

StackSage runs entirely on your machine. It connects to your AWS account with read-only credentials, detects cost waste and idle resources, estimates your savings, and generates a detailed HTML report — all locally, nothing shared.

→ **[Live demo report](https://stacksageai.com/demo-report)** · [Documentation](https://stacksageai.com/docs) · [Pricing](https://stacksageai.com/#pricing)

---

## Install

```bash
pip install stacksage
```

---

## Quick start

**Option 1 — local AWS credentials or SSO profile:**

```bash
stacksage scan
stacksage scan --profile my-sso-profile
```

**Option 2 — assume a cross-account read-only role:**

```bash
stacksage scan --role-arn arn:aws:iam::123456789012:role/StackSageReadOnly
```

StackSage opens the HTML report in your browser automatically when the scan completes.

---

## Free tier

Run a full scan on any AWS account at no cost. The free tier shows your **top 50 findings ranked by estimated monthly savings**.

To unlock all findings, [get a license key](https://stacksageai.com/#pricing) and set:

```bash
export STACKSAGE_LICENSE=your-key
stacksage scan
```

---

## What it detects

| Category | Examples |
|---|---|
| **Compute** | Idle/stopped EC2 instances, EC2 generation upgrade opportunities |
| **Storage** | Unattached EBS volumes, old/redundant snapshots, gp2→gp3 migration |
| **Database** | Underutilized RDS instances, idle DynamoDB tables, idle ElastiCache clusters |
| **Serverless** | Overprovisioned Lambda functions, Graviton migration opportunities |
| **S3** | Buckets missing lifecycle rules, public buckets, missing encryption, **access logging disabled**, **Intelligent-Tiering not configured** |
| **CDN & DNS** | Unused CloudFront distributions, unused Route53 hosted zones |
| **Network** | Unused Elastic IPs, idle NAT Gateways, **active NAT egress cost estimate**, idle load balancers, **missing DynamoDB VPC endpoint**, missing S3 VPC endpoint |
| **CloudWatch & Logs** | Log groups missing retention policies, **large log groups with no metric filters** |
| **Security & IAM** | Root MFA disabled, root access keys present, weak IAM password policy |
| **Cost Guardrails** | Missing AWS Budgets, missing Cost Anomaly Detection |
| **Tagging** | Untagged resources, missing required tags |

---

## IAM setup

StackSage requires a read-only IAM policy. Minimum required permissions:

```json
{
  "Effect": "Allow",
  "Action": [
    "ec2:Describe*",
    "rds:Describe*",
    "s3:ListAllMyBuckets", "s3:GetBucketLocation", "s3:GetBucketTagging",
    "cloudwatch:GetMetricStatistics",
    "ce:GetCostAndUsage",
    "tag:GetResources",
    "pricing:GetProducts"
  ],
  "Resource": "*"
}
```

→ Full IAM setup guide at [stacksageai.com/docs/iam-policy](https://stacksageai.com/docs/iam-policy)

---

## CLI reference

StackSage has two commands:

| Command | Requires license? | Use case |
|---|---|---|
| `stacksage scan` | **No** | Self-serve: run locally or in CI, free tier shows top 50 findings |
| `stacksage audit` | **Yes** (`STACKSAGE_LICENSE`) | Licensed: full findings + remediation plan, designed for CI pipelines |

### `stacksage scan` (no license needed)

```
stacksage scan [OPTIONS]

  Scan your AWS account — no license needed.

  Free tier (no STACKSAGE_LICENSE set):
    Full infrastructure scan. Top 50 findings by savings shown in the report.
    Security & posture checks always shown in full.
    Remediation plan not included.

  With license (STACKSAGE_LICENSE env var set):
    All findings visible, remediation plan included.

Options:
  --profile TEXT           AWS profile name (uses default profile if omitted)
  --role-arn TEXT          Assume this read-only IAM role ARN
  --external-id TEXT       ExternalId when assuming a role (optional)
  --regions TEXT           Comma-separated regions to scan (default: all enabled)
  --out DIRECTORY          Output directory (default: reports/)
  --use-cloudwatch         Enable CloudWatch utilization metrics (recommended)
  --use-cost-explorer      Include historical spend from Cost Explorer
  --check-tagging          Flag resources missing required tags
  --cw-days INTEGER        CloudWatch lookback days (default: 14)
  --cw-max-queries INT     Max CloudWatch queries per run (default: 500)
  --no-browser             Do not auto-open the HTML report
  --demo                   Run with synthetic data — no AWS calls needed
  --log-level TEXT         DEBUG|INFO|WARNING|ERROR (default: INFO)
  --quiet                  Suppress progress output
  --help                   Show this message and exit.
```

### `stacksage audit` (license required)

```
stacksage audit [OPTIONS]

  Run a full licensed audit (STACKSAGE_LICENSE required).

  Designed for CI/CD pipelines and scheduled audits. All findings visible,
  full remediation plan included. Requires a license key.

Options:
  --profile TEXT          AWS profile name from ~/.aws/credentials or SSO config
  --role-arn TEXT         Assume this read-only IAM role ARN (overrides --profile)
  --external-id TEXT      ExternalId when assuming a role (optional)
  --regions TEXT          Comma-separated regions (default: all enabled)
  --out DIRECTORY         Output directory (default: reports/)
  --format [html|json]    Output format (default: html). Use json for pipelines.
  --use-cloudwatch        Enable CloudWatch utilization metrics
  --use-cost-explorer     Include historical spend from Cost Explorer
  --live                  Shorthand: enables --use-cloudwatch + --use-cost-explorer + --live-pricing
  --live-pricing          Use the AWS Pricing API for EC2 rates (default: static)
  --check-tagging         Flag resources missing required tags
  --cw-days INTEGER       CloudWatch lookback days (default: 14)
  --cw-max-queries INT    Max CloudWatch queries per run (default: 500)
  --demo                  Run with synthetic data — useful for testing the pipeline
  --log-level TEXT        DEBUG|INFO|WARNING|ERROR (default: INFO)
  --quiet                 Suppress progress output (errors only)
  --help                  Show this message and exit.
```

→ Full CLI reference at [stacksageai.com/docs/cli-reference](https://stacksageai.com/docs/cli-reference)

---

## Configuration (optional)

Create a `stacksage.yml` in your working directory to customise exclusions, thresholds, and filters:

```yaml
thresholds:
  idle_cpu_percent: 5.0
  unused_days: 30

exclude:
  tags:
    - key: Environment
      value: production
```

→ Full configuration guide at [stacksageai.com/docs/configuration](https://stacksageai.com/docs/configuration)

---

## Troubleshooting

- **`pricing:GetProducts` denied** — static pricing is used automatically, no action needed
- **Cost Explorer denied** — historical spend section is omitted from the report
- **`skipped-budget` badges in the report** — increase `--cw-max-queries` or narrow `--regions`

→ [Full troubleshooting guide](https://stacksageai.com/docs/troubleshooting)

---

## Links

- [Website](https://stacksageai.com)
- [Documentation](https://stacksageai.com/docs)
- [Pricing & licensing](https://stacksageai.com/#pricing)
- [Live demo report](https://stacksageai.com/demo-report)
- [Bugs & feature requests](https://github.com/amitdubey428/stacksage-ai-stacksage-community/issues)
