Feature: Expose Nebula hostmap on a socket

[HenryGrahamRivian]

This MR introduces an info server socket to serve information about the Hostmap. This is in reference to #1398.

Required config file additions

info:
  listen: 127.0.0.2:5555

Example curls

curl http://127.0.0.2:5555/host/100.100.100.100 {"curve":"P256","details":{"groups":["group1","group2"],"isCa":false,"issuer":"6a20d559ef58a72a2c8e599284fc11bfb95a61b21cd55ec51c0bdd59b4582537","name":"demo","networks":["100.100.100.100/11"],"notAfter":"2026-11-29T11:22:32-06:00","notBefore":"2025-1-03T12:00:11-05:00","unsafeNetworks":["0.0.0.0/0"]},"fingerprint":"c175687fec1ace05821b77b39f4b7520d1839e948fb7140570c0c4ffb99ac67f","publicKey":"77de6cf8a3541e527b6517532d36c0b3e01cdfcf54fe5270b7538881d5886e1885bbaa05b919a17b1d2b7dd49b5bfb103725ef1cf25c6a6212e00943caf9d8191e","signature":"9ec4e33140a71ee6e3c5ccb305f8920c3445d868b24b58f5217f84928e4dca2b8a408c32d108c5b99af0bf1f395a4468b4d21690d1fad1591a216e48d0da5a8c7726f2b34f54","version":2}% curl http://127.0.0.2:5553/hostmap {"demo":{"vpnAddrs":["100.100.100.100"],"lastHandshakeTime":"2025-08-26T09:07:13.609073708-05:00","groups":["demo1","demo2"]},{"demo2":{"vpnAddrs":["100.100.100.101"],"lastHandshakeTime":"2025-08-26T09:07:13.609073708-05:00","groups":["demo3","demo4"]}}

[johnmaguire]

Thanks for the contribution. The SSH debug server is definitely a bit painful to setup and I would love to see an easier-to-use debug interface merged. Some background:

• The SSH server requires authentication which is somewhat painful to configure, but does offer some security value. In Feature: Expose Nebula API as a socket on the local machine or Nebula interface #1398 we discussed potentially protecting the HTTP API via Nebula firewall rules. If that is the plan, we might want to avoid a listen host and instead only listen on the Nebula IP.
• Another potential option for securing this API would be HTTP Basic Auth, with either a username/password combo (perhaps ideal for logs) or simple Bearer tokens.
• Another idea floated in Feature: Expose Nebula API as a socket on the local machine or Nebula interface #1398 was to only expose this as a Unix socket protected by file system level permissions - cURL supports querying Unix domain sockets since 2015, but to expose them remotely you'd need to create a separate forwarding binary.

That said, on another ticket related to Prometheus service discovery, a user made the point that the DNS server already allows exposing some information publicly without authentication: #920 (comment)

How were you thinking about security around this API?

[JackDoan]

How were you thinking about security around this API?

https://github.com/slackhq/nebula/pull/1457/files#diff-f17225d549b302ca95e2dc524a83c9ad067923eb49ef688e8093c6d45a3e7384R86 there's a todo to refuse (or maybe just warn?) if you bind to something silly. Refusing to bind to (non-localhost || non-nebula-ip) feels right to me.

IMO, this HTTP API would be informational, a-la DNS. The driving use-case is to make "nebula aware" applications that can use stuff like group information to make authorization decisions. (such as, you need the api-user group to get past the firewall and talk to the app, but api-superuser lets you call other endpoints, without requiring the app to bind on two ports)

^ this is what makes binding to localhost valuable imo. If we only bound to the nebula IP, applications on the same host would need to discover the nebula IP to use it, which isn't hard, but it's less-pleasant.

[HenryGrahamRivian]

I'd be happy to implement the TODO for interface binding. Personally, I think there is value in having the option to bind to non-localhost interfaces (for example, a proxy terminating nebula before the service in Jacks example) so I'll be starting out with the warning implementation. I'd love to hear other opinions though.

[nbrownus]

We discussed this PR a little today and here are the takeaways

1. The built-in ssh server is neither easy to configure or friendly to use as an api.
2. There continues to be a desire to have some other method for probing nebula.
3. There is a general discomfort in having the method be unauthenticated.
4. There is a general desire in having the method require as few required libraries as possible to make functional as an api.

One option we keep coming back to is a simple unix domain socket, likely in SOCK_STREAM mode, communicating entirely via plain JSON. This provides an api that requires very few libraries and is about as straightforward as you can get to interact with. Security relies entirely on the local filesystem permissions which has decent properties assuming the socket can't be created by a less privileged user than the one running nebula. SO_PEERCRED or SCM_CREDENTIALS can be used to further raise the level of confidence the client has that it is speaking with nebula directly and could be used by nebula as well to restrict which programs it would willingly interact with, this is not 100% portable though.

Another option would be to do plain JSON over HTTP, which is a bit more ergonomic but raises the clients required library complexity and includes attack surface for the client if it were to be speaking with an adversarial nebula or man-in-the middle.

There are many other possibilities as well.

The argument to having some authentication method mainly comes down to a defense-in-depth strategy. By requiring something here we should be able to avoid low effort drive-by attacks but obviously anyone with root on the machine could nullify the entire point.

In summary: It remains to be unclear what specifically we are trying to accomplish with the api and what amount of security we should try to sprinkle on it, how ergonomic it should or shouldn't be, or how much the person configuring it should need to understand it to avoid an information disclosure foot gun.

[HenryGrahamRivian]

This was stuck in my head so I put together a rough picture of what this approach might look like. If this is more the direction y'all were thinking I'll go ahead and clean this up.

Example usage

echo '{"command":"hostmap"}' | sudo nc -U /tmp/nebula.sock