Make the API/GraphQL server bind address configurable (respect LISTEN_ADDR)

[Marvelous2095]

Is there an existing issue for this?

• I have searched the existing open and closed issues

Is your feature request related to a problem? Please describe

Current behavior: LISTEN_ADDR only applies to nginx (UI, PORT). The API/GraphQL server (server/api_server/api_server_start.py) is started with a hard-coded app.run(host="0.0.0.0", port=graphql_port, …). With LISTEN_ADDR=127.0.0.1 (typical when running behind a reverse proxy, network_mode: host) the UI listens on loopback only, but GRAPHQL_PORT (20212) stays reachable on every interface:

$ ss -ltn | grep -E ':2021[12] '
LISTEN 0  511  127.0.0.1:20211  0.0.0.0:*
LISTEN 0  128    0.0.0.0:20212  0.0.0.0:*

Access is protected by API_TOKEN (a request without a valid token gets 403 Forbidden), so this is a hardening / defense-in-depth request, not a vulnerability report. It is still unexpected, and in this setup not needed: nginx already proxies to the API via http://127.0.0.1:${BACKEND_PORT} (netalertx.conf.template).

The docs also read as if LISTEN_ADDR covered the whole container ("Listen for connections on all interfaces" in the Docker Compose guide).

Verified on the 26.9.0 release image (app.run(host="0.0.0.0", …) at line 2132) and on netalertx-dev:latest (image f854bec8bc7c, revision cd1d0ed; same hard-coded value at line 2205).

Describe the solution you'd like

Proposal: make the API server bind address configurable. Either use LISTEN_ADDR for the API server as well, or add a separate variable (e.g. GRAPHQL_LISTEN_ADDR). It must stay opt-in / default to 0.0.0.0, because existing setups depend on the API being reachable from other hosts: for example Sync Hub nodes push to the hub's API port over the network (SYNC_hub_url='http://<hub>:20212', see #1698). A separate variable avoids changing behavior for anyone who already sets LISTEN_ADDR only for the UI.

Please also mention the scope of LISTEN_ADDR / the new variable in the docs.

Describe alternatives you've considered

• Workaround I use: mount a one-line patched copy of api_server_start.py (host="127.0.0.1") read-only into the container. It works, but has to be regenerated on every image update, and the image is pinned by digest in my setup.
• Host firewall rule for the port: works, but needs a firewall on the host and is easy to forget.

Anything else?

• Related, already closed: Feature request: make the API/GraphQL server bind address configurable (respect LISTEN_ADDR) #1801 (same request, closed because it was filed with the wrong template; this issue replaces it), SYNC push mode: device data is silently never sent — sync.py reads a path that doesn't exist in the Docker image #1698 (Sync push to http://<hub>:20212/sync, the reason the default has to remain 0.0.0.0).
• Related observation (also mentioned in New devices get literal '[]' string in devParentRelType instead of the configured default #1798): on a fresh volume the GRAPHQL_PORT environment variable is not applied to the GRAPHQL_PORT setting (container env GRAPHQL_PORT=20322, but the setting and app.conf stay at 20212 and nothing listens on 20322), so a second instance on a host network collides with the first one's API port.

Am I willing to test this? 🧪

• I will do my best to test this feature on the netlertx-dev image when requested within 48h and report bugs to help deliver a great user experience for everyone and not to break existing installations.

Can I help implement this? 👩‍💻👨‍💻

• Yes
• No

[jokob-sk]

Thanks for the detailed report.

Could you clarify the specific use case that requires the GraphQL server to bind to 127.0.0.1?

You mention running behind a reverse proxy and that nginx already proxies to the API over 127.0.0.1, but I’d like to understand what problem the current 0.0.0.0 binding causes in practice for your setup, given that the API is protected by API_TOKEN.

In particular, is this primarily about reducing the number of network interfaces the API is exposed on, or is there another requirement or network configuration driving the need for this?

[Marvelous2095]

Thanks for asking. There is no functional problem; it is about least exposure in a hardened setup, with two concrete aspects:

Setup: NetAlertX runs with network_mode: host on a Docker VM in a home LAN behind a Caddy reverse proxy on the same host. Policy for all services there: TLS terminates on the host and every backend listens on 127.0.0.1 only; anything else listening on a LAN interface counts as a finding. With host networking there is no port publishing (127.0.0.1:20212:20212) to restrict a service, so LISTEN_ADDR is the only knob, and it currently covers only the UI.

Why more than "fewer interfaces":

1. The API is plain HTTP on the LAN. API_TOKEN is sent as a bearer token in cleartext if someone talks to port 20212 directly, whereas via nginx/Caddy it is protected by TLS. In my setup nothing needs the API from other hosts (no Sync Hub), so it is exposure without benefit.
2. The server is started with app.run(host="0.0.0.0", port=graphql_port, threaded=True, debug=flask_debug, …). If someone enables FLASK_DEBUG, the Werkzeug debugger would be exposed on all interfaces. Not the case in my setup, but binding to loopback would remove that class of risk for people who don't need remote API access.

Because Sync Hub nodes do need the API remotely (#1698), I'd keep 0.0.0.0 as the default and make loopback opt-in, so no existing setup changes. I currently work around it with a read-only mounted patched copy of api_server_start.py (host="127.0.0.1").

[jokob-sk]

Thanks for clarifying. I understand the hardened setup and the reasoning for wanting the API bound to loopback.

For now, though, I’m not planning to make the GraphQL bind address configurable. The current 0.0.0.0 default is intentional because the API can be used directly by other NetAlertX instances, such as Sync Hub, and I don’t see enough general need for an additional configuration option to justify adding and maintaining it at this point.

I’ll close this as not planned for now. If I get more feedback or see a broader need for this, I can revisit it in the future.