> For the complete documentation index, see [llms.txt](https://docs.soniclabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md).

# Tier 4: Control Access

Only known clients, only allowed methods. Required for nodes with debug or trace.

**Goal:** only known clients can reach the node, and each client can only call the methods it needs. **Required for any node with `debug` or `trace` enabled, including "private" nodes.**

{% hint style="info" %}
**Validators:** skip this tier, except the network rules in 4.3.
{% endhint %}

{% hint style="info" %}
**Who can do this tier.**&#x20;

Unlike Tiers 1–3, this tier isn't copy-and-paste. It needs someone who can run and maintain a web proxy (such as nginx), manage TLS certificates, and read JSON-RPC requests.&#x20;

The proxy is the main thing standing between attackers and `debug`/`trace`, and a small mistake in its rules can silently let dangerous requests through. If nobody on your team can own that, **don't enable `debug`/`trace` on your own nodes**. Use a provider that offers tracing, or contact the Sonic team at <security@soniclabs.com>.
{% endhint %}

## Why "private" isn't enough

A node with no public access can still be attacked. "Private" usually means "anyone on the internal network can call it": every server, every laptop on the VPN, every CI job. Common ways an attacker ends up "inside":

* **An internal app that passes user input to the node.** Block explorers, indexers, transaction simulators, and "trace this transaction" features often take parameters from public users and forward them to `debug_trace*`. To the node, the attack looks like it comes from your own app. **Check every internal app that calls `debug_*`/`trace_*` and make sure it never forwards user-supplied tracer settings.**
* A compromised developer laptop, CI runner, or other server on the same network.
* A VPN account shared too widely.

Treat the node's RPC like a database: authenticated, limited to known clients, every call logged.

## 4.1 Separate public and private nodes

* **Public nodes**: standard methods only (`eth`, `net`, `web3`, `sonic`, ...). Never `debug`/`trace`.
* **Debug/trace nodes**: separate machines, reachable only through the proxy below, only by named internal clients.

Don't mix the two roles on one machine.

## 4.2 Put a filtering proxy in front of the node

The node listens only on `127.0.0.1` ([Tier 1.3](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-1-essentials.md)). A proxy on the same machine is the only thing reachable from the network. The proxy must:

1. **Identify the client.** Use an API key per client (or client certificates/mTLS). Reject requests without one.
2. **Allow only listed methods, per client.** Deny everything else by default. This includes **every item in a batch request**, not just the first.
3. **For `debug_trace*`, allow only built-in tracers that can't run code from the request** (`callTracer`, `prestateTracer`, `4byteTracer`, `flatCallTracer`, or no tracer). **Reject any other `tracer` value.** A custom JavaScript tracer is just text, so anything that isn't an exact name from this list must be rejected.

   **Don't allow `muxTracer`**, even though it's built in: it takes a list of other tracers inside its settings, and the node treats any name it doesn't recognize as JavaScript code.

   If you turned custom tracers on ([Tier 1.2](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-1-essentials.md)), allow them only for the clients that need them.
4. **Limit size and rate**: maximum request size, batch size, requests per second per client, concurrent trace calls.
5. **Log** client, source IP, method, and (for rejected requests) the request body.
6. **Read each request exactly the way the node does, or reject it.** The node ignores upper/lower case in field names (`Tracer` and `tracer` are the same to it), and when a field appears twice it uses the last one. A proxy that reads requests differently can be fooled: it checks one value, and the node uses another. Reject requests with unexpected top-level fields, field names that differ only in case, and field names with unusual characters.

**WebSocket:** simple proxies can't inspect WebSocket messages. On debug/trace nodes, keep `debug`/`trace` out of `--ws.api`, or disable `--ws` entirely.

A worked example using nginx is in [**Appendix D**](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/appendix-d-filtering-proxy-nginx.md). Any proxy that can read JSON request bodies works; the six requirements are what matter.

## 4.3 Network layout

Set these rules in your cloud firewall / security groups / network switches. Server-level rules (Tiers 1–3) can be undone by an attacker who gains full control of the server; network-level rules can't.

| From                   | To                    | Allowed                                                                                  |
| ---------------------- | --------------------- | ---------------------------------------------------------------------------------------- |
| Internet               | Node                  | Peer-to-peer port (5050 TCP/UDP) only. For public RPC nodes: also the RPC or proxy port. |
| Named internal clients | Node                  | Proxy port only                                                                          |
| Monitoring server      | Node                  | Metrics port only, never the profiling port (see 1.3)                                    |
| Admin VPN / bastion    | Node                  | SSH only                                                                                 |
| **Node**               | **Internal networks** | **Nothing**, except specific services it truly needs (e.g. DNS)                          |
| Node                   | Internet              | Allowed (needed for peers)                                                               |

**Validators:** the same rules apply without the RPC rows. From the internet, only the peer-to-peer port; from internal clients, nothing.

Ideally, put RPC nodes and validators in their own network segments (subnet/VLAN), separate from each other and from databases, CI and office networks.

## 4.4 Limit expensive calls

Tracing is expensive and can be used to overload the node. In the proxy, limit concurrent `debug_trace*` calls per client. In the node, keep the built-in limits on, and lower them if your clients allow it:

| Flag                                | Limits                                    | Default    |
| ----------------------------------- | ----------------------------------------- | ---------- |
| `--rpc.timeout`, `--rpc.evmtimeout` | How long a call may run                   | 5s         |
| `--rpc.gascap`                      | Gas for `eth_call` / `eth_estimateGas`    | 50,000,000 |
| `--rpc.batch-request-limit`         | Requests in one batch                     | 1000       |
| `--rpc.batch-response-max-size`     | Bytes returned by one batch               | 25,000,000 |
| `--rpc.tracefilterrange`            | Blocks covered by one `trace_filter` call | 1000       |
| `--rpc.structloglimit`              | Opcode log entries in one `debug` trace   | 2000       |

Don't set any of them to 0: for most of them, 0 means unlimited.

## ✅ Tier 4 checklist

* [ ] Public and debug/trace roles on separate machines
* [ ] Proxy in front, with per-client keys, per-client method allowlist, built-in tracers only (no `muxTracer`), batch inspection, rate limits, logging
* [ ] Proxy rejects requests it can't read exactly like the node (case-variant or unexpected field names); bypass tests from [Appendix D](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/appendix-d-filtering-proxy-nginx.md) pass
* [ ] `debug`/`trace` not in `--ws.api` on debug nodes (or WS off)
* [ ] Internal apps reviewed: none forwards user-supplied tracer settings
* [ ] Network rules: node → internal networks blocked at the network level (validators too)
