platformforge 0.1.0__py3-none-any.whl

platformforge/cicd/backstage.py

@@ -0,0 +1,51 @@
+"""Backstage catalog-info analyzer — catalog entities as declared facts.
+
+Per file: component/api/resource entities with kind, owner, lifecycle,
+system, dependencies. Read-only — never calls a Backstage API.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+
+def analyze_backstage(path: str | Path) -> dict[str, Any]:
+    p = Path(path)
+    files = [p] if p.is_file() else sorted(
+        p.rglob("catalog-info.y*ml"))
+    facts: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            docs = list(yaml.safe_load_all(f.read_text()))
+        except yaml.YAMLError:
+            continue
+        for doc in docs:
+            if not isinstance(doc, dict) or "apiVersion" not in doc:
+                continue
+            meta = doc.get("metadata") or {}
+            spec = doc.get("spec") or {}
+            facts.append({
+                "fact_id": stable_id(
+                    "PF-BACKSTAGE", str(f), str(meta.get("name", ""))),
+                "kind": "catalog.entity",
+                "source": str(f),
+                "location": str(meta.get("name", f.name)),
+                "tier": 3,
+                "attrs": {
+                    "entity_kind": doc.get("kind", ""),
+                    "api_version": doc.get("apiVersion", ""),
+                    "owner": spec.get("owner", ""),
+                    "lifecycle": spec.get("lifecycle", ""),
+                    "system": spec.get("system", ""),
+                    "type": spec.get("type", ""),
+                    "depends_on": list(spec.get("dependsOn") or []),
+                    "provides_apis": list(spec.get("providesApis") or []),
+                    "consumes_apis": list(spec.get("consumesApis") or []),
+                    "has_owner": bool(spec.get("owner")),
+                }})
+    return {"facts": facts}

platformforge/cicd/dockerfile.py

@@ -0,0 +1,64 @@
+"""Dockerfile analyzer — build-time surface as declared facts (T3).
+
+Per Dockerfile: base images (+ pin style), USER, EXPOSE, package
+installs, ADD-vs-COPY, healthcheck presence. Read-only.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+_RE_FROM = re.compile(r"^\s*FROM\s+([^\s]+)", re.MULTILINE | re.IGNORECASE)
+_RE_USER = re.compile(r"^\s*USER\s+(\S+)", re.MULTILINE | re.IGNORECASE)
+_RE_EXPOSE = re.compile(r"^\s*EXPOSE\s+(\S+)", re.MULTILINE | re.IGNORECASE)
+_RE_ADD = re.compile(r"^\s*ADD\s+", re.MULTILINE | re.IGNORECASE)
+_RE_HEALTH = re.compile(r"^\s*HEALTHCHECK\s", re.MULTILINE | re.IGNORECASE)
+_RE_PKG = re.compile(
+    r"(apt-get|apt|apk|yum|dnf|pip|npm)\s+install", re.IGNORECASE)
+
+
+def _pin(ref: str) -> str:
+    if "@sha256:" in ref:
+        return "digest"
+    if ":" in ref:
+        return "tag"          # tags are mutable
+    if ref.upper() == "SCRATCH" or ref.startswith("${"):
+        return "variable"
+    return "unpinned"
+
+
+def analyze_dockerfile(path: str | Path) -> dict[str, Any]:
+    p = Path(path)
+    files = [p] if p.is_file() else sorted(p.rglob("Dockerfile*"))
+    facts: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            text = f.read_text()
+        except (OSError, UnicodeDecodeError):
+            continue
+        bases = _RE_FROM.findall(text)
+        users = _RE_USER.findall(text)
+        last_user = users[-1] if users else ""
+        facts.append({
+            "fact_id": stable_id("PF-DOCKERFILE", str(f)),
+            "kind": "cicd.dockerfile",
+            "source": str(f),
+            "location": str(f),
+            "tier": 3,
+            "attrs": {
+                "base_images": bases,
+                "unpinned_bases": [b for b in bases
+                                   if _pin(b) in ("tag", "unpinned")],
+                "runs_as_root": (last_user in ("", "root", "0")),
+                "exposed_ports": _RE_EXPOSE.findall(text),
+                "uses_add": bool(_RE_ADD.search(text)),
+                "has_healthcheck": bool(_RE_HEALTH.search(text)),
+                "package_managers": sorted(
+                    {m.lower() for m in _RE_PKG.findall(text)}),
+                "stage_count": len(bases),
+            }})
+    return {"facts": facts}

platformforge/cicd/github_actions.py

@@ -0,0 +1,122 @@
+"""GitHub Actions workflow analyzer — CI supply-chain surface as facts.
+
+Per workflow: triggers, permissions, job steps, third-party actions with
+pinning style (sha/tag/branch), secrets usage, self-hosted runners.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+_DANGEROUS_TRIGGERS = {"pull_request_target", "workflow_run"}
+_WRITE_PERMS = {"contents": "write", "id-token": "write",
+                "packages": "write", "actions": "write",
+                "security-events": "write"}
+
+
+def _action_ref(uses: str) -> dict[str, Any]:
+    """`org/repo@ref` → {name, ref, pinned: sha|tag|branch|none}."""
+    if not uses or uses.startswith(("./", "docker://")):
+        return {"name": uses, "ref": None, "pin": "local"}
+    name, _, ref = uses.partition("@")
+    if not ref:
+        pin = "unpinned"
+    elif re.fullmatch(r"[0-9a-f]{40}", ref):
+        pin = "sha"
+    elif re.fullmatch(r"v?\d+(\.\d+)*", ref):
+        pin = "tag"  # tags are mutable
+    else:
+        pin = "branch"
+    return {"name": name, "ref": ref, "pin": pin,
+            "third_party": not name.startswith(("actions/", "github/"))}
+
+
+def analyze_gha(path: str | Path) -> dict[str, Any]:
+    root = Path(path)
+    wf_dir = root / ".github" / "workflows" if root.is_dir() else None
+    files = ([*wf_dir.glob("*.yml"), *wf_dir.glob("*.yaml")]
+             if wf_dir and wf_dir.is_dir()
+             else ([root] if root.is_file() else []))
+    facts: list[dict[str, Any]] = []
+    for f in sorted(set(files)):
+        try:
+            doc = yaml.safe_load(f.read_text()) or {}
+        except yaml.YAMLError:
+            continue
+        if not isinstance(doc, dict) or "jobs" not in doc:
+            continue
+        name = doc.get("name") or f.stem
+        triggers = doc.get(True) or doc.get("on") or {}  # YAML 1.1 `on:`→True
+        if isinstance(triggers, str):
+            triggers = {triggers: {}}
+        perms = doc.get("permissions") or {}
+        if isinstance(perms, str):
+            perms = {"all": perms}
+        jobs = doc.get("jobs") or {}
+        uses_list, secrets_used = [], []
+        unpinned, dangerous, self_hosted = [], [], []
+        script_injection = []
+        for jname, job in jobs.items():
+            job = job or {}
+            if job.get("runs-on") and "self-hosted" in \
+                    (job["runs-on"] if isinstance(job["runs-on"], list)
+                     else [job["runs-on"]]):
+                self_hosted.append(jname)
+            jperms = job.get("permissions") or {}
+            if isinstance(jperms, str):
+                jperms = {"all": jperms}
+            for k, v in jperms.items():
+                if v in ("write", "write-all"):
+                    perms[k] = v
+            for step in job.get("steps") or []:
+                if "uses" in step:
+                    ref = _action_ref(step["uses"])
+                    uses_list.append(ref)
+                    if ref["pin"] in ("unpinned", "branch", "tag") \
+                            and ref["third_party"]:
+                        unpinned.append(f"{jname}:{ref['name']}@{ref['ref']}")
+                run = step.get("run") or ""
+                if "${{" in run and any(
+                        t in run for t in
+                        ("github.event.issue", "github.event.comment",
+                         "github.event.pull_request.title",
+                         "github.event.pull_request.body",
+                         "github.head_ref")):
+                    script_injection.append(jname)
+                env = step.get("env") or {}
+                for v in env.values():
+                    if isinstance(v, str) and "secrets." in v:
+                        secrets_used.append(v)
+        for t in triggers:
+            if t in _DANGEROUS_TRIGGERS:
+                dangerous.append(t)
+        write_perms = [k for k, v in perms.items()
+                       if v in ("write", "write-all") or v == "write-all"
+                       or perms.get("all") in ("write", "write-all")]
+        if isinstance(perms, dict) and perms.get("all") in ("write", "write-all"):
+            write_perms = ["*"]
+        attrs = {
+            "workflow": name, "triggers": sorted(triggers),
+            "dangerous_triggers": dangerous,
+            "permissions": perms, "write_perms": write_perms,
+            "jobs": sorted(jobs), "job_count": len(jobs),
+            "actions": uses_list,
+            "unpinned_third_party": unpinned,
+            "self_hosted_jobs": self_hosted,
+            "script_injection_risk": script_injection,
+            "secrets_referenced": sorted(set(secrets_used)),
+            "graph": {
+                "nodes": [{"kind": "workflow",
+                           "label": f"{f.parent.parent.parent.name}/{f.stem}"}],
+                "edges": []},
+        }
+        facts.append({"fact_id": stable_id("PF-CICD", "gha", str(f)),
+                      "kind": "cicd.github_workflow", "source": str(f),
+                      "location": str(f), "tier": 3, "attrs": attrs})
+    return {"facts": facts, "counts": {"workflows": len(facts)}}

platformforge/cicd/gitlab_ci.py

@@ -0,0 +1,56 @@
+"""GitLab CI analyzer — pipeline surface as declared facts (T3).
+
+Per pipeline: stages, jobs, images, services, `only`/`rules` triggers,
+cache usage. Read-only — never executes the pipeline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+
+def analyze_gitlab_ci(path: str | Path) -> dict[str, Any]:
+    p = Path(path)
+    f = p if p.is_file() else p / ".gitlab-ci.yml"
+    if not f.exists():
+        return {"facts": [], "error": f"no .gitlab-ci.yml at {p}"}
+    try:
+        doc = yaml.safe_load(f.read_text()) or {}
+    except yaml.YAMLError as e:
+        return {"facts": [], "error": f"yaml: {e}"}
+    if not isinstance(doc, dict):
+        return {"facts": [], "error": "not a mapping"}
+    stages = doc.get("stages") or []
+    jobs = {k: v for k, v in doc.items()
+            if isinstance(v, dict) and isinstance(v.get("script"), (list, str))}
+    images = sorted({str(j.get("image")) for j in jobs.values()
+                     if j.get("image")})
+    default_image = ""
+    if isinstance(doc.get("default"), dict):
+        default_image = str(doc["default"].get("image") or "")
+    unpinned = [i for i in images + ([default_image] if default_image else [])
+                if ":" not in i or i.endswith(":latest")]
+    facts = [{
+        "fact_id": stable_id("PF-GITLABCI", str(f)),
+        "kind": "cicd.gitlab_pipeline",
+        "source": str(f),
+        "location": str(f),
+        "tier": 3,
+        "attrs": {
+            "stages": list(stages),
+            "jobs": sorted(jobs),
+            "job_count": len(jobs),
+            "images": images,
+            "default_image": default_image,
+            "unpinned_images": sorted(set(unpinned)),
+            "uses_cache": any("cache" in j for j in jobs.values())
+            or "cache" in doc,
+            "has_rules": any("rules" in j or "only" in j or "except" in j
+                             for j in jobs.values()),
+        }}]
+    return {"facts": facts}

platformforge/cicd/gitops.py

@@ -0,0 +1,130 @@
+"""GitOps analyzers — ArgoCD Application/ApplicationSet, Flux Kustomization/
+HelmRelease/GitRepository. Facts declare sync policy, sources, targets;
+edges wire app → repo → cluster/namespace.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+ARGO_KINDS = {"Application", "ApplicationSet", "AppProject"}
+FLUX_KINDS = {"GitRepository", "HelmRepository", "OCIRepository",
+              "Kustomization", "HelmRelease", "HelmChart"}
+
+
+def _docs(path: Path):
+    files = (sorted(path.rglob("*.yaml")) + sorted(path.rglob("*.yml"))) \
+        if path.is_dir() else [path]
+    for f in files:
+        try:
+            for i, doc in enumerate(yaml.safe_load_all(f.read_text())):
+                if isinstance(doc, dict) and doc.get("kind") \
+                        and doc.get("apiVersion"):
+                    yield f, doc
+        except yaml.YAMLError:
+            continue
+
+
+def analyze_gitops(path: str | Path) -> dict[str, Any]:
+    facts: list[dict[str, Any]] = []
+    for f, doc in _docs(Path(path)):
+        kind, meta = doc["kind"], doc.get("metadata") or {}
+        spec = doc.get("spec") or {}
+        name, ns = meta.get("name", "?"), meta.get("namespace", "default")
+        loc = f"{f}::{ns}/{name}"
+        api = doc.get("apiVersion", "")
+
+        if kind in ARGO_KINDS and "argoproj.io" in api:
+            sync = spec.get("syncPolicy") or {}
+            # §69 — multi-source applications carry `sources[]`, not `source`
+            sources = spec.get("sources") or ([spec["source"]]
+                                              if spec.get("source") else [])
+            src = sources[0] if sources else {}
+            dest = spec.get("destination") or {}
+            # ArgoCD: presence of `automated` (even `{}`/null) enables sync
+            automated = "automated" in sync
+            ann = meta.get("annotations") or {}
+            attrs = {
+                "name": name, "namespace": ns, "tool": "argocd",
+                "automated_sync": automated,
+                "prune": bool((sync.get("automated") or {}).get("prune")),
+                "self_heal": bool((sync.get("automated") or {}).get("selfHeal")),
+                "source_repo": src.get("repoURL"),
+                "source_path": src.get("path"),
+                "source_revision": src.get("targetRevision"),
+                "source_count": len(sources),
+                "source_repos": sorted({s.get("repoURL") for s in sources
+                                        if s.get("repoURL")}),
+                "dest_server": dest.get("server"),
+                "dest_namespace": dest.get("namespace"),
+                "project": spec.get("project"),
+                # §69 sync waves + hooks (declared, T3)
+                "sync_wave": ann.get("argocd.argoproj.io/sync-wave"),
+                "has_hooks": "argocd.argoproj.io/hook" in ann,
+                "app_project_scope": bool(spec.get("project")),
+                "graph": {
+                    "nodes": [{"kind": "argocd_application",
+                               "label": f"{ns}/{name}",
+                               "attrs": {"project": spec.get("project")}}],
+                    "edges": []},
+            }
+            # §69 — kind-specific depth: ApplicationSet generators +
+            # AppProject source/destination restrictions
+            if kind == "ApplicationSet":
+                gens = spec.get("generators") or []
+                attrs["generators"] = [next(iter(g)) for g in gens
+                                       if isinstance(g, dict) and g]
+            elif kind == "AppProject":
+                attrs["source_restrictions"] = len(spec.get("sourceRepos") or [])
+                attrs["dest_restrictions"] = len(spec.get("destinations") or [])
+                attrs["cluster_resource_whitelist"] = len(
+                    spec.get("clusterResourceWhitelist") or [])
+                attrs["roles"] = len(spec.get("roles") or [])
+            edges = attrs["graph"]["edges"]
+            if src.get("repoURL"):
+                edges.append({"src_kind": "argocd_application",
+                              "src": f"{ns}/{name}",
+                              "dst_kind": "repository",
+                              "dst": src["repoURL"].rsplit("/", 1)[-1]
+                                     .removesuffix(".git"),
+                              "kind": "depends_on"})
+            if dest.get("namespace"):
+                edges.append({"src_kind": "argocd_application",
+                              "src": f"{ns}/{name}",
+                              "dst_kind": "namespace",
+                              "dst": dest["namespace"],
+                              "kind": "deploys_to"})
+            facts.append({"fact_id": stable_id("PF-GITOPS", "argocd", loc),
+                          "kind": "gitops.argocd_app", "source": str(f),
+                          "location": loc, "tier": 3, "attrs": attrs})
+        elif kind in FLUX_KINDS and "toolkit.fluxcd.io" in api:
+            src = spec.get("sourceRef") or {}
+            interval = spec.get("interval")
+            attrs = {
+                "name": name, "namespace": ns, "tool": "fluxcd",
+                "flux_kind": kind, "interval": interval,
+                "prune": spec.get("prune"),
+                "source_ref": f"{src.get('kind')}/{src.get('name')}"
+                    if src else None,
+                "url": spec.get("url"),
+                "suspend": doc.get("spec", {}).get("suspend", False),
+                "graph": {
+                    "nodes": [{"kind": "fluxcd_resource",
+                               "label": f"{ns}/{name}",
+                               "attrs": {"flux_kind": kind}}],
+                    "edges": []},
+            }
+            if src.get("name"):
+                attrs["graph"]["edges"].append(
+                    {"src_kind": "fluxcd_resource", "src": f"{ns}/{name}",
+                     "dst_kind": "fluxcd_resource",
+                     "dst": f"{ns}/{src['name']}", "kind": "depends_on"})
+            facts.append({"fact_id": stable_id("PF-GITOPS", "flux", loc),
+                          "kind": "gitops.flux_resource", "source": str(f),
+                          "location": loc, "tier": 3, "attrs": attrs})
+    return {"facts": facts, "counts": {"facts": len(facts)}}