Metadata-Version: 2.4
Name: kulshan
Version: 0.1.0
Summary: Unified CLI for cost, security, waste, DR, lifecycle, drift, tagging, observability, quota, and network analysis on cloud infrastructure.
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.txt
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: 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>=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: 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: 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

**Free, open-source AWS audit CLI with no infrastructure mutation or remediation.**

Kulshan scans your AWS account across ten audit dimensions and produces a unified scored report. Scanning and report generation are local-first by default.

## Install

```bash
pip install kulshan        # all platforms: macOS, Linux, Windows
```

Requires Python 3.9+. Works with the AWS credentials you already use (`aws sts get-caller-identity`).

## Quick Start

```bash
kulshan doctor              # Check AWS readiness (no cost, no writes)
kulshan report --quick      # Quick scan (3 regions)
kulshan report -o report.html  # Full HTML report
kulshan report --packs security,sweep  # Free packs only ($0 AWS cost)
kulshan shell               # Interactive REPL
```

## What You Get

- **Cost analysis** — multi-method anomaly detection (z-score, IQR, MAD), RI/SP coverage, forecasting
- **Security posture** — 50+ checks across IAM, network, encryption, logging
- **Waste detection** — orphaned EBS, EIPs, snapshots, idle ALBs, NAT gateways
- **DR readiness** — backup coverage, Multi-AZ, single points of failure
- **Lifecycle audit** — EOL runtimes, expiring certs, stale AMIs
- **IaC drift** — CloudFormation drift detection, coverage gaps
- **Tag compliance** — untagged resources, cost attribution gaps
- **Observability** — alarm coverage, logging gaps, blind spots
- **Quota headroom** — service limits, scaling blockers
- **Network topology** — CIDR overlaps, route integrity, flow log coverage

Output formats: terminal (scored dashboard), JSON, HTML, SARIF, CSV.

## Trust & Security

- **No infrastructure mutation** — no remediation or customer-resource changes
- **Auditable permissions** — 147 explicit actions, including non-mutating `DetectStackDrift`
- **Local-first by default** — no active telemetry implementation
- **Explicit integrations** — optional webhooks send data only when deliberately invoked
- **Published IAM policy** — inspect every action before granting access
- **Open source** — Apache 2.0, read every line of code on GitHub
- **Sensitive-data masking** — common identifiers are masked by default; review reports before sharing

## AWS API Costs

- Cost pack: ~$0.20-0.40/run (Cost Explorer @ $0.01/request, billed by AWS)
- All other 9 packs: $0 (free-tier APIs only)
- Skip cost pack: `kulshan report --packs security,sweep,dr`

## 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.

## AI Agents

Kulshan works with Claude Code, Codex, Kiro, Cursor, and any agent that can run shell commands. See [`agent-pack/`](https://github.com/azz-kikkr/kulshan/tree/master/agent-pack) for integration instructions.

## License

Apache 2.0 — free and open source forever.
