CleanCloud

Reduce cloud costs through safe, read-only hygiene evaluation

CleanCloud helps teams reduce cloud costs by safely identifying orphaned, untagged, and inactive resources for review. Built as a read-only, trust-first hygiene evaluation engine for AWS and Azure — safe to run in production and CI/CD pipelines. Designed for SRE and platform teams who need cost optimization without mutations, deletions, or automated cleanup.

⚠️ Read-only by design - No deletions, no tag modifications, no resource changes
⚠️ Policy-safe - Conservative signals with explicit confidence levels
⚠️ Privacy-first - Zero telemetry, no phone-home, no data collection

Security & Trust

CleanCloud is designed for enterprise environments where security review and approval are required.

Why InfoSec Teams Trust CleanCloud

Verifiable Read-Only Design:

🔒 IAM Proof Pack: Audit a 30-line JSON policy, not our code
🎫 OIDC-First: Temporary credentials, no secrets stored
✅ Cloud-Enforced: AWS/Azure guarantees read-only, not us
🛡️ Conservative Detection: MEDIUM confidence by default, age thresholds, explicit evidence

How It Works:

You create a read-only IAM role (we provide the JSON policy)
Run our verification script to prove it's safe
CleanCloud scans using temporary OIDC tokens
Results are yours - we never see your data

The Trust Model:

"By requiring a separate, verifiable Read-Only IAM role, CleanCloud shifts trust from our code to your Cloud Provider's enforcement. InfoSec teams don't need to audit our Python code line-by-line—they audit a 30-line JSON policy and verify it's read-only."

Read-Only by Design

No destructive permissions required:

✅ Only List*, Describe*, Get* operations
❌ No Delete*, Modify*, or Tag* permissions
❌ No resource mutations or state changes
✅ Safe for production accounts and regulated environments

IAM Proof Pack: Ready-to-use policies and verification scripts with automated safety tests

OIDC-First Authentication

No long-lived credentials:

✅ AWS IAM Roles with GitHub Actions OIDC (recommended)
✅ Azure Workload Identity Federation (recommended)
✅ Short-lived tokens only
❌ No stored credentials in CI/CD

Privacy Guarantees

Zero telemetry, zero outbound calls:

❌ No analytics or usage tracking
❌ No phone-home or update checks
❌ No data collection of any kind
✅ Only AWS/Azure API calls (read-only)

Safety Regression Tests

Multi-layer 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

For InfoSec Teams:

🔒 Security Policy & Threat Model - Enterprise security documentation
📋 Information Security Readiness Guide
🔐 IAM Proof Pack Documentation
🛡️ Threat Model & Mitigations
✅ Safety Test Documentation

Who CleanCloud Is (and Is Not) For

CleanCloud is for:

Teams optimizing cloud costs in production and staging environments
SRE / Platform teams who need safe, read-only hygiene evaluation
Security-reviewed and regulated environments where mutations are prohibited
CI/CD pipelines that enforce cost hygiene without infrastructure changes
Organizations using IaC and ephemeral resources

CleanCloud is NOT:

❌ An automated cleanup or deletion service (one-click account nuking)
❌ A replacement for Trusted Advisor or Config
❌ A cost dashboard with rightsizing recommendations
❌ A tool that modifies, tags, or deletes resources

CleanCloud exists to answer one question safely:

What orphaned resources are costing us money — without risking production?

Built for Production & Enterprise Use

CleanCloud is designed to be approved by security teams, not bypassed.

Enterprise Features

✅ Read-only by design - No Delete*, Modify*, or Tag* permissions required
✅ OIDC-first authentication - AWS IAM Roles & Azure Workload Identity
✅ Parallel, multi-region scanning - Fast execution across all regions
✅ CI/CD native - Stable exit codes, JSON/CSV output, policy enforcement
✅ Audit-friendly - Deterministic output, no side effects, versioned schemas

Stability Guarantees

🔒 CLI backward compatibility within major versions
🔒 Exit codes are stable and intentional - Never fails builds by accident
🔒 JSON schemas are versioned - Safe to parse programmatically
🔒 Read-only always - Safety regression tests in CI

Exit Codes

Safe by Default: CleanCloud reports findings but exits with code 0 (success) unless you explicitly configure failure conditions.

Code	Meaning
`0`	Scan completed successfully (default: findings reported but don't fail)
`1`	Configuration error, invalid region/location, or unexpected error
`2`	Policy violation (only when using `--fail-on-findings` or `--fail-on-confidence`)
`3`	Missing permissions or invalid credentials

Examples:

# Default: Reports findings, exits 0 (safe for any pipeline)
cleancloud scan --provider aws --region us-east-1

# Fail on HIGH confidence findings only
cleancloud scan --provider aws --region us-east-1 --fail-on-confidence HIGH

# Fail on MEDIUM or higher confidence
cleancloud scan --provider aws --region us-east-1 --fail-on-confidence MEDIUM

# Fail on ANY findings (strict mode)
cleancloud scan --provider aws --region us-east-1 --fail-on-findings

Quick Start

Requirements

Python: 3.9 or later

Cloud Access:

AWS: AWS CLI configured, or IAM role (for CI/CD), or environment variables
Azure: Azure CLI authenticated, or Workload Identity (for CI/CD)

Running Locally

Use CleanCloud locally for development, testing, and ad-hoc hygiene reviews.

1. Installation

pip install cleancloud

2. Set Up Credentials

AWS:

export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export AWS_DEFAULT_REGION=us-east-1

Azure:

export AZURE_CLIENT_ID=<your-client-id>
export AZURE_TENANT_ID=<your-tenant-id>
export AZURE_CLIENT_SECRET=<your-client-secret>
export AZURE_SUBSCRIPTION_ID=<your-subscription-id>

Alternative methods: AWS CLI profiles and Azure CLI are also supported. See Configuration for details.

3. Validate Credentials

# AWS - validate credentials and permissions
# Defaults to us-east-1 if --region not specified
cleancloud doctor --provider aws
cleancloud doctor --provider aws --region us-west-2

# Azure - validate credentials and subscription access
# Note: --region parameter is not applicable for Azure doctor
cleancloud doctor --provider azure

4. Run a Scan

# AWS - single region
cleancloud scan --provider aws --region us-east-1

# AWS - all active regions (auto-detects regions with resources)
cleancloud scan --provider aws --all-regions

# Azure - all subscriptions (default)
cleancloud scan --provider azure

# Azure - specific subscription
cleancloud scan --provider azure --subscription <subscription-id>

# Azure - multiple subscriptions
cleancloud scan --provider azure --subscription <sub-id-1> --subscription <sub-id-2>

# Azure - filter by location
cleancloud scan --provider azure --region eastus

# Azure - specific subscription and location
cleancloud scan --provider azure --subscription <subscription-id> --region eastus

5. View Results

# Human-readable output (default)
cleancloud scan --provider aws --region us-east-1

# JSON output (AWS)
cleancloud scan --provider aws --region us-east-1 --output json --output-file results.json

# JSON output (Azure)
cleancloud scan --provider azure --output json --output-file results.json

# CSV output
cleancloud scan --provider aws --region us-east-1 --output csv --output-file results.csv

JSON Output Schema:

CleanCloud uses a versioned JSON schema (current: 1.0.0). All JSON output includes a schema_version field for backward compatibility.

Schema Definition: schemas/output-v1.0.0.json
Complete Examples: docs/ci.md#json-output-machine-readable

AWS and Azure have slightly different summary structures:

AWS: Uses region_selection_mode with values "explicit" or "all-regions"
Azure: Uses subscription_selection_mode with values "explicit" or "all", plus subscriptions_scanned array

CSV Output: CSV is a simplified format containing core fields (11 columns) for spreadsheet review. Use JSON for complete data including evidence and diagnostic details.

Running in CI/CD Pipelines

CleanCloud is designed for CI/CD environments with OIDC authentication (no secrets required).

Requirements for CI/CD

Python: 3.9 or later (usually pre-installed in GitHub Actions runners)

Authentication:

AWS: IAM Role with OIDC trust relationship (GitHub Actions recommended)
Azure: Workload Identity Federation (Microsoft Entra ID recommended)

Key Differences from Local Usage:

Uses OIDC (OpenID Connect) instead of CLI credentials
No long-lived secrets stored in CI
Safe by default: exits 0 even with findings (won't block deployments)
Opt-in strict mode with --fail-on-confidence or --fail-on-findings flags

Quick Example: GitHub Actions with AWS

permissions:
  id-token: write  # Required for OIDC
  contents: read

jobs:
  cleancloud:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<ACCOUNT_ID>:role/CleanCloudCIReadOnly
          aws-region: us-east-1

      - name: Run CleanCloud scan
        run: |
          pip install cleancloud
          cleancloud scan \
            --provider aws \
            --region us-east-1 \
            --output json \
            --output-file scan.json
            # Default: Reports findings, exits 0 (safe, won't fail deployment)
            # Add --fail-on-confidence HIGH to enforce strict policy

Quick Example: GitHub Actions with Azure

permissions:
  id-token: write  # Required for OIDC
  contents: read

jobs:
  cleancloud:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - 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: Run CleanCloud scan
        run: |
          pip install cleancloud
          cleancloud scan \
            --provider azure \
            --output json \
            --output-file scan.json
            # Default: Reports findings, exits 0 (safe, won't fail deployment)
            # Add --fail-on-confidence HIGH to enforce strict policy

Complete CI/CD documentation: See docs/ci.md for detailed setup instructions.

What CleanCloud Detects

CleanCloud intentionally starts with a small number of high-signal rules.

Each rule:

Is read-only
Uses multiple conservative signals
Avoids false positives in IaC environments
Includes explicit confidence levels

See docs/rules.md for full details.

Policy Enforcement

Default Behavior: CleanCloud reports findings but does not fail builds (exits 0). This makes it safe for scheduled scans, CI/CD pipelines, and exploratory runs.

Opt-in strict mode with explicit flags:

# Default: Report findings, don't fail builds (exit 0)
cleancloud scan --provider aws --region us-east-1

# Fail on HIGH confidence findings
cleancloud scan --provider aws --region us-east-1 --fail-on-confidence HIGH

# Fail on MEDIUM or higher confidence
cleancloud scan --provider aws --region us-east-1 --fail-on-confidence MEDIUM

# Fail on LOW or higher (all findings by confidence)
cleancloud scan --provider aws --region us-east-1 --fail-on-confidence LOW

# Fail on ANY findings (strict mode, ignores confidence levels)
cleancloud scan --provider aws --region us-east-1 --fail-on-findings

Azure Examples:

# Default: Report findings, don't fail builds (exit 0)
cleancloud scan --provider azure

# Fail on HIGH confidence findings
cleancloud scan --provider azure --fail-on-confidence HIGH

# Fail on MEDIUM or higher confidence
cleancloud scan --provider azure --fail-on-confidence MEDIUM

# Fail on LOW or higher (all findings by confidence)
cleancloud scan --provider azure --fail-on-confidence LOW

# Fail on ANY findings (strict mode, ignores confidence)
cleancloud scan --provider azure --fail-on-findings

# With specific subscription
cleancloud scan --provider azure --subscription <subscription-id>

Note: Policy enforcement works identically for both AWS and Azure providers.

Configuration

AWS Authentication

Local Development:

export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>
export AWS_DEFAULT_REGION=us-east-1

cleancloud scan --provider aws --region us-east-1

CI/CD:

Use GitHub Actions OIDC (see Running in CI/CD Pipelines)
Requires IAM role with read-only permissions

IAM Permissions:

Only List*, Describe*, Get* operations required
No Delete*, Modify*, or Tag* permissions
Full policy and alternative auth methods: docs/aws.md

Azure Authentication

Local Development:

export AZURE_CLIENT_ID=<your-client-id>
export AZURE_TENANT_ID=<your-tenant-id>
export AZURE_CLIENT_SECRET=<your-client-secret>
export AZURE_SUBSCRIPTION_ID=<your-subscription-id>

cleancloud scan --provider azure

CI/CD:

Use Azure Workload Identity Federation (see Running in CI/CD Pipelines)
Requires Reader role at subscription scope

Permissions:

Only read-only access required
No write, delete, or tag permissions
Full setup guide and alternative auth methods: docs/azure.md

Subscription Filtering:

# Default: scan all accessible subscriptions
cleancloud scan --provider azure

# Scan specific subscriptions
cleancloud scan --provider azure --subscription <sub-id-1> --subscription <sub-id-2>

Tag-Based Filtering (Ignore Only)

CleanCloud supports tag-based filtering to reduce noise by ignoring findings for resources you explicitly mark.

This is useful when certain environments, teams, or services should be out of scope for hygiene review (for example: production or shared platform resources).

⚠️ Tag filtering is ignore-only

It does not disable rules, modify resources, or protect them from deletion.
CleanCloud remains read-only and review-only.

Configuration File (cleancloud.yaml)

Create a cleancloud.yaml file in your project root (or specify a custom path with --config):

version: 1

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

Usage:

# With config file in repository root
cleancloud scan --provider aws --region us-east-1 --config cleancloud.yaml

# Or specify full path
cleancloud scan --provider aws --region us-east-1 --config /path/to/cleancloud.yaml

Behavior:

If a resource has any matching tag, its finding is ignored
Matching is exact (no regex, no partial matches)
Multiple ignore rules are OR'ed (any match ignores)

Command Line Overrides (Highest Priority)

You can pass ignore tags directly via CLI:

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

Important:

CLI --ignore-tag replaces YAML configuration
YAML and CLI tags are not merged
This ensures CI/CD runs are explicit and predictable

Scan Output & Transparency

Ignored findings are:

❌ Not included in scan results

✅ Counted and reported in the summary

✅ Preserved internally for auditability

Example summary output:

Ignored by tag policy: 7 findings

Recommended Usage

Tag filtering works best with broad ownership or scope tags, such as:

env: production
team: platform
service: core-infra

It is not intended for per-resource exceptions or lifecycle management.

Why Teams Choose CleanCloud

Cost Optimization Without Compromising Safety

Cost dashboards show you spending trends and rightsizing recommendations.

CleanCloud helps you reduce costs by safely identifying waste — orphaned resources, unattached volumes, and inactive assets — without mutations or automation risk.

Need	Cost Dashboards	CleanCloud
Spending trends & analysis	✅ Excellent	➖ Not a goal
Orphaned resource detection	❌ Limited or noisy	✅ Conservative, high-signal
Safe for production	⚠️ Varies	✅ Read-only always
CI/CD cost enforcement	❌ Not designed for it	✅ Purpose-built
Confidence scoring	❌ Binary yes/no	✅ LOW/MEDIUM/HIGH
No mutations required	⚠️ Often needs write access	✅ Read-only by design

CleanCloud Complements Your Cost Tools

Use cost dashboards to track spending and identify trends
Use CleanCloud to find and review orphaned resources that are costing money

Cost dashboards show you what you're spending. CleanCloud shows you what you can safely stop spending.

Learn more: Where CleanCloud Fits (design diagram)

Design Philosophy

CleanCloud is built on three core principles:

1. Conservative by Default - Multiple signals with explicit confidence levels (LOW/MEDIUM/HIGH) reduce false positives

2. Read-Only Always - No Delete*, Tag*, or Modify* permissions; safe for production

3. Review-Only Recommendations - Findings are candidates for review, not automated action

Learn more: Confidence logic documentation

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 (unused Elastic IPs, old AMIs, empty security groups)
Additional Azure rules (unused NICs, old images)
Rule filtering (--rules flag)

Not Planned

These are intentional non-goals to preserve safety and trust.

Automated cleanup or deletion
Rightsizing or instance optimization suggestions
Billing data access or spending analysis
Resource tagging or mutations

CleanCloud will remain focused on safe cost optimization through hygiene detection, not automation or infrastructure changes.

Documentation

SECURITY.md - Security policy and threat model for enterprise evaluation
docs/infosec-readiness.md - Information security readiness guide for enterprise teams
security/ - IAM Proof Pack (ready-to-use policies and verification scripts)
docs/rules.md - Detailed rule behavior and signals
docs/aws.md - AWS setup and IAM policy
docs/azure.md - Azure setup and RBAC configuration
docs/ci.md - CI/CD integration examples

💬 Questions or Feedback?

We'd love to hear from you:

🐛 Found a bug? Open an issue
💡 Have a feature request? Start a discussion
📧 Want to chat? Email us at suresh@getcleancloud.com
🌟 Like CleanCloud? Star us on GitHub

Using CleanCloud in production? We'd love to feature your story!

Contributing

Contributions are welcome! Please ensure all PRs:

Include tests for new rules
Follow the conservative design philosophy
Maintain read-only operation
Include documentation updates

See CONTRIBUTING.md for details.

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github		.github
cleancloud		cleancloud
docs		docs
schemas		schemas
security		security
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MAINTAINERS.md		MAINTAINERS.md
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini

License

cleancloud-io/cleancloud

Folders and files

Latest commit

History

Repository files navigation

CleanCloud

Table of Contents

Security & Trust

Why InfoSec Teams Trust CleanCloud

Read-Only by Design

OIDC-First Authentication

Privacy Guarantees

Safety Regression Tests

Who CleanCloud Is (and Is Not) For

Built for Production & Enterprise Use

Enterprise Features

Stability Guarantees

Exit Codes

Quick Start

Requirements

Running Locally

1. Installation

2. Set Up Credentials

3. Validate Credentials

4. Run a Scan

5. View Results

Running in CI/CD Pipelines

Requirements for CI/CD

Quick Example: GitHub Actions with AWS

Quick Example: GitHub Actions with Azure

What CleanCloud Detects

Policy Enforcement

Configuration

AWS Authentication

Azure Authentication

Tag-Based Filtering (Ignore Only)

Configuration File (cleancloud.yaml)

Command Line Overrides (Highest Priority)

Scan Output & Transparency

Recommended Usage

Why Teams Choose CleanCloud

Cost Optimization Without Compromising Safety

CleanCloud Complements Your Cost Tools

Design Philosophy

Roadmap

Coming Soon

Not Planned

Documentation

💬 Questions or Feedback?

Contributing

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages