Metadata-Version: 2.4
Name: spendslicer
Version: 1.0.0
Summary: Self-hosted AWS cost visibility and waste audit — runs on your machine, against your own AWS credentials.
Author: Tirth Teraiya
License-Expression: MIT
Project-URL: Homepage, https://github.com/tirthteraiya/SpendSlicer
Project-URL: Repository, https://github.com/tirthteraiya/SpendSlicer
Project-URL: Issues, https://github.com/tirthteraiya/SpendSlicer/issues
Project-URL: Changelog, https://github.com/tirthteraiya/SpendSlicer/blob/main/CHANGELOG.md
Keywords: aws,cost,finops,billing,audit,cloud,devops
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: boto3>=1.34
Requires-Dist: botocore>=1.34
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: fpdf2>=2.8
Provides-Extra: web
Provides-Extra: exporters
Requires-Dist: slack-sdk>=3.27; extra == "exporters"
Provides-Extra: cur
Requires-Dist: duckdb>=1.0; extra == "cur"
Provides-Extra: desktop
Requires-Dist: pywebview>=5.1; extra == "desktop"
Requires-Dist: pyobjc-core>=10.1; sys_platform == "darwin" and extra == "desktop"
Requires-Dist: pyobjc-framework-Cocoa>=10.1; sys_platform == "darwin" and extra == "desktop"
Requires-Dist: pyobjc-framework-WebKit>=10.1; sys_platform == "darwin" and extra == "desktop"
Requires-Dist: pythonnet>=3.0; sys_platform == "win32" and extra == "desktop"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: httpx2>=2.12; extra == "dev"
Requires-Dist: moto[ec2,elbv2,organizations,rds,sts]>=5.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.6; extra == "build"
Provides-Extra: all
Requires-Dist: spendslicer[cur,exporters,web]; extra == "all"
Dynamic: license-file

# SpendSlicer

<p><img src="https://raw.githubusercontent.com/tirthteraiya/SpendSlicer/main/branding/kit/lockup-ink.svg" alt="SpendSlicer" width="360"></p>

**Self-hosted AWS cost visibility that runs on your laptop.** Point it at your
existing AWS CLI profiles and get named-resource cost attribution, a waste
radar, and numbers that reconcile against the Billing console.

No account linking. No agent. No telemetry. Every AWS call is made from your
machine with your own credentials, and no cost data ever leaves it.

[![CI](https://github.com/tirthteraiya/SpendSlicer/actions/workflows/ci.yml/badge.svg)](https://github.com/tirthteraiya/SpendSlicer/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/tirthteraiya/SpendSlicer/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

---

## Why this exists

The [brand kit](branding/kit/README.md) includes the final logo, outlined wordmarks,
desktop icons, typography, color palette, and a local visual guide.

The AWS Billing console tells you that `t4g.small · 500 hrs` cost $18.40. It
does not tell you *which instance*, what it was named, or whether it has been
sitting idle since March. Top spenders hide behind nested expanders, and EC2 is
split across a dozen line items that never add up on first read.

SpendSlicer answers the questions you actually opened the console for:

- **Which named resource** cost what — instance ID, `Name` tag, current state
- **Top services and top resources** on one screen, sorted by spend
- **Waste radar** — stopped EC2 still paying for EBS, unattached volumes,
  unassociated Elastic IPs, untagged resources, budget breaches
- **Fifteen services named without setup** — EC2, EBS, RDS, S3, ELB, Elastic IP,
  Lambda, DynamoDB, NAT Gateway, ElastiCache, ECR, EFS, Secrets Manager,
  CloudFront and Route 53. Every service with the CUR warehouse enabled.
- **Numbers you can defend** — every figure carries a provenance record saying
  which API produced it, over what window, with what filters

### Honest accuracy

This is the part most cost tools are vague about, so to be explicit:

| Source | How the number is produced |
| --- | --- |
| Service totals | Cost Explorer `GetCostAndUsage`. Ground truth — matches the console. |
| Per-resource cost | **Estimated.** Cost Explorer `USAGE_TYPE` buckets, split across the resources in that bucket by running hours and list price, then rescaled to match the service total. |
| Per-resource cost, with CUR enabled | **Exact.** Real billed line items from your Cost and Usage Report. See [docs/CUR.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/CUR.md). |

So: **service totals are exact, per-resource splits are estimates** unless you
enable the CUR warehouse. SpendSlicer says which you are looking at rather than
blurring the two.

Per-resource attribution deliberately does *not* use Cost Explorer's
`GetCostAndUsageWithResources`. That call bills $0.00001 per usage record on
top of the $0.01 per request, and on a real account it dominated the tool's
running cost. CUR gives the same per-resource precision from a local warehouse
for free.

Whatever cannot be attributed to a named resource is shown as explicit
**unattributed drift** rather than being silently spread across rows. Rescaling
is skipped entirely when the raw attributed sum falls outside 0.2x–5x of the
Cost Explorer total, since a tiny raw sum would otherwise inflate every row.

Costs are **pre-credit gross**, matching what the Billing console shows by
default.

---

## Install

### Desktop app (easiest)

Download from [Releases](https://github.com/tirthteraiya/SpendSlicer/releases):

| Platform | File |
| --- | --- |
| macOS, Apple Silicon | `SpendSlicer-<version>-macos-arm64.dmg` |
| macOS, Intel | `SpendSlicer-<version>-macos-x86_64.dmg` |
| Windows x64 | `SpendSlicer-<version>-windows-x64.zip` |

> **These builds are not code-signed yet.** macOS will claim the app "is
> damaged and can't be opened" — that is what Gatekeeper says about any
> unsigned download, not a real problem with the file. Windows SmartScreen will
> warn similarly. [docs/DESKTOP.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/DESKTOP.md) has the one-line fix for
> each, and instructions for building it yourself if you would rather not trust
> a binary.

### pip

```bash
pipx install spendslicer   # or: pip install spendslicer
spendslicer                # starts locally and opens your default browser
```

The dashboard bundle and PDF export support ship with the package, so Node.js
is not required. Keep the terminal open while using the app; press Ctrl+C to stop.
Each launch opens your default browser after the server is listening and prints
a protected dashboard link as a fallback. Local browser tabs can also open `/app` directly and
reconnect automatically after a server restart. For
exact per-resource costs from the CUR warehouse, install the extra:
`pipx install "spendslicer[cur]"`. Try it without installing anything:
`uvx spendslicer`.

```bash
spendslicer --help              # commands and launch options
spendslicer --version           # installed version
spendslicer --port 8081         # use another port
spendslicer --no-browser        # run without opening a browser
spendslicer doctor --help       # AWS credential diagnostics
```

`--host` and `--port` override `SPENDSLICER_HOST` and `SPENDSLICER_PORT`.
The old `spendslicer-web` command remains available for existing scripts.

### From source

```bash
git clone https://github.com/tirthteraiya/SpendSlicer.git
cd SpendSlicer
./run.sh                # Windows: run.bat
```

Requires Python 3.10+. The script creates a virtualenv, installs the `web` and
`cur` extras, and starts the server.

---

## First run

Pick an **AWS CLI profile** from the dropdown — the same profiles `aws
configure list-profiles` shows. If you have never set one up:

```bash
aws configure --profile my-account
```

SpendSlicer reads credentials exactly the way boto3 does, so whatever works
for `aws` works here. SSO profiles work once `aws sso login` has been run.

If no profiles appear, or you get "AWS credentials not found":

```bash
spendslicer doctor
```

It prints which files boto3 is actually reading, every profile it can see, and
whether each one's credentials resolve — enough to tell a missing profile from
a wrong `HOME` from a profile with no usable keys. It makes no billable calls.

### A note on Cost Explorer costs

Cost Explorer is a paid API: **$0.01 per request**. SpendSlicer is built around
that fact rather than ignoring it.

- Every response carries `X-CE-Calls-Spent` and `X-CE-Estimated-Cost-USD`
  headers, and the UI shows a running session meter
- Results are cached on disk for 30 minutes, then served stale for another
  6 hours while refreshing in the background
- Background refreshes are deduplicated per cache key and capped globally

A typical dashboard session costs a few cents. Tune it with
`SPENDSLICER_CACHE_TTL_SECONDS` — see [docs/CONFIGURATION.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/CONFIGURATION.md).

---

## IAM permissions

SpendSlicer is strictly read-only. It never creates, modifies, or deletes
anything. The minimum policy is in [docs/IAM.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/IAM.md), which lists
every API call the code actually makes and which feature breaks without it.

The short version: `ReadOnlyAccess` works, or attach the least-privilege policy
from that document.

---

## Documentation

| Document | What's in it |
| --- | --- |
| [docs/DESKTOP.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/DESKTOP.md) | Installing the unsigned builds; building your own |
| [docs/CONFIGURATION.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/CONFIGURATION.md) | Every environment variable |
| [docs/IAM.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/IAM.md) | Least-privilege policy, per-call breakdown |
| [docs/ARCHITECTURE.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/ARCHITECTURE.md) | How attribution works, module layout |
| [docs/CUR.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/docs/CUR.md) | Optional CUR warehouse for exact line-item costs |
| [CONTRIBUTING.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/CONTRIBUTING.md) | Dev setup, tests, PR expectations |
| [SECURITY.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/SECURITY.md) | Threat model, reporting a vulnerability |

---

## Security posture

SpendSlicer binds to `127.0.0.1` and nothing else by default.

- **Desktop builds** mint a random auth token per launch and bind an ephemeral
  port. Nothing else on the machine can drive them.
- **Web launches** also mint a random token by default and print the protected
  dashboard link. A configured `SPENDSLICER_AUTH_TOKEN` is preserved.
- Hosts are validated on every request. For a non-loopback deployment, set
  `SPENDSLICER_ALLOWED_HOSTS` to the hostname you use to open the dashboard.

Cost Explorer requests spend real money, so an open port is a financial
exposure and not just a data one. [SECURITY.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/SECURITY.md) covers the full
threat model.

---

## Project status

Stable. The CLI, environment variables and HTTP endpoints are settled, and the
test suite covers the attribution math, time-window handling, cache semantics
and the audit engine against Python 3.10–3.14 on every push.

The accuracy model is the part still moving — CUR-based attribution is the path
to making per-resource estimates exact, and it is the most valuable place to
contribute. That work makes numbers *better*, not incompatible, so it will not
break anything you build on top.

Known limitations:

- The Pricing API fallback table only carries `ap-south-1` rates; other regions
  fall through to the live API.
- PDF export uses the core PDF fonts, so resource names outside Latin-1 (CJK,
  Cyrillic, emoji) render as `?`. CSV and JSON carry them as UTF-8.

## Contributing

Contributions welcome — especially CUR-based attribution, more service
enumerators, and regional pricing coverage. See
[CONTRIBUTING.md](https://github.com/tirthteraiya/SpendSlicer/blob/main/CONTRIBUTING.md).

## License

MIT — see [LICENSE](https://github.com/tirthteraiya/SpendSlicer/blob/main/LICENSE).
