Metadata-Version: 2.4
Name: kulshan
Version: 0.3.0
Summary: Local-first, read-only AWS audit CLI. Generate a VP/CFO-ready AWS audit report in minutes.
Project-URL: Homepage, https://github.com/azz-kikkr/kulshan
Project-URL: Repository, https://github.com/azz-kikkr/kulshan
Project-URL: Documentation, https://github.com/azz-kikkr/kulshan/tree/master/docs
Project-URL: Issues, https://github.com/azz-kikkr/kulshan/issues
Author: Yuvdeep Singh
License: Apache-2.0
License-File: LICENSE
Keywords: aws,cli,cost,devops,finops,local-ai,mission-finops,security,slm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Security
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Requires-Dist: awscrt>=0.19
Requires-Dist: boto3>=1.28
Requires-Dist: click>=8.0
Requires-Dist: duckdb>=1.0.0
Requires-Dist: httpx>=0.25
Requires-Dist: jinja2>=3.1
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: plotext>=5.2.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: rich-click>=1.7
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: all
Requires-Dist: huggingface-hub>=0.20; extra == 'all'
Requires-Dist: llama-cpp-python>=0.3; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: openpyxl>=3.1.0; extra == 'all'
Requires-Dist: python-pptx>=0.6.21; extra == 'all'
Requires-Dist: weasyprint>=60.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: jsonschema>=4.20; extra == 'dev'
Requires-Dist: moto[ce,ec2,iam,organizations,rds,s3,sts]>=5.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == 'excel'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: pdf
Requires-Dist: weasyprint>=60.0; extra == 'pdf'
Provides-Extra: pptx
Requires-Dist: python-pptx>=0.6.21; extra == 'pptx'
Provides-Extra: slm
Requires-Dist: huggingface-hub>=0.20; extra == 'slm'
Requires-Dist: llama-cpp-python>=0.3; extra == 'slm'
Description-Content-Type: text/markdown

# Kulshan

The blood test for your AWS bill.

Generate a local AWS audit report in minutes.

```bash
pip install kulshan
kulshan report
```

No setup. No data uploads. No infrastructure changes.

Just your AWS account and your laptop.

[![PyPI](https://img.shields.io/pypi/v/kulshan)](https://pypi.org/project/kulshan/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE.txt)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)

[Documentation](docs/README.md) | [IAM Policy](iam/kulshan-readonly.json) | [GitHub](https://github.com/azz-kikkr/kulshan)

---

## What is Kulshan?

Kulshan reads your AWS account (Cost Explorer and your own CUR/Data Export files) and generates a business-ready report covering:

- Cost anomalies and trends
- Waste and orphaned resources
- Tag compliance and cost attribution
- Commitment health (RI/SP coverage)
- Spend forecasting and acceleration
- Security posture
- DR readiness

Reads Cost Explorer and your own CUR data in place. No data leaves your environment.

Think of it as a baseline before deeper FinOps work, platform evaluations, or leadership reviews.

---

## What You Get

An HTML report you can open in a browser and hand to your VP, CFO, or platform team. Also available as JSON, SARIF, and CSV.

The report scores your account 0-100 across each dimension, highlights the top findings by dollar impact, and provides an executive summary paragraph.

---

## Install

```bash
pip install kulshan
```

Requires Python 3.9+. macOS, Linux, Windows.

---

## AWS Credentials

Kulshan uses your existing AWS CLI credentials. If `aws sts get-caller-identity` works, Kulshan works.

The recommended flow is:

```bash
aws login
kulshan report
```

Kulshan identifies your active AWS identity automatically and routes to the correct local database.

Named profiles and explicit credentials also work:

```bash
# Named profile
kulshan --profile your-profile report

# Environment variable
AWS_PROFILE=customer-a kulshan report

# Assume role
kulshan --role-arn arn:aws:iam::123456789012:role/KulshanAudit report
```

---

## Multi-Environment Isolation

Kulshan automatically separates data for different AWS identities.

On first use, Kulshan creates a local environment named after your AWS role or user:

```text
✓ Created environment readonlyrole-cedar
  Using readonlyrole-cedar · account 1234…5678
```

Future runs with the same identity reuse the same environment and database. Different identities get separate environments automatically.

No `--workspace` flags or manual setup required.

### Payer Binding

When Kulshan reads CUR data containing a `bill_payer_account_id`, it binds the environment to that payer:

```text
✓ Bound this environment to payer XXXX-XXXX-9999 using CUR evidence.
```

### Reconciliation

If multiple AWS identities access the same payer account, Kulshan offers to link them:

```bash
kulshan workspace reconcile
```

After linking, all identities route to one payer environment, and `kulshan history` shows a unified timeline.

### Workspace Commands

```bash
kulshan workspace list                    # Show all environments
kulshan workspace show                    # Show current environment details
kulshan workspace rename ws_abc "Acme"    # Change display name
kulshan workspace reconcile               # Link shared-payer environments
kulshan workspace use ws_abc              # Set active workspace
```

### History

```bash
kulshan history                    # Show scans (including linked environments)
kulshan history --direct-only      # Only scans from this workspace
kulshan history --account 123456789012   # Filter by credential account
```

### Consolidated Reports

When a payer environment has multiple approved connections:

```bash
kulshan report     # Runs all approved connections, produces one report
```

The report shows coverage and source attribution:

```text
Report status: Complete
Payer cost coverage: Verified payer-wide
Connections: billing, audit
Accounts verified: XXXX-XXXX-1111, XXXX-XXXX-2222
```

To run a single connection:

```bash
kulshan --connection audit report
```

---

## Quick Commands

```bash
kulshan --version                       # Show version
kulshan doctor                          # Verify credentials and permissions
kulshan report                          # Default FinOps baseline (cost pack)
kulshan report --quick                  # Fast scan (skips confirmation)
kulshan report -o report.html           # Save as HTML
kulshan report --packs security,sweep   # Run specific packs
kulshan report --packs all --regions us-east-1  # Full 10-pack diagnostic
kulshan history                         # View past scans
kulshan shell                           # Interactive REPL
```

---

## All 10 Audit Packs

| Pack | What it detects |
|------|-----------------|
| `cost` | Cost trends, anomalies, commitment gaps (default) |
| `security` | IAM misconfigurations, encryption gaps, network exposure |
| `sweep` | Orphaned and idle resources (waste detection) |
| `dr` | Backup coverage gaps, multi-AZ gaps, single points of failure |
| `age` | EOL runtimes, expiring certificates, stale resources |
| `drift` | CloudFormation drift, IaC coverage gaps |
| `tag` | Tag compliance violations, unattributed spend |
| `pulse` | Observability gaps, missing alarms |
| `limit` | Service quota headroom issues |
| `topo` | VPC topology issues, CIDR overlaps, route integrity problems |

```bash
kulshan report --packs cost,security,sweep --regions us-east-1
kulshan report --packs all --regions us-east-1,us-west-2
```

---

## CUR / Data Export Investigations

Kulshan can investigate cost movements directly from AWS Cost and Usage Report (CUR) or Data Export Parquet files, both locally and from S3. No Athena, no Glue, no data warehouse required. DuckDB queries your data in place.

### Validate and Inspect

```bash
# Validate CUR Parquet structure
kulshan cur validate --path ./cur/

# Validate S3 manifest
kulshan cur validate --s3 s3://bucket/prefix/ --month 2024-06

# Inspect schema mapping
kulshan cur schema --path ./cur/

# Check S3 readiness (no data download)
kulshan cur s3-check --s3 s3://bucket/prefix/
```

### Investigate Cost Movements

```bash
# Local investigation
kulshan investigate cost --path ./cur/ --month 2024-06

# S3 investigation (queries in place via DuckDB httpfs)
kulshan investigate cost --s3 s3://bucket/prefix/ --month 2024-06

# EC2-specific investigation
kulshan investigate ec2 --cur ./cur/ --month 2024-06

# Export as JSON or Markdown
kulshan investigate cost --path ./cur/ --month 2024-06 -o report.json
kulshan investigate ec2 --cur ./cur/ --month 2024-06 -o report.md
```

### What Investigations Include

**Cost Investigation:** Top movers by service, account, region, usage type. Period-over-period delta with percentages. Suggested next steps for deeper analysis.

**EC2 Investigation:** Instance family, region, and pricing model breakdowns. Resource-level contributors. Tag coverage analysis.

All investigation outputs include structured evidence with unique IDs, schema version, timestamps, and `human_review_required: true`.

---

## MCP Server (Agent Integration)

Kulshan exposes its findings to MCP-compatible agents (Claude Desktop, Cursor, Kiro, and others). The agent may reason over that evidence; Kulshan itself returns deterministic, inspectable evidence.

```bash
kulshan mcp-serve
```

### MCP Configuration

Add to your MCP client configuration (e.g., `.kiro/settings/mcp.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "kulshan": {
      "command": "kulshan",
      "args": ["mcp-serve"]
    }
  }
}
```

### Available MCP Tools

| Tool | Parameters | Description |
|------|------------|-------------|
| `kulshan_doctor` | (none) | Check AWS caller identity |
| `kulshan_report` | `packs`, `days`, `regions` | Run audit packs and return findings |
| `kulshan_quick_security` | `region` | Fast security scan of a single region |
| `kulshan_list_packs` | (none) | List available audit packs |
| `kulshan_cur_validate` | `cur_path` | Validate local CUR Parquet |
| `kulshan_investigate_ec2` | `cur_path`, `month` | Investigate EC2 costs from local CUR |
| `kulshan_investigate_cost` | `s3_uri`, `month` | Investigate costs from S3 CUR |

Kulshan produces deterministic, inspectable evidence that humans and AI systems can verify.

---

## Output Formats

```bash
kulshan report                          # Terminal
kulshan report -o report.html           # HTML (self-contained, shareable)
kulshan report --format json            # JSON
kulshan report --format sarif           # SARIF (GitHub Security tab compatible)
kulshan report --format csv             # CSV (spreadsheet)
```

Convert a previous scan to a different format without re-running:

```bash
kulshan convert -i previous-scan.json --format html -o report.html
```

---

## Trust and Security

Read-only by design. No write permissions required. Published IAM policy included.

> Kulshan is read-only by construction, not read-only by default. There is no cleanup mode to leave off, no write path to enable, and no telemetry to opt out of. Nothing to disable, because nothing exists. The published IAM policy contains zero actions that create, modify, or delete resources. Read every line, verify everything.

- Every action in the published policy is read-level per the AWS service authorization reference
- 147 read-only actions, zero write actions
- Reports stay on your machine, no uploads
- No telemetry, no phone-home
- Open source: Apache 2.0

[View the IAM policy](iam/kulshan-readonly.json)

---

## AWS API Cost

Typical run cost: approximately $0.15 to $0.25 in AWS Cost Explorer API charges. AWS bills Cost Explorer requests at $0.01 per request. All non-cost packs use free AWS APIs.

The CLI asks for confirmation before running Cost Explorer queries. Use `--yes` for CI/CD.

---

## Performance

Kulshan uses parallel execution for audit packs and region scanning. A full 10-pack scan completes substantially faster than sequential execution.

---

## About the Name

Kulshan is the Lummi name for the mountain known colonially as Mt. Baker, meaning "great white watcher." We acknowledge the Lummi and Nooksack peoples as the original namers of this mountain.

---

## Built by

[Mission FinOps](https://missionfinops.com) | Mission, BC, Canada

For questions about what Kulshan detects, or for help investigating and explaining findings, contact Mission FinOps.

---

## Links

- [Documentation](docs/README.md)
- [IAM Policy](iam/kulshan-readonly.json)
- [GitHub](https://github.com/azz-kikkr/kulshan)
- [PyPI](https://pypi.org/project/kulshan/)

---

## License

Apache 2.0. Free and open source forever.
