sofe-server 0.1.0__py3-none-any.whl

sofe_server/__init__.py

@@ -0,0 +1,2 @@
+"""SOFE Server — FinOps Policies as Code API."""
+__version__ = "0.1.0"

sofe_server/app.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+from fastapi import FastAPI, Header, HTTPException
+from pydantic import BaseModel
+
+from sofe.loader import load_policies, validate_policies
+from sofe.collectors import collect_all
+from sofe.engine import evaluate, evaluate_architecture
+
+app = FastAPI(
+    title="SOFE API",
+    version="0.1.0",
+    description="Stairway Open FinOps Engine — FinOps Policies as Code",
+)
+
+# --- Models ---
+
+class EvaluateRequest(BaseModel):
+    policies_dir: str = "./policies"
+    profile: Optional[str] = None
+    resource_types: Optional[list[str]] = None
+    regions: Optional[list[str]] = None
+    fail_on: Optional[str] = None
+
+class ValidateRequest(BaseModel):
+    policy_yaml: str
+
+# --- Auth (optional) ---
+
+def check_api_key(x_api_key: Optional[str] = Header(None)):
+    # Local mode: no key required. Hosted mode: validate key (future).
+    pass
+
+# --- Routes ---
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "version": "0.1.0"}
+
+@app.post("/evaluate")
+async def evaluate_endpoint(req: EvaluateRequest):
+    policies = load_policies(req.policies_dir)
+    if not policies:
+        raise HTTPException(status_code=422, detail="No policies found")
+
+    resources = collect_all(
+        profile=req.profile,
+        resource_types=req.resource_types,
+        regions=req.regions,
+    )
+
+    # Architecture-aware evaluation (includes cross-resource analysis)
+    arch_result = evaluate_architecture(policies, resources)
+    findings = arch_result["findings"]
+    insights = arch_result["insights"]
+
+    severity_order = ["critical", "high", "medium", "low", "info"]
+    failed = False
+    if req.fail_on:
+        threshold_idx = severity_order.index(req.fail_on)
+        failed = any(
+            severity_order.index(f.severity.value) <= threshold_idx
+            for f in findings
+        )
+
+    total_savings = sum(f.estimated_savings or 0 for f in findings)
+
+    # Count resources by type for topology visualization + include IDs for BYaML generation
+    resources_by_type: dict[str, int] = {}
+    resources_detail: dict[str, list[dict]] = {}
+    for r in resources:
+        resources_by_type[r.resource_type] = resources_by_type.get(r.resource_type, 0) + 1
+        if r.resource_type not in resources_detail:
+            resources_detail[r.resource_type] = []
+        resources_detail[r.resource_type].append({
+            "resource_id": r.resource_id,
+            "region": r.region,
+        })
+
+    # Get remediation commands for each finding
+    from sofe.remediation.commands import get_remediation_commands
+
+    return {
+        "evaluation_id": str(uuid.uuid4()),
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "policies_evaluated": len(policies),
+        "resources_scanned": len(resources),
+        "findings_count": len(findings),
+        "total_estimated_savings": total_savings,
+        "failed": failed,
+        "resources_by_type": resources_by_type,
+        "resources_detail": resources_detail,
+        "findings": [
+            {
+                "id": str(uuid.uuid4()),
+                "policy_name": f.policy_name,
+                "severity": f.severity.value,
+                "resource_id": f.resource_id,
+                "resource_type": f.resource_type,
+                "region": f.region,
+                "account_id": f.account_id,
+                "message": f.message,
+                "estimated_savings": f.estimated_savings,
+                "recommendation": f.recommendation,
+                "remediation_commands": get_remediation_commands(
+                    f.policy_name, f.resource_id, f.resource_type, f.region, f.account_id or ""
+                ),
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+            }
+            for f in findings
+        ],
+        "insights": {
+            "relationships_count": insights.get("relationships_count", 0),
+            "single_points_of_failure": insights.get("single_points_of_failure", []),
+            "blast_radius": insights.get("blast_radius", {}),
+            "team_costs": insights.get("team_costs", {}),
+        },
+    }
+
+@app.post("/validate")
+async def validate_endpoint(req: ValidateRequest):
+    import tempfile, os, yaml
+    # Write YAML to temp file, validate
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False)
+    tmp.write(req.policy_yaml)
+    tmp.close()
+    try:
+        results = validate_policies(os.path.dirname(tmp.name), filename=os.path.basename(tmp.name))
+        r = results[0] if results else {"valid": False, "error": "No policy parsed"}
+        return {"valid": r.get("valid", False), "errors": [r.get("error", "")] if not r.get("valid") else []}
+    finally:
+        os.unlink(tmp.name)
+
+@app.get("/policies")
+async def list_policies(policies_dir: str = "./policies"):
+    policies = load_policies(policies_dir)
+    return [
+        {
+            "name": p.metadata.name,
+            "description": p.metadata.description,
+            "severity": p.spec.severity.value,
+            "resource_types": p.spec.scope.resource_types,
+            "metric": p.spec.rule.metric,
+        }
+        for p in policies
+    ]
+
+@app.get("/metrics")
+async def list_metrics():
+    return [
+        {"name": "avg_cpu_utilization", "source": "CloudWatch", "resource_types": ["aws.ec2", "aws.rds"], "description": "Average CPU % over period"},
+        {"name": "monthly_cost", "source": "Cost Explorer", "resource_types": ["*"], "description": "Monthly cost in USD"},
+        {"name": "running_days", "source": "LaunchTime", "resource_types": ["aws.ec2", "aws.rds"], "description": "Days since launch"},
+        {"name": "has_tag:{key}", "source": "Tags API", "resource_types": ["*"], "description": "1.0 if tag exists, 0.0 if missing"},
+        {"name": "invocations", "source": "CloudWatch", "resource_types": ["aws.lambda"], "description": "Total invocations over period"},
+        {"name": "connections", "source": "CloudWatch", "resource_types": ["aws.rds"], "description": "Active connections"},
+        {"name": "attached", "source": "EC2 API", "resource_types": ["aws.ebs"], "description": "1.0 if attached, 0.0 if not"},
+    ]
+
+
+@app.get("/collectors")
+async def list_collectors():
+    from sofe.collectors.aws import COLLECTORS
+    return [
+        {
+            "name": collector_cls.__name__.replace("Collector", ""),
+            "resource_type": resource_type,
+            "metrics": _get_collector_metrics(resource_type),
+        }
+        for resource_type, collector_cls in COLLECTORS.items()
+    ]
+
+def _get_collector_metrics(resource_type: str) -> list[str]:
+    """Return known metrics for a resource type."""
+    metrics_map = {
+        "aws.ec2": ["avg_cpu_utilization", "monthly_cost", "running_days", "has_tag:*", "purchase_option_spot", "instance_generation_old", "ebs_optimized", "public_ip_attached"],
+        "aws.s3": ["monthly_cost", "encryption_enabled", "has_lifecycle_rules", "has_tag:*", "versioning_enabled", "public_access_blocked", "logging_enabled"],
+        "aws.lambda": ["monthly_cost", "has_tag:*", "memory_size_mb", "timeout_seconds", "runtime_deprecated", "code_size_mb"],
+        "aws.rds": ["avg_connections", "monthly_cost", "has_tag:*", "multi_az", "storage_encrypted", "backup_retention_days", "publicly_accessible"],
+        "aws.ebs": ["attached", "monthly_cost", "has_tag:*", "size_gb", "volume_type_gp2", "encrypted"],
+        "aws.ecs": ["avg_cpu_utilization", "has_tag:*", "running_count", "desired_count", "launch_type_fargate"],
+        "aws.eks": ["monthly_cost", "has_tag:*", "endpoint_public_access", "logging_enabled", "version_outdated"],
+        "aws.elasticache": ["monthly_cost", "at_rest_encryption", "transit_encryption", "num_nodes"],
+        "aws.redshift": ["monthly_cost", "encrypted", "publicly_accessible", "num_nodes"],
+        "aws.dynamodb": ["monthly_cost", "has_tag:*", "billing_mode_provisioned", "item_count", "table_size_mb"],
+        "aws.cloudfront": ["compression_enabled", "monthly_cost", "https_only", "waf_enabled", "price_class_all"],
+        "aws.apigateway": ["throttle_configured", "monthly_cost", "logging_enabled", "endpoint_type_edge"],
+        "aws.natgateway": ["monthly_cost", "connectivity_public"],
+        "aws.elb": ["has_targets", "monthly_cost", "waf_enabled", "internet_facing"],
+        "aws.route53": ["record_count", "private_zone"],
+        "aws.secretsmanager": ["rotation_enabled", "days_since_last_rotation", "days_since_last_access"],
+        "aws.sagemaker": ["monthly_cost", "instance_count", "endpoint_active"],
+    }
+    return metrics_map.get(resource_type, ["monthly_cost"])
+
+
+@app.post("/connect/test")
+async def test_connection(body: dict):
+    """Test STS AssumeRole — verifies the user's IAM role works."""
+    import boto3
+    role_arn = body.get("role_arn")
+    external_id = body.get("external_id")
+    
+    if not role_arn or not external_id:
+        raise HTTPException(status_code=400, detail="role_arn and external_id required")
+    
+    try:
+        sts = boto3.client("sts")
+        resp = sts.assume_role(
+            RoleArn=role_arn,
+            RoleSessionName="sofe-connect-test",
+            ExternalId=external_id,
+            DurationSeconds=900,
+        )
+        account_id = resp["AssumedRoleUser"]["Arn"].split(":")[4]
+        return {"success": True, "account_id": account_id}
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=f"AssumeRole failed: {str(e)}")

sofe_server/main.py

@@ -0,0 +1,7 @@
+import uvicorn
+
+def run():
+    uvicorn.run("sofe_server.app:app", host="0.0.0.0", port=8080, reload=True)
+
+if __name__ == "__main__":
+    run()

sofe_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: sofe-server
+Version: 0.1.0
+Summary: SOFE API Server — FinOps Policies as Code REST API
+Author-email: Carlos Cortez <carlos@cortez.cloud>
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sofe>=0.2.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+# 🟢 SOFE Server — FinOps Policy Engine API
+
+REST API server for the [SOFE](https://sofe.dev) (Stairway Open FinOps Engine). Wraps the SOFE Python engine in a FastAPI application, enabling HTTP-based evaluations.
+
+## Quick Start
+
+```bash
+pip install sofe sofe-server
+sofe-server
+# → http://localhost:8080
+```
+
+Or use the Go CLI:
+```bash
+sofe serve    # starts sofe-server in background
+sofe evaluate # calls localhost:8080/evaluate
+```
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Health check |
+| POST | `/evaluate` | Evaluate AWS account against policies |
+| POST | `/validate` | Validate a BYaML YAML file |
+| GET | `/policies` | List all loaded policies |
+| GET | `/collectors` | List available collectors |
+| GET | `/metrics` | List metrics per collector |
+| POST | `/connect/test` | Test STS AssumeRole connection |
+
+## Usage
+
+### Evaluate your AWS account
+
+```bash
+curl -X POST http://localhost:8080/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"aws_profile": "default"}'
+```
+
+### With cross-account role
+
+```bash
+curl -X POST http://localhost:8080/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "role_arn": "arn:aws:iam::123456789012:role/SOFEReadOnlyRole",
+    "external_id": "sofe-abc123"
+  }'
+```
+
+### List policies
+
+```bash
+curl http://localhost:8080/policies
+```
+
+## Docker
+
+```bash
+docker run -p 8080:8080 -v ~/.aws:/root/.aws:ro \
+  ghcr.io/breakingthecloud/sofe-community:latest
+```
+
+## Architecture
+
+```
+sofe-server (this repo)
+    │
+    │ imports
+    ▼
+sofe/ (engine — pip install sofe)
+    │
+    │ boto3
+    ▼
+Your AWS Account (read-only)
+```
+
+sofe-server is a **thin wrapper** — all logic lives in the [sofe engine](https://github.com/breakingthecloud/sofe).
+
+## Requirements
+
+- Python 3.11+
+- `sofe` >= 0.2.0 (engine)
+- AWS credentials (profile or role)
+
+## Development
+
+```bash
+git clone https://github.com/breakingthecloud/sofe-server.git
+cd sofe-server
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]" -e ../sofe/
+uvicorn sofe_server.app:app --reload --port 8080
+```
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [sofe](https://github.com/breakingthecloud/sofe) | Python engine (collectors + policies) |
+| [sofe-cli](https://github.com/breakingthecloud/sofe-cli) | Go CLI (19 commands, TUI) |
+| [sofe-action](https://github.com/breakingthecloud/sofe-action) | GitHub Action for CI/CD |
+| [platform.sofe.dev](https://platform.sofe.dev) | SaaS dashboard (free tier) |
+| [sofe.dev/docs](https://sofe.dev/docs) | Documentation (26 pages) |
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE)

sofe_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sofe_server/__init__.py,sha256=5Wj4AQg31P9uW5dH0Too6X2BdhwFcdrhKVURqp3_UUA,73
+sofe_server/app.py,sha256=fAIFCWqyWTpp6RYKu18t_2a6MKoUtjk2HzKueK1F4zw,9527
+sofe_server/main.py,sha256=VMEs0_9V4LTnxUGtb0XvalgHgdi6egMzPL6SBLHcIFI,144
+sofe_server-0.1.0.dist-info/licenses/LICENSE,sha256=W42gOhs90g5sWk56eE-WZF4eGgKyPmKjBE2184yPKyA,4055
+sofe_server-0.1.0.dist-info/METADATA,sha256=iuZrrhLWYDteUrgPTLBMeefMrYXQnr2Cbsfim5kD0b0,3076
+sofe_server-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sofe_server-0.1.0.dist-info/entry_points.txt,sha256=8zVqtm8_MPnWPF-9XJC1c1AQiS-9tdPJm2QHUp8CARc,53
+sofe_server-0.1.0.dist-info/top_level.txt,sha256=sj9xH0-CWYvkXzSCwrMbm_JfCPlVnk-n91sWdYhCftQ,12
+sofe_server-0.1.0.dist-info/RECORD,,

sofe_server-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_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sofe-server = sofe_server.main:run

sofe_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,93 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship made available under the License.
+
+      "Derivative Works" shall mean any work that is based on the Work.
+
+      "Contribution" shall mean any work of authorship submitted to the Licensor.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of whom
+      a Contribution has been received by the Licensor.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file, You must include
+          a readable copy of the attribution notices contained within
+          such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. The Work is provided on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event shall any Contributor be
+      liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Carlos Cortez (FinOptix)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sofe_server-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sofe_server