certifyclouds 1.2.0__py3-none-any.whl

cc_scanner/security.py

@@ -0,0 +1,175 @@
+"""Security findings rules engine for CertifyClouds Scanner.
+
+Analyzes scan results and generates actionable security findings.
+Uses only data already present in scan results — no additional API calls.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+SEVERITY_ORDER = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3, "INFO": 4}
+
+
+def analyze(results: dict[str, Any]) -> list[dict[str, Any]]:
+    """Analyze scan results and return a list of security findings.
+
+    Args:
+        results: Scan results dict from scanner.scan()
+
+    Returns:
+        List of finding dicts, sorted by severity (most severe first)
+    """
+    findings: list[dict[str, Any]] = []
+    now = datetime.now(timezone.utc)
+
+    for sub in results.get("subscriptions", []):
+        sub_name = sub.get("name", sub.get("id", "unknown"))
+
+        for vault in sub.get("vaults", []):
+            vault_name = vault.get("name", "unknown")
+
+            # Vault-level findings
+            _check_vault_security(vault, vault_name, sub_name, findings)
+
+            # Asset-level findings
+            for secret in vault.get("secrets", []):
+                _check_asset_expiry(secret, "secret", vault_name, sub_name, now, findings)
+
+            for cert in vault.get("certificates", []):
+                _check_asset_expiry(cert, "certificate", vault_name, sub_name, now, findings)
+
+    # Sort by severity
+    findings.sort(key=lambda f: SEVERITY_ORDER.get(f["severity"], 99))
+    return findings
+
+
+def _check_vault_security(
+    vault: dict[str, Any],
+    vault_name: str,
+    sub_name: str,
+    findings: list[dict[str, Any]],
+) -> None:
+    """Check vault-level security configuration."""
+    if vault.get("public_network_access") == "Enabled":
+        findings.append({
+            "id": "SEC-003",
+            "severity": "HIGH",
+            "title": "Public network access enabled",
+            "resource": vault_name,
+            "subscription": sub_name,
+            "recommendation": "Restrict access to specific VNets/IPs",
+        })
+
+    if vault.get("soft_delete_enabled") is False:
+        findings.append({
+            "id": "SEC-004",
+            "severity": "HIGH",
+            "title": "Soft delete disabled",
+            "resource": vault_name,
+            "subscription": sub_name,
+            "recommendation": "Enable soft delete for recovery protection",
+        })
+
+    if vault.get("purge_protection_enabled") is False:
+        findings.append({
+            "id": "SEC-005",
+            "severity": "HIGH",
+            "title": "Purge protection disabled",
+            "resource": vault_name,
+            "subscription": sub_name,
+            "recommendation": "Enable purge protection to prevent permanent deletion",
+        })
+
+    if vault.get("rbac_enabled") is False:
+        findings.append({
+            "id": "SEC-008",
+            "severity": "MEDIUM",
+            "title": "RBAC authorization not enabled",
+            "resource": vault_name,
+            "subscription": sub_name,
+            "recommendation": "Enable RBAC for fine-grained access control",
+        })
+
+    if vault.get("sku") == "standard":
+        findings.append({
+            "id": "SEC-009",
+            "severity": "LOW",
+            "title": "Standard SKU (no HSM backing)",
+            "resource": vault_name,
+            "subscription": sub_name,
+            "recommendation": "Consider Premium SKU for HSM-backed keys",
+        })
+
+
+def _check_asset_expiry(
+    asset: dict[str, Any],
+    asset_type: str,
+    vault_name: str,
+    sub_name: str,
+    now: datetime,
+    findings: list[dict[str, Any]],
+) -> None:
+    """Check individual asset expiry status."""
+    name = asset.get("name", "unknown")
+    expires_on = asset.get("expiresOn")
+    enabled = asset.get("enabled", True)
+
+    if expires_on is None:
+        # No expiry set
+        findings.append({
+            "id": "SEC-006" if asset_type == "secret" else "SEC-007",
+            "severity": "MEDIUM",
+            "title": f"{asset_type.capitalize()} has no expiry date",
+            "resource": f"{vault_name}/{name}",
+            "subscription": sub_name,
+            "recommendation": "Set an expiry date to enforce rotation",
+        })
+        return
+
+    try:
+        expiry = datetime.fromisoformat(expires_on.replace("Z", "+00:00"))
+        if expiry.tzinfo is None:
+            expiry = expiry.replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return
+
+    if expiry < now and enabled:
+        # Expired but still enabled — critical
+        findings.append({
+            "id": "SEC-001" if asset_type == "secret" else "SEC-002",
+            "severity": "CRITICAL",
+            "title": f"Expired {asset_type} still enabled",
+            "resource": f"{vault_name}/{name}",
+            "subscription": sub_name,
+            "recommendation": f"Disable or rotate this {asset_type} immediately",
+        })
+    elif expiry < now and not enabled:
+        # Expired and disabled — no finding needed
+        pass
+    else:
+        days_left = (expiry - now).days
+        if days_left <= 30:
+            findings.append({
+                "id": "SEC-010" if asset_type == "secret" else "SEC-011",
+                "severity": "INFO",
+                "title": f"{asset_type.capitalize()} expiring in {days_left} days",
+                "resource": f"{vault_name}/{name}",
+                "subscription": sub_name,
+                "recommendation": f"Plan {'rotation' if asset_type == 'secret' else 'renewal'} before expiry",
+            })
+
+
+def count_by_severity(findings: list[dict[str, Any]]) -> dict[str, int]:
+    """Count findings by severity level."""
+    counts: dict[str, int] = {}
+    for f in findings:
+        sev = f["severity"]
+        counts[sev] = counts.get(sev, 0) + 1
+    return counts
+
+
+def has_critical_or_high(findings: list[dict[str, Any]]) -> bool:
+    """Check if any findings are CRITICAL or HIGH severity."""
+    return any(f["severity"] in ("CRITICAL", "HIGH") for f in findings)

cc_scanner/thumbprint.py

@@ -0,0 +1,98 @@
+"""Thumbprint Normalization Utility
+
+Handles certificate thumbprint normalization across different sources:
+- Azure Key Vault SDK: Returns `bytes[20]` (raw SHA1 hash)
+- Microsoft Graph API: Returns base64-encoded string
+- Display format: Lowercase hex string (40 characters)
+
+All thumbprints are normalized to lowercase hex for consistent matching.
+"""
+from __future__ import annotations
+
+import base64
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_thumbprint(thumbprint: str | bytes | None) -> str:
+    """Normalize a thumbprint to lowercase hex string format.
+
+    Handles multiple input formats:
+    1. bytes (from Azure Key Vault SDK's x509_thumbprint)
+    2. Base64 string (from Microsoft Graph API's customKeyIdentifier)
+    3. Hex string (already formatted, possibly uppercase)
+    4. None or empty (returns empty string)
+    """
+    if not thumbprint:
+        return ""
+
+    try:
+        # Case 1: bytes (from Azure Key Vault SDK)
+        if isinstance(thumbprint, bytes):
+            result = thumbprint.hex().lower()
+            logger.debug(
+                "[Thumbprint] Normalized from bytes: len=%d -> hex=%s...",
+                len(thumbprint), result[:16]
+            )
+            return result
+
+        # Case 2: String input - need to determine format
+        if isinstance(thumbprint, str):
+            thumbprint_str = thumbprint.strip()
+
+            if not thumbprint_str:
+                return ""
+
+            # Check if it's already a valid hex string (40 chars for SHA1, or 64 for SHA256)
+            if _is_hex_string(thumbprint_str):
+                result = thumbprint_str.lower()
+                logger.debug(
+                    "[Thumbprint] Normalized from hex: %s... -> %s...",
+                    thumbprint_str[:16], result[:16]
+                )
+                return result
+
+            # Try to decode as base64 (Graph API format)
+            try:
+                decoded = base64.b64decode(thumbprint_str)
+                result = decoded.hex().lower()
+                logger.debug(
+                    "[Thumbprint] Normalized from base64: %s... -> %s...",
+                    thumbprint_str[:16], result[:16]
+                )
+                return result
+            except Exception:
+                pass
+
+            # Last resort: just lowercase whatever we have
+            logger.warning(
+                "[Thumbprint] Unknown format, using as-is (lowercased): %s...",
+                thumbprint_str[:16]
+            )
+            return thumbprint_str.lower()
+
+        # Unknown type
+        logger.warning(
+            "[Thumbprint] Unexpected type %s, converting to string",
+            type(thumbprint).__name__
+        )
+        return str(thumbprint).lower()
+
+    except Exception as e:
+        logger.error(
+            "[Thumbprint] Failed to normalize thumbprint: %s - %s",
+            type(thumbprint).__name__, e
+        )
+        return ""
+
+
+def _is_hex_string(s: str) -> bool:
+    """Check if a string is a valid hexadecimal string of expected thumbprint length."""
+    if len(s) not in (40, 64):
+        return False
+    try:
+        int(s, 16)
+        return True
+    except ValueError:
+        return False

certifyclouds-1.2.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: certifyclouds
+Version: 1.2.0
+Summary: Scan Azure Key Vaults for expiring secrets, certificates, and keys
+Project-URL: Homepage, https://certifyclouds.com/scanner
+Project-URL: Documentation, https://docs.certifyclouds.com/scanner
+Project-URL: Repository, https://codeberg.org/hus/cc
+Author-email: CertifyClouds <hello@certifyclouds.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: azure,certificates,expiry,keyvault,rotation,scanner,secrets,security
+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: 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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: azure-core>=1.30
+Requires-Dist: azure-identity>=1.20
+Requires-Dist: azure-keyvault-certificates>=4.9
+Requires-Dist: azure-keyvault-keys>=4.10
+Requires-Dist: azure-keyvault-secrets>=4.9
+Requires-Dist: azure-mgmt-keyvault>=13.0
+Requires-Dist: azure-mgmt-resource>=24.0
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: tenacity>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cc-scanner
+
+**Do you know which Azure secrets expire this month?**
+
+Scan all your Azure Key Vaults across every subscription in 30 seconds. Free, open source, works in Azure Cloud Shell.
+
+```
+pip install cc-scanner
+cc-scan
+```
+
+## What you get
+
+- Cross-subscription inventory of every secret, certificate, and key
+- Expiry warnings: expired, <7 days, <30 days, <90 days (color-coded)
+- Security findings: public access, soft delete, RBAC, missing expiry dates
+- Export to JSON, CSV, or standalone HTML report
+- Works in Azure Cloud Shell with zero setup
+
+## Quick Start
+
+```bash
+# 1. Install
+pip install cc-scanner
+
+# 2. Authenticate (skip in Azure Cloud Shell)
+az login
+
+# 3. Scan
+cc-scan
+```
+
+On first run, you'll be prompted to register with your email (free, takes 10 seconds). Your API key is saved locally to `~/.certifyclouds/config.json`.
+
+## Output
+
+```
+CertifyClouds Scanner v1.2.0
+Authenticated as: you@company.com
+
+Scanning Azure subscriptions...
+
+Production (sub-abc123)
+  vault-prod (eastus) - 45 secrets, 12 certificates, 3 keys
+  vault-shared (westeurope) - 23 secrets, 5 certificates, 1 key
+
+SUMMARY
+  Subscriptions: 2    Vaults: 4    Total assets: 112
+  Secrets: 88    Certificates: 20    Keys: 4
+
+EXPIRY WARNINGS
+  EXPIRED     3 secrets, 1 certificate
+  < 7 days    2 secrets
+  < 30 days   8 secrets, 2 certificates
+
+SECURITY FINDINGS
+  CRITICAL: 3    HIGH: 2    MEDIUM: 47    LOW: 1
+
+  CRITICAL   Expired secret still enabled       vault-prod/db-password
+  HIGH       Public network access enabled      vault-legacy
+  MEDIUM     Secret has no expiry date          vault-prod/api-key
+```
+
+## Usage
+
+```bash
+# Output formats
+cc-scan --format table           # Default: pretty terminal output
+cc-scan --format json            # Full JSON (pipe-friendly)
+cc-scan --format csv             # Flat CSV (for spreadsheets)
+cc-scan --format html            # Standalone HTML report
+
+# Write to file
+cc-scan --output report.html --format html
+cc-scan --output scan.json --format json
+
+# Filters
+cc-scan --expiring 30            # Only items expiring within 30 days
+cc-scan --expired                # Only already-expired items
+cc-scan --type secrets           # Only secrets (or: certificates, keys)
+cc-scan --vault vault-prod       # Specific vault(s) (repeatable)
+cc-scan --subscription sub-123   # Specific subscription(s) (repeatable)
+
+# Security summary only
+cc-scan --security               # Show findings without per-item details
+
+# Azure auth
+cc-scan --auth cli               # Azure CLI credential (default)
+cc-scan --auth default           # DefaultAzureCredential (managed identity/SP)
+
+# Tuning
+cc-scan --workers 10             # Parallel workers (default: 5, max: 20)
+cc-scan --timeout 600            # Scan timeout in seconds (default: 300)
+
+# Other
+cc-scan --offline                # Skip license server validation
+cc-scan --register               # Re-register / change email
+cc-scan --key cc-scan-xxxxx      # Use a specific API key
+cc-scan --version                # Show version
+cc-scan --help                   # Show all options
+```
+
+## Environment Variables
+
+All flags can be set via environment variables (flags take priority):
+
+```bash
+CC_SCAN_KEY=cc-scan-xxxxx        # API key
+CC_SCAN_AUTH=cli                 # Auth method
+CC_SCAN_FORMAT=json              # Output format
+CC_SCAN_WORKERS=10               # Workers
+CC_SCAN_TIMEOUT=600              # Timeout
+CC_SCAN_OFFLINE=true             # Offline mode
+```
+
+For service principal auth (used with `--auth default`):
+
+```bash
+AZURE_CLIENT_ID=...
+AZURE_CLIENT_SECRET=...
+AZURE_TENANT_ID=...
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Scan completed, no critical/high findings |
+| 1 | Scan completed, critical or high findings detected |
+| 2 | Scan failed (auth error, network error, timeout) |
+| 3 | Registration required / invalid API key |
+
+Non-zero exit codes make this CI/cron-friendly: `cc-scan || notify-team`.
+
+## Azure Permissions
+
+Your identity needs these roles on each Key Vault:
+
+| Role | Why |
+|------|-----|
+| Key Vault Secrets User | List and read secret properties |
+| Key Vault Certificate User | List and read certificate properties |
+| Key Vault Crypto User | List and read key properties |
+| Reader | List Key Vaults across subscriptions |
+
+Assign roles in Azure Portal: Key Vault > Access control (IAM) > Add role assignment.
+
+If a vault has firewall restrictions, you'll see an inline error (the scan continues to the next vault).
+
+## Security Findings
+
+The scanner checks for 11 security rules:
+
+| ID | Severity | What it checks |
+|----|----------|---------------|
+| SEC-001 | CRITICAL | Expired secret still enabled |
+| SEC-002 | CRITICAL | Expired certificate still enabled |
+| SEC-003 | HIGH | Public network access enabled on vault |
+| SEC-004 | HIGH | Soft delete disabled |
+| SEC-005 | HIGH | Purge protection disabled |
+| SEC-006 | MEDIUM | Secret has no expiry date set |
+| SEC-007 | MEDIUM | Certificate has no expiry date set |
+| SEC-008 | MEDIUM | RBAC authorization not enabled |
+| SEC-009 | LOW | Standard SKU (no HSM backing) |
+| SEC-010 | INFO | Secret expiring within 30 days |
+| SEC-011 | INFO | Certificate expiring within 30 days |
+
+## Privacy & Telemetry
+
+CertifyClouds Scanner sends **aggregate usage statistics** to improve the product. Here's exactly what is sent:
+
+**Sent:** API key, CLI version, counts (subscriptions, vaults, secrets, certificates, keys, expired, expiring soon, security findings, vaults with errors), scan duration.
+
+**Never sent:** Vault names or URIs, secret/certificate/key names, secret values, subscription IDs or names, Azure tenant IDs, resource group names, tags, certificate subjects or thumbprints.
+
+Use `--offline` to disable all network calls to the license server. The scan works fully offline.
+
+Source code is open and auditable: [codeberg.org/hus/cc/scanner](https://codeberg.org/hus/cc)
+
+## Troubleshooting
+
+**"No Azure credentials found"**
+Run `az login` to authenticate, or set `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID` for service principal auth.
+
+**Vault shows "Firewall restriction"**
+Run cc-scan from an allowed network or add your IP in Azure Portal (Key Vault > Networking).
+
+**Vault shows "Access denied"**
+Your identity needs the roles listed in [Azure Permissions](#azure-permissions).
+
+**"Could not reach license.certifyclouds.com"**
+Check internet connection. Behind a proxy? Set `HTTPS_PROXY`. Or use `--offline` mode.
+
+**Slow scans**
+Increase workers: `cc-scan --workers 10`. Each subscription is scanned in parallel.
+
+## Requirements
+
+- Python 3.9+
+- Azure CLI (`az login`) or service principal credentials
+- Network access to Azure management and Key Vault data plane APIs
+
+## License
+
+Apache 2.0. See [LICENSE](LICENSE).
+
+## Links
+
+- [CertifyClouds](https://certifyclouds.com) - Automate secret rotation & compliance
+- [Documentation](https://docs.certifyclouds.com/scanner)
+- [Source Code](https://codeberg.org/hus/cc)

certifyclouds-1.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+cc_scanner/__init__.py,sha256=UvDKQpOLThCNfGAnT7jqr3SXEuVUZMGtUZfRbALIoaA,123
+cc_scanner/auth.py,sha256=LEUPT1OM4Ut3-igSzvRP5LQu-fjnp8l7kv5VLJ_4FWo,3035
+cc_scanner/cli.py,sha256=RubxCSnhQYj0jJNlHMmummx1jhv8lWn8wtg6G0YC1AI,12309
+cc_scanner/config.py,sha256=2mWfMu_jWfF66SOcySYze4xGKuAO1hppcpZR5eOY1FY,2766
+cc_scanner/filters.py,sha256=yauU88xWDkab_hhr2mni9f7xBWW3Tiyd2I4nNj23WE8,4905
+cc_scanner/registration.py,sha256=2bbE7UQ_8zeBFqjXu9oosoR65FA3UMJUOfqSe4aKdWc,2928
+cc_scanner/scanner.py,sha256=di82PqwGn47gxzQTT62p5IBjgMrTAXfPUCcPfR--6YE,30382
+cc_scanner/security.py,sha256=X8OqghtRC6IQI7R2IQxK0JVXXazNbV5knwC4fL7K2TA,6025
+cc_scanner/thumbprint.py,sha256=hwcg5qqy0p-f4W4uS8eIbVRKBppeF_PcxiLu_0ov7w0,3197
+cc_scanner/formatters/__init__.py,sha256=ZpxcJqEBRtXJpfaM2k02i_I-m1kGOyFruqiZb2r04Ac,555
+cc_scanner/formatters/csv_fmt.py,sha256=vtC_fhIgS_YEI6ZAIdwCTjml50KcYkN-tB1SYhpQi2M,2588
+cc_scanner/formatters/html.py,sha256=IbWyvhP-zfDRAHVcv-j2rlB0uKg_ZTXDk3X8udpM5Vs,8840
+cc_scanner/formatters/json_fmt.py,sha256=LVJK8pNyZiumF7zLKCiWr8Vw8QosgaIkwCrFtSn4-hU,793
+cc_scanner/formatters/table.py,sha256=dcdR3X_7qx_oQ6n5CB3cbmy9ePCmQJEXenKFkiiZVno,6823
+certifyclouds-1.2.0.dist-info/METADATA,sha256=7ECsp68t8s3lTqJLUm0keYZCYUCEHYFSWmNFrbNSKhQ,8673
+certifyclouds-1.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+certifyclouds-1.2.0.dist-info/entry_points.txt,sha256=vxwSbE52iqCuQEHIx17VwPPdMIE6am0e46kmYAbCZ7g,48
+certifyclouds-1.2.0.dist-info/licenses/LICENSE,sha256=LstlN_mRiSNm-hVYNdlu6sEDIRozNIXd-0wnYXoqbSA,10764
+certifyclouds-1.2.0.dist-info/RECORD,,

certifyclouds-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

certifyclouds-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cc-scan = cc_scanner.cli:main