Security Policy

CleanCloud Security Documentation Version: 1.0 Last Updated: 2026-01-21 Classification: Public

Executive Summary

CleanCloud is a read-only cloud hygiene evaluation tool designed for enterprise and government organizations with strict security requirements. This document provides comprehensive security information for InfoSec teams, security architects, and compliance officers evaluating CleanCloud for deployment.

Automated Security Scanning

Every code change undergoes 6 automated security gates:

┌─────────────────────────────────────────────────────┐
│   Automated Security Pipeline (Every PR + Main)     │
├─────────────────────────────────────────────────────┤
│  ✅ Dependency CVE Scan     → pip-audit             │
│  ✅ SAST (Code Security)    → Bandit                │
│  ✅ Advanced SAST           → CodeQL                │
│  ✅ Secrets Detection       → TruffleHog            │
│  ✅ License Compliance      → pip-licenses          │
│  ✅ Safety Regression       → Custom read-only test │
│                                                     │
│  Policy: ANY FAILURE = MERGE BLOCKED                │
└─────────────────────────────────────────────────────┘

Current Status (2026-01-21): ✅ Zero CVEs, ✅ Zero HIGH/MEDIUM issues, ✅ Zero secrets

Security Posture Summary

Security Domain	Status	Details
Read-Only by Design	✅ Enforced	No write, delete, or modify permissions required
Zero Telemetry	✅ Enforced	No data leaves your environment
OIDC Authentication	✅ Supported	Short-lived credentials, no secrets storage
Automated Security Scanning	✅ Active	6 security gates on every commit (pip-audit, Bandit, CodeQL, TruffleHog, license checks, safety tests)
Supply Chain Security	✅ Active	Real-time CVE monitoring, SBOM generation, Dependabot auto-updates
Secrets Detection	✅ Active	TruffleHog scans every commit for leaked credentials
Audit Trail	✅ Supported	Deterministic output, versioned schemas, 30-day scan artifact retention
Open Source	✅ MIT License	Full code transparency, community security review

Security Architecture

Design Principles

CleanCloud is built on defense-in-depth principles with security enforced at multiple layers:

Read-Only by Design - Architecture prevents mutations through IAM policy restrictions
Least Privilege - Minimal permissions (List*, Describe*, Get* only)
Zero Trust - No implicit trust in cloud provider APIs
Fail-Safe Defaults - Operations default to safe, non-destructive behavior
Complete Mediation - All cloud API calls go through auditable SDK layers

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                      User Environment                        │
│  ┌────────────┐     ┌──────────────┐     ┌──────────────┐  │
│  │   CI/CD    │────▶│  CleanCloud  │────▶│  Cloud APIs  │  │
│  │  Pipeline  │     │   (Read-Only)│     │  (Read-Only) │  │
│  └────────────┘     └──────────────┘     └──────────────┘  │
│         │                   │                     │          │
│         │                   ▼                     │          │
│         │            ┌──────────────┐            │          │
│         └───────────▶│ JSON/CSV Out │◀───────────┘          │
│                      │  (Local FS)  │                       │
│                      └──────────────┘                       │
│                                                              │
│  ❌ No outbound calls to CleanCloud servers                 │
│  ❌ No telemetry or phone-home                              │
│  ❌ No write operations to cloud providers                  │
└─────────────────────────────────────────────────────────────┘

Network Security

Outbound Connections:

✅ AWS/Azure API endpoints only (HTTPS, TLS 1.2+)
❌ No connections to CleanCloud infrastructure (we have none)
❌ No analytics or telemetry endpoints
❌ No update servers or phone-home

Inbound Connections:

❌ Not applicable (CleanCloud is a CLI tool, not a service)

Authentication & Authorization

Supported Authentication Methods

Provider	Method	Security Level	Use Case
AWS	OIDC (IAM Roles)	⭐⭐⭐⭐⭐ Excellent	CI/CD (GitHub Actions) - Recommended
AWS	IAM Access Keys	⭐⭐ Poor	Local development only
Azure	OIDC (Workload Identity)	⭐⭐⭐⭐⭐ Excellent	CI/CD (GitHub Actions) - Recommended
Azure	Service Principal (Secret)	⭐⭐ Poor	Local development only
Azure	Azure CLI	⭐⭐⭐ Acceptable	Local development only
Azure	Managed Identity	⭐⭐⭐⭐⭐ Excellent	Azure VM/Container Apps

OIDC Implementation (Recommended)

CleanCloud supports OpenID Connect (OIDC) federation with GitHub Actions, eliminating the need to store long-lived credentials:

✅ Short-lived tokens (1 hour validity)
✅ No secrets in CI/CD
✅ Automatic rotation
✅ Conditional access via trust policies

Example AWS IAM Trust Policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:your-org/your-repo:*"
        }
      }
    }
  ]
}

See: IAM Proof Pack for complete examples.

Threat Model

Overview

CleanCloud is designed with security-first architecture to address industry-standard threats facing cloud tooling. This section demonstrates how CleanCloud's design mitigates common attack vectors through defense-in-depth principles.

Assets Protected

Cloud Resource Metadata (read by CleanCloud) - Protected by read-only access
Cloud Credentials (provided by user) - Protected by OIDC and IAM least privilege
Scan Results (stored locally) - User-controlled, no external transmission
CleanCloud Source Code (open source, MIT licensed) - Transparent and auditable

Industry Threat Landscape & CleanCloud's Defenses

CleanCloud's architecture addresses standard cloud security threats:

Threat Category	Industry Risk	CleanCloud's Defense	Status
Credential Exposure	Long-lived secrets in code/CI	OIDC support, no secret storage	✅ Mitigated
Excessive Permissions	Over-privileged cloud access	Read-only by design, IAM Proof Pack	✅ Mitigated
Supply Chain Attacks	Compromised dependencies	Automated CVE scanning, SBOM	✅ Monitored
Data Exfiltration	Telemetry to vendor servers	Zero telemetry, fully local	✅ Eliminated
Accidental Changes	Unintended resource mutations	Architectural impossibility (read-only)	✅ Eliminated

Threat Analysis & Mitigations

T1: Credential Protection

Scenario: Cloud credentials used by any tool could be exposed through code commits, logs, or CI/CD systems.