sofe 0.1.0__py3-none-any.whl

sofe/__init__.py

@@ -0,0 +1,2 @@
+"""SOFE — Stairway Open FinOps Engine. Policies as Code for AWS."""
+__version__ = "0.1.0"

sofe/cli.py

@@ -0,0 +1,121 @@
+"""SOFE CLI — sofe evaluate, sofe validate."""
+
+import json
+import click
+from .loader import load_policies, validate_policies
+from .engine import evaluate
+from .models import Finding
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def main():
+    """SOFE — Stairway Open FinOps Engine. Policies as Code for AWS."""
+    pass
+
+
+@main.command()
+@click.option("--policies", "-p", required=True, help="Path to policies directory or file")
+@click.option("--format", "-f", "fmt", default="table", type=click.Choice(["table", "json", "markdown"]))
+@click.option("--min-severity", default=None, type=click.Choice(["critical", "high", "medium", "low", "info"]))
+@click.option("--fail-on", default=None, type=click.Choice(["critical", "high", "medium", "low"]))
+@click.option("--profile", default=None, help="AWS profile to use")
+@click.option("--dry-run", is_flag=True, help="Show what would be evaluated without calling AWS")
+def evaluate_cmd(policies, fmt, min_severity, fail_on, profile, dry_run):
+    """Evaluate policies against live AWS resources."""
+    from .collectors import collect_all
+
+    click.echo(f"📋 Loading policies from: {policies}")
+    policy_list = load_policies(policies)
+    click.echo(f"   Found {len(policy_list)} policies")
+
+    if dry_run:
+        click.echo("\n🔍 DRY RUN — would evaluate:")
+        for p in policy_list:
+            click.echo(f"   • {p.metadata.name} ({p.spec.severity.value}) → {p.spec.scope.resource_types}")
+        return
+
+    click.echo(f"\n☁️  Scanning AWS resources (profile: {profile or 'default'})...")
+    resources = collect_all(profile=profile, resource_types=_get_required_types(policy_list))
+    click.echo(f"   Found {len(resources)} resources")
+
+    click.echo(f"\n⚡ Evaluating {len(policy_list)} policies against {len(resources)} resources...")
+    findings = evaluate(policy_list, resources)
+
+    # Filter by severity
+    if min_severity:
+        severity_order = ["critical", "high", "medium", "low", "info"]
+        min_idx = severity_order.index(min_severity)
+        findings = [f for f in findings if severity_order.index(f.severity.value) <= min_idx]
+
+    # Output
+    if fmt == "json":
+        click.echo(json.dumps([f.model_dump(mode="json") for f in findings], indent=2, default=str))
+    elif fmt == "markdown":
+        _output_markdown(findings)
+    else:
+        _output_table(findings)
+
+    # Exit code
+    if fail_on and findings:
+        severity_order = ["critical", "high", "medium", "low"]
+        fail_idx = severity_order.index(fail_on)
+        blocking = [f for f in findings if severity_order.index(f.severity.value) <= fail_idx]
+        if blocking:
+            raise SystemExit(1)
+
+
+@main.command()
+@click.option("--policies", "-p", required=True, help="Path to policies directory or file")
+def validate(policies):
+    """Validate policy YAML files without evaluating."""
+    results = validate_policies(policies)
+    all_valid = True
+    for r in results:
+        status = "✅" if r["valid"] else "❌"
+        click.echo(f"  {status} {r['file']}")
+        if r["error"]:
+            click.echo(f"     {r['error']}")
+            all_valid = False
+
+    click.echo(f"\n{'All valid ✅' if all_valid else 'Some invalid ❌'}")
+    if not all_valid:
+        raise SystemExit(1)
+
+
+def _get_required_types(policies) -> list[str]:
+    types = set()
+    for p in policies:
+        types.update(p.spec.scope.resource_types)
+    return list(types)
+
+
+def _output_table(findings: list[Finding]):
+    if not findings:
+        click.echo("\n✅ No violations found!")
+        return
+
+    click.echo(f"\n{'─'*80}")
+    click.echo(f"{'Severity':<10} {'Policy':<25} {'Resource':<20} {'Message':<25}")
+    click.echo(f"{'─'*80}")
+    icons = {"critical": "🔴", "high": "🟠", "medium": "🟡", "low": "🔵", "info": "⚪"}
+    for f in findings:
+        icon = icons.get(f.severity.value, "⚪")
+        click.echo(f"{icon} {f.severity.value:<8} {f.policy_name:<25} {f.resource_id:<20} {f.message:<25}")
+
+    total_savings = sum(f.estimated_savings or 0 for f in findings)
+    click.echo(f"{'─'*80}")
+    click.echo(f"Summary: {len(findings)} findings | Potential savings: ${total_savings:.2f}/mo")
+
+
+def _output_markdown(findings: list[Finding]):
+    click.echo(f"# SOFE Evaluation Results\n")
+    click.echo(f"**Findings:** {len(findings)}\n")
+    click.echo("| Severity | Policy | Resource | Message |")
+    click.echo("|----------|--------|----------|---------|")
+    for f in findings:
+        click.echo(f"| {f.severity.value} | {f.policy_name} | {f.resource_id} | {f.message} |")
+
+
+if __name__ == "__main__":
+    main()

sofe/collectors/__init__.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+"""AWS resource collectors for SOFE — scan resources + fetch metrics."""
+
+import boto3
+from ..models import Resource
+
+
+def collect_all(profile: str = None, resource_types: list[str] = None, regions: list[str] = None) -> list[Resource]:
+    """Collect resources from AWS using the given profile."""
+    session = boto3.Session(profile_name=profile) if profile else boto3.Session()
+    account_id = session.client('sts').get_caller_identity()['Account']
+    target_regions = regions or [session.region_name or 'us-east-1']
+
+    resources: list[Resource] = []
+    types = resource_types or ['aws.ec2', 'aws.s3', 'aws.lambda', 'aws.rds']
+
+    for region in target_regions:
+        if 'aws.ec2' in types:
+            resources.extend(_collect_ec2(session, region, account_id))
+        if 'aws.s3' in types:
+            resources.extend(_collect_s3(session, region, account_id))
+        if 'aws.lambda' in types:
+            resources.extend(_collect_lambda(session, region, account_id))
+        if 'aws.rds' in types:
+            resources.extend(_collect_rds(session, region, account_id))
+
+    # Fetch metrics for collected resources
+    _enrich_metrics(session, resources, target_regions[0])
+
+    # Add tag-based metrics
+    for r in resources:
+        for key in ['owner', 'env', 'costCenter', 'Environment', 'Name']:
+            r.metrics[f'has_tag:{key}'] = 1.0 if key in r.tags else 0.0
+
+    return resources
+
+
+def _collect_ec2(session: boto3.Session, region: str, account_id: str) -> list[Resource]:
+    try:
+        ec2 = session.client('ec2', region_name=region)
+        resp = ec2.describe_instances(Filters=[{'Name': 'instance-state-name', 'Values': ['running']}])
+        resources = []
+        for res in resp.get('Reservations', []):
+            for inst in res.get('Instances', []):
+                tags = {t['Key']: t['Value'] for t in inst.get('Tags', [])}
+                resources.append(Resource(
+                    resource_id=inst['InstanceId'],
+                    resource_type='aws.ec2',
+                    region=region,
+                    account_id=account_id,
+                    tags=tags,
+                    properties={'instance_type': inst.get('InstanceType'), 'launch_time': str(inst.get('LaunchTime', ''))},
+                ))
+        return resources
+    except Exception as e:
+        print(f"  ⚠️  EC2 scan failed in {region}: {e}")
+        return []
+
+
+def _collect_s3(session: boto3.Session, region: str, account_id: str) -> list[Resource]:
+    try:
+        s3 = session.client('s3', region_name=region)
+        buckets = s3.list_buckets().get('Buckets', [])
+        return [Resource(
+            resource_id=b['Name'],
+            resource_type='aws.s3',
+            region='global',
+            account_id=account_id,
+            properties={'creation_date': str(b.get('CreationDate', ''))},
+        ) for b in buckets]
+    except Exception as e:
+        print(f"  ⚠️  S3 scan failed: {e}")
+        return []
+
+
+def _collect_lambda(session: boto3.Session, region: str, account_id: str) -> list[Resource]:
+    try:
+        client = session.client('lambda', region_name=region)
+        functions = client.list_functions().get('Functions', [])
+        return [Resource(
+            resource_id=fn['FunctionName'],
+            resource_type='aws.lambda',
+            region=region,
+            account_id=account_id,
+            properties={'runtime': fn.get('Runtime'), 'memory': fn.get('MemorySize')},
+        ) for fn in functions]
+    except Exception as e:
+        print(f"  ⚠️  Lambda scan failed in {region}: {e}")
+        return []
+
+
+def _collect_rds(session: boto3.Session, region: str, account_id: str) -> list[Resource]:
+    try:
+        client = session.client('rds', region_name=region)
+        instances = client.describe_db_instances().get('DBInstances', [])
+        return [Resource(
+            resource_id=db['DBInstanceIdentifier'],
+            resource_type='aws.rds',
+            region=region,
+            account_id=account_id,
+            properties={'engine': db.get('Engine'), 'class': db.get('DBInstanceClass')},
+        ) for db in instances]
+    except Exception as e:
+        print(f"  ⚠️  RDS scan failed in {region}: {e}")
+        return []
+
+
+def _enrich_metrics(session: boto3.Session, resources: list[Resource], region: str):
+    """Fetch CloudWatch metrics for resources (CPU, cost)."""
+    from datetime import datetime, timedelta
+    try:
+        cw = session.client('cloudwatch', region_name=region)
+        ce = session.client('ce', region_name='us-east-1')
+        now = datetime.utcnow()
+        start = now - timedelta(days=30)
+
+        for r in resources:
+            if r.resource_type == 'aws.ec2':
+                try:
+                    resp = cw.get_metric_statistics(
+                        Namespace='AWS/EC2', MetricName='CPUUtilization',
+                        Dimensions=[{'Name': 'InstanceId', 'Value': r.resource_id}],
+                        StartTime=start, EndTime=now, Period=86400 * 30, Statistics=['Average'],
+                    )
+                    if resp['Datapoints']:
+                        r.metrics['avg_cpu_utilization'] = round(resp['Datapoints'][0]['Average'], 2)
+                except:
+                    pass
+
+            # Running days
+            if 'launch_time' in r.properties and r.properties['launch_time']:
+                try:
+                    from dateutil.parser import parse
+                    launch = parse(r.properties['launch_time'])
+                    r.metrics['running_days'] = (now - launch.replace(tzinfo=None)).days
+                except:
+                    pass
+
+        # Monthly cost (simplified: total / resource count as estimate)
+        try:
+            s = (now.replace(day=1) - timedelta(days=1)).replace(day=1).strftime('%Y-%m-%d')
+            e = now.replace(day=1).strftime('%Y-%m-%d')
+            resp = ce.get_cost_and_usage(TimePeriod={'Start': s, 'End': e}, Granularity='MONTHLY', Metrics=['UnblendedCost'])
+            total = float(resp['ResultsByTime'][0]['Total']['UnblendedCost']['Amount'])
+            if resources:
+                per_resource = total / len(resources)
+                for r in resources:
+                    r.metrics['monthly_cost'] = round(per_resource, 2)
+        except:
+            pass
+    except:
+        pass

sofe/engine/__init__.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+"""Evaluation engine — applies policies against resources."""
+
+import uuid
+from datetime import datetime
+from ..models import Policy, Resource, Finding, Operator, Severity
+
+
+def evaluate(policies: list[Policy], resources: list[Resource]) -> list[Finding]:
+    """Evaluate all policies against all resources. Returns findings (violations)."""
+    findings: list[Finding] = []
+
+    for policy in policies:
+        matching = _filter_by_scope(resources, policy)
+        for resource in matching:
+            violation = _check_rule(resource, policy)
+            if violation:
+                findings.append(violation)
+
+    return findings
+
+
+def _filter_by_scope(resources: list[Resource], policy: Policy) -> list[Resource]:
+    """Filter resources by policy scope."""
+    scope = policy.spec.scope
+    result = []
+
+    for r in resources:
+        # Check resource type
+        if not _matches_list(r.resource_type, scope.resource_types):
+            continue
+        # Check region
+        if not _matches_list(r.region, scope.regions):
+            continue
+        # Check account
+        if not _matches_list(r.account_id, scope.accounts):
+            continue
+        # Check environment tag
+        if scope.environments != ["*"]:
+            env = r.tags.get("Environment", r.tags.get("env", ""))
+            if not _matches_list(env, scope.environments):
+                continue
+        # Check exclude
+        if scope.exclude:
+            exclude_tags = scope.exclude.get("tags", {})
+            if any(r.tags.get(k) == v for k, v in exclude_tags.items()):
+                continue
+            if r.resource_id in scope.exclude.get("resource_ids", []):
+                continue
+
+        result.append(r)
+
+    return result
+
+
+def _check_rule(resource: Resource, policy: Policy) -> Finding | None:
+    """Check if a resource violates the policy rule."""
+    rule = policy.spec.rule
+    metric_value = resource.metrics.get(rule.metric)
+
+    if metric_value is None:
+        return None  # No data for this metric — skip
+
+    # Apply operator
+    violated = _apply_operator(metric_value, rule.operator, rule.threshold)
+    if not violated:
+        return None
+
+    # Check additional conditions (AND logic)
+    for cond in rule.additional_conditions:
+        cond_value = resource.metrics.get(cond.field) or resource.properties.get(cond.field)
+        if cond_value is None:
+            return None  # Missing data — skip
+        if not _apply_operator(float(cond_value), cond.operator, float(cond.value)):
+            return None  # Condition not met
+
+    # Build finding
+    recommendation = None
+    estimated_savings = None
+    for action in policy.spec.actions:
+        if action.type == "recommend" and action.suggestion:
+            recommendation = action.suggestion
+        if action.estimated_savings == "calc":
+            estimated_savings = resource.metrics.get("monthly_cost")
+
+    return Finding(
+        id=str(uuid.uuid4())[:8],
+        policy_name=policy.metadata.name,
+        severity=policy.spec.severity,
+        resource_id=resource.resource_id,
+        resource_type=resource.resource_type,
+        region=resource.region,
+        account_id=resource.account_id,
+        message=f"{rule.metric} = {metric_value} (threshold: {rule.operator.value}{rule.threshold})",
+        metric_name=rule.metric,
+        metric_value=metric_value,
+        threshold=rule.threshold,
+        estimated_savings=estimated_savings,
+        recommendation=recommendation,
+        remediation_eligible=policy.spec.remediation.auto_eligible if policy.spec.remediation else False,
+        timestamp=datetime.utcnow(),
+    )
+
+
+def _apply_operator(value: float, operator: Operator, threshold: float) -> bool:
+    if operator == Operator.lt: return value < threshold
+    elif operator == Operator.gt: return value > threshold
+    elif operator == Operator.lte: return value <= threshold
+    elif operator == Operator.gte: return value >= threshold
+    elif operator == Operator.eq: return value == threshold
+    elif operator == Operator.ne: return value != threshold
+    return False
+
+
+def _matches_list(value: str, allowed: list[str]) -> bool:
+    if "*" in allowed:
+        return True
+    return value in allowed

sofe/loader/__init__.py

@@ -0,0 +1,54 @@
+"""Load and validate YAML policy files."""
+
+import os
+import yaml
+from pathlib import Path
+from ..models import Policy
+
+
+def load_policies(path: str) -> list[Policy]:
+    """Load all .yaml policy files from a directory or single file."""
+    policies = []
+    p = Path(path)
+
+    if p.is_file():
+        policies.append(_load_single(p))
+    elif p.is_dir():
+        for f in sorted(p.glob("*.yaml")):
+            policies.append(_load_single(f))
+        for f in sorted(p.glob("*.yml")):
+            policies.append(_load_single(f))
+    else:
+        raise FileNotFoundError(f"Policy path not found: {path}")
+
+    return policies
+
+
+def _load_single(path: Path) -> Policy:
+    """Load and validate a single policy file."""
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    if not data:
+        raise ValueError(f"Empty policy file: {path}")
+
+    try:
+        return Policy(**data)
+    except Exception as e:
+        raise ValueError(f"Invalid policy {path.name}: {e}")
+
+
+def validate_policies(path: str) -> list[dict]:
+    """Validate policies without evaluating. Returns list of {file, valid, error}."""
+    results = []
+    p = Path(path)
+    files = [p] if p.is_file() else list(p.glob("*.yaml")) + list(p.glob("*.yml"))
+
+    for f in files:
+        try:
+            _load_single(f)
+            results.append({"file": f.name, "valid": True, "error": None})
+        except Exception as e:
+            results.append({"file": f.name, "valid": False, "error": str(e)})
+
+    return results

sofe/models/__init__.py

@@ -0,0 +1,109 @@
+"""Core models for SOFE — Policy, Resource, Finding."""
+
+from pydantic import BaseModel
+from typing import Optional, Union
+from enum import Enum
+from datetime import datetime
+
+
+class Severity(str, Enum):
+    critical = "critical"
+    high = "high"
+    medium = "medium"
+    low = "low"
+    info = "info"
+
+
+class Operator(str, Enum):
+    lt = "<"
+    gt = ">"
+    lte = "<="
+    gte = ">="
+    eq = "=="
+    ne = "!="
+
+
+class AdditionalCondition(BaseModel):
+    field: str
+    operator: Operator
+    value: Union[float, str]
+
+
+class Scope(BaseModel):
+    environments: list[str] = ["*"]
+    resource_types: list[str]
+    regions: list[str] = ["*"]
+    accounts: list[str] = ["*"]
+    exclude: Optional[dict] = None
+
+
+class Rule(BaseModel):
+    metric: str
+    period: str = "30d"
+    operator: Operator
+    threshold: float
+    additional_conditions: list[AdditionalCondition] = []
+
+
+class Action(BaseModel):
+    type: str  # finding, notify, recommend, block
+    channel: Optional[str] = None
+    suggestion: Optional[str] = None
+    estimated_savings: Optional[str] = None
+
+
+class Remediation(BaseModel):
+    auto_eligible: bool = False
+    action: Optional[str] = None
+    requires_approval_if: Optional[dict] = None
+
+
+class PolicyMetadata(BaseModel):
+    name: str
+    description: str
+    author: Optional[str] = None
+    created: Optional[str] = None
+    tags: list[str] = []
+
+
+class PolicySpec(BaseModel):
+    scope: Scope
+    rule: Rule
+    severity: Severity
+    actions: list[Action] = []
+    remediation: Optional[Remediation] = None
+
+
+class Policy(BaseModel):
+    apiVersion: str = "sofe/v1"
+    kind: str = "Policy"
+    metadata: PolicyMetadata
+    spec: PolicySpec
+
+
+class Resource(BaseModel):
+    resource_id: str
+    resource_type: str
+    region: str
+    account_id: str
+    tags: dict[str, str] = {}
+    properties: dict = {}
+    metrics: dict[str, float] = {}
+
+
+class Finding(BaseModel):
+    id: str
+    policy_name: str
+    severity: Severity
+    resource_id: str
+    resource_type: str
+    region: str
+    account_id: str
+    message: str
+    metric_name: str
+    metric_value: float
+    threshold: float
+    estimated_savings: Optional[float] = None
+    recommendation: Optional[str] = None
+    remediation_eligible: bool = False
+    timestamp: datetime

sofe-0.1.0.dist-info/METADATA

@@ -0,0 +1,374 @@
+Metadata-Version: 2.4
+Name: sofe
+Version: 0.1.0
+Summary: Stairway Open FinOps Engine — FinOps Policies as Code for AWS
+Author-email: Carlos Cortez <carlos@cortez.cloud>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/breakingthecloud/sofe
+Project-URL: Repository, https://github.com/breakingthecloud/sofe
+Project-URL: Issues, https://github.com/breakingthecloud/sofe/issues
+Keywords: finops,aws,cloud-governance,policy-as-code,cost-optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: boto3>=1.34
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+
+# 🏗️ SOFE — Stairway Open FinOps Engine
+
+**FinOps Policies as Code for AWS.**
+
+SOFE evaluates declarative YAML policies against live AWS infrastructure and produces actionable findings — idle resources, missing tags, governance violations, and cost savings opportunities.
+
+```bash
+sofe evaluate --policies ./policies/ --profile production
+```
+
+```
+────────────────────────────────────────────────────────────────────────────────
+Severity   Policy                    Resource             Message
+────────────────────────────────────────────────────────────────────────────────
+🟠 high    no-idle-ec2               i-0abc123def         avg_cpu = 2.1% (threshold: <5%)
+🟡 medium  require-cost-tags         i-0def456ghi         missing: costCenter, owner
+🟡 medium  no-unattached-ebs         vol-789abc           180 days old, 500GB
+────────────────────────────────────────────────────────────────────────────────
+Summary: 3 findings | Potential savings: $365.00/mo
+```
+
+---
+
+## Why SOFE?
+
+### The Problem
+
+Teams today manage cloud costs **reactively** — they see the bill spike, panic, then scramble to find what changed. Existing tools either:
+
+- **Alert on total spend** (AWS Budgets) — no root cause, no policy enforcement
+- **Scan for security** (Prowler, ScoutSuite) — not cost-focused
+- **Estimate costs** (Infracost) — pre-deploy only, no runtime enforcement
+- **Lock you in** (Sentinel/HCP) — vendor-specific, not portable
+
+**No tool does:** declarative cost+governance policies that evaluate against **live** infrastructure and produce findings with dollar-amount savings.
+
+### The Solution
+
+SOFE fills this gap:
+
+```yaml
+# policies/no-idle-production.yaml
+apiVersion: sofe/v1
+kind: Policy
+metadata:
+  name: no-idle-production
+  description: "Flag idle EC2 in production (< 5% CPU for 30 days)"
+spec:
+  scope:
+    environments: [production]
+    resource_types: [aws.ec2]
+  rule:
+    metric: avg_cpu_utilization
+    period: 30d
+    operator: "<"
+    threshold: 5
+  severity: high
+  actions:
+    - type: recommend
+      suggestion: "Rightsize or terminate"
+      estimated_savings: calc
+```
+
+Write a policy once. Run it daily. Get findings with savings.
+
+---
+
+## Who Should Use SOFE?
+
+| Role | Why SOFE matters |
+|------|-----------------|
+| **Cloud/DevOps Engineers** | Automate governance checks in CI/CD. `sofe evaluate --fail-on high` blocks deploys that violate cost policies. |
+| **FinOps Practitioners** | Define cost optimization rules as code. Track compliance across accounts. Quantify waste. |
+| **Platform Engineers** | Enforce tagging standards, idle resource cleanup, and architecture best practices at scale. |
+| **CTOs / Engineering Managers** | Visibility into cloud waste without manual audits. "We save $X/month because of these policies." |
+| **AWS Partners / Consultants** | Deliver FinOps assessments faster with repeatable, auditable policy evaluations. |
+
+---
+
+## Why SOFE is Key for FinOps + Governance
+
+### 1. FinOps: Cost Optimization as Code
+
+Traditional FinOps is manual: someone opens Cost Explorer, finds waste, creates a ticket. SOFE automates this:
+
+```
+Write policy → sofe evaluate → findings with $ savings → action
+```
+
+Every policy produces **quantified savings**: "$340/mo if you terminate this idle instance."
+
+### 2. Cloud Governance: Policies that Actually Enforce
+
+Tags, encryption, public access, budget limits — every team has rules but no enforcement. SOFE makes them executable:
+
+```yaml
+- require-cost-tags       → "All resources must have owner + costCenter"
+- s3-encryption-required  → "All S3 buckets must have encryption enabled"
+- no-public-without-waf   → "No public-facing resource without WAF"
+```
+
+Not just documentation. Actual enforcement in CI/CD.
+
+### 3. DevOps: Shift-Left Cost Awareness
+
+Add `sofe evaluate --fail-on high` to your GitHub Action or CI pipeline. Developers see cost violations **before** merge, not after the bill arrives.
+
+### 4. BYaML Integration: Architecture-Aware FinOps
+
+SOFE uses [BYaML](https://byaml.org) component types (`aws.ec2`, `aws.s3`, etc.) — the same type system used for architecture governance. This means:
+
+- Policies reference the same types as your architecture definitions
+- Findings map directly to BYaML components
+- Cost data correlates with architecture versions
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+pip install sofe
+```
+
+### Write Your First Policy
+
+```yaml
+# policies/require-tags.yaml
+apiVersion: sofe/v1
+kind: Policy
+metadata:
+  name: require-cost-tags
+  description: "All resources must have owner and costCenter tags"
+spec:
+  scope:
+    resource_types: [aws.ec2, aws.rds, aws.s3]
+  rule:
+    metric: has_tag:owner
+    operator: "=="
+    threshold: 0
+  severity: medium
+  actions:
+    - type: finding
+```
+
+### Validate
+
+```bash
+sofe validate --policies ./policies/
+```
+
+### Evaluate
+
+```bash
+# Against real AWS (uses your AWS profile)
+sofe evaluate --policies ./policies/ --profile production
+
+# Output as JSON (for automation)
+sofe evaluate --policies ./policies/ --format json > findings.json
+
+# CI/CD mode (exit code 1 if high/critical found)
+sofe evaluate --policies ./policies/ --fail-on high
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌──────────────────────┐
+│ Policy Loader   │     │  Collectors  │     │  Evaluation Engine   │
+│                 │     │              │     │                      │
+│ Reads YAML      │────▶│ AWS APIs:    │────▶│ For each policy:     │
+│ Validates       │     │ EC2, RDS     │     │ match scope →        │
+│ schema          │     │ S3, Lambda   │     │ evaluate condition → │
+│                 │     │ CloudWatch   │     │ if violated →        │
+└─────────────────┘     └──────────────┘     │   generate finding   │
+                                             └──────────┬───────────┘
+                                                        │
+                                              ┌─────────▼─────────┐
+                                              │  Output            │
+                                              │  • Table (CLI)     │
+                                              │  • JSON (CI/CD)    │
+                                              │  • Markdown (PRs)  │
+                                              └────────────────────┘
+```
+
+---
+
+## Supported Metrics
+
+| Metric | Source | Resources |
+|--------|--------|-----------|
+| `avg_cpu_utilization` | CloudWatch (30d avg) | EC2, RDS |
+| `monthly_cost` | Cost Explorer | All |
+| `running_days` | LaunchTime | EC2, RDS |
+| `has_tag:{key}` | Tags API | All |
+| `storage_used_gb` | CloudWatch | S3, EBS |
+| `connections` | CloudWatch | RDS |
+| `invocations` | CloudWatch | Lambda |
+
+---
+
+## Pre-Built Policies
+
+| Policy | Type | Severity |
+|--------|------|----------|
+| `no-idle-ec2` | Cost Optimization | high |
+| `no-idle-rds` | Cost Optimization | high |
+| `require-cost-tags` | Governance | medium |
+| `no-oversized-staging` | Cost Optimization | high |
+| `s3-lifecycle-required` | Storage | medium |
+| `s3-encryption-required` | Security/Cost | high |
+| `no-unattached-ebs` | Storage | medium |
+| `no-old-snapshots` | Storage | low |
+| `budget-exceeded` | Budget | critical |
+| `no-public-without-waf` | Security/Cost | high |
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: FinOps Policy Check
+  run: |
+    pip install sofe
+    sofe evaluate --policies ./policies/ --fail-on high --format json > findings.json
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|:----:|---------|
+| 0 | No violations (or below `--fail-on` threshold) |
+| 1 | Violations found at or above `--fail-on` severity |
+
+---
+
+## Comparison
+
+| Tool | Cost Policies | Live Eval | Savings Calc | CI/CD | Open Source |
+|------|:---:|:---:|:---:|:---:|:---:|
+| **SOFE** | ✅ | ✅ | ✅ | ✅ | ✅ |
+| AWS Budgets | ❌ (alerts only) | ❌ | ❌ | ❌ | ❌ |
+| Infracost | 🟡 (pre-deploy) | ❌ | ✅ | ✅ | ✅ |
+| OPA/Rego | ✅ (security) | ❌ | ❌ | ✅ | ✅ |
+| Sentinel | ✅ | ❌ | ❌ | ✅ | ❌ (HCP only) |
+| Prowler | ❌ (security only) | ✅ | ❌ | ✅ | ✅ |
+
+---
+
+## Ecosystem: Competitors & Complementary Tools
+
+### Competitors (overlap with SOFE)
+
+| Tool | Type | What it does | How SOFE differs |
+|------|------|-------------|-----------------|
+| **OPA / Rego** | OSS | General policy engine (security-focused) | SOFE is cost/FinOps-focused with savings calculations. OPA doesn't calculate $. |
+| **HashiCorp Sentinel** | Proprietary | Policy-as-code for Terraform | Locked to HCP/Terraform Cloud. SOFE is runtime (evaluates live infra, not just plans). |
+| **Infracost** | OSS | Cost estimation pre-deploy | Pre-deploy only. SOFE evaluates running infra + historical drift. Complementary. |
+| **AWS Config Rules** | AWS Native | Compliance rules on AWS resources | Limited to AWS, no cost focus, no CI/CD output, no portability. |
+| **Prowler** | OSS | Security & compliance scanning | Security-focused (CIS, PCI-DSS). Doesn't calculate cost savings or enforce FinOps. |
+| **Checkov** | OSS | IaC static analysis (Terraform, CF) | Pre-deploy only (scans .tf files). SOFE scans live resources. |
+| **Cloud Custodian** | OSS | Policy engine for cloud resources | Closest competitor. Actions (stop/terminate) built-in. SOFE is lighter, YAML-first, FinOps-focused. |
+| **Kubecost** | OSS/Paid | Kubernetes cost monitoring | K8s only. SOFE covers all AWS services. |
+| **Vantage** | SaaS | FinOps dashboard + alerts | Dashboard, not policy engine. No CI/CD. No custom rules. |
+| **CloudZero** | SaaS | Cost intelligence platform | Enterprise SaaS ($$$). No self-hosted. No policies-as-code. |
+| **Spot.io / NetApp** | SaaS | Cloud optimization + autoscaling | Optimization execution, not policy definition. Complementary. |
+| **Apptio Cloudability** | SaaS | Enterprise FinOps platform | Enterprise-only, expensive. No CI/CD integration. No code-first approach. |
+| **nOps** | SaaS | AWS cost optimization + scheduling | Automation focus. No declarative policies. |
+| **CAST AI** | SaaS | K8s cost optimization | K8s-only autoscaling. Not a policy engine. |
+
+### Complementary Tools (use alongside SOFE)
+
+| Tool | How it complements SOFE |
+|------|------------------------|
+| **Infracost** | Pre-deploy cost estimation → SOFE catches what slipped through post-deploy |
+| **Terraform / OpenTofu** | Defines infra → SOFE evaluates if running infra matches cost policies |
+| **AWS Cost Explorer** | Data source → SOFE collectors fetch from it |
+| **CloudWatch** | Metrics source → SOFE uses CPU, connections, invocations |
+| **Steampipe** | SQL-based cloud inventory → could be alternate data source for SOFE |
+| **Prometheus + Grafana** | Monitoring → SOFE could consume Prometheus metrics (future) |
+| **BYaML** | Architecture definitions → SOFE policies use same type system |
+| **byaml-finops-mcp** | MCP tools for AI assistants → SOFE findings feed into AI reasoning |
+| **FinOptix** | AI model for FinOps → explains SOFE findings in natural language |
+| **GitHub Actions / GitLab CI** | CI/CD → SOFE runs as pipeline step with `--fail-on` |
+| **Slack / PagerDuty** | Notifications → SOFE can webhook findings (future) |
+| **Neo4j** | Graph DB → SOFE findings + BYaML relationships = cost propagation graph (future) |
+
+### The SOFE Position
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Cloud Cost Lifecycle                           │
+├─────────────┬──────────────┬──────────────────┬─────────────────┤
+│  PLAN       │  DEPLOY      │  RUN             │  OPTIMIZE       │
+│             │              │                  │                 │
+│ Infracost   │ Sentinel     │ ★ SOFE ★         │ Spot.io         │
+│ Checkov     │ OPA/Rego     │ Cloud Custodian  │ CAST AI         │
+│             │ Checkov      │ AWS Config       │ nOps            │
+│             │              │ Prowler          │ Kubecost        │
+├─────────────┴──────────────┴──────────────────┴─────────────────┤
+│  VISIBILITY: Vantage, CloudZero, Apptio, AWS Cost Explorer       │
+└─────────────────────────────────────────────────────────────────┘
+
+SOFE lives in the RUN phase: evaluate LIVE infrastructure against
+declarative FinOps policies. Produce findings with dollar savings.
+```
+
+### Why SOFE vs Cloud Custodian?
+
+Cloud Custodian is the closest open source alternative. Key differences:
+
+| | SOFE | Cloud Custodian |
+|--|------|----------------|
+| **Focus** | FinOps + cost governance | Security + compliance + ops |
+| **Policy format** | Clean YAML (Pydantic-validated) | Complex YAML with filters/actions DSL |
+| **Savings calculation** | Built-in ($ per finding) | Not included |
+| **BYaML integration** | Native (same type system) | None |
+| **AI reasoning** | FinOptix integration (future) | None |
+| **CI/CD** | `--fail-on` exit code | Requires wrapper |
+| **Scope** | AWS first, multi-cloud future | AWS + Azure + GCP |
+| **Maturity** | New (2026) | Mature (2016+, Capital One) |
+
+SOFE is opinionated toward **FinOps** — every finding has a dollar amount. Cloud Custodian is a general-purpose policy engine that happens to work on cloud resources.
+
+---
+
+## License
+
+Apache 2.0 — free to use, modify, and distribute.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Add a policy to `policies/` or a collector to `sofe/collectors/`
+3. Submit a PR
+
+---
+
+## Built by
+
+[Carlos Cortez](https://cortez.cloud) — AWS Community Hero, CTO @ BWIT Solutions.
+Part of the [BYaML](https://byaml.org) ecosystem for cloud architecture governance.

sofe-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sofe/__init__.py,sha256=lBrL-ij6gZimgN3fPaVJPU2fZNzurfBtMLzYgmMeGbw,92
+sofe/cli.py,sha256=qjeY504zxfS8S8Kudu1TCBZxua9AX3ag_q8BqZHij4Q,4630
+sofe/collectors/__init__.py,sha256=s65VhKot726K7IcWF_n6CkNQ-jMNRHAWINgMtw0F7EU,6355
+sofe/engine/__init__.py,sha256=4l7RrJeIgCHdacNrVtnW3xbqkOi_qGseiUwUXTWQXWw,4258
+sofe/loader/__init__.py,sha256=4k6ygsZ-0HFzcfZ2TJsTdQjpdNhOxM9s6ZgHp2Rgjgw,1503
+sofe/models/__init__.py,sha256=PvfA6BFMyl9bviw8TumZkii4QqtR6ysCMX5ttUFUJM8,2277
+sofe-0.1.0.dist-info/METADATA,sha256=XUWxXLWt67mphgbQp2VooTAN0DCBLvzr8iYFGSa2kZk,16061
+sofe-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sofe-0.1.0.dist-info/entry_points.txt,sha256=QOQi7OO-5oQUr2mJubvIVKmWusSj2D2SmPkk6iYt35Y,39
+sofe-0.1.0.dist-info/top_level.txt,sha256=GCmO2On-zrWOiECzxOWg-dfI2hbObe0kddQjvuNET94,5
+sofe-0.1.0.dist-info/RECORD,,

sofe-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sofe-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sofe = sofe.cli:main

sofe-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sofe