> 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-1-essentials.md).

# Tier 1: Essentials

Close what shouldn't be open. Everyone should do this tier.

**Goal:** the dangerous parts of the node aren't reachable by people who shouldn't reach them. **Everyone should do this tier.**

{% hint style="info" %}
**Validators:** every step applies. With no RPC, 1.2 to 1.4 come down to keeping it off.
{% endhint %}

## 1.1 Run the latest Sonic release

Security fixes only help if they're installed. Run the latest release ([v2.2.5](https://github.com/0xsoniclabs/sonic/releases/tag/v2.2.5) as of October 2026), and follow new releases in the [Sonic GitHub repository](https://github.com/0xsoniclabs/sonic/releases) so you hear about new fixes quickly. Check your current version:

```bash
/usr/local/bin/sonicd version
```

## 1.2 Only enable the RPC method groups you actually need

RPC methods are grouped into "namespaces" (`eth`, `net`, `debug`, ...). You choose which ones are enabled with the `--http.api` and `--ws.api` flags, and possibly in your config file.&#x20;

Check both:

```bash
systemctl cat sonic | grep -E 'http.api|ws.api'
grep -nE 'HTTPModules|WSModules|api' /etc/sonic/config.toml
```

Rules of thumb:

| Namespace                     | Public nodes                 | Private nodes                                                                                                                                |
| ----------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `eth`, `net`, `web3`, `sonic` | OK                           | OK                                                                                                                                           |
| `txpool`, `dag`, `abft`       | Only if your users need them | OK                                                                                                                                           |
| `debug`, `trace`              | **Never**                    | Only on a dedicated node, behind [Tier 4](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md) controls |
| `admin`, `personal`           | **Never**                    | **Never** over the network                                                                                                                   |
| `ftm`                         | **Off**: deprecated          | **Off**: deprecated                                                                                                                          |

Every method group left on is code an attacker can reach, and nobody should still depend on the deprecated `ftm`, so remove it from both lists. The node warns at startup while it's on. If an app still calls `ftm_*` methods, removing `ftm` breaks it, so move the app off them first.

Remember that **HTTP and WebSocket have separate lists.** Removing `debug` from `--http.api` but leaving it in `--ws.api` leaves it open.

There's also a third, local way in: the **IPC file** (a `.ipc` file in the data folder). It gives **every** method group, including `admin` and `debug`, to anything on the machine that can open the file. If you don't use it, turn it off with `--ipcdisable`.

**If you need `debug`, keep custom JavaScript tracers off.** They run code sent inside an RPC request. Since v2.2.5 they're off by default, and only `--rpc.allow-js-tracers` or `AllowJSTracers = true` in the `[Opera]` section of the config file turns them on. Both of these should print nothing:

```bash
systemctl cat sonic | grep allow-js-tracers
grep -n AllowJSTracers /etc/sonic/config.toml
```

{% hint style="warning" %}
**Turn custom tracers on only if you truly depend on them.** An attacker who gets a single request through to such a node can misuse them, so protect it with every tier of this guide, including [Tier 4](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md).
{% endhint %}

Never use `--allow-insecure-unlock` (or `--unlock`) on any node: together they let RPC callers use accounts unlocked on the node. **Validators** don't need them either. The signing key is unlocked with `--validator.password`.&#x20;

This should print nothing:

```bash
systemctl cat sonic | grep -E 'allow-insecure-unlock|--unlock'
```

## 1.3 Listen only where needed

Change the listening addresses so the node isn't reachable from everywhere:

* If a proxy or load balancer runs **on the same machine** (recommended, see [Tier 4](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md)): use `--http.addr=127.0.0.1` and `--ws.addr=127.0.0.1`.
* If clients connect over a private network: use the server's **private** IP, never `0.0.0.0`.
* **Public RPC** without a proxy on the same machine: the RPC has to accept connections from the internet, so `0.0.0.0` is expected for the HTTP and WebSocket ports only. Make sure 1.2 is done, so only public method groups are reachable. A proxy in front ([Tier 4](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md)) is still worth it for rate limits.
* **Validators:** no RPC at all. Remove `--http` and `--ws`, and every `--http.*` and `--ws.*` flag, from the service file.
* Profiling (`--pprof`) must listen on `127.0.0.1` only, in every setup. Profiling endpoints expose a lot of internal detail and must never be reachable from the network.
* Metrics (`--metrics`): use `127.0.0.1` if an agent on the same machine collects them. If a monitoring server scrapes them over the network, give metrics their own port on the **private** IP, separate from profiling, and allow only the monitoring server to reach it (1.5 and [Tier 2B](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-2-lock-the-node-in-a-box.md)).

The flags are `--pprof.addr`/`--pprof.port` and `--metrics.addr`/`--metrics.port`. Both default to `127.0.0.1:6060`, so if you turn both on, give one of them another port.

## 1.4 Remove "allow everything" wildcards

These settings control which websites and host names the node accepts requests from. A `*` blocks nothing. Replace it with your real domains:

```
--http.vhosts="*"       →  --http.vhosts="rpc.example.com,localhost"
--http.corsdomain="*"   →  --http.corsdomain="https://app.example.com"
--ws.origins="*"        →  --ws.origins="https://app.example.com"
```

`vhosts` lists the host names clients use to reach the node. Keep `localhost` in it if you use a proxy on the same machine ([Tier 4](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-4-control-access.md)).

For `corsdomain` and `origins`:

* **Private nodes:** list only your own web apps. If no web page talks to the node directly (only servers do), remove the flags entirely. This costs nothing and blocks a family of browser-based tricks, where a malicious website makes a visitor's browser send requests to a node the visitor can reach but the website can't.
* **Public RPC** used by any website or wallet: `*` is needed and acceptable. Anyone can already send requests to a public node directly, so a browser adds no extra access.

## 1.5 Turn on a firewall

Only the peer-to-peer port (default `5050`, TCP and UDP) needs to be open to the whole internet. Everything else should be open only to specific addresses.

**Public RPC:** also open the RPC port (or your proxy's port, if you use one) to everyone. Never open the profiling or metrics ports.

**Validators:** open nothing but the peer-to-peer port, SSH from your own addresses, and the metrics port to your monitoring server if it scrapes over the network. Leave out the RPC lines of the example below.

{% hint style="warning" %}
**Don't lock yourself out.** Always allow SSH *before* enabling the firewall, and keep a second SSH session open while you test.
{% endhint %}

Example with `ufw` (Ubuntu/Debian):

```bash
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp                                   # SSH, ideally restrict to your office/VPN IP
sudo ufw allow 5050/tcp                                 # Sonic peer-to-peer
sudo ufw allow 5050/udp                                 # Sonic peer discovery
sudo ufw allow from 203.0.113.10 to any port 18545 proto tcp   # private RPC: one line per client
# sudo ufw allow 18545/tcp                               # public RPC only: open RPC to everyone
sudo ufw enable
sudo ufw status verbose
```

If you're in a cloud (AWS, GCP, Hetzner, ...), set the same rules in the provider's firewall / security group too. Do both: the provider firewall keeps working even if the server is compromised.

The node can also open ports by itself: by default (`--nat=any`) it asks routers on its network to forward ports to it (UPnP, NAT-PMP). Set `--nat=extip:<public IP>` with the server's public IP address instead, as the starter service file in [Appendix A](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/appendix-a-starter-service-file.md) does. This also stops a router lookup at every start, which the [Tier 3](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-3-get-alerted.md) rules would log as a blocked connection to your private network.

{% hint style="info" %}
**Docker users:** ports published with `docker run -p` bypass `ufw` completely. See [Tier 5.3](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-5-stay-current.md).
{% endhint %}

## 1.6 Run the node as a locked-down user

The node should run as its own user (e.g. `sonic`), never as `root`. Check who it runs as now:

```bash
systemctl show -p User sonic        # should print User=sonic, not User= (empty) or User=root
```

**If it runs as root (or `User=` is empty)**, move it to its own user. The node is stopped for a few minutes while you do this.

**a) Create the user and stop the node:**

```bash
sudo useradd --system --home-dir /var/lib/sonic --no-create-home --shell /usr/sbin/nologin sonic   # skip if the user exists
sudo systemctl stop sonic
```

**b) Only if your data folder is inside `/root`** (e.g. `/root/.sonic`): the `sonic` user can't reach it there. Move it, then change `--datadir=` to `/var/lib/sonic` in the service file (`sudo systemctl edit --full sonic` opens it in an editor):

```bash
sudo mv /root/.sonic /var/lib/sonic
```

**c) Give the data folder to the new user:**

```bash
sudo chown -R sonic:sonic /var/lib/sonic     # your --datadir
```

**Validators:** the new user also needs the password file in `--validator.password=`. Set it up as described in [Validator Node](https://docs.soniclabs.com/pages/ycklmVREhe4bDmkq6Vvn#id-9.-run-your-validator-node), step 9, and change the flag to match.

**d) Tell the service to use the new user.** `sudo systemctl edit sonic` opens an editor; add these lines and save:

```ini
[Service]
User=sonic
Group=sonic
```

If the RPC listens on a port below 1024 (e.g. 80), a non-root user isn't allowed to use it. Either move it to the default port 18545 (recommended), or also add `AmbientCapabilities=CAP_NET_BIND_SERVICE` in the same editor (see 2C).

**e) Start the node again:**

```bash
sudo systemctl start sonic
sudo systemctl status sonic
```

The node's user shouldn't be able to log in or use `sudo`:

```bash
getent passwd sonic                         # last field should be /usr/sbin/nologin or /bin/false
sudo usermod -s /usr/sbin/nologin sonic     # fix it if not
sudo -l -U sonic                            # should say the user may not run sudo
sudo ls -la ~sonic/.ssh 2>/dev/null         # should not exist, or contain no keys
```

The `sonicd` binary itself should belong to `root` and not be writable by the `sonic` user, so a compromised node can't replace it:

```bash
ls -l /usr/local/bin/sonicd                 # owner should be root, permissions like -rwxr-xr-x
```

## 1.7 Keep secrets off the server

Assume anything stored on a node server can be stolen. Make sure these are **not** on the machine (or at least not readable by the `sonic` user):

* wallet keys, keystores, mnemonic phrases, and validator signing keys (except the one on the validator itself)
* cloud access keys (`~/.aws`, `~/.config/gcloud`, service account JSON files)
* SSH private keys that open other servers
* `.env` files, deploy tokens, database passwords for other systems
* credentials in the node's own command line or config (e.g. `--metrics.influxdb.password` or `--metrics.influxdb.token` for pushing metrics). Anything in the command line is visible to every process on the machine. If you need one, give it the narrowest scope possible (write-only, single bucket).

Quick check for obvious leftovers:

```bash
sudo -u sonic find / \( -path /proc -o -path /sys -o -path /dev \) -prune -o -readable \( -name '*.key' -o -name '*.pem' -o -name 'id_rsa*' -o -name 'id_ed25519*' -o -name '.env' -o -name 'credentials' -o -name '*keystore*' \) -print 2>/dev/null
```

**Validators:** the signing key (in the `keystore/validator` folder inside the data folder) and its password are the only secrets that belong on the server. The node needs both to sign, so it can always reach them. Everything else in this guide is about keeping attackers away from the node and noticing them quickly.

* The **validator wallet**, which holds the self-stake, must not be on the server. If you created it as a key file there (`sonictool account new`, [Validator Node](https://docs.soniclabs.com/pages/ycklmVREhe4bDmkq6Vvn#id-6.-create-a-validator-wallet) step 6), its file is directly in the `keystore` folder: move it to secure offline storage, and use it only from a separate, protected machine.
* Keep the **backup of the signing key** offline and encrypted, not on another server.
* On a validator, the check above lists the `keystore` folder. Make sure it holds nothing but the `validator` folder.

## 1.8 Don't run diagnostic or experimental builds in production

* Don't run the `sonicd-debug` build in production. It enables extra debug methods that can write files.
* The `Dockerfile` in the Sonic repository is marked experimental. Its final image is a full development image with a shell, compiler and download tools. Don't use it as-is in production (see [Tier 5.3](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-5-stay-current.md)).

## 1.9 Protect cloud credentials

Cloud servers can ask a special internal address (`169.254.169.254`, the "metadata service") for credentials. If the server has a powerful role attached, an attacker who controls the node can use it to take over other parts of your cloud account. This takes five minutes to fix:

* **Don't attach powerful roles** (IAM roles / service accounts) to node servers. Give them nothing, or the minimum.
* **AWS:** require IMDSv2 and set the hop limit to 1:

  ```bash
  aws ec2 modify-instance-metadata-options --instance-id <ID> \
    --http-tokens required --http-put-response-hop-limit 1
  ```
* **GCP / Azure:** use a service account / managed identity with no permissions, or none at all.

[Tier 2B](https://docs.soniclabs.com/sonic/node-deployment/node-hardening/tier-2-lock-the-node-in-a-box.md) also blocks the node from reaching the metadata service.

## ✅ Tier 1 checklist

* [ ] Running the latest release; following new releases on GitHub
* [ ] `debug`/`trace`/`admin`/`personal` removed wherever not strictly needed, and deprecated `ftm` removed, in **both** HTTP and WS lists; IPC off if unused
* [ ] RPC listens on `127.0.0.1` or a private IP (public RPC without a proxy: RPC ports only); validators: no RPC at all; pprof always on `127.0.0.1`
* [ ] No `*` in vhosts; no `*` in CORS / origins except on public RPC
* [ ] Firewall: only 5050 open to the world (plus the RPC or proxy port for public RPC); everything else only to known IPs
* [ ] Node runs as a non-root user with no shell, no sudo, no SSH keys; binary owned by root
* [ ] `--allow-insecure-unlock` and `--unlock` not used
* [ ] Custom JavaScript tracers off: no `--rpc.allow-js-tracers`, no `AllowJSTracers = true`
* [ ] No secrets on the machine (validators: only the signing key and its password; validator wallet and key backup kept elsewhere)
* [ ] No powerful cloud roles; metadata service protected
