chaintrace 0.1.0__py3-none-any.whl

chaintrace/probe.py

@@ -0,0 +1,71 @@
+"""A short read-only bpftrace program for one pid."""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+_TEMPLATE = """// Read-only trace for one process. Prints exec, connect, open, and chmod.
+// IPv4 connections only. IPv6 peers show up in `chaintrace status`.
+
+BEGIN
+{
+  printf("chaintrace probe\\n");
+}
+
+tracepoint:syscalls:sys_enter_execve
+/pid == __PID__/
+{
+  printf("exec %d %s %s\\n", pid, comm, str(args->filename));
+}
+
+tracepoint:syscalls:sys_enter_connect
+/pid == __PID__/
+{
+  $sa = args->uservaddr;
+  if ($sa->sa_family == 2) {
+    $port = ($sa->sa_data[0] << 8) | $sa->sa_data[1];
+    $v4 = (struct sockaddr_in *)args->uservaddr;
+    printf("connect %d %s %s %d\\n", pid, comm, ntop($v4->sin_addr.s_addr), $port);
+  }
+}
+
+tracepoint:syscalls:sys_enter_openat
+/pid == __PID__/
+{
+  printf("open %d %s %s\\n", pid, comm, str(args->filename));
+}
+
+tracepoint:syscalls:sys_enter_fchmodat
+/pid == __PID__/
+{
+  printf("chmod %d %s %s %d\\n", pid, comm, str(args->filename), args->mode);
+}
+
+interval:s:__SECONDS__
+{
+  exit();
+}
+"""
+
+
+def render_probe(pid: int, seconds: int) -> str:
+    if pid <= 0:
+        raise ValueError("pid must be positive")
+    if seconds < 1 or seconds > 300:
+        raise ValueError("seconds must be from 1 to 300")
+    return _TEMPLATE.replace("__PID__", str(pid)).replace("__SECONDS__", str(seconds))
+
+
+def unavailable(seconds_ok: bool = True) -> str | None:
+    if shutil.which("bpftrace") is None:
+        return "bpftrace is not installed"
+    try:
+        euid = os.geteuid()
+    except AttributeError:
+        return "bpftrace needs Linux"
+    if euid != 0:
+        return "bpftrace needs root"
+    if not seconds_ok:
+        return "seconds must be from 1 to 300"
+    return None

chaintrace/procfs.py

@@ -0,0 +1,217 @@
+"""Read a /proc-shaped directory. File contents are never opened."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from chaintrace.clients import recognize
+from chaintrace.models import Child, Connection, Observation, OpenFile
+from chaintrace.net import RawSocket, connection_from_raw, parse_proc_net
+from chaintrace.redact import redact_argv
+
+_TABLES = ("tcp", "tcp6", "udp", "udp6")
+_STATE_WORDS = {
+    "R": "running",
+    "S": "sleeping",
+    "D": "disk",
+    "Z": "zombie",
+    "T": "stopped",
+    "t": "tracing",
+    "I": "idle",
+    "X": "dead",
+}
+_SENSITIVE = (
+    "jwtsecret",
+    "jwt.hex",
+    "keystore",
+    "utc--",
+    "nodekey",
+    "validator_keys",
+    "mnemonic",
+)
+
+
+class ProcError(ValueError):
+    """The process table could not be read."""
+
+
+def is_sensitive(path: str) -> bool:
+    lowered = path.lower()
+    return any(marker in lowered for marker in _SENSITIVE)
+
+
+def read_pid(proc_root: Path, pid: int) -> Observation:
+    root = Path(proc_root)
+    base = root / str(pid)
+    if not base.is_dir():
+        raise ProcError(f"pid {pid} is not in {root}")
+    comm = _read_comm(base)
+    exe = _read_exe(base)
+    cmdline = redact_argv(_read_cmdline(base))
+    letter, ppid, utime, stime, rss_pages = _read_stat(base / "stat")
+    client = recognize(comm, exe)
+    files = _open_files(base, comm)
+    inodes = _socket_inodes(base)
+    raw = _sockets(root, pid, inodes)
+    connections = tuple(connection_from_raw(item, client) for item in raw)
+    children = _children(root, pid)
+    for child in children:
+        child_base = root / str(child.pid)
+        files.extend(_open_files(child_base, child.comm))
+    files.sort(key=lambda item: (item.path, item.comm))
+    ordered = tuple(sorted(connections, key=lambda item: (item.kind, item.local, item.remote)))
+    return Observation(
+        pid=pid,
+        comm=comm,
+        client=client.name,
+        exe=exe,
+        state=_STATE_WORDS.get(letter, letter),
+        rss_bytes=rss_pages * _page_size(),
+        cpu_seconds=round((utime + stime) / _clk_tck(), 3),
+        ppid=ppid,
+        cmdline=cmdline,
+        files=tuple(files),
+        connections=ordered,
+        children=tuple(children),
+    )
+
+
+def find_pids(proc_root: Path, name: str) -> list[int]:
+    root = Path(proc_root)
+    if not root.is_dir():
+        raise ProcError(f"{root} is not a process table")
+    matches: list[int] = []
+    for entry in root.iterdir():
+        if not entry.name.isdigit() or not entry.is_dir():
+            continue
+        try:
+            comm = _read_comm(entry)
+            exe = _read_exe(entry)
+        except ProcError:
+            continue
+        if comm == name or Path(exe).name == name:
+            matches.append(int(entry.name))
+    return sorted(matches)
+
+
+def _read_comm(base: Path) -> str:
+    path = base / "comm"
+    try:
+        return path.read_text().strip()
+    except OSError as exc:
+        raise ProcError(f"cannot read {path}") from exc
+
+
+def _read_exe(base: Path) -> str:
+    link = base / "exe"
+    if not link.is_symlink() and not link.exists():
+        return ""
+    try:
+        return os.readlink(link)
+    except OSError as exc:
+        raise ProcError(f"cannot read {link}") from exc
+
+
+def _read_cmdline(base: Path) -> list[str]:
+    path = base / "cmdline"
+    if not path.is_file():
+        return []
+    raw = path.read_bytes().split(b"\0")
+    return [part.decode("utf-8", "replace") for part in raw if part]
+
+
+def _read_stat(path: Path) -> tuple[str, int, int, int, int]:
+    if not path.is_file():
+        raise ProcError(f"cannot read {path}")
+    text = path.read_text()
+    end = text.rfind(")")
+    if end < 0:
+        raise ProcError(f"bad stat line in {path}")
+    rest = text[end + 1 :].split()
+    if len(rest) < 22:
+        raise ProcError(f"short stat line in {path}")
+    return rest[0], int(rest[1]), int(rest[11]), int(rest[12]), int(rest[21])
+
+
+def _open_files(base: Path, comm: str) -> list[OpenFile]:
+    fd_dir = base / "fd"
+    if not fd_dir.is_dir():
+        return []
+    found: list[OpenFile] = []
+    for fd in fd_dir.iterdir():
+        try:
+            target = os.readlink(fd)
+        except OSError:
+            continue
+        if not target.startswith("/"):
+            continue
+        found.append(OpenFile(target, is_sensitive(target), comm))
+    return found
+
+
+def _socket_inodes(base: Path) -> set[str]:
+    fd_dir = base / "fd"
+    inodes: set[str] = set()
+    if not fd_dir.is_dir():
+        return inodes
+    for fd in fd_dir.iterdir():
+        try:
+            target = os.readlink(fd)
+        except OSError:
+            continue
+        if target.startswith("socket:[") and target.endswith("]"):
+            inodes.add(target[len("socket:[") : -1])
+    return inodes
+
+
+def _sockets(root: Path, pid: int, inodes: set[str]) -> list[RawSocket]:
+    if not inodes:
+        return []
+    found: list[RawSocket] = []
+    seen: set[str] = set()
+    for table in _TABLES:
+        protocol = "udp" if table.startswith("udp") else "tcp"
+        for path in (root / str(pid) / "net" / table, root / "net" / table):
+            if not path.is_file():
+                continue
+            for raw in parse_proc_net(path.read_text(), protocol):
+                if raw.inode in inodes and raw.inode not in seen:
+                    seen.add(raw.inode)
+                    found.append(raw)
+            break
+    return found
+
+
+def _children(root: Path, pid: int) -> list[Child]:
+    children: list[Child] = []
+    for entry in root.iterdir():
+        if not entry.name.isdigit() or int(entry.name) == pid or not entry.is_dir():
+            continue
+        stat = entry / "stat"
+        if not stat.is_file():
+            continue
+        try:
+            _letter, ppid, *_rest = _read_stat(stat)
+            comm = _read_comm(entry)
+            exe = _read_exe(entry)
+        except ProcError:
+            continue
+        if ppid == pid:
+            children.append(Child(int(entry.name), comm, exe))
+    children.sort(key=lambda child: child.pid)
+    return children
+
+
+def _page_size() -> int:
+    try:
+        return os.sysconf("SC_PAGE_SIZE") or 4096
+    except (ValueError, OSError):
+        return 4096
+
+
+def _clk_tck() -> int:
+    try:
+        return os.sysconf("SC_CLK_TCK") or 100
+    except (ValueError, OSError):
+        return 100

chaintrace/redact.py

@@ -0,0 +1,44 @@
+"""Hide password-style command arguments. Paths stay visible."""
+
+from __future__ import annotations
+
+import re
+
+_SECRET = re.compile(r"(password|mnemonic|privkey|private-key|privatekey|secret-key)", re.I)
+
+
+def redact_argv(argv: list[str]) -> tuple[str, ...]:
+    redacted: list[str] = []
+    hide_next = False
+    for arg in argv:
+        if hide_next:
+            redacted.append(arg if _is_path(arg) else "[redacted]")
+            hide_next = False
+            continue
+        name, sep, value = _split(arg)
+        if sep and _is_secret(name):
+            shown = value if _is_path(value) else "[redacted]"
+            redacted.append(f"{name}{sep}{shown}")
+            continue
+        redacted.append(arg)
+        if sep == "" and _is_secret(name):
+            hide_next = True
+    return tuple(redacted)
+
+
+def _split(arg: str) -> tuple[str, str, str]:
+    if "=" in arg and arg.startswith("-"):
+        name, value = arg.split("=", 1)
+        return name, "=", value
+    return arg, "", ""
+
+
+def _is_secret(name: str) -> bool:
+    flag = name.lstrip("-")
+    if "jwt" in flag.lower():
+        return False
+    return _SECRET.search(flag) is not None
+
+
+def _is_path(value: str) -> bool:
+    return value.startswith("/") or value.startswith("./") or value.startswith("../")

chaintrace/render.py

@@ -0,0 +1,117 @@
+"""Text, JSON, and markdown for one observation."""
+
+from __future__ import annotations
+
+import json
+
+from chaintrace.models import Finding, Observation
+
+_KIND_ORDER = {
+    "listen": 0,
+    "local": 1,
+    "peer": 2,
+    "expected": 3,
+    "remote": 4,
+    "unknown": 5,
+    "metadata": 6,
+}
+
+
+def render_status(obs: Observation) -> str:
+    lines = [f"client {obs.client}", f"pid {obs.pid}", f"comm {obs.comm}"]
+    if obs.exe:
+        lines.append(f"exe {obs.exe}")
+    if obs.state != "traced":
+        lines.append(f"state {obs.state}")
+        lines.append(f"rss {obs.rss_bytes}")
+        lines.append(f"cpu {obs.cpu_seconds:.1f}s")
+        lines.append(f"ppid {obs.ppid}")
+        if obs.cmdline:
+            lines.append("cmdline " + " ".join(obs.cmdline))
+        if obs.children:
+            for child in obs.children:
+                lines.append(f"child {child.pid} {child.comm} {child.exe or 'unknown'}")
+        else:
+            lines.append("child none")
+    for event in obs.events:
+        if event.kind == "exec":
+            lines.append(f"exec {event.path}")
+        elif event.kind == "chmod":
+            lines.append(f"chmod {event.path} {event.mode}")
+    if obs.files:
+        for item in obs.files:
+            mark = " sensitive" if item.sensitive else ""
+            lines.append(f"file {item.path} {item.comm}{mark}")
+    else:
+        lines.append("file none")
+    if obs.connections:
+        ordered = sorted(obs.connections, key=lambda item: (_KIND_ORDER.get(item.kind, 9), item.local, item.remote))
+        for conn in ordered:
+            if conn.kind == "listen" or conn.remote.endswith(":0"):
+                lines.append(f"{conn.kind} {conn.local} {conn.protocol}")
+            elif conn.local == "-":
+                lines.append(f"{conn.kind} {conn.remote} {conn.protocol}")
+            else:
+                lines.append(f"{conn.kind} {conn.local} {conn.remote} {conn.protocol}")
+    else:
+        lines.append("connection none")
+    return "\n".join(lines) + "\n"
+
+
+def render_findings(findings: list[Finding]) -> str:
+    if not findings:
+        return "ok\n"
+    lines = [f"{item.severity} {item.rule} {item.message}" for item in findings]
+    if all(item.severity == "info" for item in findings):
+        lines.append("ok")
+    return "\n".join(lines) + "\n"
+
+
+def render_check(obs: Observation, findings: list[Finding]) -> str:
+    return render_status(obs) + "\n" + render_findings(findings)
+
+
+def render_report(obs: Observation, findings: list[Finding]) -> str:
+    return (
+        "# ChainTrace\n\n"
+        "What this node is doing internally.\n\n"
+        "## Status\n\n"
+        "```\n"
+        f"{render_status(obs)}"
+        "```\n\n"
+        "## Findings\n\n"
+        "```\n"
+        f"{render_findings(findings)}"
+        "```\n"
+    )
+
+
+def render_json(obs: Observation, findings: list[Finding] | None = None) -> str:
+    body: dict[str, object] = {
+        "client": obs.client,
+        "pid": obs.pid,
+        "comm": obs.comm,
+        "exe": obs.exe,
+        "state": obs.state,
+        "rss_bytes": obs.rss_bytes,
+        "cpu_seconds": obs.cpu_seconds,
+        "ppid": obs.ppid,
+        "cmdline": list(obs.cmdline),
+        "children": [{"pid": child.pid, "comm": child.comm, "exe": child.exe} for child in obs.children],
+        "files": [{"path": item.path, "comm": item.comm, "sensitive": item.sensitive} for item in obs.files],
+        "connections": [
+            {
+                "kind": conn.kind,
+                "local": conn.local,
+                "remote": conn.remote,
+                "protocol": conn.protocol,
+                "state": conn.state,
+            }
+            for conn in obs.connections
+        ],
+    }
+    if findings is not None:
+        body["findings"] = [
+            {"severity": item.severity, "rule": item.rule, "message": item.message} for item in findings
+        ]
+    return json.dumps(body, indent=2) + "\n"

chaintrace/rules.py

@@ -0,0 +1,146 @@
+"""Findings from a process snapshot or a kernel trace."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from chaintrace.baseline import Baseline
+from chaintrace.clients import Client, ClientError, client_named
+from chaintrace.models import Finding, Observation
+from chaintrace.net import is_loopback, split_endpoint, suspicious_port
+
+UNKNOWN_LIMIT = 5
+SHELLS = frozenset(
+    {
+        "bash",
+        "sh",
+        "dash",
+        "ash",
+        "zsh",
+        "ksh",
+        "curl",
+        "wget",
+        "nc",
+        "ncat",
+        "socat",
+        "python",
+        "python3",
+        "perl",
+        "ruby",
+    }
+)
+_PERSISTENCE = (
+    "/etc/ld.so.preload",
+    "/etc/crontab",
+    "/etc/cron",
+    "/var/spool/cron",
+    "/etc/sudoers",
+    "/etc/systemd/system",
+    "/etc/rc.local",
+)
+_RANK = {"critical": 0, "warning": 1, "info": 2}
+
+
+def evaluate(obs: Observation, baseline: Baseline | None = None) -> list[Finding]:
+    client = _profile(obs)
+    found: list[Finding] = []
+    if "(deleted)" in obs.exe:
+        found.append(Finding("warning", "deleted-binary", obs.exe))
+    if baseline and obs.exe and baseline.exe and obs.exe != baseline.exe:
+        found.append(Finding("warning", "binary-changed", f"was {baseline.exe} now {obs.exe}"))
+    for child in obs.children:
+        if child.comm in SHELLS:
+            found.append(Finding("critical", "shell-child", f"pid {child.pid} {child.comm}"))
+    for event in obs.events:
+        if event.kind == "exec":
+            finding = _exec(event.path, client, obs.comm)
+            if finding is not None:
+                found.append(finding)
+        elif event.kind == "chmod":
+            found.append(_chmod(event.path, event.mode))
+    for item in obs.files:
+        if _persistence(item.path):
+            found.append(Finding("critical", "persistence", item.path))
+        elif item.sensitive:
+            severity = "info" if item.comm == obs.comm or item.comm in client.comms else "warning"
+            found.append(Finding(severity, "sensitive-file", item.path))
+    unknown: set[str] = set()
+    for conn in obs.connections:
+        if conn.kind == "metadata":
+            found.append(Finding("critical", "metadata-destination", conn.remote))
+        elif suspicious_port(conn):
+            found.append(Finding("warning", "suspicious-port", conn.remote))
+        elif conn.kind == "unknown":
+            unknown.add(conn.remote)
+            if baseline and conn.remote not in baseline.unknown:
+                found.append(Finding("warning", "new-destination", conn.remote))
+            elif baseline is None:
+                found.append(Finding("info", "unknown-destination", conn.remote))
+        elif conn.kind == "listen":
+            found.extend(_listen(conn.local, client, baseline))
+    if len(unknown) >= UNKNOWN_LIMIT:
+        found.append(Finding("warning", "traffic-anomaly", f"{len(unknown)} unknown destinations"))
+    unique = list(dict.fromkeys(found))
+    unique.sort(key=lambda item: (_RANK[item.severity], item.rule, item.message))
+    return unique
+
+
+def exit_code(findings: list[Finding]) -> int:
+    if any(item.severity == "critical" for item in findings):
+        return 2
+    if any(item.severity == "warning" for item in findings):
+        return 1
+    return 0
+
+
+def _profile(obs: Observation) -> Client:
+    if obs.client == "unknown":
+        return Client("unknown", frozenset({obs.comm}), frozenset(), frozenset(), frozenset())
+    try:
+        return client_named(obs.client)
+    except ClientError:
+        return Client("unknown", frozenset({obs.comm}), frozenset(), frozenset(), frozenset())
+
+
+def _exec(path: str, client: Client, comm: str) -> Finding | None:
+    name = Path(path).name
+    if name in SHELLS:
+        return Finding("critical", "unexpected-exec", path)
+    if name and name not in client.comms and name != comm:
+        return Finding("warning", "unexpected-exec", path)
+    return None
+
+
+def _chmod(path: str, mode: str) -> Finding:
+    severity = "critical" if _other_writable(mode) else "warning"
+    return Finding(severity, "permission-change", f"{path} mode {mode}")
+
+
+def _listen(local: str, client: Client, baseline: Baseline | None) -> list[Finding]:
+    found: list[Finding] = []
+    try:
+        ip, port = split_endpoint(local)
+    except ValueError:
+        return found
+    if port in client.loopback_ports and not is_loopback(ip):
+        found.append(Finding("warning", "exposed-port", local))
+    if baseline and local not in baseline.listen:
+        found.append(Finding("warning", "new-listener", local))
+    return found
+
+
+def _persistence(path: str) -> bool:
+    if "/.ssh/authorized_keys" in path:
+        return True
+    for prefix in _PERSISTENCE:
+        if path == prefix or path.startswith(prefix + "/") or path.startswith(prefix + "."):
+            return True
+    return False
+
+
+def _other_writable(mode: str) -> bool:
+    try:
+        value = int(mode, 8) if mode.startswith("0") and len(mode) > 1 else int(mode, 10)
+    except ValueError:
+        return False
+    return bool(value & 0o002)