stacksage 0.8.1

AWS cost & security audit — runs on your machine, nothing shared

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

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:

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

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

---

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