invctl 0.1.0__py3-none-any.whl

invctl/__init__.py

@@ -0,0 +1,3 @@
+"""invctl — Infrastructure Inventory Control for Proxmox VE."""
+
+__version__ = "0.1.0"

invctl/client.py

@@ -0,0 +1,96 @@
+"""Proxmox API client factory with Rich error reporting."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import requests
+from proxmoxer import ProxmoxAPI
+from rich.console import Console
+
+_console = Console(stderr=True)
+
+
+def get_client(
+    host: str,
+    port: int = 8006,
+    token_id: str | None = None,
+    token_secret: str | None = None,
+    user: str | None = None,
+    password: str | None = None,
+    verify_ssl: bool = True,
+) -> ProxmoxAPI:
+    """Return an authenticated ProxmoxAPI instance.
+
+    Authentication priority:
+    1. API token (token_id + token_secret) — recommended
+    2. Username + password
+
+    Env vars (used when CLI flags are absent):
+    - PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET
+    - PROXMOX_USER, PROXMOX_PASSWORD
+
+    Raises SystemExit with a Rich-formatted error on connection failure.
+    """
+    host = host or os.getenv("PROXMOX_HOST", "")
+    if not host:
+        _console.print("[bold red]Error:[/] --host / PROXMOX_HOST is required.")
+        sys.exit(1)
+
+    token_id = token_id or os.getenv("PROXMOX_TOKEN_ID")
+    token_secret = token_secret or os.getenv("PROXMOX_TOKEN_SECRET")
+    user = user or os.getenv("PROXMOX_USER")
+    password = password or os.getenv("PROXMOX_PASSWORD")
+
+    kwargs: dict[str, Any] = {
+        "host": host,
+        "port": port,
+        "verify_ssl": verify_ssl,
+        "service": "PVE",
+    }
+
+    if token_id and token_secret:
+        # token_id format: "USER@REALM!TOKENNAME" or just "TOKENNAME" when user is separate
+        if "!" in token_id:
+            kwargs["user"] = token_id
+            kwargs["password"] = token_secret
+        else:
+            # Assume user flag holds the user@realm part
+            if not user:
+                _console.print(
+                    "[bold red]Error:[/] --token-id without '@realm!' prefix requires --user."
+                )
+                sys.exit(1)
+            kwargs["user"] = f"{user}!{token_id}"
+            kwargs["password"] = token_secret
+    elif user and password:
+        kwargs["user"] = user
+        kwargs["password"] = password
+    else:
+        _console.print(
+            "[bold red]Error:[/] Provide either --token-id/--token-secret "
+            "or --user/--password (or matching env vars)."
+        )
+        sys.exit(1)
+
+    try:
+        proxmox = ProxmoxAPI(**kwargs)
+        # Probe connectivity — version endpoint is always available
+        proxmox.version.get()
+        return proxmox
+    except requests.exceptions.SSLError as exc:
+        _console.print(
+            f"[bold red]SSL Error:[/] {exc}\n"
+            "[dim]Tip: use --no-verify-ssl to skip certificate validation.[/]"
+        )
+        sys.exit(1)
+    except requests.exceptions.ConnectionError as exc:
+        _console.print(f"[bold red]Connection Error:[/] Cannot reach {host}:{port} — {exc}")
+        sys.exit(1)
+    except Exception as exc:  # proxmoxer raises various auth errors as generic exceptions
+        msg = str(exc)
+        # Never leak token secrets or passwords in error output
+        _console.print(f"[bold red]Authentication Error:[/] {msg}")
+        sys.exit(1)

invctl/collectors/__init__.py

@@ -0,0 +1,23 @@
+"""Proxmox data collectors."""
+
+from invctl.collectors.backups import BackupsCollector
+from invctl.collectors.cluster import ClusterCollector
+from invctl.collectors.containers import ContainersCollector
+from invctl.collectors.firewall import FirewallCollector
+from invctl.collectors.network import NetworkCollector
+from invctl.collectors.nodes import NodesCollector
+from invctl.collectors.storage import StorageCollector
+from invctl.collectors.users import UsersCollector
+from invctl.collectors.vms import VMsCollector
+
+__all__ = [
+    "BackupsCollector",
+    "ClusterCollector",
+    "ContainersCollector",
+    "FirewallCollector",
+    "NetworkCollector",
+    "NodesCollector",
+    "StorageCollector",
+    "UsersCollector",
+    "VMsCollector",
+]

invctl/collectors/backups.py

@@ -0,0 +1,66 @@
+"""Backup collector: scheduled backup jobs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from invctl.collectors.base import BaseCollector
+
+
+class BackupsCollector(BaseCollector):
+    """Collect all vzdump backup jobs configured in the cluster."""
+
+    def collect(self) -> dict[str, Any]:
+        """Return a BackupInfo-compatible dict."""
+        try:
+            return self._collect()
+        except Exception as exc:
+            self._warn("backups", exc)
+            return {"available": False, "error": str(exc), "jobs": []}
+
+    def _collect(self) -> dict[str, Any]:
+        jobs: list[dict[str, Any]] = []
+        try:
+            raw_jobs: list[dict[str, Any]] = self.proxmox.cluster.backup.get()
+        except Exception as exc:
+            self._warn("backups.list", exc)
+            return {"available": True, "jobs": []}
+
+        for job in raw_jobs:
+            try:
+                parsed = self._parse_job(job)
+                jobs.append(parsed)
+            except Exception as exc:
+                self._warn(f"backups.job.{job.get('id')}", exc)
+
+        return {"available": True, "jobs": jobs}
+
+    @staticmethod
+    def _parse_job(raw: dict[str, Any]) -> dict[str, Any]:
+        """Convert a raw backup job config to our schema."""
+        vmid_raw: str = raw.get("vmid", "") or ""
+        all_vms = not vmid_raw or vmid_raw.strip() == "all"
+        vmids = [v.strip() for v in vmid_raw.split(",") if v.strip() and v.strip() != "all"]
+
+        return {
+            "job_id": raw.get("id"),
+            "schedule": raw.get("schedule") or raw.get("starttime"),
+            "storage": raw.get("storage"),
+            "vmids": vmids,
+            "all_vms": all_vms,
+            "mode": raw.get("mode"),
+            "keep_last": _int_or_none(raw.get("keep-last")),
+            "keep_daily": _int_or_none(raw.get("keep-daily")),
+            "keep_weekly": _int_or_none(raw.get("keep-weekly")),
+            "keep_monthly": _int_or_none(raw.get("keep-monthly")),
+            "keep_yearly": _int_or_none(raw.get("keep-yearly")),
+            "comment": raw.get("comment"),
+            "enabled": bool(raw.get("enabled", 1)),
+        }
+
+
+def _int_or_none(val: Any) -> int | None:
+    try:
+        return int(val)
+    except (TypeError, ValueError):
+        return None

invctl/collectors/base.py

@@ -0,0 +1,37 @@
+"""Abstract base class for all Proxmox data collectors."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from proxmoxer import ProxmoxAPI
+from rich.console import Console
+
+console = Console(stderr=True)
+
+
+class BaseCollector(ABC):
+    """Base class every collector must subclass.
+
+    Subclasses implement :meth:`collect` and return a plain dict
+    whose structure matches the corresponding Pydantic model.
+    On total failure the dict must be ``{"available": False, "error": "<msg>"}``.
+    """
+
+    def __init__(self, proxmox: ProxmoxAPI) -> None:
+        """Initialise with an authenticated ProxmoxAPI client."""
+        self.proxmox = proxmox
+
+    @abstractmethod
+    def collect(self) -> dict[str, Any]:
+        """Run the collection and return a serialisable dict."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Shared helpers
+    # ------------------------------------------------------------------
+
+    def _warn(self, context: str, exc: Exception) -> None:
+        """Print a non-fatal warning to stderr via Rich."""
+        console.print(f"[yellow]Warning[/] [{context}]: {exc}")

invctl/collectors/cluster.py

@@ -0,0 +1,81 @@
+"""Cluster-level collector: name, quorum, HA."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from invctl.collectors.base import BaseCollector
+
+
+class ClusterCollector(BaseCollector):
+    """Collect cluster name, quorum status, and HA configuration."""
+
+    def collect(self) -> dict[str, Any]:
+        """Return ClusterInfo-compatible dict."""
+        try:
+            return self._collect()
+        except Exception as exc:
+            self._warn("cluster", exc)
+            return {"available": False, "error": str(exc)}
+
+    def _collect(self) -> dict[str, Any]:
+        name: str | None = None
+        quorum_status: str | None = None
+        node_count: int | None = None
+
+        try:
+            status_items: list[dict[str, Any]] = self.proxmox.cluster.status.get()
+            for item in status_items:
+                if item.get("type") == "cluster":
+                    name = item.get("name")
+                    quorum_status = "ok" if item.get("quorate", 0) else "nok"
+                    node_count = item.get("nodes")
+                    break
+        except Exception as exc:
+            self._warn("cluster.status", exc)
+
+        ha_info: dict[str, Any] | None = None
+        try:
+            ha_info = self._collect_ha()
+        except Exception as exc:
+            self._warn("cluster.ha", exc)
+
+        return {
+            "available": True,
+            "name": name,
+            "quorum_status": quorum_status,
+            "node_count": node_count,
+            "ha": ha_info,
+        }
+
+    def _collect_ha(self) -> dict[str, Any]:
+        """Collect HA status and groups."""
+        status = "unknown"
+        try:
+            ha_status: list[dict[str, Any]] = self.proxmox.cluster.ha.status.current.get()
+            if ha_status:
+                states = {r.get("state", "") for r in ha_status}
+                status = "ok" if all(s in ("started", "ignored") for s in states) else "degraded"
+            else:
+                status = "no resources"
+        except Exception as exc:
+            self._warn("cluster.ha.status", exc)
+
+        groups: list[dict[str, Any]] = []
+        try:
+            raw_groups: list[dict[str, Any]] = self.proxmox.cluster.ha.groups.get()
+            for g in raw_groups:
+                nodes_str: str = g.get("nodes", "")
+                node_names = [n.split(":")[0] for n in nodes_str.split(",") if n]
+                groups.append(
+                    {
+                        "name": g.get("group", ""),
+                        "nodes": node_names,
+                        "restricted": bool(g.get("restricted", 0)),
+                        "nofailback": bool(g.get("nofailback", 0)),
+                    }
+                )
+        except Exception as exc:
+            self._warn("cluster.ha.groups", exc)
+
+        return {"status": status, "groups": groups}

invctl/collectors/containers.py

@@ -0,0 +1,162 @@
+"""Container collector: LXC containers, config and runtime stats."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from invctl.collectors.base import BaseCollector
+
+_NET_RE = re.compile(r"^net\d+$")
+_MP_RE = re.compile(r"^mp\d+$")
+
+
+def _parse_ct_net(key: str, value: str) -> dict[str, Any]:
+    """Parse an LXC network config string into a CTNetworkInterface dict."""
+    parts_dict: dict[str, str] = {}
+    for part in value.split(","):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            parts_dict[k] = v
+    return {
+        "key": key,
+        "name": parts_dict.get("name"),
+        "bridge": parts_dict.get("bridge"),
+        "ip": parts_dict.get("ip"),
+        "ip6": parts_dict.get("ip6"),
+        "gateway": parts_dict.get("gw"),
+        "mac": parts_dict.get("hwaddr"),
+    }
+
+
+def _parse_storage_spec(value: str, mp_path: str | None = None) -> dict[str, Any]:
+    """Parse a rootfs/mp config string into a MountpointInfo dict."""
+    parts = value.split(",")
+    storage_volume = parts[0]
+    storage_backend = storage_volume.split(":")[0] if ":" in storage_volume else None
+    parts_dict: dict[str, str] = {}
+    for part in parts[1:]:
+        if "=" in part:
+            k, v = part.split("=", 1)
+            parts_dict[k] = v
+    return {
+        "storage_backend": storage_backend,
+        "size": parts_dict.get("size"),
+        "mountpoint": parts_dict.get("mp", mp_path),
+    }
+
+
+class ContainersCollector(BaseCollector):
+    """Collect all LXC containers across every node."""
+
+    def collect(self) -> dict[str, Any]:
+        """Return a list of ContainerInfo-compatible dicts under key 'containers'."""
+        containers: list[dict[str, Any]] = []
+        try:
+            raw_nodes: list[dict[str, Any]] = self.proxmox.nodes.get()
+        except Exception as exc:
+            self._warn("containers.nodes", exc)
+            return {"containers": []}
+
+        for node in raw_nodes:
+            node_name: str = node.get("node", "")
+            if node.get("status") != "online":
+                continue
+            try:
+                node_cts = self._collect_node_containers(node_name)
+                containers.extend(node_cts)
+            except Exception as exc:
+                self._warn(f"containers.{node_name}", exc)
+
+        return {"containers": containers}
+
+    def _collect_node_containers(self, node_name: str) -> list[dict[str, Any]]:
+        """Collect all LXC containers on a single node."""
+        containers: list[dict[str, Any]] = []
+        try:
+            raw_list: list[dict[str, Any]] = self.proxmox.nodes(node_name).lxc.get()
+        except Exception as exc:
+            self._warn(f"containers.{node_name}.list", exc)
+            return []
+
+        for ct_summary in raw_list:
+            vmid = ct_summary.get("vmid")
+            if vmid is None:
+                continue
+            try:
+                ct_data = self._collect_container(node_name, vmid, ct_summary)
+            except Exception as exc:
+                self._warn(f"containers.{node_name}.{vmid}", exc)
+                ct_data = {
+                    "available": False,
+                    "error": str(exc),
+                    "vmid": vmid,
+                    "node": node_name,
+                    "status": ct_summary.get("status", "unknown"),
+                }
+            containers.append(ct_data)
+
+        return containers
+
+    def _collect_container(
+        self, node_name: str, vmid: int, summary: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Collect detailed config and stats for a single LXC container."""
+        config: dict[str, Any] = {}
+        try:
+            config = self.proxmox.nodes(node_name).lxc(vmid).config.get()
+        except Exception as exc:
+            self._warn(f"containers.{node_name}.{vmid}.config", exc)
+
+        snapshots: list[dict[str, Any]] = []
+        try:
+            raw_snaps: list[dict[str, Any]] = (
+                self.proxmox.nodes(node_name).lxc(vmid).snapshot.get()
+            )
+            for snap in raw_snaps:
+                if snap.get("name") == "current":
+                    continue
+                snapshots.append(
+                    {
+                        "name": snap.get("name", ""),
+                        "snaptime": snap.get("snaptime"),
+                        "description": snap.get("description"),
+                    }
+                )
+        except Exception as exc:
+            self._warn(f"containers.{node_name}.{vmid}.snapshots", exc)
+
+        networks = [_parse_ct_net(k, v) for k, v in config.items() if _NET_RE.match(k)]
+        mountpoints = [_parse_storage_spec(v) for k, v in config.items() if _MP_RE.match(k)]
+
+        rootfs: dict[str, Any] | None = None
+        if "rootfs" in config:
+            rootfs = _parse_storage_spec(config["rootfs"], "/")
+
+        tags_raw: str = config.get("tags", "") or summary.get("tags", "") or ""
+        tags = [t.strip() for t in re.split(r"[;,]", tags_raw) if t.strip()]
+
+        return {
+            "available": True,
+            "vmid": vmid,
+            "name": config.get("hostname") or summary.get("name"),
+            "node": node_name,
+            "status": summary.get("status", "unknown"),
+            "cpu_allocated": config.get("cores") or config.get("cpulimit"),
+            "ram_allocated_mb": config.get("memory"),
+            "swap_allocated_mb": config.get("swap"),
+            "cpu_usage_percent": round(float(summary.get("cpu", 0)) * 100, 2)
+            if summary.get("status") == "running"
+            else None,
+            "ram_usage_bytes": summary.get("mem")
+            if summary.get("status") == "running"
+            else None,
+            "rootfs": rootfs,
+            "mountpoints": mountpoints,
+            "networks": networks,
+            "os_template": config.get("ostype"),
+            "unprivileged": bool(config.get("unprivileged", 0)),
+            "tags": tags,
+            "description": config.get("description"),
+            "snapshots": snapshots,
+        }

invctl/collectors/firewall.py

@@ -0,0 +1,187 @@
+"""Firewall collector: cluster, node, and per-VM/CT rules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from invctl.collectors.base import BaseCollector
+
+
+class FirewallCollector(BaseCollector):
+    """Collect firewall configuration at every level of the hierarchy."""
+
+    def collect(self) -> dict[str, Any]:
+        """Return a FirewallInfo-compatible dict."""
+        try:
+            return self._collect()
+        except Exception as exc:
+            self._warn("firewall", exc)
+            return {"available": False, "error": str(exc)}
+
+    def _collect(self) -> dict[str, Any]:
+        cluster_opts = self._collect_cluster_options()
+        security_groups = self._collect_security_groups()
+        node_rules, vm_firewalls = self._collect_node_and_vm_rules()
+
+        return {
+            "available": True,
+            "cluster_enabled": cluster_opts.get("cluster_enabled", False),
+            "cluster_policy_in": cluster_opts.get("policy_in"),
+            "cluster_policy_out": cluster_opts.get("policy_out"),
+            "cluster_policy_forward": cluster_opts.get("policy_forward"),
+            "ebtables": cluster_opts.get("ebtables", False),
+            "security_groups": security_groups,
+            "node_rules": node_rules,
+            "vm_firewalls": vm_firewalls,
+        }
+
+    def _collect_cluster_options(self) -> dict[str, Any]:
+        try:
+            opts: dict[str, Any] = self.proxmox.cluster.firewall.options.get()
+            return {
+                "cluster_enabled": bool(opts.get("enable", 0)),
+                "policy_in": opts.get("policy_in"),
+                "policy_out": opts.get("policy_out"),
+                "policy_forward": opts.get("policy_forward"),
+                "ebtables": bool(opts.get("ebtables", 0)),
+            }
+        except Exception as exc:
+            self._warn("firewall.cluster.options", exc)
+            return {}
+
+    def _collect_security_groups(self) -> list[dict[str, Any]]:
+        groups: list[dict[str, Any]] = []
+        try:
+            raw_groups: list[dict[str, Any]] = self.proxmox.cluster.firewall.groups.get()
+        except Exception as exc:
+            self._warn("firewall.cluster.groups", exc)
+            return []
+
+        for g in raw_groups:
+            group_name = g.get("group", "")
+            rules: list[dict[str, Any]] = []
+            try:
+                raw_rules: list[dict[str, Any]] = (
+                    self.proxmox.cluster.firewall.groups(group_name).get()
+                )
+                rules = [_parse_rule(r) for r in raw_rules]
+            except Exception as exc:
+                self._warn(f"firewall.group.{group_name}.rules", exc)
+
+            groups.append(
+                {
+                    "name": group_name,
+                    "comment": g.get("comment"),
+                    "rules": rules,
+                }
+            )
+        return groups
+
+    def _collect_node_and_vm_rules(
+        self,
+    ) -> tuple[dict[str, list[dict[str, Any]]], list[dict[str, Any]]]:
+        node_rules: dict[str, list[dict[str, Any]]] = {}
+        vm_firewalls: list[dict[str, Any]] = []
+
+        try:
+            raw_nodes: list[dict[str, Any]] = self.proxmox.nodes.get()
+        except Exception as exc:
+            self._warn("firewall.nodes", exc)
+            return node_rules, vm_firewalls
+
+        for node in raw_nodes:
+            node_name: str = node.get("node", "")
+            if node.get("status") != "online":
+                continue
+
+            try:
+                raw_rules: list[dict[str, Any]] = (
+                    self.proxmox.nodes(node_name).firewall.rules.get()
+                )
+                node_rules[node_name] = [_parse_rule(r) for r in raw_rules]
+            except Exception as exc:
+                self._warn(f"firewall.{node_name}.rules", exc)
+
+            try:
+                vm_list: list[dict[str, Any]] = self.proxmox.nodes(node_name).qemu.get()
+                for vm in vm_list:
+                    vmid = vm.get("vmid")
+                    if vmid is None:
+                        continue
+                    try:
+                        fw = self._collect_vm_firewall(node_name, vmid, "qemu")
+                        vm_firewalls.append(fw)
+                    except Exception as exc:
+                        self._warn(f"firewall.{node_name}.qemu.{vmid}", exc)
+            except Exception as exc:
+                self._warn(f"firewall.{node_name}.vms", exc)
+
+            try:
+                ct_list: list[dict[str, Any]] = self.proxmox.nodes(node_name).lxc.get()
+                for ct in ct_list:
+                    vmid = ct.get("vmid")
+                    if vmid is None:
+                        continue
+                    try:
+                        fw = self._collect_vm_firewall(node_name, vmid, "lxc")
+                        vm_firewalls.append(fw)
+                    except Exception as exc:
+                        self._warn(f"firewall.{node_name}.lxc.{vmid}", exc)
+            except Exception as exc:
+                self._warn(f"firewall.{node_name}.cts", exc)
+
+        return node_rules, vm_firewalls
+
+    def _collect_vm_firewall(
+        self, node_name: str, vmid: int, vm_type: str
+    ) -> dict[str, Any]:
+        """Collect firewall options and rules for a single VM or container."""
+        api_node = self.proxmox.nodes(node_name)
+        vm_api = api_node.qemu(vmid) if vm_type == "qemu" else api_node.lxc(vmid)
+
+        policy_in: str | None = None
+        policy_out: str | None = None
+        enabled = False
+
+        try:
+            opts: dict[str, Any] = vm_api.firewall.options.get()
+            enabled = bool(opts.get("enable", 0))
+            policy_in = opts.get("policy_in")
+            policy_out = opts.get("policy_out")
+        except Exception as exc:
+            self._warn(f"firewall.{node_name}.{vm_type}.{vmid}.options", exc)
+
+        rules: list[dict[str, Any]] = []
+        try:
+            raw_rules: list[dict[str, Any]] = vm_api.firewall.rules.get()
+            rules = [_parse_rule(r) for r in raw_rules]
+        except Exception as exc:
+            self._warn(f"firewall.{node_name}.{vm_type}.{vmid}.rules", exc)
+
+        return {
+            "vmid": vmid,
+            "node": node_name,
+            "vm_type": vm_type,
+            "enabled": enabled,
+            "policy_in": policy_in,
+            "policy_out": policy_out,
+            "rules": rules,
+        }
+
+
+def _parse_rule(raw: dict[str, Any]) -> dict[str, Any]:
+    """Convert a raw Proxmox firewall rule dict to our schema."""
+    return {
+        "pos": raw.get("pos"),
+        "rule_type": raw.get("type"),
+        "action": raw.get("action"),
+        "source": raw.get("source"),
+        "dest": raw.get("dest"),
+        "proto": raw.get("proto"),
+        "dport": raw.get("dport"),
+        "sport": raw.get("sport"),
+        "comment": raw.get("comment"),
+        "enabled": bool(raw.get("enable", 1)),
+        "macro": raw.get("macro"),
+        "iface": raw.get("iface"),
+    }