Metadata-Version: 2.4
Name: cleancloud
Version: 1.5.0
Summary: Reduce cloud costs through safe, read-only hygiene evaluation. Built for production environments with confidence-scored signals for AWS and Azure.
Author-email: CleanCloud <suresh@getcleancloud.com>
License: MIT
Project-URL: Homepage, https://github.com/cleancloud-io/cleancloud
Project-URL: Documentation, https://github.com/cleancloud-io/cleancloud#readme
Project-URL: Repository, https://github.com/cleancloud-io/cleancloud
Project-URL: Issues, https://github.com/cleancloud-io/cleancloud/issues
Project-URL: Discussions, https://github.com/cleancloud-io/cleancloud/discussions
Project-URL: Source Code, https://github.com/cleancloud-io/cleancloud
Project-URL: Changelog, https://github.com/cleancloud-io/cleancloud/releases
Keywords: aws,azure,cloud,hygiene,devops,sre,infrastructure,security,compliance,enterprise,ci-cd,read-only
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: urllib3>=2.6.3
Requires-Dist: jaraco-context>=6.1.0
Requires-Dist: pyasn1>=0.6.2
Requires-Dist: boto3>=1.26.0
Requires-Dist: botocore>=1.29.0
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: azure-mgmt-resource>=23.0.0
Requires-Dist: azure-mgmt-subscription>=3.0.0
Requires-Dist: azure-mgmt-compute>=30.0.0
Requires-Dist: azure-mgmt-network>=25.0.0
Requires-Dist: azure-mgmt-web>=8.0.0
Requires-Dist: azure-mgmt-sql>=3.0.0
Requires-Dist: azure-mgmt-monitor>=6.0.0
Requires-Dist: azure-core>=1.38.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.7.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Dynamic: license-file

# CleanCloud

![PyPI](https://img.shields.io/pypi/v/cleancloud)
![Python Versions](https://img.shields.io/pypi/pyversions/cleancloud)
![License](https://img.shields.io/badge/License-MIT-yellow.svg)
[![Security Scanning](https://github.com/cleancloud-io/cleancloud/actions/workflows/security-scan.yml/badge.svg)](https://github.com/cleancloud-io/cleancloud/actions/workflows/security-scan.yml)
![GitHub stars](https://img.shields.io/github/stars/cleancloud-io/cleancloud?style=social)

**Find what's costing you money — safely — and optionally fail your build until it's fixed.**

Developer-first cloud hygiene scanner for AWS and Azure.

- **Read-only by design** — no deletions, no tag changes, no resource mutations
- **Finds orphaned & idle resources** — 20 high-signal detection rules
- **Shows minimum estimated monthly waste** — per finding and aggregate
- **Can fail CI on high-confidence findings** — `--fail-on-confidence HIGH`
- **No agents. No telemetry. No SaaS.** — runs in your environment, data never leaves

```bash
pipx install cleancloud

# AWS
cleancloud scan --provider aws --all-regions

# Azure
cleancloud scan --provider azure
```

---

## See It In Action

### `cleancloud scan --provider aws --all-regions`

```
Found 6 hygiene issues:

1. [AWS] Unattached EBS Volume
   Risk       : Low
   Confidence : High
   Resource   : aws.ebs.volume → vol-0a1b2c3d4e5f67890
   Region     : us-east-1
   Rule       : aws.ebs.volume.unattached
   Reason     : Volume has been unattached for 47 days
   Detected   : 2026-02-08T14:32:01+00:00
   Details:
     - size_gb: 500
     - availability_zone: us-east-1a
     - state: available
     - tags: {"Project": "legacy-api", "Owner": "platform"}

2. [AWS] Idle NAT Gateway
   Risk       : Medium
   Confidence : Medium
   Resource   : aws.ec2.nat_gateway → nat-0abcdef1234567890
   Region     : us-west-2
   Rule       : aws.ec2.nat_gateway.idle
   Reason     : No traffic detected for 21 days
   Detected   : 2026-02-08T14:32:04+00:00
   Details:
     - name: staging-nat
     - state: available
     - vpc_id: vpc-0abc123
     - total_bytes_out: 0
     - total_bytes_in: 0
     - estimated_monthly_cost_usd: 32.40
     - idle_threshold_days: 14

3. [AWS] Unattached Elastic IP
   Risk       : Low
   Confidence : High
   Resource   : aws.ec2.elastic_ip → eipalloc-0a1b2c3d4e5f6
   Region     : eu-west-1
   Rule       : aws.ec2.elastic_ip.unattached
   Reason     : Elastic IP not associated with any instance or ENI (age: 92 days)
   Detected   : 2026-02-08T14:32:06+00:00
   Details:
     - public_ip: 52.18.xxx.xxx
     - domain: vpc
     - age_days: 92

--- Scan Summary ---
Total findings: 6
By risk:    low: 5  medium: 1
By confidence:  high: 2  medium: 4
Minimum estimated waste: ~$147/month
(4 of 6 findings costed)
Regions scanned: us-east-1, us-west-2, eu-west-1 (auto-detected)

```

> **New in v1.5:** Cost impact summary with estimated monthly waste per finding and aggregate totals.

### `cleancloud scan --provider azure` — Azure scan output

```
Found 5 hygiene issues:

1. [AZURE] Unattached Managed Disk
   Risk       : Low
   Confidence : Medium
   Resource   : azure.compute.disk → data-disk-legacy-api
   Region     : eastus
   Rule       : azure.unattached_disk
   Reason     : Managed disk not attached to any VM (age: 34 days)
   Detected   : 2026-02-08T14:45:12+00:00
   Details:
     - size_gb: 256
     - disk_state: Unattached
     - subscription: Production

2. [AZURE] Unused Public IP
   Risk       : Low
   Confidence : High
   Resource   : azure.network.public_ip → pip-old-gateway
   Region     : westeurope
   Rule       : azure.public_ip_unused
   Reason     : Public IP not associated with any resource
   Detected   : 2026-02-08T14:45:13+00:00
   Details:
     - ip_address: 20.82.xxx.xxx
     - allocation_method: Static
     - subscription: Staging

3. [AZURE] Load Balancer with No Backends
   Risk       : Medium
   Confidence : High
   Resource   : azure.network.load_balancer → lb-deprecated-service
   Region     : eastus
   Rule       : azure.lb_no_backends
   Reason     : Load balancer has no backend pools configured
   Detected   : 2026-02-08T14:45:14+00:00
   Details:
     - sku: Standard
     - subscription: Production

--- Scan Summary ---
Total findings: 5
By risk:    low: 4  medium: 1
By confidence:  high: 3  medium: 2
Minimum estimated waste: ~$72/month
(3 of 5 findings costed)
Subscriptions scanned: Production, Staging (all accessible)
```

> Every finding includes confidence levels and evidence so your team reviews with context — not guesswork.

For full output examples including doctor validation, JSON, and CSV formats, see [`docs/example-outputs.md`](docs/example-outputs.md).

---

## How It Works

```
Your Cloud Account          CleanCloud (pip install)         Your CI/CD Pipeline
(AWS / Azure)               (read-only scan)                 (GitHub Actions, etc.)

IAM Role       ──────────►   cleancloud scan    ──────────►  Findings (JSON/CSV/human)
(Reader only)               - 20 detection rules                      │
No write access             - Confidence scoring                      ▼
OIDC temporary tokens       - Evidence per finding           --fail-on-confidence HIGH
                            - Estimated waste per finding    Exit 0 = pass
                                                             Exit 2 = policy violation
```

---

## What CleanCloud Detects

20 high-signal rules across AWS and Azure — each read-only, conservative, and designed to avoid false positives in IaC environments.

**AWS:**
* Unattached EBS volumes (HIGH) 
* Old EBS snapshots 
* Infinite retention logs 
* Unattached Elastic IPs (HIGH) 
* Detached ENIs 
* Untagged resources 
* Old AMIs 
* Idle NAT Gateways 
* Idle RDS instances (HIGH) 
* Idle load balancers (HIGH)

**Azure:** 
* Unattached managed disks
* Old snapshots
* Unused public IPs (HIGH)
* Empty load balancers (HIGH)
* Empty App Gateways (HIGH)
* Empty App Service Plans (HIGH)
* Idle VNet Gateways
* Stopped (not deallocated) VMs (HIGH)
* Idle SQL databases (HIGH)
* Untagged resources

Rules not marked are MEDIUM confidence — they use time-based heuristics or multiple signals.

> **You control the threshold.** Start with `--fail-on-confidence HIGH` to catch obvious waste, then tighten to `MEDIUM` as your team validates. Exclude specific resources with [tag-based filtering](#tag-based-filtering).

**Full rule details, signals, and evidence:** [`docs/rules.md`](docs/rules.md)

---

## CI/CD Enforcement

By default, scans exit `0` even with findings — safe for any pipeline. Opt in to enforcement:

| Flag | Behavior | Exit code |
|------|----------|-----------|
| *(none)* | Report findings, never fail | `0` |
| `--fail-on-confidence HIGH` | Fail only on HIGH confidence findings | `2` |
| `--fail-on-confidence MEDIUM` | Fail on MEDIUM or higher | `2` |
| `--fail-on-confidence LOW` | Fail on any confidence level | `2` |
| `--fail-on-findings` | Fail on any finding (strict mode) | `2` |

```bash
# Recommended starting point
cleancloud scan --provider aws --all-regions --fail-on-confidence HIGH

# Full CI/CD example: OIDC auth, JSON output, enforce HIGH confidence
cleancloud scan --provider aws --all-regions \
  --output json --output-file scan.json \
  --fail-on-confidence HIGH
```

---

## Commands

### `doctor` — Validate credentials and permissions

Run this first. Checks authentication, security grade, and read-only permissions.

```bash
cleancloud doctor --provider aws
cleancloud doctor --provider azure
```

```
Authentication Method: OIDC (AssumeRoleWithWebIdentity)
[OK] Security Grade: EXCELLENT
[OK]   - Temporary credentials
[OK]   - Auto-rotated
Permissions Tested: 14/14 passed
[OK] AWS ENVIRONMENT READY FOR CLEANCLOUD
```

### `scan` — Find orphaned and idle resources

```bash
# AWS — single region or all regions
cleancloud scan --provider aws --region us-east-1
cleancloud scan --provider aws --all-regions

# Azure — all subscriptions or specific
cleancloud scan --provider azure
cleancloud scan --provider azure --subscription <subscription-id>

# Output formats
cleancloud scan --provider aws --all-regions --output json --output-file results.json
cleancloud scan --provider azure --output csv --output-file results.csv

# Exclude resources by tag
cleancloud scan --provider aws --all-regions --ignore-tag env:production
```

---

## Installation

### Quick Install
```bash
pipx install cleancloud
```

### Don't have pipx?

**macOS:**
```bash
brew install pipx
pipx install cleancloud
```

**Linux:**
```bash
sudo apt install pipx  # Ubuntu/Debian
pipx install cleancloud
```

**Windows:**
```powershell
python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install cleancloud
```

### CI/CD Environments
```bash
pip install cleancloud
```


Troubleshooting

**Command not found: pip** — Use `pip3 install cleancloud` or `python3 -m pip install cleancloud`

**externally-managed-environment error** — Use `pipx` (see above)

**Command not found: cleancloud** — Run `pipx ensurepath` then restart your shell

**'cleancloud' already seems to be installed** — Run `pipx install cleancloud --force`

### Verify Installation
```bash
cleancloud --version
```

---

## Try It Locally (2 minutes)

No OIDC or CI/CD setup needed — just your existing cloud credentials.

### AWS

```bash
# Your existing AWS CLI credentials work — no extra setup
cleancloud doctor --provider aws
cleancloud scan --provider aws --region us-east-1
```

**Permissions required:** 14 read-only permissions (`ec2:Describe*`, `rds:Describe*`, `s3:List*`, etc.). The `doctor` command tells you exactly which are missing. Full IAM policy: [`docs/aws.md`](docs/aws.md)

### Azure

```bash
# Your existing Azure CLI session works — no extra setup
cleancloud doctor --provider azure
cleancloud scan --provider azure
```

**Permissions required:** `Reader` role at subscription scope (built-in, no custom definition needed). Full RBAC setup: [`docs/azure.md`](docs/azure.md)

---

## Running in CI/CD Pipelines

One-time OIDC setup (~5 minutes) — no long-lived secrets needed.

### AWS — GitHub Actions with OIDC

```yaml
- name: Configure AWS credentials (OIDC)
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::${{ vars.AWS_ACCOUNT_ID }}:role/CleanCloudCIReadOnly
    aws-region: us-east-1

- name: Install CleanCloud
  run: pip install cleancloud

- name: Validate AWS permissions
  run: cleancloud doctor --provider aws --region us-east-1

- name: Scan and enforce
  run: |
    cleancloud scan --provider aws --region us-east-1 \
      --output json --output-file scan.json \
      --fail-on-confidence HIGH
```

### Azure — GitHub Actions with Workload Identity

```yaml
- name: Azure Login (OIDC)
  uses: azure/login@v2
  with:
    client-id: ${{ secrets.AZURE_CLIENT_ID }}
    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

- name: Install CleanCloud
  run: pip install cleancloud

- name: Validate Azure permissions
  run: cleancloud doctor --provider azure

- name: Scan and enforce
  run: |
    cleancloud scan --provider azure \
      --output json --output-file scan.json \
      --fail-on-confidence MEDIUM
```

**Complete CI/CD guide:** [`docs/ci.md`](docs/ci.md) — workflow examples, OIDC setup, enforcement patterns, output formats, and troubleshooting.

Setup guides: [AWS OIDC](docs/aws.md) · [Azure Workload Identity](docs/azure.md)

---

## Security & Trust

CleanCloud shifts trust from code to your cloud provider's enforcement.

**Read-only always:**
- Only `List*`, `Describe*`, `Get*` operations — no `Delete*`, `Modify*`, or `Tag*`
- You create the IAM role, you audit the JSON policy
- OIDC-first: temporary credentials, no secrets stored
- Zero telemetry: no phone-home, no analytics, no outbound calls

**Safety verification:**
- Static AST analysis blocks forbidden SDK calls
- Runtime SDK guards prevent mutations in tests
- IAM policy validation ensures read-only access
- Runs automatically in CI for all PRs

**Enterprise security documentation:**
- [Security Policy & Threat Model](SECURITY.md)
- [InfoSec Readiness Guide](docs/infosec-readiness.md) — IAM Proof Pack, threat model, mitigations
- [IAM Proof Pack](security/) — ready-to-use policies and verification scripts
- [Safety Test Documentation](docs/safety.md)

---

## Tag-Based Filtering

Ignore findings for resources you explicitly mark. Useful when certain environments, teams, or services are out of scope.

### Config file (`cleancloud.yaml`)

```yaml
version: 1

tag_filtering:
  enabled: true
  ignore:
    - key: env
      value: production
    - key: team
      value: platform
    - key: keep   # key-only match (any value)
```

```bash
cleancloud scan --provider aws --region us-east-1 --config cleancloud.yaml
```

### CLI overrides (highest priority)

```bash
cleancloud scan --provider aws --region us-east-1 \
  --ignore-tag env:production \
  --ignore-tag team:platform
```

CLI `--ignore-tag` replaces YAML configuration (not merged) for predictable CI/CD runs. Ignored findings are counted in the summary for auditability.

---

## How CleanCloud Compares

### vs. Cost Dashboards & Cleanup Automation

| Need | Cost Dashboards | Cleanup Automation | CleanCloud |
|------|-----------------|-------------------|------------|
| **Orphaned resource detection** | Limited or noisy | Aggressive | Conservative, high-signal |
| **Safe for production** | Varies | Risk of deletion | Read-only always |
| **CI/CD enforcement** | Not designed for it | Risky | Purpose-built |
| **Confidence scoring** | Binary yes/no | Binary yes/no | LOW/MEDIUM/HIGH |
| **Telemetry / data sharing** | Usually required | Usually required | Zero — fully private |

CleanCloud complements dashboards and advisors. Use **AWS Cost Explorer / Azure Cost Management** for spending trends. Use **Trusted Advisor / Azure Advisor** for rightsizing. Use **CleanCloud** to find orphaned resources safely and enforce it as a CI/CD gate.

### vs. Azure Orphan Resources

[Azure Orphan Resources](https://github.com/dolevshor/azure-orphan-resources) is a popular Azure Workbook for visualizing orphaned resources in the portal — great for ad-hoc visibility, but a different tool for a different workflow.

| | Azure Orphan Resources | CleanCloud                                                 |
|---|---|------------------------------------------------------------|
| **Cloud support** | Azure only | AWS + Azure                                                |
| **Interface** | Azure Portal workbook | CLI (`pipx install`)                                       |
| **CI/CD enforcement** | None — manual review only | `--fail-on-confidence HIGH` gates builds                   |
| **Delete capability** | Yes (requires Contributor role) | Read-only — no mutations ever                              |
| **Detection model** | Binary: orphaned or not | Confidence scoring with evidence per finding               |
| **Cost estimates** | Labels resources as "billable" | Per-finding `estimated_monthly_cost_usd` + aggregate waste |
| **Automation** | Manual import, no scheduling | `pipx install` in any pipeline, cron, or script            |

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Scan completed (findings reported but don't fail by default) |
| `1` | Configuration error or unexpected error |
| `2` | Policy violation (`--fail-on-findings` or `--fail-on-confidence`) |
| `3` | Missing permissions or invalid credentials |

---

## Roadmap

> Roadmap items are added only after conservative signal design and safety review.

### Coming Soon
- GCP support (read-only, parity with existing trust guarantees)
- Additional AWS rules (empty security groups)
- Additional Azure rules (unused NICs, old images)
- Rule filtering (`--rules` flag)
- Multi-account scanning (AWS Organizations support)

### Not Planned
- Automated cleanup or deletion
- Rightsizing or instance optimization
- Billing data access or spending analysis
- Resource tagging or mutations

---

## Documentation

- [`docs/rules.md`](docs/rules.md) - Detection rules, signals, and evidence
- [`docs/aws.md`](docs/aws.md) - AWS setup and IAM policy
- [`docs/azure.md`](docs/azure.md) - Azure setup and RBAC configuration
- [`docs/ci.md`](docs/ci.md) - CI/CD integration guide
- [`docs/example-outputs.md`](docs/example-outputs.md) - Full output examples (doctor, scan, JSON)
- [`SECURITY.md`](SECURITY.md) - Security policy and threat model
- [`docs/infosec-readiness.md`](docs/infosec-readiness.md) - InfoSec readiness guide
- [`security/`](security/) - IAM Proof Pack (policies and verification scripts)

---

## Enterprise & Production Use

CleanCloud is designed for production environments where write access is prohibited, InfoSec review is mandatory, and data cannot leave the cloud account.

If your team is assessing cloud cost governance or hygiene controls, we can support security reviews, CI/CD rollout design, and multi-account architecture discussions.

**[Start an evaluation discussion](https://www.getcleancloud.com/#contact)**

---

## Questions or Feedback?

- **Found a bug?** [Open an issue](https://github.com/cleancloud-io/cleancloud/issues)
- **Have a feature request?** [Start a discussion](https://github.com/cleancloud-io/cleancloud/discussions)
- **Want to chat?** Email us at suresh@getcleancloud.com
- **Like CleanCloud?** [Star us on GitHub](https://github.com/cleancloud-io/cleancloud)

## Contributing

Contributions are welcome! Please ensure all PRs include tests, follow the conservative design philosophy, and maintain read-only operation. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details.

---

## License

[MIT License](LICENSE)
