propt 0.1.0__py3-none-any.whl

propt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

propt/audit.py

@@ -0,0 +1,57 @@
+"""
+S3 audit logging.
+
+Every impact analysis propt performs gets written to S3 as a timestamped
+JSON record -- an auditable history of what was proposed, what evidence
+was found, and whether the engineer chose to proceed. This matches the
+"security/trust principles" in the original project spec: expose
+evidence, keep an auditable trail, never silently change policy.
+
+Uses boto3 (the AWS SDK) with the caller's existing AWS CLI credentials
+-- no keys are stored or handled by propt itself.
+"""
+import json
+import os
+import socket
+from datetime import datetime, timezone
+
+BUCKET = os.environ.get("PROPT_AUDIT_BUCKET", "propt-audit-logs-sid-2026")
+
+
+def log_decision(change, impact, executed: bool):
+    """
+    Fire-and-forget: failures here must NEVER block or crash the actual
+    kubectl operation. Audit logging is a bonus, not a dependency.
+    """
+    try:
+        import boto3
+    except ImportError:
+        return  # boto3 not installed -- skip silently, propt still works
+
+    try:
+        record = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "hostname": socket.gethostname(),
+            "command": " ".join(change.raw_args),
+            "target": change.target(),
+            "namespace": change.namespace,
+            "impact_level": impact.level,
+            "evidence": impact.evidence,
+            "context": impact.context,
+            "consequence": impact.consequence,
+            "unavailable_signals": impact.unavailable_signals,
+            "executed": executed,
+        }
+        key = f"decisions/{record['timestamp']}.json"
+        s3 = boto3.client("s3")
+        s3.put_object(
+            Bucket=BUCKET,
+            Key=key,
+            Body=json.dumps(record, indent=2).encode("utf-8"),
+            ContentType="application/json",
+        )
+    except Exception:
+        # Never let audit logging break the actual workflow -- this is
+        # the same "honest degradation" principle used for Popeye and
+        # metrics-server: missing signal, not a crash.
+        pass

propt/cli.py

@@ -0,0 +1,60 @@
+"""
+propt CLI entrypoint.
+
+Usage:
+    propt kubectl delete pod payment-api-7d9f
+    propt kubectl get pods          <- passes straight through, no analysis
+
+The `propt` prefix is transparent: whatever command follows it runs
+exactly as normal (after an optional confirmation for mutating ops).
+"""
+import subprocess
+import sys
+
+from . import parser as change_parser
+from . import engine, explain, audit
+
+
+def main():
+    argv = sys.argv[1:]
+    if not argv:
+        print("Usage: propt <command> [args...]   e.g. propt kubectl delete pod foo")
+        sys.exit(1)
+
+    tool = argv[0]
+    rest = argv[1:]
+
+    if tool != "kubectl":
+        # Pass through untouched for non-kubectl commands (v1 scope is k8s-only)
+        _run(argv)
+        return
+
+    change = change_parser.parse_kubectl(rest)
+
+    if not change.is_mutating:
+        # Read-only command: don't slow the engineer down, just run it.
+        _run(argv)
+        return
+
+    impact = engine.analyze(change)
+    print(explain.format_impact(impact))
+    print()
+
+    answer = input("Execute? [y/N]: ").strip().lower()
+    executed = answer == "y"
+    audit.log_decision(change, impact, executed)
+
+    if executed:
+        _run(argv)
+    else:
+        print("Aborted. No changes made.")
+        sys.exit(0)
+
+
+def _run(argv):
+    result = subprocess.run(argv)
+    sys.exit(result.returncode)
+
+
+if __name__ == "__main__":
+    main()

propt/engine.py

@@ -0,0 +1,107 @@
+"""
+Impact Inference Engine.
+
+Combines:
+  - the parsed Change
+  - the live dependency graph
+  - live context (replica counts, pod phase)
+  - real Popeye findings, filtered to the affected chain
+  - real metrics, if available
+
+...into a structured Impact result. No hardcoded per-command risk
+table -- risk comes from what's actually true in the cluster right now.
+"""
+from dataclasses import dataclass, field
+from typing import List
+
+from . import k8s_graph, popeye_runner, metrics
+
+
+@dataclass
+class Impact:
+    level: str  # "HIGH", "MEDIUM", "LOW", "NONE", "UNKNOWN"
+    target: str
+    affected: List[str] = field(default_factory=list)
+    evidence: List[str] = field(default_factory=list)
+    context: List[str] = field(default_factory=list)
+    consequence: str = ""
+    unavailable_signals: List[str] = field(default_factory=list)
+
+
+def analyze(change) -> Impact:
+    target_node = f"{change.resource_type}/{change.resource_name}" if change.resource_type and change.resource_name else None
+
+    if not change.is_mutating or not target_node:
+        return Impact(level="NONE", target=target_node or "unknown",
+                       consequence="Read-only or unrecognized operation; no impact analysis needed.")
+
+    try:
+        graph = k8s_graph.build_graph(change.namespace)
+    except Exception as e:
+        return Impact(level="UNKNOWN", target=target_node,
+                       consequence=f"Could not reach cluster: {e}",
+                       unavailable_signals=["cluster"])
+
+    if not graph.has_node(target_node):
+        return Impact(level="UNKNOWN", target=target_node,
+                       consequence="Resource not found in current cluster state.")
+
+    affected_nodes = k8s_graph.affected_chain(graph, target_node)
+    evidence = []      # signals that actually indicate risk -> drive the level
+    context = []       # informational signals -> shown, but never drive the level
+    unavailable = []
+
+    # 1. Live replica/context evidence -- a real risk signal
+    for node in [target_node] + affected_nodes:
+        ctx = k8s_graph.get_context(graph, node)
+        if ctx.get("kind") == "deployment":
+            desired = ctx.get("desired_replicas")
+            available = ctx.get("available_replicas")
+            if desired is not None and available is not None and available < desired:
+                evidence.append(
+                    f"{node}: available replicas ({available}) below desired ({desired})"
+                )
+
+    # 2. Popeye findings, filtered to affected chain -- Warning/Error are risk
+    #    signals; Info/OK-level notes are informational context only.
+    popeye_findings = popeye_runner.run_popeye(change.namespace)
+    if popeye_findings.get("_unavailable"):
+        unavailable.append(f"popeye ({popeye_findings.get('_reason')})")
+    else:
+        for node in [target_node] + affected_nodes:
+            for finding in popeye_findings.get(node, []):
+                line = f"Popeye [{finding['level']}] {node}: {finding['message']}"
+                if str(finding.get("level", "")).lower() in ("warning", "error", "critical"):
+                    evidence.append(line)
+                else:
+                    context.append(line)
+
+    # 3. Metrics: informational context only -- we don't have a resource
+    #    limit to compare against, so a raw usage number is context, not
+    #    a risk signal by itself.
+    if change.resource_type == "pod":
+        if metrics.metrics_available():
+            m = metrics.get_pod_metrics(change.namespace, change.resource_name)
+            if m.get("available"):
+                context.append(f"{target_node}: {m['cpu_millicores']}m CPU usage observed")
+        else:
+            unavailable.append("metrics-server")
+
+    level = "NONE"
+    consequence = "No significant impact detected from currently available signals."
+    if evidence:
+        level = "HIGH" if any("below desired" in e or "error" in e.lower() or "critical" in e.lower() for e in evidence) else "MEDIUM"
+        consequence = (
+            f"Potential reduction in capacity or degraded state propagating to: "
+            f"{', '.join(affected_nodes) if affected_nodes else target_node}."
+        )
+
+    return Impact(
+        level=level,
+        target=target_node,
+        affected=affected_nodes,
+        evidence=evidence,
+        context=context,
+        consequence=consequence,
+        unavailable_signals=unavailable,
+    )

propt/explain.py

@@ -0,0 +1,29 @@
+from .engine import Impact
+
+
+def format_impact(impact: Impact) -> str:
+    lines = []
+    header = f"{impact.level} POTENTIAL IMPACT" if impact.level != "NONE" else "NO SIGNIFICANT IMPACT DETECTED"
+    lines.append(header)
+    lines.append("")
+    lines.append(f"Target: {impact.target}")
+    if impact.affected:
+        lines.append(f"Affected: {', '.join(impact.affected)}")
+    if impact.evidence:
+        lines.append("")
+        lines.append("Evidence:")
+        for e in impact.evidence:
+            lines.append(f" • {e}")
+    if impact.context:
+        lines.append("")
+        lines.append("Context:")
+        for c in impact.context:
+            lines.append(f" • {c}")
+    if impact.unavailable_signals:
+        lines.append("")
+        lines.append("Unknown / missing context:")
+        for u in impact.unavailable_signals:
+            lines.append(f" • {u} not available")
+    lines.append("")
+    lines.append(f"Potential consequence: {impact.consequence}")
+    return "\n".join(lines)

propt/k8s_graph.py

@@ -0,0 +1,114 @@
+"""
+Live Kubernetes discovery + dependency graph.
+
+Builds a networkx.DiGraph of the current cluster state (in a given
+namespace) using real ownerReferences and label-selector matching --
+no hardcoded relationships. Edges point from a resource to the thing
+that depends on it (child -> parent-of-traffic direction), i.e.:
+
+    Pod --owned_by--> ReplicaSet --owned_by--> Deployment
+    Pod --selected_by--> Service --routed_by--> Ingress
+
+We traverse "upward" (toward things that would be affected) when
+analyzing impact of a change to a lower-level resource.
+"""
+import networkx as nx
+from kubernetes import client, config
+
+
+def load_cluster_client():
+    """Load kubeconfig (works with minikube's default context)."""
+    config.load_kube_config()
+    return client.CoreV1Api(), client.AppsV1Api(), client.NetworkingV1Api()
+
+
+def build_graph(namespace: str = "default") -> nx.DiGraph:
+    core, apps, net = load_cluster_client()
+    g = nx.DiGraph()
+
+    pods = core.list_namespaced_pod(namespace).items
+    rsets = apps.list_namespaced_replica_set(namespace).items
+    deployments = apps.list_namespaced_deployment(namespace).items
+    services = core.list_namespaced_service(namespace).items
+    try:
+        ingresses = net.list_namespaced_ingress(namespace).items
+    except Exception:
+        ingresses = []
+
+    # Nodes
+    for p in pods:
+        g.add_node(f"pod/{p.metadata.name}", kind="pod", raw=p)
+    for r in rsets:
+        g.add_node(f"replicaset/{r.metadata.name}", kind="replicaset", raw=r)
+    for d in deployments:
+        g.add_node(f"deployment/{d.metadata.name}", kind="deployment", raw=d)
+    for s in services:
+        g.add_node(f"service/{s.metadata.name}", kind="service", raw=s)
+    for i in ingresses:
+        g.add_node(f"ingress/{i.metadata.name}", kind="ingress", raw=i)
+
+    # Pod -> ReplicaSet (ownerReferences)
+    for p in pods:
+        for owner in (p.metadata.owner_references or []):
+            if owner.kind == "ReplicaSet":
+                node = f"replicaset/{owner.name}"
+                if g.has_node(node):
+                    g.add_edge(f"pod/{p.metadata.name}", node, relation="owned_by")
+
+    # ReplicaSet -> Deployment (ownerReferences)
+    for r in rsets:
+        for owner in (r.metadata.owner_references or []):
+            if owner.kind == "Deployment":
+                node = f"deployment/{owner.name}"
+                if g.has_node(node):
+                    g.add_edge(f"replicaset/{r.metadata.name}", node, relation="owned_by")
+
+    # Pod -> Service (label selector matching)
+    for s in services:
+        selector = s.spec.selector or {}
+        if not selector:
+            continue
+        for p in pods:
+            labels = p.metadata.labels or {}
+            if all(labels.get(k) == v for k, v in selector.items()):
+                g.add_edge(f"pod/{p.metadata.name}", f"service/{s.metadata.name}", relation="selected_by")
+
+    # Service -> Ingress (backend rules)
+    for i in ingresses:
+        rules = i.spec.rules or []
+        for rule in rules:
+            http = getattr(rule, "http", None)
+            if not http:
+                continue
+            for path in (http.paths or []):
+                backend = path.backend
+                svc = getattr(getattr(backend, "service", None), "name", None)
+                if svc and g.has_node(f"service/{svc}"):
+                    g.add_edge(f"service/{svc}", f"ingress/{i.metadata.name}", relation="routed_by")
+
+    return g
+
+
+def affected_chain(g: nx.DiGraph, target_node: str) -> list:
+    """Everything reachable upward (toward services/ingress) from target."""
+    if not g.has_node(target_node):
+        return []
+    return list(nx.descendants(g, target_node))
+
+
+def get_context(g: nx.DiGraph, node: str) -> dict:
+    """Pull live status fields for a node (replicas, ready state, etc.)."""
+    if not g.has_node(node):
+        return {}
+    kind = g.nodes[node]["kind"]
+    raw = g.nodes[node]["raw"]
+    ctx = {"kind": kind}
+    if raw is None:
+        return ctx
+    if kind == "deployment":
+        ctx["desired_replicas"] = raw.spec.replicas
+        ctx["available_replicas"] = raw.status.available_replicas or 0
+        ctx["ready_replicas"] = raw.status.ready_replicas or 0
+    if kind == "pod":
+        ctx["phase"] = raw.status.phase
+    return ctx

propt/metrics.py

@@ -0,0 +1,49 @@
+"""
+Optional metrics-server integration.
+
+Pulls real CPU usage for pods via the Kubernetes metrics API, if
+metrics-server is installed in the cluster. If it isn't, we say so
+explicitly rather than inventing a "traffic" number -- consistent with
+the project's own principle of distinguishing observed facts from
+missing context.
+"""
+from kubernetes import client, config
+
+
+def metrics_available() -> bool:
+    try:
+        config.load_kube_config()
+        api = client.CustomObjectsApi()
+        api.list_cluster_custom_object("metrics.k8s.io", "v1beta1", "pods")
+        return True
+    except Exception:
+        return False
+
+
+def get_pod_metrics(namespace: str, pod_name: str) -> dict:
+    try:
+        config.load_kube_config()
+        api = client.CustomObjectsApi()
+        data = api.get_namespaced_custom_object(
+            "metrics.k8s.io", "v1beta1", namespace, "pods", pod_name
+        )
+        containers = data.get("containers", [])
+        cpu_total = 0
+        for c in containers:
+            cpu_str = c.get("usage", {}).get("cpu", "0")
+            cpu_total += _parse_cpu(cpu_str)
+        return {"cpu_millicores": cpu_total, "available": True}
+    except Exception as e:
+        return {"available": False, "reason": str(e)}
+
+
+def _parse_cpu(cpu_str: str) -> int:
+    """Convert k8s cpu strings ('100m', '1') to millicores."""
+    if cpu_str.endswith("n"):
+        return int(cpu_str[:-1]) // 1_000_000
+    if cpu_str.endswith("m"):
+        return int(cpu_str[:-1])
+    try:
+        return int(float(cpu_str) * 1000)
+    except ValueError:
+        return 0

propt/parser.py

@@ -0,0 +1,116 @@
+"""
+Common Change Model + kubectl command parser.
+
+Turns a raw kubectl command (as a list of argv tokens, minus the
+leading `propt`) into a normalized Change object the rest of the
+engine can reason about.
+"""
+from dataclasses import dataclass, field
+from typing import Optional
+
+# Operations we intercept for risk analysis. Anything else (get,
+# describe, logs, top, explain, ...) is treated as a read and passed
+# straight through without analysis.
+MUTATING_OPS = {"delete", "scale", "apply", "patch", "edit", "replace", "rollout"}
+
+# kubectl resource shorthands we normalize to a canonical singular form.
+RESOURCE_ALIASES = {
+    "po": "pod", "pods": "pod", "pod": "pod",
+    "deploy": "deployment", "deployments": "deployment", "deployment": "deployment",
+    "svc": "service", "services": "service", "service": "service",
+    "ing": "ingress", "ingresses": "ingress", "ingress": "ingress",
+    "rs": "replicaset", "replicasets": "replicaset", "replicaset": "replicaset",
+    "sts": "statefulset", "statefulsets": "statefulset", "statefulset": "statefulset",
+    "ds": "daemonset", "daemonsets": "daemonset", "daemonset": "daemonset",
+}
+
+
+@dataclass
+class Change:
+    actor: str
+    provider: str
+    operation: str
+    resource_type: Optional[str]
+    resource_name: Optional[str]
+    namespace: str
+    parameters: dict = field(default_factory=dict)
+    raw_args: list = field(default_factory=list)
+    is_mutating: bool = False
+
+    def target(self) -> str:
+        if self.resource_type and self.resource_name:
+            return f"{self.resource_type}/{self.resource_name}"
+        return self.resource_type or "unknown"
+
+
+def _extract_namespace(tokens: list) -> str:
+    for flag in ("-n", "--namespace"):
+        if flag in tokens:
+            idx = tokens.index(flag)
+            if idx + 1 < len(tokens):
+                return tokens[idx + 1]
+    return "default"
+
+
+def _extract_replicas(tokens: list) -> Optional[int]:
+    for tok in tokens:
+        if tok.startswith("--replicas"):
+            if "=" in tok:
+                try:
+                    return int(tok.split("=", 1)[1])
+                except ValueError:
+                    return None
+    return None
+
+
+def parse_kubectl(args: list) -> Change:
+    """
+    args: the kubectl invocation WITHOUT the leading 'kubectl' token,
+          e.g. ["delete", "pod", "payment-api-7d9f"]
+    """
+    if not args:
+        return Change(
+            actor="user", provider="kubernetes", operation="unknown",
+            resource_type=None, resource_name=None, namespace="default",
+            raw_args=args, is_mutating=False,
+        )
+
+    op = args[0].lower()
+    rest = [a for a in args[1:] if not a.startswith("-")]
+    # crude flag-value stripping: drop flag tokens and the value that follows
+    # a flag we recognize (namespace, replicas) so they don't get mistaken
+    # for resource type/name.
+    namespace = _extract_namespace(args)
+
+    resource_type = None
+    resource_name = None
+
+    if rest:
+        first = rest[0]
+        if "/" in first:
+            # e.g. `pod/payment-api-7d9f`
+            resource_type, resource_name = first.split("/", 1)
+        else:
+            resource_type = first
+            if len(rest) > 1:
+                resource_name = rest[1]
+
+    if resource_type:
+        resource_type = RESOURCE_ALIASES.get(resource_type.lower(), resource_type.lower())
+
+    parameters = {}
+    replicas = _extract_replicas(args)
+    if replicas is not None:
+        parameters["replicas"] = replicas
+
+    return Change(
+        actor="user",
+        provider="kubernetes",
+        operation=op,
+        resource_type=resource_type,
+        resource_name=resource_name,
+        namespace=namespace,
+        parameters=parameters,
+        raw_args=args,
+        is_mutating=op in MUTATING_OPS,
+    )

propt/popeye_runner.py

@@ -0,0 +1,68 @@
+"""
+Popeye integration.
+
+Runs the open-source Popeye cluster sanitizer (https://github.com/derailed/popeye)
+against the live cluster and parses its JSON output into findings keyed
+by resource, so the impact engine can filter to just the resources in
+a change's dependency chain.
+
+Popeye must be installed and on PATH as `popeye`.
+"""
+import json
+import shutil
+import subprocess
+
+
+def popeye_available() -> bool:
+    return shutil.which("popeye") is not None
+
+
+def run_popeye(namespace: str = "default") -> dict:
+    """
+    Returns {"pod/name": [finding, ...], "deployment/name": [...], ...}
+    Falls back to an empty dict (with a note) if popeye isn't installed
+    or the scan fails -- we never fabricate findings.
+    """
+    if not popeye_available():
+        return {"_unavailable": True, "_reason": "popeye not found on PATH"}
+
+    try:
+        result = subprocess.run(
+            ["popeye", "-n", namespace, "-o", "json", "--force-exit-zero"],
+            capture_output=True, text=True, timeout=60,
+        )
+        data = json.loads(result.stdout)
+    except Exception as e:
+        return {"_unavailable": True, "_reason": str(e)}
+
+    findings = {}
+    try:
+        sanitizers = data.get("popeye", {}).get("sanitizers", [])
+        for section in sanitizers:
+            gvr = section.get("sanitizer", "")
+            for issue_group in section.get("issues", {}).items():
+                resource_name, issues = issue_group
+                # Popeye keys issues by "namespace/name"
+                short_name = resource_name.split("/")[-1]
+                kind = _gvr_to_kind(gvr)
+                key = f"{kind}/{short_name}"
+                findings.setdefault(key, [])
+                for issue in issues:
+                    findings[key].append({
+                        "level": issue.get("level"),
+                        "message": issue.get("message"),
+                    })
+    except Exception:
+        pass
+
+    return findings
+
+
+def _gvr_to_kind(sanitizer_name: str) -> str:
+    mapping = {
+        "pod": "pod", "po": "pod",
+        "deployment": "deployment", "dp": "deployment",
+        "service": "service", "svc": "service",
+        "replicaset": "replicaset", "rs": "replicaset",
+    }
+    return mapping.get(sanitizer_name.lower(), sanitizer_name.lower())

propt-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: propt
+Version: 0.1.0
+Summary: Pre-action operational intelligence layer for infrastructure changes.
+Requires-Python: >=3.9
+Requires-Dist: kubernetes>=29.0.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: pyyaml>=6.0

propt-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+propt/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+propt/audit.py,sha256=nNcnipjuewUFLRJrUQhJXXtvhG6Bwv6pthPD0ApJvjY,2091
+propt/cli.py,sha256=n8aNzOz2dzEhxYLegHjqYWWP7h1EDcn665U00i_U57w,1389
+propt/engine.py,sha256=wvigf3EOBAQ7ZpO_nQurIvZdSnYXB4r3FFFMhvu9JBY,4411
+propt/explain.py,sha256=1n4aokc0CZyqSlcm-vxnyJGogAIu1VhFT5xnCAIWQAQ,1005
+propt/k8s_graph.py,sha256=7DbmAlBU-7T6QMXgP2XSiH_k2aT7e9IT-KqOeiUD2po,4284
+propt/metrics.py,sha256=2zN1aTUPoD8letmC7PHfppQnx-46JOBWaodpW5PyYtA,1578
+propt/parser.py,sha256=4GPFPwiaxaudMoX5Jcf6W7EWaAEnbOtCBMN7OoHjflg,3791
+propt/popeye_runner.py,sha256=p6S3wJTFEdbzhKMeuXUYh7vRxd8NAgxIpCwpeyQE1yc,2289
+propt-0.1.0.dist-info/METADATA,sha256=dnKszc7i8sX6GqZ3QoHIwMhP53zvCpLOhBvXwKo1B0s,307
+propt-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+propt-0.1.0.dist-info/entry_points.txt,sha256=vThvx1V0s1ejRgU4JMNcKikTf_rebHslrLwN_RqHiv0,41
+propt-0.1.0.dist-info/top_level.txt,sha256=Gr1nnzwiH4AJl7RyB6pWCwMFTsMget0VEwrx2MSpksk,6
+propt-0.1.0.dist-info/RECORD,,

propt-0.1.0.dist-info/WHEEL

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

propt-0.1.0.dist-info/entry_points.txt

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

propt-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+propt