chaintrace 0.1.0__tar.gz

chaintrace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chaintrace contributors
+
+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.

chaintrace-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: chaintrace
+Version: 0.1.0
+Summary: See what a blockchain node is doing, from the process table and a short kernel trace.
+Author: ehsanhajian
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ehsanhajian/chaintrace
+Project-URL: Issues, https://github.com/ehsanhajian/chaintrace/issues
+Project-URL: Changelog, https://github.com/ehsanhajian/chaintrace/releases
+Keywords: ebpf,bpftrace,ethereum,geth,lighthouse,security,node
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ChainTrace
+
+ChainTrace answers one question: **what is my node doing internally?**
+
+It reads the process, the files it has open, and the connections it holds. When you ask, it also attaches a short read-only kernel probe. A finding is printed when that behavior does not belong on a node.
+
+It does not stop the process, read a file, open a connection, or store a key.
+
+ValidatorPulse raises an alert. ChainDiff decides whether an upgrade is safe. chainlog-ai explains a failure from the logs. ChainTrace is the view of the process itself.
+
+## Install
+
+```bash
+pip install chaintrace
+```
+
+Python 3.11 or newer. The package is published from a GitHub release to [PyPI](https://pypi.org/project/chaintrace/).
+
+```bash
+chaintrace --version
+```
+
+## Which command
+
+| Question | Command |
+| --- | --- |
+| What is this process doing? | `status --pid` or `status --name` |
+| Is any of that suspicious? | `check` |
+| What should the next check compare against? | `baseline` |
+| Can I keep the answer? | `report` |
+| What did the kernel see for a few seconds? | `watch --pid` |
+
+`status` and `check` read a process table. That is `/proc` on the node. `watch` needs `bpftrace` and root, and it only traces the one pid you name. The probe prints `exec`, `connect`, `open`, and `chmod`. It does not follow a child after the exec, and it prints IPv4 connections. IPv6 peers still show up in `status`.
+
+## Examples
+
+A saved process table and a saved trace are in `examples/`. Neither needs root.
+
+```bash
+chaintrace status --proc examples/geth --pid 4242
+chaintrace check --proc examples/geth --pid 4242
+chaintrace check --trace examples/compromise.trace
+```
+
+On the node:
+
+```bash
+chaintrace status --name geth
+chaintrace check --name lighthouse
+chaintrace check --pid 4242 --client teku
+chaintrace baseline --name geth
+chaintrace report --name geth
+chaintrace watch --pid 4242 --seconds 10 > /tmp/node.trace
+chaintrace check --trace /tmp/node.trace
+```
+
+`--client` selects a profile when the process name is generic, such as `java` for Teku. `--json` prints one document. `report` writes `chaintrace-report.md`.
+
+A password-style argument is printed as `[redacted]`. A path, including a JWT file path, stays visible. File contents are never read.
+
+## What a connection means
+
+| Line | Meaning |
+| --- | --- |
+| `listen` | The process is waiting on this address. |
+| `local` | The other end is on this machine, such as the engine API. |
+| `peer` | The local or remote port is a peer port for this client. |
+| `expected` | The remote port is normal for this client, such as a builder relay on 443. |
+| `remote` | The process has no profile, so the destination is shown and not judged. |
+| `unknown` | This profiled client connected somewhere that is not a peer, a loopback address, or an expected port. |
+| `metadata` | The destination is a cloud metadata address. |
+
+Profiles cover the execution, consensus, and builder clients these tools already talk about: Geth, Reth, Nethermind, Erigon, Besu, Lighthouse, Prysm, Teku, Nimbus, Lodestar, MEV-boost, op-node, and op-geth. Any other process is still listed. Its public connections are `remote` rather than `unknown`.
+
+## Findings
+
+Exit 0 means there is no warning or critical finding. An `info` line still exits 0. Exit 1 means a warning. Exit 2 means a critical finding. Exit 3 means the process or the trace could not be read.
+
+| Finding | Severity | When |
+| --- | --- | --- |
+| `sensitive-file` | info, or warning if another program has it open | A JWT, keystore, node key, or mnemonic path is open. |
+| `unknown-destination` | info | An unknown destination, and no baseline has been saved. |
+| `new-destination` | warning | An unknown destination that was not in the baseline. |
+| `new-listener` | warning | A listen address that was not in the baseline. |
+| `binary-changed` | warning | The executable path changed since the baseline. |
+| `deleted-binary` | warning | The executable path is marked deleted. |
+| `exposed-port` | warning | The HTTP or engine port is listening outside loopback. |
+| `suspicious-port` | warning | An outbound connection to a shell or file-share port. |
+| `traffic-anomaly` | warning | Five or more distinct unknown destinations. |
+| `unexpected-exec` | warning, or critical for a shell or downloader | The process executed something other than itself. |
+| `permission-change` | warning, or critical if the mode is world-writable | `chmod` on a path. |
+| `shell-child` | critical | A child is a shell, downloader, or interpreter. |
+| `metadata-destination` | critical | A connection to a cloud metadata address. |
+| `persistence` | critical | An open path under cron, systemd, sudoers, preload, or authorized keys. |
+
+`baseline` stores the executable, the listen addresses, and the unknown destinations in `~/.chaintrace/baseline.json`, or under `CHAINTRACE_HOME`. The file is readable only by its owner. One client name has one baseline. `--no-baseline` ignores it.
+
+## Kernel probe
+
+`watch` writes a bpftrace program and runs it. The program is read-only: exec, connect, open, and chmod for that pid, then it exits. A saved probe file is the same text `check --trace` reads. A JSON line per event works too.
+
+```text
+exec 4242 geth /bin/bash
+connect 4242 geth 169.254.169.254 80
+open 4242 geth /etc/ld.so.preload
+chmod 4242 geth /usr/bin/geth 511
+```
+
+Run `watch` only on a host you administer. It does not survive past `--seconds`, which is at most 300.
+
+## What it does not do
+
+ChainTrace does not call a node RPC, restart a client, or decide whether a release is safe. It does not read key material. A report can include paths and destination addresses, which is the observation.

chaintrace-0.1.0/README.md

@@ -0,0 +1,113 @@
+# ChainTrace
+
+ChainTrace answers one question: **what is my node doing internally?**
+
+It reads the process, the files it has open, and the connections it holds. When you ask, it also attaches a short read-only kernel probe. A finding is printed when that behavior does not belong on a node.
+
+It does not stop the process, read a file, open a connection, or store a key.
+
+ValidatorPulse raises an alert. ChainDiff decides whether an upgrade is safe. chainlog-ai explains a failure from the logs. ChainTrace is the view of the process itself.
+
+## Install
+
+```bash
+pip install chaintrace
+```
+
+Python 3.11 or newer. The package is published from a GitHub release to [PyPI](https://pypi.org/project/chaintrace/).
+
+```bash
+chaintrace --version
+```
+
+## Which command
+
+| Question | Command |
+| --- | --- |
+| What is this process doing? | `status --pid` or `status --name` |
+| Is any of that suspicious? | `check` |
+| What should the next check compare against? | `baseline` |
+| Can I keep the answer? | `report` |
+| What did the kernel see for a few seconds? | `watch --pid` |
+
+`status` and `check` read a process table. That is `/proc` on the node. `watch` needs `bpftrace` and root, and it only traces the one pid you name. The probe prints `exec`, `connect`, `open`, and `chmod`. It does not follow a child after the exec, and it prints IPv4 connections. IPv6 peers still show up in `status`.
+
+## Examples
+
+A saved process table and a saved trace are in `examples/`. Neither needs root.
+
+```bash
+chaintrace status --proc examples/geth --pid 4242
+chaintrace check --proc examples/geth --pid 4242
+chaintrace check --trace examples/compromise.trace
+```
+
+On the node:
+
+```bash
+chaintrace status --name geth
+chaintrace check --name lighthouse
+chaintrace check --pid 4242 --client teku
+chaintrace baseline --name geth
+chaintrace report --name geth
+chaintrace watch --pid 4242 --seconds 10 > /tmp/node.trace
+chaintrace check --trace /tmp/node.trace
+```
+
+`--client` selects a profile when the process name is generic, such as `java` for Teku. `--json` prints one document. `report` writes `chaintrace-report.md`.
+
+A password-style argument is printed as `[redacted]`. A path, including a JWT file path, stays visible. File contents are never read.
+
+## What a connection means
+
+| Line | Meaning |
+| --- | --- |
+| `listen` | The process is waiting on this address. |
+| `local` | The other end is on this machine, such as the engine API. |
+| `peer` | The local or remote port is a peer port for this client. |
+| `expected` | The remote port is normal for this client, such as a builder relay on 443. |
+| `remote` | The process has no profile, so the destination is shown and not judged. |
+| `unknown` | This profiled client connected somewhere that is not a peer, a loopback address, or an expected port. |
+| `metadata` | The destination is a cloud metadata address. |
+
+Profiles cover the execution, consensus, and builder clients these tools already talk about: Geth, Reth, Nethermind, Erigon, Besu, Lighthouse, Prysm, Teku, Nimbus, Lodestar, MEV-boost, op-node, and op-geth. Any other process is still listed. Its public connections are `remote` rather than `unknown`.
+
+## Findings
+
+Exit 0 means there is no warning or critical finding. An `info` line still exits 0. Exit 1 means a warning. Exit 2 means a critical finding. Exit 3 means the process or the trace could not be read.
+
+| Finding | Severity | When |
+| --- | --- | --- |
+| `sensitive-file` | info, or warning if another program has it open | A JWT, keystore, node key, or mnemonic path is open. |
+| `unknown-destination` | info | An unknown destination, and no baseline has been saved. |
+| `new-destination` | warning | An unknown destination that was not in the baseline. |
+| `new-listener` | warning | A listen address that was not in the baseline. |
+| `binary-changed` | warning | The executable path changed since the baseline. |
+| `deleted-binary` | warning | The executable path is marked deleted. |
+| `exposed-port` | warning | The HTTP or engine port is listening outside loopback. |
+| `suspicious-port` | warning | An outbound connection to a shell or file-share port. |
+| `traffic-anomaly` | warning | Five or more distinct unknown destinations. |
+| `unexpected-exec` | warning, or critical for a shell or downloader | The process executed something other than itself. |
+| `permission-change` | warning, or critical if the mode is world-writable | `chmod` on a path. |
+| `shell-child` | critical | A child is a shell, downloader, or interpreter. |
+| `metadata-destination` | critical | A connection to a cloud metadata address. |
+| `persistence` | critical | An open path under cron, systemd, sudoers, preload, or authorized keys. |
+
+`baseline` stores the executable, the listen addresses, and the unknown destinations in `~/.chaintrace/baseline.json`, or under `CHAINTRACE_HOME`. The file is readable only by its owner. One client name has one baseline. `--no-baseline` ignores it.
+
+## Kernel probe
+
+`watch` writes a bpftrace program and runs it. The program is read-only: exec, connect, open, and chmod for that pid, then it exits. A saved probe file is the same text `check --trace` reads. A JSON line per event works too.
+
+```text
+exec 4242 geth /bin/bash
+connect 4242 geth 169.254.169.254 80
+open 4242 geth /etc/ld.so.preload
+chmod 4242 geth /usr/bin/geth 511
+```
+
+Run `watch` only on a host you administer. It does not survive past `--seconds`, which is at most 300.
+
+## What it does not do
+
+ChainTrace does not call a node RPC, restart a client, or decide whether a release is safe. It does not read key material. A report can include paths and destination addresses, which is the observation.

chaintrace-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "chaintrace"
+version = "0.1.0"
+description = "See what a blockchain node is doing, from the process table and a short kernel trace."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+  "ebpf",
+  "bpftrace",
+  "ethereum",
+  "geth",
+  "lighthouse",
+  "security",
+  "node",
+]
+authors = [{ name = "ehsanhajian" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: System :: Networking :: Monitoring",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Repository = "https://github.com/ehsanhajian/chaintrace"
+Issues = "https://github.com/ehsanhajian/chaintrace/issues"
+Changelog = "https://github.com/ehsanhajian/chaintrace/releases"
+
+[project.scripts]
+chaintrace = "chaintrace.cli:main"
+
+[build-system]
+requires = ["setuptools>=84"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+chaintrace = ["clients.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

chaintrace-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

chaintrace-0.1.0/src/chaintrace/__init__.py

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

chaintrace-0.1.0/src/chaintrace/__main__.py

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

chaintrace-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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]
+  }
+}