You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+67-56Lines changed: 67 additions & 56 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,13 +11,28 @@
11
11
12
12
---
13
13
14
+
## Quick Start
15
+
16
+
```bash
17
+
pipx install cleancloud
18
+
cleancloud demo # see sample findings — no credentials needed
19
+
```
20
+
21
+
Scan your cloud:
22
+
23
+
```bash
24
+
cleancloud scan --provider aws --all-regions
25
+
cleancloud scan --provider azure
26
+
cleancloud scan --provider gcp --all-projects
27
+
```
28
+
29
+
---
30
+
14
31
**CleanCloud is the Cloud Hygiene Engine — the missing layer between cost visibility and cleanup.**
15
32
16
33
**Supports:** AWS · Azure · GCP
17
34
18
-
Cloud waste hit 29% of spend in 2026 — the first rise in five years (Flexera). Most teams already have cost dashboards. Dashboards show spend trends; they don't tell engineers what to clean up. SaaS FinOps platforms require vendor access to your cloud account — a non-starter for regulated industries. And as cloud environments scale across accounts and subscriptions, unused resources are no longer exceptions — they are continuous drift. Platform teams need a deterministic, enforceable process to turn that drift into a list of exactly what to act on.
19
-
20
-
That's CleanCloud. Scan your AWS, Azure, and GCP environments, get specific actionable findings with per-resource cost estimates, and enforce waste thresholds on a schedule — no agents, no SaaS, no data leaving your environment.
35
+
CleanCloud scans your AWS, Azure, and GCP environments and tells you exactly what to clean up — with per-resource cost estimates. No agents. No SaaS. Read-only. Runs entirely in your environment.
-**32 curated, high-signal detection rules:** orphaned volumes, idle databases, stopped instances, unused registries, and more — designed to avoid false positives in IaC environments, each with a deterministic cost estimate. AI/ML rules (SageMaker, Azure ML) are opt-in via `--category ai`
34
-
-**Governance enforcement (opt-in):**`--fail-on-confidence HIGH` or `--fail-on-cost 100` — enforce waste thresholds on a schedule, owned by platform or FinOps teams
35
-
-**Multi-account scanning (AWS):** scan entire AWS Organizations in one run — config file, inline IDs, or auto-discovery via `--org`
36
-
-**Multi-subscription scanning (Azure):** scan all Azure subscriptions in parallel — auto-discovery via Management Group, per-subscription cost breakdown included
37
-
-**Multi-project scanning (GCP):** scan all accessible GCP projects in parallel — auto-discovery via Application Default Credentials, per-project cost breakdown included
38
-
-**Safe for regulated environments:** read-only, no agents, no telemetry, no SaaS — runs entirely inside your own infrastructure. Suitable for financial services, healthcare, and government accounts where third-party SaaS access is restricted
39
-
-**Ecosystem-ready output:** JSON for Slack alerts, cost dashboards, and ticketing automation — CSV for spreadsheet workflows — markdown to paste directly into GitHub PRs, Jira, or Confluence
40
-
-**No agents. No telemetry. No SaaS.** Data never leaves your environment
41
-
42
-
### What CleanCloud does NOT do
43
-
44
-
|||
45
-
|---|---|
46
-
| ❌ Delete resources | ❌ Modify or create tags |
47
-
| ❌ Write to any cloud API | ❌ Store or log credentials |
48
-
| ❌ Send telemetry or usage data | ❌ Require a SaaS account or agent |
49
-
50
-
All operations are read-only. Safe for production accounts, air-gapped environments, and security-reviewed pipelines.
51
-
52
-
**Who uses it:**
53
-
-**Platform and FinOps teams** — run weekly hygiene scans across your AWS Org or Azure tenant, enforce waste thresholds, catch drift before it compounds
54
-
-**Regulated industries** — financial services, healthcare, and government teams that cannot send cloud account data to a SaaS vendor
55
-
-**Mid-market engineering teams** — too large to ignore cloud waste, too lean for enterprise FinOps platforms. Native cost tools show bills; CleanCloud shows you what to fix
56
-
-**Cloud consultants and MSPs** — run a read-only audit against a client account in minutes, export findings to markdown or JSON
57
-
58
-
**Use cases:**
59
-
- One-time cloud waste audit — run in CloudShell, see findings in 60 seconds
60
-
- Scheduled hygiene governance — weekly job that catches new waste and enforces thresholds across all accounts
61
-
- Pre-review reports — export findings to markdown before a quarterly cost review or board meeting
62
-
63
48
## What It Looks Like
64
49
65
50
```
@@ -154,6 +139,39 @@ No cloud account yet? `cleancloud demo` shows sample output without any credenti
154
139
155
140
---
156
141
142
+
## Key Features
143
+
144
+
-**32 curated, high-signal detection rules:** orphaned volumes, idle databases, stopped instances, unused registries, and more — designed to avoid false positives in IaC environments, each with a deterministic cost estimate. AI/ML rules (SageMaker, Azure ML) are opt-in via `--category ai`
145
+
-**Governance enforcement (opt-in):**`--fail-on-confidence HIGH` or `--fail-on-cost 100` — enforce waste thresholds on a schedule, owned by platform or FinOps teams
146
+
-**Multi-account scanning (AWS):** scan entire AWS Organizations in one run — config file, inline IDs, or auto-discovery via `--org`
147
+
-**Multi-subscription scanning (Azure):** scan all Azure subscriptions in parallel — auto-discovery via Management Group, per-subscription cost breakdown included
148
+
-**Multi-project scanning (GCP):** scan all accessible GCP projects in parallel — auto-discovery via Application Default Credentials, per-project cost breakdown included
149
+
-**Safe for regulated environments:** no agents, no telemetry, no SaaS — runs entirely inside your own infrastructure. Suitable for financial services, healthcare, and government accounts where third-party SaaS access is restricted
150
+
-**Ecosystem-ready output:** JSON for Slack alerts, cost dashboards, and ticketing automation — CSV for spreadsheet workflows — markdown to paste directly into GitHub PRs, Jira, or Confluence
151
+
152
+
### What CleanCloud does NOT do
153
+
154
+
|||
155
+
|---|---|
156
+
| ❌ Delete resources | ❌ Modify or create tags |
157
+
| ❌ Write to any cloud API | ❌ Store or log credentials |
158
+
| ❌ Send telemetry or usage data | ❌ Require a SaaS account or agent |
159
+
160
+
All operations are read-only. Safe for production accounts, air-gapped environments, and security-reviewed pipelines.
161
+
162
+
**Who uses it:**
163
+
-**Platform and FinOps teams** — run weekly hygiene scans across your AWS Org or Azure tenant, enforce waste thresholds, catch drift before it compounds
164
+
-**Regulated industries** — financial services, healthcare, and government teams that cannot send cloud account data to a SaaS vendor
165
+
-**Mid-market engineering teams** — too large to ignore cloud waste, too lean for enterprise FinOps platforms. Native cost tools show bills; CleanCloud shows what to fix
166
+
-**Cloud consultants and MSPs** — run a read-only audit against a client account in minutes, export findings to markdown or JSON
167
+
168
+
**Use cases:**
169
+
- One-time cloud waste audit — run in CloudShell, see findings in 60 seconds
170
+
- Scheduled hygiene governance — weekly job that catches new waste and enforces thresholds across all accounts
171
+
- Pre-review reports — export findings to markdown before a quarterly cost review or board meeting
**Not sure if your credentials have the right permissions?**
223
+
**Not sure if your credentials have the right permissions?**
206
224
207
-
Run:
208
-
209
-
`cleancloud doctor --provider aws`,
210
-
211
-
`cleancloud doctor --provider azure`, or
212
-
213
-
`cleancloud doctor --provider gcp` first.
225
+
Run `cleancloud doctor --provider aws`, `cleancloud doctor --provider azure`, or `cleancloud doctor --provider gcp` first.
214
226
215
227
### Scan flags:
216
228
@@ -267,11 +279,7 @@ cleancloud doctor --provider gcp # check what permissions your session has
267
279
cleancloud scan --provider gcp --all-projects
268
280
```
269
281
270
-
Both AWS and Azure shells authenticate using your portal session — no separate credentials needed.
271
-
272
-
GCP Cloud Shell authenticates via gcloud Application Default Credentials, which are pre-configured in Cloud Shell.
273
-
274
-
Permissions vary by account; `doctor` tells you exactly what's available before you scan. If permissions are missing, CleanCloud skips those rules and reports what was skipped.
282
+
All three shells authenticate using your portal session — no separate credentials needed. Permissions vary by account; `doctor` tells you exactly what's available before you scan. If permissions are missing, CleanCloud skips those rules and reports what was skipped.
**Need help with OIDC or enforcement flags?**[Ask in our setup discussion →](https://github.com/cleancloud-io/cleancloud/discussions/98)
446
454
447
455
---
448
456
449
-
## Multi-Account Scanning (AWS only)
457
+
<details>
458
+
<summary>Multi-Account Scanning (AWS)</summary>
450
459
451
460
Built for enterprises running AWS Organizations. Scan every account in parallel — findings aggregated into one report.
452
461
@@ -490,23 +499,22 @@ accounts:
490
499
}
491
500
```
492
501
493
-
Full IAM policy, trust policy, and IaC templates: [AWS multi-account setup →](docs/aws.md#multi-account-scanning)
494
-
495
502
**How it works:**
496
503
497
504
-**Hub-and-spoke** — CleanCloud assumes `CleanCloudReadOnlyRole` in each target account using STS. No persistent access, no stored credentials.
498
505
-**Three discovery modes** — `.cleancloud/accounts.yaml` for explicit control, `--accounts` for quick ad-hoc scans, `--org` for full AWS Organizations auto-discovery.
499
506
-**Efficient region detection** — active regions are discovered once on the hub account and reused across all spokes. Without this: N accounts × 160 API calls just for region probing. With it: 160 calls once.
500
507
-**Parallel with isolation** — each account runs in its own thread with its own session. One account failing (AccessDenied, timeout) never affects the others.
501
-
-**Partial-success visibility** — if 2 regions fail and 7 succeed within an account, the account is marked `partial` with the failed regions named. You see exactly what was missed, not just a binary pass/fail.
508
+
-**Partial-success visibility** — if 2 regions fail and 7 succeed within an account, the account is marked `partial` with the failed regions named.
502
509
-**Live progress** — `[3/50] done production (123456789012) — 47s, 12 findings` printed as each account completes.
503
510
-**Per-account cost breakdown** — JSON output includes estimated monthly waste per account, sortable and scriptable.
Built for enterprises running large Azure tenants. Scan every subscription in parallel with one identity — findings aggregated into one report with a per-subscription cost breakdown.
Built for teams running multiple GCP projects. Scan all accessible projects in parallel with one identity — findings aggregated into one report with a per-project cost breakdown.
555
564
@@ -588,6 +597,8 @@ All read-only permissions are covered by four predefined roles: `roles/compute.v
0 commit comments