StackSage

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

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 · Documentation · Pricing

Install

pip install stacksage

Quick start

Option 1 — local AWS credentials or SSO profile:

stacksage scan
stacksage scan --profile my-sso-profile

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

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 and set:

export STACKSAGE_LICENSE=your-key
stacksage scan

What it detects

IAM setup

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

{
  "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

CLI reference

StackSage has two commands:

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

Configuration (optional)

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

thresholds:
  idle_cpu_percent: 5.0
  unused_days: 30

exclude:
  tags:
    - key: Environment
      value: production

→ Full configuration guide at 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

Links

• Website
• Documentation
• Pricing & licensing
• Live demo report
• Bugs & feature requests