servchart-agent 0.2.0__py3-none-any.whl

servchart_agent/__init__.py

@@ -0,0 +1,4 @@
+"""ServChart agent: reads Docker state on one host and reports it to a ServChart hub."""
+
+__version__ = "0.2.0"
+SCHEMA_VERSION = 1

servchart_agent/__main__.py

@@ -0,0 +1,108 @@
+"""ServChart agent entry point.
+
+    python -m servchart_agent --hub https://servchart.example.com --token sc_xxx
+    python -m servchart_agent --stdout          # print one snapshot and exit
+
+Every option can also be set with an environment variable (shown in --help).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import ssl
+import sys
+import time
+import urllib.error
+import urllib.request
+
+from . import __version__
+from .collect import collect
+from .docker_api import DockerClient, DockerError
+
+log = logging.getLogger("servchart.agent")
+
+
+def push(snapshot: dict, hub: str, token: str, ca_file: str | None = None, insecure: bool = False) -> None:
+    url = hub.rstrip("/") + "/api/v1/report"
+    data = json.dumps(snapshot).encode()
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+            "User-Agent": f"servchart-agent/{__version__}",
+        },
+    )
+    ctx = None
+    if url.startswith("https://"):
+        ctx = ssl.create_default_context(cafile=ca_file) if ca_file else ssl.create_default_context()
+        if insecure:
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+    with urllib.request.urlopen(req, timeout=20, context=ctx) as resp:
+        if resp.status >= 300:
+            raise RuntimeError(f"hub answered HTTP {resp.status}")
+
+
+def parse_args(argv=None):
+    env = os.environ.get
+    p = argparse.ArgumentParser(prog="servchart-agent", description="Report this host's Docker state to a ServChart hub.")
+    p.add_argument("--hub", default=env("SERVCHART_HUB"), help="Hub URL (env SERVCHART_HUB)")
+    p.add_argument("--token", default=env("SERVCHART_TOKEN"), help="Host token from the hub (env SERVCHART_TOKEN)")
+    p.add_argument("--interval", type=int, default=int(env("SERVCHART_INTERVAL", "60")),
+                   help="Seconds between reports (env SERVCHART_INTERVAL, default 60)")
+    p.add_argument("--hostname", default=env("SERVCHART_HOSTNAME"),
+                   help="Override the reported host name (env SERVCHART_HOSTNAME)")
+    p.add_argument("--ca-file", default=env("SERVCHART_CA_FILE"), help="CA bundle for a self-signed hub (env SERVCHART_CA_FILE)")
+    p.add_argument("--insecure", action="store_true", default=env("SERVCHART_INSECURE") == "1",
+                   help="Skip TLS verification (env SERVCHART_INSECURE=1). Not recommended.")
+    p.add_argument("--once", action="store_true", help="Report once and exit")
+    p.add_argument("--stdout", action="store_true", help="Print the snapshot as JSON instead of sending it")
+    p.add_argument("--version", action="version", version=f"servchart-agent {__version__}")
+    return p.parse_args(argv)
+
+
+def main(argv=None) -> int:
+    logging.basicConfig(level=os.environ.get("SERVCHART_LOG_LEVEL", "INFO"),
+                        format="%(asctime)s %(levelname)s %(message)s")
+    args = parse_args(argv)
+    client = DockerClient()
+
+    if args.stdout:
+        json.dump(collect(client, args.hostname), sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return 0
+
+    if not args.hub or not args.token:
+        log.error("--hub and --token are required (or SERVCHART_HUB / SERVCHART_TOKEN)")
+        return 2
+
+    log.info("servchart-agent %s reporting to %s every %ss", __version__, args.hub, args.interval)
+    backoff = 0
+    while True:
+        try:
+            snap = collect(client, args.hostname)
+            push(snap, args.hub, args.token, args.ca_file, args.insecure)
+            log.info("reported %d containers, %d networks", len(snap["containers"]), len(snap["networks"]))
+            backoff = 0
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 403):
+                log.error("hub rejected the token (HTTP %s) - check SERVCHART_TOKEN", exc.code)
+            else:
+                log.warning("hub error: HTTP %s", exc.code)
+            backoff = min(max(backoff * 2, args.interval), 900)
+        except (DockerError, OSError, RuntimeError) as exc:
+            log.warning("report failed: %s", exc)
+            backoff = min(max(backoff * 2, args.interval), 900)
+        if args.once:
+            return 0 if backoff == 0 else 1
+        time.sleep(backoff or args.interval)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

servchart_agent/collect.py

@@ -0,0 +1,170 @@
+"""Build a sanitized inventory snapshot of one Docker host.
+
+Privacy rules (enforced here, before anything leaves the host):
+  * Container environment variables (Config.Env) are never read into the snapshot.
+  * Command lines / entrypoint arguments are dropped (they often carry secrets).
+  * Label values whose key looks secret-ish are replaced with "[redacted]".
+  * Bind-mount source paths are kept (they are useful for the map) but can be
+    hidden entirely with SERVCHART_HIDE_PATHS=1.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from datetime import datetime, timezone
+
+from . import SCHEMA_VERSION, __version__
+from .docker_api import DockerClient
+
+SECRET_KEY_RE = re.compile(r"(pass|secret|token|key|auth|credential|cookie|private)", re.IGNORECASE)
+REDACTED = "[redacted]"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def sanitize_labels(labels: dict | None) -> dict:
+    out = {}
+    for key, value in (labels or {}).items():
+        out[key] = REDACTED if SECRET_KEY_RE.search(key) else value
+    return out
+
+
+def _ports(inspect: dict) -> list[dict]:
+    """One entry per (private port, protocol, public port); host IPs are merged.
+
+    Docker reports IPv4 and IPv6 bindings of the same port separately; the map
+    only needs to know the port is published and on which addresses.
+    """
+    merged: dict[tuple, dict] = {}
+    bindings = (inspect.get("NetworkSettings") or {}).get("Ports") or {}
+    for spec, published in bindings.items():
+        private, _, proto = spec.partition("/")
+        proto = proto or "tcp"
+        for b in published or [None]:
+            public = int(b["HostPort"]) if b and b.get("HostPort") else None
+            entry = merged.setdefault(
+                (int(private), proto, public),
+                {"private": int(private), "protocol": proto, "public": public, "ips": []},
+            )
+            ip = (b or {}).get("HostIp")
+            if ip and ip not in entry["ips"]:
+                entry["ips"].append(ip)
+    return [merged[k] for k in sorted(merged, key=lambda k: (k[0], k[1], k[2] or 0))]
+
+
+def _mounts(inspect: dict, hide_paths: bool) -> list[dict]:
+    mounts = []
+    for m in inspect.get("Mounts") or []:
+        kind = m.get("Type")
+        if kind == "volume":
+            source = m.get("Name")
+        elif hide_paths:
+            source = None
+        else:
+            source = m.get("Source")
+        mounts.append(
+            {"type": kind, "source": source, "destination": m.get("Destination"), "rw": bool(m.get("RW"))}
+        )
+    return mounts
+
+
+def _networks(inspect: dict) -> list[dict]:
+    nets = []
+    for name, cfg in sorted(((inspect.get("NetworkSettings") or {}).get("Networks") or {}).items()):
+        cfg = cfg or {}
+        nets.append(
+            {
+                "name": name,
+                "ip": cfg.get("IPAddress") or None,
+                "aliases": sorted(set(cfg.get("Aliases") or []) - {inspect.get("Id", "")[:12]}),
+            }
+        )
+    return nets
+
+
+def compose_info(labels: dict, hide_paths: bool = False) -> dict:
+    """Which Compose stack a container belongs to, and the folder/files it was started from.
+
+    Docker Compose stamps every container with these labels, so no access to the
+    compose files themselves is needed. Portainer and Dockge stacks use Compose too.
+    """
+    config_files = labels.get("com.docker.compose.project.config_files") or ""
+    return {
+        "project": labels.get("com.docker.compose.project"),
+        "service": labels.get("com.docker.compose.service"),
+        "working_dir": None if hide_paths else labels.get("com.docker.compose.project.working_dir"),
+        "config_files": [] if hide_paths else [f for f in config_files.split(",") if f],
+    }
+
+
+def container_record(inspect: dict, hide_paths: bool = False) -> dict:
+    """Convert a `docker inspect` document into a sanitized ServChart record.
+
+    Deliberately whitelists fields instead of copying the document, so new
+    Docker fields (or Env) can never leak by accident.
+    """
+    config = inspect.get("Config") or {}
+    state = inspect.get("State") or {}
+    host_config = inspect.get("HostConfig") or {}
+    labels = config.get("Labels") or {}
+    health = (state.get("Health") or {}).get("Status")
+    return {
+        "id": (inspect.get("Id") or "")[:12],
+        "name": (inspect.get("Name") or "").lstrip("/"),
+        "image": config.get("Image"),
+        "state": state.get("Status"),
+        "health": health,
+        "started_at": state.get("StartedAt"),
+        "restart_policy": (host_config.get("RestartPolicy") or {}).get("Name") or None,
+        "network_mode": host_config.get("NetworkMode"),
+        "compose": compose_info(labels, hide_paths),
+        "labels": sanitize_labels(labels),
+        "networks": _networks(inspect),
+        "ports": _ports(inspect),
+        "mounts": _mounts(inspect, hide_paths),
+    }
+
+
+def network_record(net: dict) -> dict:
+    ipam = (net.get("IPAM") or {}).get("Config") or []
+    return {
+        "id": (net.get("Id") or "")[:12],
+        "name": net.get("Name"),
+        "driver": net.get("Driver"),
+        "scope": net.get("Scope"),
+        "internal": bool(net.get("Internal")),
+        "subnets": [c.get("Subnet") for c in ipam if c.get("Subnet")],
+    }
+
+
+def collect(client: DockerClient | None = None, hostname: str | None = None) -> dict:
+    client = client or DockerClient()
+    hide_paths = os.environ.get("SERVCHART_HIDE_PATHS", "0") == "1"
+    info = client.info()
+    version = client.version()
+    containers = []
+    for summary in client.containers():
+        try:
+            containers.append(container_record(client.inspect_container(summary["Id"]), hide_paths))
+        except Exception:  # container vanished between list and inspect
+            continue
+    networks = [network_record(n) for n in client.networks()]
+    return {
+        "schema": SCHEMA_VERSION,
+        "agent_version": __version__,
+        "collected_at": _now(),
+        "host": {
+            "hostname": hostname or os.environ.get("SERVCHART_HOSTNAME") or info.get("Name"),
+            "os": info.get("OperatingSystem"),
+            "kernel": info.get("KernelVersion"),
+            "arch": info.get("Architecture"),
+            "cpus": info.get("NCPU"),
+            "memory_bytes": info.get("MemTotal"),
+            "docker_version": version.get("Version"),
+        },
+        "containers": sorted(containers, key=lambda c: c["name"]),
+        "networks": sorted(networks, key=lambda n: n["name"] or ""),
+    }

servchart_agent/docker_api.py

@@ -0,0 +1,83 @@
+"""Minimal, dependency-free, read-only client for the Docker Engine API.
+
+Only GET requests are ever issued. Supports unix sockets (default) and plain
+TCP (e.g. a docker-socket-proxy sidecar) via the standard DOCKER_HOST variable.
+"""
+
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import socket
+from urllib.parse import quote, urlparse
+
+DEFAULT_DOCKER_HOST = "unix:///var/run/docker.sock"
+
+
+class DockerError(RuntimeError):
+    pass
+
+
+class _UnixHTTPConnection(http.client.HTTPConnection):
+    def __init__(self, socket_path: str, timeout: float = 10.0):
+        super().__init__("localhost", timeout=timeout)
+        self.socket_path = socket_path
+
+    def connect(self) -> None:  # pragma: no cover - exercised against a real daemon
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.settimeout(self.timeout)
+        sock.connect(self.socket_path)
+        self.sock = sock
+
+
+class DockerClient:
+    """Read-only Docker Engine API client."""
+
+    def __init__(self, docker_host: str | None = None, timeout: float = 10.0):
+        self.docker_host = docker_host or os.environ.get("DOCKER_HOST") or DEFAULT_DOCKER_HOST
+        self.timeout = timeout
+        parsed = urlparse(self.docker_host)
+        if parsed.scheme == "unix":
+            self._target = ("unix", parsed.path)
+        elif parsed.scheme in ("tcp", "http"):
+            self._target = ("tcp", (parsed.hostname or "localhost", parsed.port or 2375))
+        else:
+            raise DockerError(f"Unsupported DOCKER_HOST scheme: {self.docker_host!r} (use unix:// or tcp://)")
+
+    def _connection(self) -> http.client.HTTPConnection:
+        kind, target = self._target
+        if kind == "unix":
+            return _UnixHTTPConnection(target, timeout=self.timeout)
+        host, port = target
+        return http.client.HTTPConnection(host, port, timeout=self.timeout)
+
+    def get(self, path: str):
+        conn = self._connection()
+        try:
+            conn.request("GET", path, headers={"Accept": "application/json"})
+            resp = conn.getresponse()
+            body = resp.read()
+        except OSError as exc:
+            raise DockerError(f"Cannot reach Docker at {self.docker_host}: {exc}") from exc
+        finally:
+            conn.close()
+        if resp.status >= 400:
+            raise DockerError(f"Docker API GET {path} -> HTTP {resp.status}: {body[:200]!r}")
+        return json.loads(body or b"null")
+
+    # Convenience wrappers -------------------------------------------------
+    def info(self):
+        return self.get("/info")
+
+    def version(self):
+        return self.get("/version")
+
+    def containers(self):
+        return self.get("/containers/json?all=1")
+
+    def inspect_container(self, container_id: str):
+        return self.get(f"/containers/{quote(container_id)}/json")
+
+    def networks(self):
+        return self.get("/networks")

servchart_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: servchart-agent
+Version: 0.2.0
+Summary: ServChart agent: reports a host's Docker containers, networks and Compose stacks to a ServChart hub.
+Project-URL: Homepage, https://github.com/opticodev/servchart
+Project-URL: Issues, https://github.com/opticodev/servchart/issues
+Author: OptiCoDev
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docker,homelab,infrastructure,monitoring,self-hosted,topology
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# servchart-agent
+
+The agent for [ServChart](https://github.com/opticodev/servchart), a self-hosted map of your servers, containers and Compose stacks.
+
+It reads this host's Docker state (GET requests only), drops anything sensitive, and sends it to your ServChart hub every 60 seconds. It has no dependencies beyond Python's standard library.
+
+## Run it
+
+**With Docker** (recommended):
+
+```bash
+docker run -d --name servchart-agent --restart unless-stopped \
+  -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -e SERVCHART_HUB=https://servchart.example.com \
+  -e SERVCHART_TOKEN=sc_... \
+  opticodev/servchart-agent:latest
+```
+
+**Without Docker**, from PyPI. The user running it needs access to the Docker socket, for example by being in the `docker` group:
+
+```bash
+pipx install servchart-agent        # or: pip install servchart-agent
+servchart-agent --hub https://servchart.example.com --token sc_...
+servchart-agent --stdout            # print what would be sent, send nothing
+```
+
+Get the token from the hub: **+ Add host** in the map.
+
+## What it sends
+
+It sends container names, images, state and health, networks and IPs, published ports, mounts, restart policy, and Compose stack details (project, service, folder, compose files). It **never** sends environment variables or container commands, and secret-looking label values are redacted. Set `SERVCHART_HIDE_PATHS=1` to also drop host paths and stack folders.
+
+All options are in the [main README](https://github.com/opticodev/servchart#agent).

servchart_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+servchart_agent/__init__.py,sha256=9Zd5KB0SHiCdH4k9Kjzcq1H1vDnMIsZA2NdUT-ZQKhA,131
+servchart_agent/__main__.py,sha256=qkf4e9GeJvulSL70GVUilmADpB2rjzX8nmDrid_z2MI,4418
+servchart_agent/collect.py,sha256=aZ1CQbSmKUaVfsqH4iR7JPicj04rbGOnv_L19XNbX4M,6545
+servchart_agent/docker_api.py,sha256=FwZKGtJXRuDpCBHBkBA0-Fau_w2Flr2URuf-_k72YmI,2901
+servchart_agent-0.2.0.dist-info/METADATA,sha256=PHNg8D6OhTSsSw-_FbmQazQPstF5PT88QzvlvZuRq8Y,2335
+servchart_agent-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+servchart_agent-0.2.0.dist-info/entry_points.txt,sha256=3UWxVJcW8zzuYepv4WpeJJofPuiIt_36DQGtrBMB3wc,66
+servchart_agent-0.2.0.dist-info/licenses/LICENSE,sha256=kAQrAjhxxejwnDdhzTFv7HaAMeL250OOWcW-AlY_eHc,1066
+servchart_agent-0.2.0.dist-info/RECORD,,

servchart_agent-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

servchart_agent-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+servchart-agent = servchart_agent.__main__:main

servchart_agent-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OptiCoDev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.