servchart-agent 0.2.0__tar.gz → 0.3.0__tar.gz

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: servchart-agent
-Version: 0.2.0
+Version: 0.3.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
@@ -29,8 +29,9 @@ It reads this host's Docker state (GET requests only), drops anything sensitive,
 **With Docker** (recommended):
 
 ```bash
-docker run -d --name servchart-agent --restart unless-stopped \
+docker run -d --name servchart-agent --restart unless-stopped --pid host \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -e SERVCHART_OBSERVE_CONNECTIONS=1 \
   -e SERVCHART_HUB=https://servchart.example.com \
   -e SERVCHART_TOKEN=sc_... \
   opticodev/servchart-agent:latest

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/README.md

@@ -9,8 +9,9 @@ It reads this host's Docker state (GET requests only), drops anything sensitive,
 **With Docker** (recommended):
 
 ```bash
-docker run -d --name servchart-agent --restart unless-stopped \
+docker run -d --name servchart-agent --restart unless-stopped --pid host \
   -v /var/run/docker.sock:/var/run/docker.sock:ro \
+  -e SERVCHART_OBSERVE_CONNECTIONS=1 \
   -e SERVCHART_HUB=https://servchart.example.com \
   -e SERVCHART_TOKEN=sc_... \
   opticodev/servchart-agent:latest

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/servchart_agent/__init__.py

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

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/servchart_agent/__main__.py

@@ -18,35 +18,44 @@ import time
 import urllib.error
 import urllib.request
 
-from . import __version__
+from . import __version__, commands
 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__}",
-        },
-    )
+def hub_request(hub: str, token: str, ca_file: str | None = None, insecure: bool = False):
+    """Returns request(method, path, body) -> parsed JSON, bound to this hub and token."""
     ctx = None
-    if url.startswith("https://"):
+    if hub.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 request(method: str, path: str, body):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            hub.rstrip("/") + path,
+            data=data,
+            method=method,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Authorization": f"Bearer {token}",
+                "User-Agent": f"servchart-agent/{__version__}",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=20, context=ctx) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else None
+
+    return request
+
+
+def push(snapshot: dict, hub: str, token: str, ca_file: str | None = None, insecure: bool = False) -> None:
+    hub_request(hub, token, ca_file, insecure)("POST", "/api/v1/report", snapshot)
 
 
 def parse_args(argv=None):
@@ -83,6 +92,8 @@ def main(argv=None) -> int:
         return 2
 
     log.info("servchart-agent %s reporting to %s every %ss", __version__, args.hub, args.interval)
+    if not args.once:
+        commands.start(client, hub_request(args.hub, args.token, args.ca_file, args.insecure))
     backoff = 0
     while True:
         try:

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/servchart_agent/collect.py

@@ -15,6 +15,7 @@ import re
 from datetime import datetime, timezone
 
 from . import SCHEMA_VERSION, __version__
+from . import connections as conn
 from .docker_api import DockerClient
 
 SECRET_KEY_RE = re.compile(r"(pass|secret|token|key|auth|credential|cookie|private)", re.IGNORECASE)
@@ -97,9 +98,20 @@ def compose_info(labels: dict, hide_paths: bool = False) -> dict:
         "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],
+        "depends_on": parse_depends_on(labels.get("com.docker.compose.depends_on")),
     }
 
 
+def parse_depends_on(value: str | None) -> list[str]:
+    """Compose (v2.17+) stores depends_on as "db:service_healthy:false,redis:service_started:false"."""
+    services = []
+    for item in (value or "").split(","):
+        name = item.split(":", 1)[0].strip()
+        if name and name not in services:
+            services.append(name)
+    return services
+
+
 def container_record(inspect: dict, hide_paths: bool = False) -> dict:
     """Convert a `docker inspect` document into a sanitized ServChart record.
 
@@ -119,6 +131,7 @@ def container_record(inspect: dict, hide_paths: bool = False) -> dict:
         "health": health,
         "started_at": state.get("StartedAt"),
         "restart_policy": (host_config.get("RestartPolicy") or {}).get("Name") or None,
+        "restart_count": inspect.get("RestartCount") or 0,
         "network_mode": host_config.get("NetworkMode"),
         "compose": compose_info(labels, hide_paths),
         "labels": sanitize_labels(labels),
@@ -140,31 +153,85 @@ def network_record(net: dict) -> dict:
     }
 
 
+def observe_enabled() -> bool:
+    return os.environ.get("SERVCHART_OBSERVE_CONNECTIONS", "0").lower() in ("1", "true", "yes", "on")
+
+
 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"
+    include_public = os.environ.get("SERVCHART_OBSERVE_PUBLIC", "0") == "1"
     info = client.info()
     version = client.version()
-    containers = []
+
+    inspected = []
     for summary in client.containers():
         try:
-            containers.append(container_record(client.inspect_container(summary["Id"]), hide_paths))
+            inspected.append(client.inspect_container(summary["Id"]))
         except Exception:  # container vanished between list and inspect
             continue
+    containers = [container_record(i, hide_paths) for i in inspected]
     networks = [network_record(n) for n in client.networks()]
-    return {
+
+    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"),
+        "observe": "off",
+        # on-demand log viewing, opt-in per host (SERVCHART_ALLOW_LOGS=1)
+        "logs": "on" if os.environ.get("SERVCHART_ALLOW_LOGS", "0").lower() in ("1", "true", "yes", "on") else "off",
+    }
+    snapshot = {
         "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 ""),
+        "host": host,
+        "containers": containers,
+        "networks": networks,
     }
+
+    # The host's own addresses let the hub resolve other hosts' connections to this one.
+    # Readable only when we see the host's /proc (native, or --pid host); else SERVCHART_HOST_IPS.
+    subnets = [s for n in networks for s in n.get("subnets") or []]
+    host["ips"] = conn.host_ips(subnets) if conn.observe_available() else conn.host_ips_from_env()
+
+    if observe_enabled():
+        if conn.observe_available():
+            observe(snapshot, inspected, include_public)
+        else:
+            host["observe"] = "unavailable"  # needs --pid host when running in a container
+
+    snapshot["containers"] = sorted(containers, key=lambda c: c["name"])
+    snapshot["networks"] = sorted(networks, key=lambda n: n["name"] or "")
+    return snapshot
+
+
+def observe(snapshot: dict, inspected: list[dict], include_public: bool = False) -> None:
+    """Add observed outbound connections to each container and to the host itself."""
+    host = snapshot["host"]
+    container_ips = {n["ip"] for c in snapshot["containers"] for n in c["networks"] if n.get("ip")}
+    by_name = {c["name"]: c for c in snapshot["containers"]}
+    read = 0
+    for doc in inspected:
+        rec = by_name.get((doc.get("Name") or "").lstrip("/"))
+        state = doc.get("State") or {}
+        mode = (doc.get("HostConfig") or {}).get("NetworkMode") or ""
+        # host-mode containers share the host's table (reported below); container:X shares X's.
+        if not rec or not state.get("Running") or mode == "host" or mode.startswith("container:"):
+            continue
+        rows = conn.read_netns(state.get("Pid") or 0)
+        if rows is None:
+            continue
+        read += 1
+        own_ips = {n["ip"] for n in rec["networks"] if n.get("ip")}
+        rec["connections"] = conn.outbound(rows, exclude_ips=own_ips, include_public=include_public)
+        rec["listening"] = conn.listening_ports(rows)
+    host_rows = conn.read_netns(1)
+    if host_rows is not None:
+        # skip host -> own containers: that's Docker's port forwarding, not an application talking
+        snapshot["host_connections"] = conn.outbound(host_rows, exclude_ips=container_ips | set(host.get("ips") or []), include_public=include_public)
+    host["observe"] = "on" if (read or host_rows is not None) else "unavailable"

servchart_agent-0.3.0/servchart_agent/commands.py

@@ -0,0 +1,67 @@
+"""Hub -> agent requests (currently: "show me this container's logs").
+
+The agent never accepts inbound connections. Instead, when logs are allowed
+(SERVCHART_ALLOW_LOGS=1), a background thread asks the hub every few seconds whether an
+admin is waiting for something, does it, and posts the answer back. Each request is
+re-checked here: only known request types, only containers that exist on this host.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+
+from . import logs as logs_mod
+
+log = logging.getLogger("servchart.agent.commands")
+
+
+def logs_allowed() -> bool:
+    return os.environ.get("SERVCHART_ALLOW_LOGS", "0").lower() in ("1", "true", "yes", "on")
+
+
+def handle(client, command: dict) -> dict:
+    """Run one command; returns the result payload (never raises)."""
+    kind = command.get("type")
+    try:
+        if kind == "logs":
+            if not logs_allowed():
+                return {"ok": False, "error": "Logs are disabled on this host (SERVCHART_ALLOW_LOGS=0)."}
+            name = str(command.get("container") or "")
+            known = {(c.get("Names") or [""])[0].lstrip("/") for c in client.containers()}
+            if name not in known:
+                return {"ok": False, "error": f"No container named {name!r} on this host."}
+            since = command.get("since")
+            return {"ok": True, "result": logs_mod.fetch(client, name, tail=command.get("tail") or 200, since=int(since) if since else None)}
+        return {"ok": False, "error": f"Unknown request type {kind!r}."}
+    except Exception as exc:  # report the failure to the admin instead of dying
+        log.warning("command %s failed: %s", command.get("id"), exc)
+        return {"ok": False, "error": str(exc)[:500]}
+
+
+def loop(client, request, interval: float = 3.0, stop: threading.Event | None = None) -> None:
+    """Poll the hub for commands until `stop` is set. `request(method, path, body)` does the HTTP."""
+    stop = stop or threading.Event()
+    backoff = 0.0
+    while not stop.is_set():
+        try:
+            pending = (request("GET", "/api/v1/agent/commands", None) or {}).get("commands") or []
+            for cmd in pending:
+                request("POST", f"/api/v1/agent/commands/{cmd['id']}/result", handle(client, cmd))
+            backoff = 0.0
+        except Exception as exc:
+            backoff = min(max(backoff * 2, interval * 2), 60.0)
+            log.debug("command poll failed: %s", exc)
+        stop.wait(backoff or interval)
+
+
+def start(client, request) -> threading.Thread | None:
+    if not logs_allowed():
+        return None
+    interval = float(os.environ.get("SERVCHART_COMMAND_POLL", "3"))
+    t = threading.Thread(target=loop, args=(client, request, interval), name="servchart-commands", daemon=True)
+    t.start()
+    log.info("log viewing enabled: checking the hub for requests every %ss", interval)
+    return t

servchart_agent-0.3.0/servchart_agent/connections.py

@@ -0,0 +1,164 @@
+"""Observed network connections ("who talks to whom"), read from the kernel's TCP tables.
+
+Every network namespace has its own /proc/<pid>/net/tcp{,6} - the same data `ss -tn`
+shows. Reading another container's table needs the host's /proc, so the agent must run
+with `--pid host` (or as a plain process on the host). This is opt-in:
+SERVCHART_OBSERVE_CONNECTIONS=1.
+
+What is reported, per container and for the host itself:
+  * outbound ESTABLISHED connections only (inbound ones are the other side's outbound),
+    aggregated to (destination IP, destination port, count) - no source ports, no payloads;
+  * private destinations only (RFC 1918, CGNAT/Tailscale 100.64/10, ULA fc00::/7) unless
+    SERVCHART_OBSERVE_PUBLIC=1, so the internet hosts your apps call never leave the host.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+import struct
+from collections import Counter
+
+PROC = os.environ.get("SERVCHART_PROC", "/proc")
+TCP_ESTABLISHED = "01"
+TCP_LISTEN = "0A"
+CGNAT = ipaddress.ip_network("100.64.0.0/10")
+MAX_PER_SOURCE = 200
+
+
+def _hex_to_ip(h: str) -> str:
+    if len(h) == 8:  # IPv4: one 32-bit word in host (little-endian) order
+        return socket.inet_ntop(socket.AF_INET, struct.pack("<I", int(h, 16)))
+    # IPv6: four 32-bit words, each in host order
+    raw = b"".join(struct.pack("<I", int(h[i : i + 8], 16)) for i in range(0, 32, 8))
+    addr = ipaddress.IPv6Address(raw)
+    return str(addr.ipv4_mapped) if addr.ipv4_mapped else str(addr)
+
+
+def parse_tcp_table(text: str) -> list[tuple[str, int, str, int, str]]:
+    """Parse /proc/net/tcp or tcp6 into (local_ip, local_port, remote_ip, remote_port, state)."""
+    rows = []
+    for line in text.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 4:
+            continue
+        try:
+            lip, lport = parts[1].split(":")
+            rip, rport = parts[2].split(":")
+            rows.append((_hex_to_ip(lip), int(lport, 16), _hex_to_ip(rip), int(rport, 16), parts[3].upper()))
+        except (ValueError, struct.error):
+            continue
+    return rows
+
+
+def read_netns(pid: int | str) -> list[tuple[str, int, str, int, str]] | None:
+    """TCP rows of the network namespace that process `pid` lives in, or None if unreadable."""
+    rows, ok = [], False
+    for name in ("tcp", "tcp6"):
+        try:
+            with open(f"{PROC}/{pid}/net/{name}") as fh:
+                rows.extend(parse_tcp_table(fh.read()))
+                ok = True
+        except OSError:
+            continue
+    return rows if ok else None
+
+
+def is_reportable(ip: str, include_public: bool = False) -> bool:
+    try:
+        addr = ipaddress.ip_address(ip)
+    except ValueError:
+        return False
+    if addr.is_loopback or addr.is_unspecified or addr.is_link_local or addr.is_multicast:
+        return False
+    if include_public:
+        return True
+    return addr.is_private or (addr.version == 4 and addr in CGNAT)
+
+
+def outbound(rows, exclude_ips=(), include_public: bool = False) -> list[dict]:
+    """Aggregate outbound established connections: [{"ip", "port", "count"}].
+
+    A connection is outbound when its local port isn't one this namespace listens on.
+    """
+    listening = {lport for _, lport, _, _, st in rows if st == TCP_LISTEN}
+    exclude = set(exclude_ips)
+    counts: Counter = Counter()
+    for _lip, lport, rip, rport, st in rows:
+        if st != TCP_ESTABLISHED or lport in listening:
+            continue
+        if rip in exclude or not is_reportable(rip, include_public):
+            continue
+        counts[(rip, rport)] += 1
+    out = [{"ip": ip, "port": port, "count": n} for (ip, port), n in counts.items()]
+    out.sort(key=lambda c: (-c["count"], c["ip"], c["port"]))
+    return out[:MAX_PER_SOURCE]
+
+
+def listening_ports(rows) -> list[int]:
+    return sorted({lport for lip, lport, _, _, st in rows if st == TCP_LISTEN and not lip.startswith("127.")})
+
+
+def host_ips(docker_subnets=()) -> list[str]:
+    """Addresses of the host itself (from the host's routing trie), minus Docker bridge gateways.
+
+    Docker bridge gateways (172.17.0.1, ...) exist on every host, so they would make
+    cross-host matching ambiguous; anything inside a Docker network subnet is dropped.
+    Extra addresses can be added with SERVCHART_HOST_IPS=ip1,ip2 (e.g. a public IP).
+    """
+    found = set()
+    try:
+        with open(f"{PROC}/1/net/fib_trie") as fh:
+            last = None
+            for line in fh:
+                s = line.strip()
+                if s.startswith("|--"):
+                    last = s[3:].strip()
+                elif "/32 host LOCAL" in s and last:
+                    found.add(last)
+    except OSError:
+        pass
+    nets = []
+    for sn in docker_subnets:
+        try:
+            nets.append(ipaddress.ip_network(sn, strict=False))
+        except ValueError:
+            continue
+    keep = set()
+    for ip in found:
+        try:
+            addr = ipaddress.ip_address(ip)
+        except ValueError:
+            continue
+        if addr.is_loopback or any(addr in n for n in nets if n.version == addr.version):
+            continue
+        keep.add(ip)
+    keep.update(host_ips_from_env())
+    return sorted(keep)
+
+
+def host_ips_from_env() -> list[str]:
+    return sorted({ip.strip() for ip in (os.environ.get("SERVCHART_HOST_IPS") or "").split(",") if ip.strip()})
+
+
+INIT_NAMES = {"systemd", "init", "runit", "openrc-init", "s6-svscan", "launchd"}
+
+
+def _in_container() -> bool:
+    return os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv")
+
+
+def observe_available() -> bool:
+    """True when this process sees the host's processes: run natively, or in a container with --pid host.
+
+    Without --pid host, PID 1 is the container's own entrypoint, and /proc/1/net would be
+    our own namespace - so it must never be mistaken for the host's.
+    """
+    if not _in_container():
+        return True
+    try:
+        with open(f"{PROC}/1/comm") as fh:
+            return fh.read().strip() in INIT_NAMES
+    except OSError:
+        return False

{servchart_agent-0.2.0 → servchart_agent-0.3.0}/servchart_agent/docker_api.py

@@ -52,19 +52,23 @@ class DockerClient:
         host, port = target
         return http.client.HTTPConnection(host, port, timeout=self.timeout)
 
-    def get(self, path: str):
+    def get_raw(self, path: str, limit: int | None = None) -> bytes:
+        """GET returning raw bytes (read at most `limit` bytes)."""
         conn = self._connection()
         try:
             conn.request("GET", path, headers={"Accept": "application/json"})
             resp = conn.getresponse()
-            body = resp.read()
+            body = resp.read(limit) if limit else 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")
+        return body
+
+    def get(self, path: str):
+        return json.loads(self.get_raw(path) or b"null")
 
     # Convenience wrappers -------------------------------------------------
     def info(self):
@@ -81,3 +85,9 @@ class DockerClient:
 
     def networks(self):
         return self.get("/networks")
+
+    def logs(self, container: str, tail: int = 200, since: int | None = None, limit: int = 2 * 1024 * 1024) -> bytes:
+        q = f"stdout=1&stderr=1&timestamps=1&tail={int(tail)}"
+        if since:
+            q += f"&since={int(since)}"
+        return self.get_raw(f"/containers/{quote(container)}/logs?{q}", limit=limit)

servchart_agent-0.3.0/servchart_agent/logs.py

@@ -0,0 +1,87 @@
+"""On-demand container logs, for the hub's log viewer.
+
+Opt-in per host with SERVCHART_ALLOW_LOGS=1. Logs are read only when an admin asks for
+them in the hub, are capped (lines and bytes), and pass through a redaction step that
+masks the most common secret patterns before leaving the host. Redaction is best effort -
+that's why the feature is off by default.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import struct
+
+MAX_LINES = 2000
+MAX_BYTES = 1024 * 1024  # what we send to the hub
+READ_LIMIT = 4 * 1024 * 1024  # what we read from Docker
+
+# (pattern, replacement) - replacements keep the key so lines stay readable
+REDACT_RULES = [
+    # key=value / key: value where the key looks secret
+    (re.compile(r"(?i)\b([\w.-]*(?:pass(?:word|wd)?|secret|token|api[_-]?key|access[_-]?key|private[_-]?key)[\w.-]*[\"']?\s*[=:]\s*)(\"[^\"]*\"|'[^']*'|[^\s,;&\"']+)"),
+     r"\1[redacted]"),
+    # Authorization headers
+    (re.compile(r"(?i)\b(authorization\s*[:=]\s*(?:bearer|basic|token)\s+)[A-Za-z0-9._~+/=-]+"), r"\1[redacted]"),
+    # credentials in URLs: scheme://user:pass@host
+    (re.compile(r"(\b[a-z][a-z0-9+.-]*://[^\s:/@]+:)[^\s@/]+@"), r"\1[redacted]@"),
+    # JSON Web Tokens
+    (re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}"), "[redacted-jwt]"),
+]
+
+
+def redaction_enabled() -> bool:
+    return os.environ.get("SERVCHART_LOGS_REDACT", "1").lower() not in ("0", "false", "no", "off")
+
+
+def redact(line: str) -> str:
+    for pattern, replacement in REDACT_RULES:
+        line = pattern.sub(replacement, line)
+    return line
+
+
+def demux(raw: bytes, tty: bool) -> list[tuple[str, str]]:
+    """Split Docker's log stream into (stream, line).
+
+    Without a TTY, Docker multiplexes stdout/stderr in frames:
+    [stream(1) 0 0 0 size(4, big-endian)] payload.  With a TTY it's one raw stream.
+    """
+    if tty:
+        return [("out", ln) for ln in raw.decode("utf-8", "replace").splitlines()]
+    out, i = [], 0
+    buffers = {1: "", 2: ""}
+    while i + 8 <= len(raw):
+        stream, size = raw[i], struct.unpack(">I", raw[i + 4 : i + 8])[0]
+        chunk = raw[i + 8 : i + 8 + size].decode("utf-8", "replace")
+        i += 8 + size
+        key = 2 if stream == 2 else 1
+        text = buffers[key] + chunk
+        *lines, rest = text.split("\n")
+        buffers[key] = rest
+        out.extend(("err" if key == 2 else "out", ln) for ln in lines)
+    for key, rest in buffers.items():
+        if rest:
+            out.append(("err" if key == 2 else "out", rest))
+    return out
+
+
+def fetch(client, container: str, tail: int = 200, since: int | None = None) -> dict:
+    """Read, split, cap and redact a container's recent logs."""
+    tail = max(1, min(int(tail or 200), MAX_LINES))
+    info = client.inspect_container(container)
+    tty = bool((info.get("Config") or {}).get("Tty"))
+    raw = client.logs(info.get("Id") or container, tail=tail, since=since, limit=READ_LIMIT)
+    redact_on = redaction_enabled()
+    lines, size, truncated = [], 0, len(raw) >= READ_LIMIT
+    for stream, text in demux(raw, tty)[-tail:]:
+        ts, _, msg = text.partition(" ")
+        if not ts[:4].isdigit():
+            ts, msg = "", text  # line without a timestamp prefix
+        if redact_on:
+            msg = redact(msg)
+        size += len(msg) + 40
+        if size > MAX_BYTES:
+            truncated = True
+            break
+        lines.append({"t": ts, "s": stream, "m": msg})
+    return {"lines": lines, "truncated": truncated, "redacted": redact_on, "tty": tty}

servchart_agent-0.3.0/tests/test_connections.py

@@ -0,0 +1,132 @@
+import json
+import os
+import sys
+import tempfile
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from servchart_agent import collect as collect_mod  # noqa: E402
+from servchart_agent import connections as conn  # noqa: E402
+from servchart_agent.collect import collect, parse_depends_on  # noqa: E402
+
+HEADER = "  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode\n"
+# 10.18.0.2 is the container. Hex addresses are little-endian 32-bit words, ports big-endian.
+TCP = HEADER + "\n".join(
+    [
+        "   0: 00000000:0050 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 1",  # LISTEN :80
+        "   1: 0200120A:9C40 0500120A:0CEA 01 00000000:00000000 00:00000000 00000000     0        0 2",  # -> 10.18.0.5:3306
+        "   2: 0200120A:9C44 0500120A:0CEA 01 00000000:00000000 00:00000000 00000000     0        0 3",  # -> same again
+        "   3: 0200120A:0050 0900120A:A000 01 00000000:00000000 00:00000000 00000000     0        0 4",  # inbound to :80
+        "   4: 0200120A:9C41 08080808:01BB 01 00000000:00000000 00:00000000 00000000     0        0 5",  # -> 8.8.8.8:443 (public)
+        "   5: 0100007F:9C42 0100007F:1F90 01 00000000:00000000 00:00000000 00000000     0        0 6",  # loopback
+        "   6: 0200120A:9C43 0600120A:18EB 06 00000000:00000000 00:00000000 00000000     0        0 7",  # TIME_WAIT
+    ]
+)
+# ::ffff:10.18.0.2 -> ::ffff:192.168.0.28:8484 established
+TCP6 = HEADER + "   0: 0000000000000000FFFF00000200120A:9C50 0000000000000000FFFF00001C00A8C0:2124 01 0 0 0 0 0 0 8\n"
+FIB_TRIE = """Main:
+  +-- 0.0.0.0/0 3 0 5
+     |-- 192.168.0.28
+        /32 host LOCAL
+     |-- 172.17.0.1
+        /32 host LOCAL
+     |-- 127.0.0.1
+        /32 host LOCAL
+"""
+
+
+class ParseTests(unittest.TestCase):
+    def test_parse_ipv4_and_mapped_ipv6(self):
+        rows = conn.parse_tcp_table(TCP) + conn.parse_tcp_table(TCP6)
+        self.assertIn(("10.18.0.2", 40000, "10.18.0.5", 3306, "01"), rows)
+        self.assertIn(("10.18.0.2", 40016, "192.168.0.28", 8484, "01"), rows)
+
+    def test_outbound_only_private_aggregated(self):
+        rows = conn.parse_tcp_table(TCP) + conn.parse_tcp_table(TCP6)
+        out = conn.outbound(rows, exclude_ips={"10.18.0.2"})
+        self.assertEqual(out, [{"ip": "10.18.0.5", "port": 3306, "count": 2}, {"ip": "192.168.0.28", "port": 8484, "count": 1}])
+
+    def test_public_opt_in(self):
+        rows = conn.parse_tcp_table(TCP)
+        self.assertIn({"ip": "8.8.8.8", "port": 443, "count": 1}, conn.outbound(rows, include_public=True))
+
+    def test_listening(self):
+        self.assertEqual(conn.listening_ports(conn.parse_tcp_table(TCP)), [80])
+
+    def test_cgnat_counts_as_private(self):
+        self.assertTrue(conn.is_reportable("100.101.1.2"))
+        self.assertFalse(conn.is_reportable("1.1.1.1"))
+
+    def test_depends_on_label(self):
+        self.assertEqual(parse_depends_on("db:service_healthy:false,redis:service_started:false,db:x:y"), ["db", "redis"])
+        self.assertEqual(parse_depends_on(None), [])
+
+
+class ObserveTests(unittest.TestCase):
+    """End to end: a fake /proc with one container namespace (pid 4242) and the host (pid 1)."""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        for pid, files in {"4242": {"tcp": TCP, "tcp6": TCP6}, "1": {"tcp": HEADER, "fib_trie": FIB_TRIE}}.items():
+            os.makedirs(f"{self.tmp.name}/{pid}/net")
+            for name, text in files.items():
+                with open(f"{self.tmp.name}/{pid}/net/{name}", "w") as fh:
+                    fh.write(text)
+        self.patches = [
+            mock.patch.object(conn, "PROC", self.tmp.name),
+            mock.patch.object(conn, "observe_available", return_value=True),
+            mock.patch.dict(os.environ, {"SERVCHART_OBSERVE_CONNECTIONS": "1"}),
+        ]
+        for p in self.patches:
+            p.start()
+
+    def tearDown(self):
+        for p in self.patches:
+            p.stop()
+        self.tmp.cleanup()
+
+    def test_snapshot_has_connections_and_host_ips(self):
+        class Client:
+            def info(self):
+                return {"Name": "docker-host"}
+
+            def version(self):
+                return {"Version": "29"}
+
+            def containers(self):
+                return [{"Id": "a"}]
+
+            def inspect_container(self, cid):
+                return {
+                    "Id": "a" * 12,
+                    "Name": "/web",
+                    "Config": {"Image": "nginx", "Env": ["SECRET=x"], "Labels": {}},
+                    "State": {"Status": "running", "Running": True, "Pid": 4242},
+                    "HostConfig": {"NetworkMode": "app_default"},
+                    "NetworkSettings": {"Networks": {"app_default": {"IPAddress": "10.18.0.2"}}},
+                }
+
+            def networks(self):
+                return [{"Name": "app_default", "IPAM": {"Config": [{"Subnet": "10.18.0.0/16"}]}},
+                        {"Name": "bridge", "IPAM": {"Config": [{"Subnet": "172.17.0.0/16"}]}}]
+
+        snap = collect(Client())
+        web = snap["containers"][0]
+        self.assertEqual(snap["host"]["observe"], "on")
+        self.assertEqual(snap["host"]["ips"], ["192.168.0.28"])  # docker gateway + loopback dropped
+        self.assertEqual([(c["ip"], c["port"]) for c in web["connections"]], [("10.18.0.5", 3306), ("192.168.0.28", 8484)])
+        self.assertEqual(web["listening"], [80])
+        self.assertEqual(snap["host_connections"], [])
+        self.assertNotIn("SECRET", json.dumps(snap))
+
+    def test_unavailable_without_pid_host(self):
+        with mock.patch.object(conn, "observe_available", return_value=False):
+            snap = collect_mod.collect(type("C", (), {
+                "info": lambda s: {"Name": "h"}, "version": lambda s: {}, "containers": lambda s: [], "networks": lambda s: []})())
+        self.assertEqual(snap["host"]["observe"], "unavailable")
+
+
+if __name__ == "__main__":
+    unittest.main()

servchart_agent-0.3.0/tests/test_logs.py

@@ -0,0 +1,110 @@
+import os
+import struct
+import sys
+import threading
+import unittest
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from servchart_agent import commands  # noqa: E402
+from servchart_agent import logs as logs_mod  # noqa: E402
+
+
+def frame(stream: int, text: str) -> bytes:
+    data = text.encode()
+    return bytes([stream, 0, 0, 0]) + struct.pack(">I", len(data)) + data
+
+
+RAW = (
+    frame(1, "2026-10-19T10:00:00.000000001Z starting web\n")
+    + frame(2, "2026-10-19T10:00:01.000000001Z WARN DB_PASSWORD=hunter2 rejected\n2026-10-19T10:00:02.0Z sec")
+    + frame(2, "ond line split across frames\n")
+    + frame(1, "2026-10-19T10:00:03.0Z GET /api 200\n")
+)
+
+
+class FakeClient:
+    def __init__(self, raw=RAW, tty=False):
+        self.raw, self.tty, self.calls = raw, tty, []
+
+    def containers(self):
+        return [{"Names": ["/web"]}, {"Names": ["/db"]}]
+
+    def inspect_container(self, name):
+        return {"Id": "abc123", "Config": {"Tty": self.tty}}
+
+    def logs(self, cid, tail=200, since=None, limit=None):
+        self.calls.append((cid, tail, since))
+        return self.raw
+
+
+class DemuxTests(unittest.TestCase):
+    def test_multiplexed_stream(self):
+        lines = logs_mod.demux(RAW, tty=False)
+        self.assertEqual([s for s, _ in lines], ["out", "err", "err", "out"])
+        self.assertTrue(lines[2][1].endswith("second line split across frames"))
+
+    def test_tty_stream(self):
+        lines = logs_mod.demux(b"2026-10-19T10:00:00Z hello\n2026-10-19T10:00:01Z world\n", tty=True)
+        self.assertEqual([m for _, m in lines], ["2026-10-19T10:00:00Z hello", "2026-10-19T10:00:01Z world"])
+
+
+class FetchTests(unittest.TestCase):
+    def test_fetch_splits_timestamp_and_redacts(self):
+        out = logs_mod.fetch(FakeClient(), "web", tail=50)
+        self.assertEqual(out["lines"][0], {"t": "2026-10-19T10:00:00.000000001Z", "s": "out", "m": "starting web"})
+        self.assertEqual(out["lines"][1]["m"], "WARN DB_PASSWORD=[redacted] rejected")
+        self.assertTrue(out["redacted"])
+
+    def test_redaction_can_be_turned_off(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_LOGS_REDACT": "0"}):
+            out = logs_mod.fetch(FakeClient(), "web")
+        self.assertIn("hunter2", out["lines"][1]["m"])
+
+    def test_tail_is_capped(self):
+        client = FakeClient()
+        logs_mod.fetch(client, "web", tail=999999)
+        self.assertEqual(client.calls[0][1], logs_mod.MAX_LINES)
+
+    def test_byte_cap(self):
+        big = b"".join(frame(1, f"2026-10-19T10:00:00Z {'x' * 900}\n") for _ in range(2000))
+        out = logs_mod.fetch(FakeClient(raw=big), "web", tail=2000)
+        self.assertTrue(out["truncated"])
+        self.assertLess(sum(len(l["m"]) for l in out["lines"]), logs_mod.MAX_BYTES)
+
+
+class CommandTests(unittest.TestCase):
+    def test_disabled_by_default(self):
+        with mock.patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("SERVCHART_ALLOW_LOGS", None)
+            self.assertFalse(commands.handle(FakeClient(), {"type": "logs", "container": "web"})["ok"])
+            self.assertIsNone(commands.start(FakeClient(), lambda *a: None))
+
+    def test_only_existing_containers_and_known_types(self):
+        with mock.patch.dict(os.environ, {"SERVCHART_ALLOW_LOGS": "1"}):
+            self.assertIn("No container", commands.handle(FakeClient(), {"type": "logs", "container": "../etc"})["error"])
+            self.assertIn("Unknown request", commands.handle(FakeClient(), {"type": "exec", "container": "web"})["error"])
+            ok = commands.handle(FakeClient(), {"type": "logs", "container": "web", "tail": 10})
+            self.assertTrue(ok["ok"])
+            self.assertEqual(len(ok["result"]["lines"]), 4)
+
+    def test_loop_polls_and_posts_results(self):
+        stop = threading.Event()
+        posted = []
+
+        def request(method, path, body):
+            if method == "GET":
+                return {"commands": [{"id": "r1", "type": "logs", "container": "web", "tail": 5}]}
+            posted.append((path, body))
+            stop.set()
+            return {"ok": True}
+
+        with mock.patch.dict(os.environ, {"SERVCHART_ALLOW_LOGS": "1"}):
+            commands.loop(FakeClient(), request, interval=0.01, stop=stop)
+        self.assertEqual(posted[0][0], "/api/v1/agent/commands/r1/result")
+        self.assertTrue(posted[0][1]["ok"])
+
+
+if __name__ == "__main__":
+    unittest.main()