SSerguey Asael Shinder
Java coding notes: the JVM, and writing software that lasts

Serguey Asael Shinder: The address on the socket is not the caller: Bitcoin Core's Tor whitelist bug

· by Serguey Asael Shinder / Serguey Shinder

On 10 November Bitcoin Core published the details of CVE-2025-62860. The node has a -whitelist option that lifts denial-of-service limits and privacy protections for trusted peers, and it can be set as an IP range. For an inbound Tor peer, the disclosure explains, the IP address Bitcoin Core sees is that of the Tor daemon, which usually runs on the same machine or the local network. If the configured range covered the proxy, every inbound Tor connection inherited the trust.

This was not an exotic setup. According to the disclosure, popular node packages bundled Bitcoin Core with a Tor daemon and set -whitelist to a range matching that daemon, and some client software required the option. The result was thousands of reachable mainnet nodes treating all incoming Tor traffic as trusted. The fix, in 30.0, 29.2 and 28.3, is to never whitelist inbound connections received on an onion bind.

The code was not wrong about the address. The address really was local. It was wrong about what the address meant: on that path, the socket's peer was the proxy, and the proxy forwarded strangers.

The Java version of the same bug

Any Java service behind a reverse proxy, a load balancer or a sidecar has the same shape. The Jakarta Servlet javadoc for ServletRequest.getRemoteAddr() says it returns the IP "of the remote end of the connection on which the request was received". Behind a proxy, the remote end of that connection is the proxy. A filter like this one is easy to write and easy to approve in review:

// "only callers from inside the cluster may reach /admin"
String ip = request.getRemoteAddr();
if (ip.startsWith("10.") || ip.equals("127.0.0.1")) {
    chain.doFilter(request, response);
} else {
    response.sendError(403);
}
Serguey Asael Shinder: The address on the socket is not the caller: Bitcoin Core's Tor whitelist bug
The address on the socket is not the caller: Bitcoin Core's Tor whitelist bug — Serguey Asael Shinder

If an ingress or a local agent terminates the connection, every request from the internet reaches the application from an address inside 10. or from 127.0.0.1, and the check passes for everyone. Reading a forwarding header instead does not fix it by itself, because a header is only as trustworthy as the hop that set it.

What to take from it

Three habits follow, none of them specific to Bitcoin.

First, decide trust by how a connection arrived, not by the address it shows. Bitcoin Core's fix keys on the listener, the onion bind. In a Java service the equivalent is a separate port or connector for internal traffic, or mutual TLS, so that the question "where did this come from" is answered by something the caller cannot choose.

Second, when an option grants trust by address range, ask what else shares that range. A sidecar, a VPN endpoint, a health checker and a proxy all look "local".

Third, notice who set the option. In the Bitcoin case it was often the vendor of a bundled package, not the operator. A default shipped in a container image or a Helm chart is configuration someone else wrote for you, and the disclosure is a good reason to read it.