stacksage 0.7.5__tar.gz

stacksage-0.7.5/MANIFEST.in

@@ -0,0 +1,32 @@
+# MANIFEST.in — controls what gets included in the sdist (source distribution).
+# The wheel is built via build_wheel.sh which compiles + strips .py for key modules.
+
+# Include essential project files
+include README.md
+include README.pypi.md
+include TROUBLESHOOTING.md
+include requirements.txt
+include pyproject.toml
+
+# Include all package source (sdist only — wheel build script strips the sensitive ones)
+recursive-include stacksage *.py
+recursive-include stacksage *.jinja2
+recursive-include stacksage *.html
+recursive-include stacksage *.css
+recursive-include stacksage *.js
+recursive-include stacksage/templates *
+
+# Explicitly exclude compiled artefacts from sdist (they're platform-specific)
+recursive-exclude stacksage *.so
+recursive-exclude stacksage *.pyc
+recursive-exclude stacksage *.c
+recursive-exclude stacksage __pycache__
+
+# Exclude test + dev files from distributions
+recursive-exclude tests *
+recursive-exclude docs *
+recursive-exclude scripts *
+exclude Dockerfile
+exclude Dockerfile.trial
+exclude .pre-commit-config.yaml
+exclude pytest.ini

stacksage-0.7.5/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: stacksage
+Version: 0.7.5
+Summary: AWS cost & security audit — runs on your machine, nothing shared
+License-Expression: LicenseRef-Commercial
+Project-URL: Homepage, https://stacksageai.com
+Project-URL: Documentation, https://stacksageai.com/docs
+Project-URL: Changelog, https://stacksageai.com/docs
+Keywords: aws,cloud,cost,audit,security,finops,optimization,cloud-cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Internet
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: cryptography>=41.0.0
+
+# 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 |
+| **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:
+
+```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
+  --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:
+  --role-arn TEXT         Assume this read-only IAM role ARN
+  --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](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)

stacksage-0.7.5/README.md

@@ -0,0 +1,132 @@
+# StackSage Cloud Cost Audit (MVP)
+
+Run an end-to-end AWS cost audit: scan resources, analyze waste, estimate savings, and generate a human-readable report.
+
+## Quick start
+
+Requirements:
+- Python 3.10+
+- AWS credentials or a read-only role (see `docs/read-only-policy.json`)
+- (Optional) `stacksage.yml` for custom configuration
+
+Install deps (MVP uses boto3, jinja2, click):
+
+```zsh
+# optional: create venv
+python -m venv .venv && source .venv/bin/activate
+pip install boto3 jinja2 click pyyaml
+```
+
+### Configuration (Optional)
+
+StackSage supports optional configuration via `stacksage.yml` in your repository root:
+
+```bash
+cp stacksage.yml.example stacksage.yml
+# Edit stacksage.yml to customize exclusions, thresholds, and filters
+```
+
+See [docs/configuration.md](docs/configuration.md) for full configuration guide.
+
+### Full audit
+
+```zsh
+python -m stacksage.cli.cli audit --role-arn YOUR_ROLE_ARN --out reports --format html
+```
+
+Optional region selection:
+```zsh
+python -m stacksage.cli.cli audit --regions us-east-1,eu-west-1 --out reports --format html
+```
+
+### Scan only
+
+```zsh
+python -m stacksage.cli.cli scan --role-arn YOUR_ROLE_ARN --out reports
+```
+
+### Analyze only
+
+```zsh
+python -m stacksage.cli.cli analyze --in-file reports/scan_raw.json --out reports/findings.json
+```
+
+### Report only
+
+```zsh
+python -m stacksage.cli.cli report --findings reports/findings.json --out reports
+```
+
+## CLI options
+- `--role-arn` Assume a read-only role (optional; uses local creds if omitted)
+- `--out` Output directory (`reports` by default)
+- `--format` `html|json` for audit output
+- `--regions` Comma-separated AWS regions (default: all enabled)
+- `--cw-days` CloudWatch metrics lookback days (default: 14)
+- `--cw-max-queries` Max CloudWatch metric queries per run (budget). Budget exhaustion lowers confidence and flags findings as skipped-budget.
+- `--log-level` Logging level: `DEBUG|INFO|WARNING|ERROR` (default: `INFO`). Logs are structured JSON.
+
+## Files
+- `run_scan.py` Scan-only entrypoint (writes `reports/scan_raw.json` with metadata)
+- `stacksage/scanner/aws_scanner.py` Scans EC2/EBS/RDS per region; S3 globally
+- `stacksage/analyzer/analysis.py` Analyzes raw scan data and produces findings
+	- CloudWatch helper `cw_avg`: retry/backoff (up to 2 retries) and error classification (`throttle`, `not_authorized`, `no_data`, `other`).
+	- Provenance includes CloudWatch counters: `cloudwatch_queries_attempted`, `cloudwatch_queries_used`, `cloudwatch_queries_remaining`.
+	- Skipped-budget behavior: detectors set `metric_status=skipped_budget`, `confidence=0.4`, and clear explanation.
+- `stacksage/pricing.py` Static pricing and helper functions
+- `stacksage/cli/cli.py` CLI with `audit`, `scan`, `analyze`, `report`
+- `stacksage/cli/report_gen.py` Generates HTML report from findings JSON
+- `stacksage/templates/report.html.jinja` HTML template (shows metadata, top savings, counts)
+- `docs/read-only-policy.json` IAM policy to grant read-only access
+- `docs/schema.md` Data shapes for resources/findings
+- `docs/function_signatures.md` Signatures for planning/testing
+- `docs/TODOs.md` Roadmap and tasks
+
+## IAM Read-Only Policy
+Provide customers with `docs/read-only-policy.json`. It includes actions:
+- `ec2:Describe*`
+- `s3:ListAllMyBuckets`, `s3:GetBucketLocation`
+- `rds:Describe*`
+- `cloudwatch:GetMetricStatistics` (Phase-1 offline analyzer does not call CloudWatch; keep for future utilization insights)
+	- When enabled, StackSage uses only aggregate metrics (Averages) and a bounded query budget.
+- `pricing:GetProducts` (optional; remove if using only static pricing)
+- `ce:GetCostAndUsage`, `ce:GetDimensionValues` (for historical cost summary)
+- `tag:GetResources`
+- `iam:GetRole`
+	(Remove unused log event permissions if present.)
+
+Recommendations:
+- Keep `cloudwatch:GetMetricStatistics` for utilization metrics.
+- If customers have SCPs, ensure `ec2:Describe*` and `rds:Describe*` are allowed in all target regions.
+- If historical spend is desired, include Cost Explorer permissions (`ce:GetCostAndUsage`).
+
+## Development notes
+
+- Install dev tooling + enable local git hooks (recommended):
+
+```zsh
+./scripts/setup_dev.sh
+```
+
+This installs both `pre-commit` and `pre-push` hooks, so ruff/black/isort run on every commit and push.
+
+- Protecting `main` (recommended): enable GitHub branch protection for `main` and require the **CI** workflow checks to pass before merge. This prevents direct pushes and ensures linting/tests gate changes.
+
+- Multi-region scanning is supported; omit `--regions` to scan all enabled regions.
+- Findings include both estimated monthly cost and savings where applicable.
+- Analyzer operates offline in Phase-1 and uses only scanner outputs (no live AWS calls).
+- Optional real pricing: set `STACKSAGE_PRICING_MODE=api` to use AWS Pricing API for EC2.
+ - Optional CloudWatch live-mode: enable `--use-cloudwatch` or `--live`. Budget enforced via `--cw-max-queries`.
+ - Provenance counters are also written to `reports/run_provenance.json` when HTML report is generated.
+ - Error classification from CloudWatch is attached to findings (`metrics_error`).
+- Optional historical costs: if `ce:GetCostAndUsage` is allowed, audit includes last 30-day spend summary.
+- Reports include an AI executive summary (heuristic, offline) and CSV export of findings.
+
+## Troubleshooting
+- If `pricing:GetProducts` is denied, static pricing is used.
+- If Cost Explorer is denied, the report will omit historical spend.
+- For IAM setup, see `docs/customer-iam-role-setup.md`. Use `--log-level DEBUG` for detailed structured logs.
+ - If you see `skipped-budget` badges in the report, consider increasing `--cw-max-queries` or narrowing regions.
+
+### Refreshing auditor/source credentials
+- See `docs/refresh-auditor-creds.md` for step-by-step instructions to mint fresh auditor/source credentials (IAM user or CloudShell), export them to your shell or `.env`, and re-run `scripts/run_audit.sh` with a preflight identity check.

stacksage-0.7.5/README.pypi.md

@@ -0,0 +1,197 @@
+# 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 |
+| **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:
+
+```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
+  --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:
+  --role-arn TEXT         Assume this read-only IAM role ARN
+  --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](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)