chaintrace 0.1.0__py3-none-any.whl

chaintrace/__init__.py

@@ -0,0 +1,3 @@
+"""See what a blockchain node is doing."""
+
+__version__ = "0.1.0"

chaintrace/__main__.py

@@ -0,0 +1,4 @@
+from chaintrace.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

chaintrace/baseline.py

@@ -0,0 +1,81 @@
+"""Remember the binary, the listeners, and the unknown destinations."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from chaintrace.models import Observation
+
+
+class BaselineError(ValueError):
+    """The baseline file could not be read."""
+
+
+@dataclass(frozen=True)
+class Baseline:
+    client: str
+    exe: str
+    unknown: frozenset[str]
+    listen: frozenset[str]
+
+
+def baseline_key(obs: Observation) -> str:
+    return obs.comm if obs.client == "unknown" else obs.client
+
+
+def home_file() -> Path:
+    override = os.environ.get("CHAINTRACE_HOME")
+    root = Path(override) if override else Path.home() / ".chaintrace"
+    return root / "baseline.json"
+
+
+def capture(obs: Observation) -> Baseline:
+    return Baseline(
+        client=baseline_key(obs),
+        exe=obs.exe,
+        unknown=frozenset(conn.remote for conn in obs.connections if conn.kind == "unknown"),
+        listen=frozenset(conn.local for conn in obs.connections if conn.kind == "listen"),
+    )
+
+
+def load(path: Path, client: str) -> Baseline | None:
+    if not path.is_file():
+        return None
+    try:
+        raw = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise BaselineError(f"{path} is not a baseline file") from exc
+    item = raw.get(client)
+    if not isinstance(item, dict):
+        return None
+    return Baseline(
+        client=client,
+        exe=str(item.get("exe", "")),
+        unknown=frozenset(item.get("unknown", [])),
+        listen=frozenset(item.get("listen", [])),
+    )
+
+
+def save(path: Path, baseline: Baseline) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.parent.chmod(0o700)
+    data: dict[str, object] = {}
+    if path.is_file():
+        try:
+            loaded = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            raise BaselineError(f"{path} is not a baseline file") from exc
+        if isinstance(loaded, dict):
+            data = loaded
+    data[baseline.client] = {
+        "exe": baseline.exe,
+        "unknown": sorted(baseline.unknown),
+        "listen": sorted(baseline.listen),
+    }
+    temporary = path.with_suffix(".json.tmp")
+    temporary.write_text(json.dumps(data, indent=2) + "\n")
+    temporary.chmod(0o600)
+    temporary.replace(path)

chaintrace/cli.py

@@ -0,0 +1,159 @@
+"""Command line for chaintrace."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from chaintrace import __version__
+from chaintrace.baseline import BaselineError, baseline_key, capture, home_file, load, save
+from chaintrace.clients import ClientError, apply_client
+from chaintrace.models import Observation
+from chaintrace.probe import render_probe, unavailable
+from chaintrace.procfs import ProcError, find_pids, read_pid
+from chaintrace.render import render_check, render_json, render_report, render_status
+from chaintrace.rules import evaluate, exit_code
+from chaintrace.trace import TraceError, read_trace
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.version:
+        print(f"chaintrace {__version__}")
+        return 0
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 3
+    try:
+        return args.func(args)
+    except (ProcError, TraceError, ClientError, BaselineError) as exc:
+        print(exc, file=sys.stderr)
+        return 3
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="chaintrace", description="See what a blockchain node is doing.")
+    parser.add_argument("--version", action="store_true")
+    commands = parser.add_subparsers(dest="command")
+
+    status = commands.add_parser("status", help="Show the process, files, and connections")
+    _process_flags(status)
+    status.set_defaults(func=cmd_status, trace=None, no_baseline=True)
+
+    check = commands.add_parser("check", help="Report behavior that does not belong on a node")
+    _process_flags(check)
+    check.add_argument("--trace", type=Path)
+    check.add_argument("--no-baseline", action="store_true")
+    check.set_defaults(func=cmd_check)
+
+    baseline = commands.add_parser("baseline", help="Remember this binary, its listeners, and unknown destinations")
+    _process_flags(baseline)
+    baseline.set_defaults(func=cmd_baseline, trace=None, no_baseline=True)
+
+    report = commands.add_parser("report", help="Write a markdown report")
+    _process_flags(report)
+    report.add_argument("--trace", type=Path)
+    report.add_argument("--no-baseline", action="store_true")
+    report.add_argument("--output", type=Path, default=Path("chaintrace-report.md"))
+    report.set_defaults(func=cmd_report)
+
+    watch = commands.add_parser("watch", help="Trace exec, connect, open, and chmod for one pid")
+    watch.add_argument("--pid", type=int, required=True)
+    watch.add_argument("--seconds", type=int, default=10)
+    watch.set_defaults(func=cmd_watch)
+    return parser
+
+
+def _process_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--proc", type=Path, help="Process table. Defaults to /proc")
+    parser.add_argument("--pid", type=int)
+    parser.add_argument("--name", help="Process name, such as geth or lighthouse")
+    parser.add_argument("--client", help="Client profile when the process name is generic")
+    parser.add_argument("--json", action="store_true")
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    obs = _load(args)
+    print(render_json(obs) if args.json else render_status(obs), end="")
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    obs = _load(args)
+    findings = evaluate(obs, _stored(args, obs))
+    print(render_json(obs, findings) if args.json else render_check(obs, findings), end="")
+    return exit_code(findings)
+
+
+def cmd_baseline(args: argparse.Namespace) -> int:
+    obs = _load(args)
+    saved = capture(obs)
+    path = home_file()
+    save(path, saved)
+    print(f"baseline {saved.client} {path}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    obs = _load(args)
+    findings = evaluate(obs, _stored(args, obs))
+    args.output.write_text(render_report(obs, findings))
+    print(f"report {args.output}")
+    return exit_code(findings)
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    try:
+        script = render_probe(args.pid, args.seconds)
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 3
+    reason = unavailable()
+    if reason:
+        print(reason, file=sys.stderr)
+        return 3
+    with tempfile.TemporaryDirectory() as directory:
+        path = Path(directory) / "node.bt"
+        path.write_text(script)
+        try:
+            completed = subprocess.run(["bpftrace", str(path)], check=False, timeout=args.seconds + 20)
+        except subprocess.TimeoutExpired:
+            print("bpftrace did not exit", file=sys.stderr)
+            return 3
+    return 0 if completed.returncode == 0 else 3
+
+
+def _stored(args: argparse.Namespace, obs: Observation):
+    if args.no_baseline:
+        return None
+    return load(home_file(), baseline_key(obs))
+
+
+def _load(args: argparse.Namespace):
+    trace = getattr(args, "trace", None)
+    if trace and (args.pid or args.name):
+        raise TraceError("pass a trace or a process, not both")
+    if args.pid and args.name:
+        raise ProcError("pass --pid or --name, not both")
+    if trace:
+        return apply_client(read_trace(trace), args.client)
+    proc = args.proc if args.proc is not None else Path("/proc")
+    if not proc.is_dir():
+        raise ProcError(f"{proc} is not a process table")
+    if args.name:
+        found = find_pids(proc, args.name)
+        if not found:
+            raise ProcError(f"no process named {args.name}")
+        if len(found) > 1:
+            listed = ", ".join(str(item) for item in found)
+            raise ProcError(f"more than one {args.name}: {listed}")
+        pid = found[0]
+    elif args.pid is None:
+        raise ProcError("pass --pid or --name")
+    else:
+        pid = args.pid
+    return apply_client(read_pid(proc, pid), args.client)

chaintrace/clients.json

@@ -0,0 +1,69 @@
+{
+  "geth": {
+    "comms": ["geth"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  },
+  "reth": {
+    "comms": ["reth"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  },
+  "nethermind": {
+    "comms": ["nethermind", "Nethermind"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  },
+  "erigon": {
+    "comms": ["erigon"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  },
+  "besu": {
+    "comms": ["besu"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  },
+  "lighthouse": {
+    "comms": ["lighthouse"],
+    "p2p_ports": [9000],
+    "loopback_ports": [5052]
+  },
+  "prysm": {
+    "comms": ["prysm", "beacon-chain"],
+    "p2p_ports": [13000, 12000],
+    "loopback_ports": [3500, 4000]
+  },
+  "teku": {
+    "comms": ["teku"],
+    "p2p_ports": [9000],
+    "loopback_ports": [5051]
+  },
+  "nimbus": {
+    "comms": ["nimbus", "nimbus_beacon_node", "nimbus_beacon_n"],
+    "p2p_ports": [9000],
+    "loopback_ports": [5052]
+  },
+  "lodestar": {
+    "comms": ["lodestar"],
+    "p2p_ports": [9000],
+    "loopback_ports": [9596]
+  },
+  "mev-boost": {
+    "comms": ["mev-boost"],
+    "p2p_ports": [],
+    "remote_ports": [443, 18550],
+    "loopback_ports": [18550]
+  },
+  "op-node": {
+    "comms": ["op-node"],
+    "p2p_ports": [9222],
+    "remote_ports": [443],
+    "loopback_ports": [9545]
+  },
+  "op-geth": {
+    "comms": ["op-geth"],
+    "p2p_ports": [30303],
+    "loopback_ports": [8545, 8551]
+  }
+}

chaintrace/clients.py

@@ -0,0 +1,106 @@
+"""Client profiles shipped with the package."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+from pathlib import Path
+
+from chaintrace.models import Observation
+
+
+class ClientError(ValueError):
+    """The named client is not in the catalog."""
+
+
+@dataclass(frozen=True)
+class Client:
+    name: str
+    comms: frozenset[str]
+    p2p_ports: frozenset[int]
+    remote_ports: frozenset[int]
+    loopback_ports: frozenset[int]
+
+    @property
+    def profiled(self) -> bool:
+        return self.name != "unknown"
+
+
+@lru_cache(maxsize=1)
+def catalog() -> tuple[Client, ...]:
+    raw = json.loads(files("chaintrace").joinpath("clients.json").read_text())
+    clients = []
+    for name, item in raw.items():
+        clients.append(
+            Client(
+                name=name,
+                comms=frozenset(item.get("comms", [])),
+                p2p_ports=frozenset(item.get("p2p_ports", [])),
+                remote_ports=frozenset(item.get("remote_ports", [])),
+                loopback_ports=frozenset(item.get("loopback_ports", [])),
+            )
+        )
+    return tuple(clients)
+
+
+def client_named(name: str) -> Client:
+    for client in catalog():
+        if client.name == name:
+            return client
+    known = ", ".join(client.name for client in catalog())
+    raise ClientError(f"unknown client {name}. known clients: {known}")
+
+
+def _basename(exe: str) -> str:
+    name = Path(exe).name
+    suffix = " (deleted)"
+    if name.endswith(suffix):
+        return name[: -len(suffix)]
+    return name
+
+
+def recognize(comm: str, exe: str) -> Client:
+    """Match the executable name first, then the process name."""
+    base = _basename(exe)
+    if base:
+        for client in catalog():
+            if base in client.comms:
+                return client
+    for client in catalog():
+        if comm in client.comms:
+            return client
+    return Client("unknown", frozenset({comm} if comm else set()), frozenset(), frozenset(), frozenset())
+
+
+def resolve(comm: str, exe: str, override: str | None) -> Client:
+    if override:
+        return client_named(override)
+    return recognize(comm, exe)
+
+
+def apply_client(obs: Observation, override: str | None) -> Observation:
+    client = resolve(obs.comm, obs.exe, override)
+    if client.name == obs.client and override is None:
+        return obs
+    from chaintrace.net import classify_connection
+
+    connections = tuple(
+        classify_connection(conn, client) for conn in obs.connections
+    )
+    return Observation(
+        pid=obs.pid,
+        comm=obs.comm,
+        client=client.name,
+        exe=obs.exe,
+        state=obs.state,
+        rss_bytes=obs.rss_bytes,
+        cpu_seconds=obs.cpu_seconds,
+        ppid=obs.ppid,
+        cmdline=obs.cmdline,
+        files=obs.files,
+        connections=connections,
+        children=obs.children,
+        events=obs.events,
+    )

chaintrace/models.py

@@ -0,0 +1,62 @@
+"""Process snapshot and findings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OpenFile:
+    path: str
+    sensitive: bool
+    comm: str
+
+
+@dataclass(frozen=True)
+class Connection:
+    protocol: str
+    local: str
+    remote: str
+    state: str
+    kind: str
+
+
+@dataclass(frozen=True)
+class Child:
+    pid: int
+    comm: str
+    exe: str
+
+
+@dataclass(frozen=True)
+class Event:
+    kind: str
+    pid: int
+    comm: str
+    path: str = ""
+    remote: str = ""
+    mode: str = ""
+
+
+@dataclass(frozen=True)
+class Observation:
+    pid: int
+    comm: str
+    client: str
+    exe: str
+    state: str
+    rss_bytes: int
+    cpu_seconds: float
+    ppid: int
+    cmdline: tuple[str, ...]
+    files: tuple[OpenFile, ...]
+    connections: tuple[Connection, ...]
+    children: tuple[Child, ...]
+    events: tuple[Event, ...] = ()
+
+
+@dataclass(frozen=True)
+class Finding:
+    severity: str
+    rule: str
+    message: str

chaintrace/net.py

@@ -0,0 +1,179 @@
+"""Parse /proc socket tables and classify a destination."""
+
+from __future__ import annotations
+
+import socket
+from dataclasses import dataclass
+
+from chaintrace.clients import Client
+from chaintrace.models import Connection
+
+METADATA_HOSTS = frozenset({"169.254.169.254", "169.254.170.2", "fd00:ec2::254"})
+SUSPICIOUS_PORTS = frozenset({22, 23, 25, 445, 3389, 4444, 1337, 31337})
+
+_STATES = {
+    "01": "ESTABLISHED",
+    "02": "SYN_SENT",
+    "03": "SYN_RECV",
+    "04": "FIN_WAIT1",
+    "05": "FIN_WAIT2",
+    "06": "TIME_WAIT",
+    "07": "CLOSE",
+    "08": "CLOSE_WAIT",
+    "09": "LAST_ACK",
+    "0A": "LISTEN",
+    "0B": "CLOSING",
+}
+
+
+class NetError(ValueError):
+    """A socket address could not be parsed."""
+
+
+@dataclass(frozen=True)
+class RawSocket:
+    protocol: str
+    local_ip: str
+    local_port: int
+    remote_ip: str
+    remote_port: int
+    state: str
+    inode: str
+
+
+def parse_proc_net(text: str, protocol: str) -> tuple[RawSocket, ...]:
+    """Parse `/proc/net/tcp` or the udp, tcp6, and udp6 tables.
+
+    The inode is the 10th column. See proc(5).
+    """
+    found: list[RawSocket] = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 10 or ":" not in parts[1] or ":" not in parts[2]:
+            continue
+        try:
+            local_ip, local_port = _address(parts[1])
+            remote_ip, remote_port = _address(parts[2])
+        except NetError:
+            continue
+        found.append(
+            RawSocket(
+                protocol=protocol,
+                local_ip=local_ip,
+                local_port=local_port,
+                remote_ip=remote_ip,
+                remote_port=remote_port,
+                state=_STATES.get(parts[3].upper(), parts[3]),
+                inode=parts[9],
+            )
+        )
+    return tuple(found)
+
+
+def _address(field: str) -> tuple[str, int]:
+    hex_ip, _, hex_port = field.partition(":")
+    if not hex_port:
+        raise NetError(f"bad socket address {field}")
+    return _ip(hex_ip), int(hex_port, 16)
+
+
+def _ip(hex_ip: str) -> str:
+    if len(hex_ip) == 8:
+        raw = bytes.fromhex(hex_ip)
+        return ".".join(str(b) for b in raw[::-1])
+    if len(hex_ip) == 32:
+        raw = bytes.fromhex(hex_ip)
+        words = [raw[i : i + 4][::-1] for i in range(0, 16, 4)]
+        return socket.inet_ntop(socket.AF_INET6, b"".join(words))
+    raise NetError(f"bad ip length {len(hex_ip)}")
+
+
+def format_endpoint(ip: str, port: int) -> str:
+    if ":" in ip:
+        return f"[{ip}]:{port}"
+    return f"{ip}:{port}"
+
+
+def split_endpoint(endpoint: str) -> tuple[str, int]:
+    if endpoint.startswith("["):
+        host, _, port = endpoint[1:].rpartition("]:")
+        return host, int(port)
+    host, _, port = endpoint.rpartition(":")
+    if not host or not port:
+        raise NetError(f"bad endpoint {endpoint}")
+    return host, int(port)
+
+
+def is_loopback(ip: str) -> bool:
+    if ip == "::1":
+        return True
+    return ip.startswith("127.")
+
+
+def is_unspecified(ip: str) -> bool:
+    return ip in {"0.0.0.0", "::"}
+
+
+def is_metadata(ip: str) -> bool:
+    return ip in METADATA_HOSTS
+
+
+def classify(raw: RawSocket, client: Client) -> str:
+    listening = raw.state == "LISTEN" or raw.remote_port == 0
+    if listening:
+        return "listen"
+    if is_metadata(raw.remote_ip):
+        return "metadata"
+    if is_loopback(raw.remote_ip):
+        return "local"
+    if not client.profiled:
+        return "remote"
+    if raw.remote_port in client.p2p_ports or raw.local_port in client.p2p_ports:
+        return "peer"
+    if raw.remote_port in client.remote_ports:
+        return "expected"
+    return "unknown"
+
+
+def connection_from_raw(raw: RawSocket, client: Client) -> Connection:
+    return Connection(
+        protocol=raw.protocol,
+        local=format_endpoint(raw.local_ip, raw.local_port),
+        remote=format_endpoint(raw.remote_ip, raw.remote_port),
+        state=raw.state,
+        kind=classify(raw, client),
+    )
+
+
+def classify_connection(conn: Connection, client: Client) -> Connection:
+    """Re-label a connection after the operator names the client."""
+    if conn.local == "-":
+        local_ip, local_port = "0.0.0.0", 0
+    else:
+        local_ip, local_port = split_endpoint(conn.local)
+    remote_ip, remote_port = split_endpoint(conn.remote)
+    raw = RawSocket(
+        protocol=conn.protocol,
+        local_ip=local_ip,
+        local_port=local_port,
+        remote_ip=remote_ip,
+        remote_port=remote_port,
+        state=conn.state,
+        inode="",
+    )
+    kind = classify(raw, client)
+    if kind == conn.kind:
+        return conn
+    return Connection(conn.protocol, conn.local, conn.remote, conn.state, kind)
+
+
+def suspicious_port(conn: Connection) -> bool:
+    if conn.kind in {"listen", "local"}:
+        return False
+    try:
+        remote_ip, remote_port = split_endpoint(conn.remote)
+    except NetError:
+        return False
+    if is_loopback(remote_ip):
+        return False
+    return remote_port in SUSPICIOUS_PORTS