Quick Start

Get your first AWS audit in under 5 minutes. No containers, no CI pipeline, no sign-up.

Prerequisites

• Python 3.10 or higher (python3 --version)
• AWS credentials already configured on your machine (any method: ~/.aws/credentials, env vars, SSO, or instance profile)
• Read-only AWS access to the account you want to audit

Step 1 — Install StackSage

pip install stacksage

That's it. StackSage is a standard Python package — no Docker, no GitHub Actions workflow to set up first.

Step 2 — Run your first scan

Run against your default AWS profile:

stacksage scan

Or specify an SSO profile or role:

# Named profile (SSO, named credential, etc.)
stacksage scan --profile my-sso-profile

# Assume a cross-account read-only role
stacksage scan --role-arn arn:aws:iam::123456789012:role/StackSageReadOnly

The scan reads only metadata and aggregate metrics — no resource data leaves your machine. Expect it to complete in 2–5 minutes depending on the size of your account.

Step 3 — Review your report

When the scan finishes, StackSage automatically opens audit_report.html in your browser. You'll also find these files in the output directory:

• audit_report.html — shareable HTML report with evidence and remediation commands
• findings.json / findings.csv — machine-readable outputs for automation
• summary.md — one-page executive summary, ready to paste into Slack or an email

Adding your Pro license

Set your license key as an environment variable before scanning:

export STACKSAGE_LICENSE=STACKSAGE1.eyJ...
stacksage scan

Add the export line to your ~/.zshrc or ~/.bashrc to persist it across sessions.

Recommended: least-privilege IAM

For production use, create a dedicated read-only IAM role and pass it via --role-arn. This means StackSage never touches your default admin credentials. See the IAM Policy Setup guide for a 5-minute setup using the AWS CLI.

Optional: schedule with GitHub Actions

Want automated weekly audits that upload the report as a CI artifact? See the GitHub Actions setup guide. GitHub Actions is optional — stacksage scan on your machine is fully functional without it.

What's next?

• CLI reference — all flags and environment variables
• Configuration — exclusions, thresholds, stacksage.yml
• IAM policy setup — least-privilege read-only role
• All detectors — what StackSage checks
• GitHub Actions — automated scheduled audits
• Troubleshooting — common issues