stacksage 0.7.12

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
CDN & DNS	Unused CloudFront distributions, unused Route53 hosted zones
Network	Unused Elastic IPs, idle NAT Gateways, idle load balancers, missing S3 VPC endpoints
CloudWatch & Logs	Log groups missing retention policies
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
  --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)
  --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)
  --regions TEXT          Comma-separated regions (default: all enabled)
  --out DIRECTORY         Output directory (default: reports/)
  --use-cloudwatch        Enable CloudWatch utilization metrics
  --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)
  --log-level TEXT        DEBUG|INFO|WARNING|ERROR (default: INFO)
  --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