APIs used by xySat - possibility to identify xySat traffic

[rfx77]

Since i would like to have a clearer isolation between the Admin Webinterface and what xySat is allowed to access on the xyOps Coordinator, i would like to do a Caddy Reverseproxy configuration which only allows xySat calls from "unrestricted" networks and restricts all other traffic to management stations (Webadmin, Webhooks, Configuration API,...)

I did not find a list of http: and ws: endpoints which are needed for xySat to work. Would it be possible to get such a list or could you steer me in the right direction so i could work it out myself (if its not very hard).

Since xySat has a activation process which seems to involve some sort of authentication, is there a cockie or some identifiable information in the requests which i could use on the reverse-proxy to identify that its a xySat request. (Bearer Auth, Basic Auth, Cookie, Token or URL parameter)

Another alternative would be if xySat could use a client certificate in its calls (secure=true). we could then validate this certificate on the proxy easily.

Here is how the nodejs ws library can use client certificates: https://github.com/websockets/ws/blob/ae1de54330cef77e487548890fabfeb9aae1d83d/test/websocket.test.js#L4062

[jhuckaby]

Hi Franz,

I think I understand what you are trying to achieve, but unfortunately there is no single HTTP header, cookie, bearer token, or URL parameter that reliably identifies every request originating from xySat.

The main xySat connection is a WebSocket connection to /. The satellite identifies and authenticates itself inside the WebSocket protocol after the HTTP upgrade has completed, so Caddy cannot distinguish a satellite socket from another WebSocket client by inspecting the initial HTTP request alone.

xySat also makes several regular HTTP requests. In the current implementation these include health checks, job input downloads, job output uploads, final job updates, and install or upgrade requests. Authentication is not carried in one common place across all of these. Depending on the operation, it may be part of the WebSocket messages, the request body, or the query string. Some install and upgrade steps are also performed by external tools such as curl, wget, or PowerShell rather than by the Node.js process.

There is one additional complication: jobs running on a satellite are deliberately given the conductor base URL. Marketplace Plugins, the xyOps SDK, and custom job scripts may use that URL to call any xyOps API for which you have supplied a suitable API key. From the reverse proxy's point of view, those requests originate from the same worker host as xySat itself. This means a proxy cannot reliably separate "the xySat process" from "a job launched by xySat" based on the source address or a standard request marker.

For reference, a worker-only proxy would need at least the following kinds of traffic today:

• A WebSocket upgrade on /
• /health and /api/app/ping
• /api/app/satellite/* for installation, configuration, and upgrades
• /api/app/upload_job_file and /api/app/finish_job
• Job input downloads under dynamically generated /files/* paths
• Any additional /api/app/* endpoints used by your Marketplace Plugins, SDK code, or job scripts

I would treat that as an implementation snapshot rather than a permanent API contract. The set can change as xyOps evolves, and the final item is necessarily specific to each installation. All these will be documented in the near future, I just haven't been able to cover it yet.

Client certificates have a similar limitation, alas. Node.js TLS options would only cover requests made through the Node.js networking stack. They would not automatically configure the curl, wget, or PowerShell processes used during bootstrap and self-upgrade. Requiring a client certificate at Caddy would therefore break parts of the satellite lifecycle unless you added an external tunnel or gateway that presents the certificate on xySat's behalf.

The most practical approaches I can suggest are:

1. Use a separate worker-facing hostname or listener. For example, keep the complete UI and API on an admin hostname that is reachable only from management networks, and point satellite.config.host, satellite.config.port, and satellite.config.secure at a worker hostname. On the worker hostname, allow WebSocket upgrades and the routes listed above. You would also need to allow every API route legitimately used by jobs. This reduces exposure, but it does not create a security boundary between xySat and its jobs.

2. Use source network controls. If the worker systems have known source addresses, VPN addresses, or dedicated subnets, Caddy or a firewall can allow the worker listener only from those networks. In this model, the worker host is the trusted identity. All processes on that host with network access are inside the same trust boundary.

3. Use infrastructure-level process isolation if you need a stronger boundary. A dedicated VM, container network namespace, egress gateway, or local TLS tunnel can give the satellite service its own network identity and can present an mTLS certificate externally. Jobs must then run under a different network identity, or they will still share the satellite's access. This can be done outside xyOps, but it is an operating-system or network architecture project rather than a Caddy header rule.

For authorization, I also recommend using separate, least-privileged API keys for jobs and supplying them only through the Secret Vaults that need them. The satellite's own authentication token is used for satellite-specific operations and is not a general administrator credential. Job API access should be controlled by the privileges of the API key assigned to that job, even when both kinds of traffic pass through the same proxy.

My practical recommendation would be the separate worker hostname combined with a worker IP or VPN allowlist, while treating each worker host and the jobs it runs as one network trust zone. Then keep job API keys narrowly scoped. If the requirement is to distinguish the xySat daemon from every job process on the same machine at the reverse proxy, xyOps does not currently provide a reliable request-level identity for that.

I'm sorry if this doesn't help your issue.

[rfx77]

Hi!

Thanks for the answer.
I did some investigation of the login process.

So if i deny access to

• http to / (not ws)
• http to /api/app/config
• http to /api/user/login

from anywhere other then my management network, noone could get a login page and noone could login.

Do you think this can work. I really dont want anyone on the servers where my agents run to be able to login to the coordinator.

I do not se a different way to secure the coordinator from the servers because i have to open the web-interface according to your description and firewalling cannot apply here.

[jhuckaby]

Hi Franz,

Thank you for clarifying the goal. I understand the use case now, and yes, I think this approach can work.

Rather than trying to identify every request made by xySat, you can prevent clients outside your management network from establishing or resuming a human user session.

I would recommend denying all methods for the following paths outside the management network:

/
/index.html
/api/app/config*
/api/user/*

The root path should still allow WebSocket upgrade requests because xySat connects there. Ordinary HTTP requests to both / and /index.html can be denied.

I recommend blocking the entire /api/user/* namespace rather than listing individual endpoints. This includes:

/api/user/login
/api/user/resume_session
/api/user/external_login
/api/user/forgot_password
/api/user/reset_password

/api/user/resume_session does not create a new session from a username and password, but it does recover an existing session and returns the information needed by the web application, including the CSRF token. It should therefore be blocked as well.

There is also an API routing detail to be aware of. xyOps may accept additional path components after an API name, so an exact match against only /api/user/login may not be sufficient. For example, /api/user/login/v1 can reach the same API handler. Blocking /api/user/* avoids that issue. For the same reason, I suggest matching /api/app/config* rather than only the exact path.

xySat itself does not use the /api/user/* namespace, so blocking it should not interfere with the satellite. Jobs using Marketplace Plugins, the xyOps SDK, or API keys normally use /api/app/*, which remains available.

One limitation is worth mentioning: this prevents someone on a worker network from creating or resuming an interactive user login. It does not invalidate a session ID that has already been obtained elsewhere. A valid session can be presented directly to other API endpoints or to the browser WebSocket.

If you also want to prevent existing human sessions from being used through the worker-facing proxy, you could reject requests containing either of these request headers outside the management network:

Cookie: session_id=...
X-Session-ID: ...

xySat does not use either of those headers for its own authentication, and API-key-authenticated jobs use X-API-Key instead.

So yes, with those adjustments, I think your Caddy approach is reasonable for this particular security boundary. I would test installation, reconnection, file transfer, job completion, and self-upgrade afterward to verify the final proxy rules.