Unable to Access Teku REST API from Local Network Client

[HannesZ]

Description

I am attempting to use the Teku REST API from a machine within my local network but different from the one running the Teku client. By default, the REST API access is restricted, so I have been trying to configure the Teku settings to allow access from within the local network.

Steps to Reproduce (Bug)

Setup details:

• --rest-api-enabled=true

• ufw status for port 5051 is allowed on the Teku machine

• I can successfully ping from the client machine to the Teku machine and back

• --rest-api-host-allowlist=* (This works, but it exposes the API globally, which I want to avoid)

Attempted configuration (preferred solution):

teku --rest-api-enabled=true \
     --rest-api-interface=0.0.0.0 \
     --rest-api-port=5051 \
     --rest-api-host-allowlist=192.168.1.*,localhost,127.0.0.1

Additional attempts (all unsuccessful):

• --rest-api-host-allowlist=192.168.1.0/24,localhost,127.0.0.1
• --rest-api-host-allowlist=192.168.1.111,localhost,127.0.0.1 (allowing only the specific client machine)
• --rest-api-host-allowlist=my_host,localhost,127.0.0.1 (where my_host is the result of hostname on the client machine)

Expected behavior:
Get a result when running the following (or similar) on the client machine:

curl http://192.168.1.112:5051/eth/v1/beacon/states/head/validators?status=pending_queued

Actual behavior:
These configuration run without any errors, but from the client machine, I receive the following error when trying to access the API:

{
    "title": "Host not authorized",
    "status": 403,
    "type": "https://javalin.io/documentation#forbiddenresponse",
    "details": {}
}

Versions

• Software version: teku 24.8.0
• Java version:

openjdk 21.0.4 2024-07-16
OpenJDK Runtime Environment (build 21.0.4+7-Ubuntu-1ubuntu224.04)
OpenJDK 64-Bit Server VM (build 21.0.4+7-Ubuntu-1ubuntu224.04, mixed mode, sharing)

• OS Name & Version: Ubuntu 24.04 LTS

[rolfyone]

Hey - thanks for raising this, we'll take a look and see if we can reproduce it...

[rolfyone]

This got interesting.
From what I can see, its a lot less technical than to ever allow things like 192.168.1.0/24, 192.168.1.* and that does appear to be what's documented, so all of that I understand.
It does appear that the filtering class is actually for some reason returning the server host ip address to filter on. I'm not sure if this was always the behaviour, but it looks like it definitely isn't the intent.

I ended up talking to the software team creating the HTTP server we use, because it seemed at odds with documented behaviour.

Technically, we referenced the http context host, and that (at least now) is the server address, not the client address, so that's a bug. From that regard, you'd have to use the IP address of the server to allow access to anyone accessing the server, and that is clearly not our intent.

context also has ip, and this is the caller address. I'll make this change and thats more like what our initial intent was.

The logic is also more limited perhaps than it seems. While we do allow '*' to allow literally from any IP, we don't use it as a mask, so 192.168.1.* will not match that entire subnet. Also, subnet masking in any form like /24 has not been implemented.

After my change, you'll at least be able to specify that 192.168.1.11 can call to the server on 192.68.1.12, so that's a great improvement, but for subnet filtering like you'd find in firewalls, i'd suggest using your hosts firewall in preference to this relatively simple allow list that we've provided.

In the short term, you could potentially allow '*' and then control actual access via firewall rules, this is the only real workaround I have to offer...

[benjaminion]

Technically, we referenced the http context host, and that (at least now) is the server address, not the client address, so that's a bug.

No - it should be the server address; that is correct. The clue is in host in --rest-api-host-allowlist - host is the Teku node/server.

that is clearly not our intent.

It is exactly the intent.

The rest API host allowlist is for protection against DNS rebinding attacks. You need to list any hostnames and IP addresses that your Teku node is known by on the network, so CIDR and * notation doesn't make sense here. It is not a list of remote addresses that are allowed to access the API - you should use a firewall to put restrictions on that. The Teku docs are hopeless on this, and it's a very common stumbling block.

In this specific case, @HannesZ should use something like

--rest-api-host-allowlist=192.168.1.112,localhost,127.0.0.1

since 192.168.1.112 is the address of the Teku node on the network. The address of the client machine is irrelevant here.

ETA: If I recall correctly, this protection can be switched off by using --rest-api-host-allowlist="*".

[HannesZ]

Yes, that works. Thanks also for the clarification!

[rolfyone]

hrm ok - I stand corrected! Thanks @benjaminion ! I'll close the PR.

[benjaminion]

Might be a good time to improve the docs for this. The Besu equivalent docs are equally as bad.