XySat security / risks

[W13N3N]

First off, thanks for making such a great tool! Even right after the 1.0 launch, it looks very polished and most things are working OOTB for me ❤️ This looks very promising for the future of XyOps.

I'm fairly new to the world of Linux (Unraid, in my case). I recently migrated my homelab server from Windows to Unraid because most of my native apps were also available as Docker containers, and I wanted to achieve a more secure/controlled environment.

Therefore, security is a top priority for me. Since Linux is still new to me, I’m trying to wrap my head around a few things. Does using the XySat companion app introduce extra security risks? And how is the system built with security in mind? I've read through the documentation—specifically the satellite section—but I don't fully understand how the XySat agent works, what permissions it requires, and if this introduces potential vulnerabilities.

I understand that using a tool to manage my host(s) comes with certain risks because it needs elevated privileges to function, but I want to weigh those risks against the advantages the tool provides.

So far, I haven't installed the XySat agent yet; I've only used the Remote SSH Plugin with a public/private key stored in the vault to run events on my Unraid host.

Could someone explain how the XySat agent works, what rights it has, and if it introduces more security risks compared to using the Remote SSH Plugin?

Thanks in advance!

[jhuckaby]

These are great questions, thank you! Please give me a few hours to write a document that properly explains all this.

[W13N3N]

Thanks Joseph for your quick response! Take your time writing the document, I’m not in a hurry.

[jhuckaby]

Whew! Okay, all done. Here's my reply, and a link to the new security document at the bottom:

First of all, thank you for your kind words, and for checking out xyOps! ❤️

Short answer: yes, installing xySat does expand the trust surface a bit, but it is not doing anything fundamentally different from giving xyOps another authorized way to execute work on that host. A good mental model is: installing xySat is similar to authorizing a persistent automation channel on the server, much like adding an SSH key for unattended access. If an attacker got hold of your xyOps admin account or another credential that lets them schedule privileged work, they could use that access to run commands on the host, just as they could if they had the private key for your Remote SSH setup. So there is additional trust involved, but it is not a mysterious hidden backdoor. It is an explicit remote-execution path that you choose to authorize.

The important distinction is how xySat is built and constrained. xySat does not open any inbound ports, does not run a socket listener, and does not expose its own server API. It only makes an outbound connection back to the xyOps conductor and authenticates with an auth token. On the xyOps side, the platform is built with a lot of guardrails: passwords are bcrypt-hashed, sessions and CSRF tokens are cryptographically generated, cookies are HttpOnly with SameSite=Lax by default, API keys are never stored in plaintext, and Secret Vault values are encrypted at rest with AES-256-GCM. Also, by default, ordinary users cannot create plugins or edit admin-locked fields like the Shell Plugin script body or the HTTP Request plugin URL, so the dangerous execution surfaces are admin-gated from the start.

As for what rights xySat has: by default it is often installed as root or administrator so it can register itself as a startup service and perform self-upgrades. But that does not mean every job has to run with those same privileges. On POSIX systems, xySat can launch jobs as a different UID/GID, and that is the recommended hardening path for production. In other words, you can install xySat with enough privilege to manage itself, while still forcing normal jobs to run as a low-privilege service account. You can also install and run xySat manually as an underprivileged user, but then you give up some convenience, mainly self-upgrade and the ability to switch child processes to other users.

Compared to the Remote SSH Plugin, the tradeoff is mostly this:

• Remote SSH feels smaller because there is no resident agent. You are reusing SSH, a stored key, and the permissions of the remote account.
• xySat adds a resident agent, but in exchange you get native job execution, real-time logs, monitoring, file handling, tighter integration, and no need to manage separate SSH orchestration for every job.
• Security-wise, the real question is not just "agent or no agent", but "what privileges does the remote execution path actually have?" If your SSH key logs into a powerful account, that can be just as sensitive as xySat. If xySat is configured so jobs run as a locked-down user, that can actually be a very solid production setup.

So I would frame it this way:

• If you only want occasional command execution and you are more comfortable with SSH, the Remote SSH Plugin is perfectly reasonable.
• If you want the full xyOps experience on that host, including monitoring, alerting, streaming job output, file upload and download, and native execution, xySat is the better fit.
• In either case, the biggest security factor is the privilege level of the account or process actually running the work.

I also just published a new Security Overview document that goes through all of this in more detail, including xySat, secrets, API keys, sessions, cookies, CSRF, and privilege boundaries. That should help fill in the implementation details behind the high-level answer.

[W13N3N]

Thank you for taking the time to provide this well-written, detailed, and transparent documentation on how xyOps is designed with security in mind. It is incredibly useful and interesting for those of us who take security seriously.

As an IT Project Manager (primarily in the Windows world, with some technical roots from the Server 2003 era 😅), the document was a very accessible read. However, I did have to fall back on AI to fully grasp a few of the deeper technical parts. Compliments from both me and my AI assistant 😁 on this well-designed, enterprise-grade architecture!

Also, thanks for pointing out that it's possible to execute shell jobs/scripts as another user; I hadn't discovered that feature myself yet. Since this needs to be configured within the plugin itself, and given that different jobs might require different user rights, is the intended workflow to clone the Shell Script plugin so you have multiple versions with specific permissions/settings?

What is the best way for installing xySat on Unraid. Given its RAM-based architecture, any standard install is lost after a restart. Is triggering the install URL at boot a supported way to keep the satellite linked?

Lastly, are there any plans to implement 2FA for logging into the xyOps portal?

Have a great weekend and keep up the great work! ❤️

[jhuckaby]

Thank you so much, and very glad to have you aboard! 😃

It's so funny, I've also worked in the industry for about as long as you have, but always on Linux, and I only just recently learned Windows for running xySat on it. So we had basically opposite or criss-crossed experiences between the two worlds 😉

To answer your questions:

is the intended workflow to clone the Shell Script plugin so you have multiple versions with specific permissions/settings?

Exactly -- you got it. I kept the UID/GID permission thing at the Plugin level, because I suspect most people will set it to a single "service account", and use that for everything, or maybe have a few other Plugins (or clones) tied to specific user accounts or groups.

What is the best way for installing xySat on Unraid. Given its RAM-based architecture, any standard install is lost after a restart. Is triggering the install URL at boot a supported way to keep the satellite linked?

Forgive me, I am very new to Unraid, but I think it is a Docker-compatible container management platform, right? If so, all you need is a volume mount for the xySat configuration, plus an environment variable to point the configuration file to live inside the mount. This was very recently added to the one-liner Docker install command in xyOps:

docker run --detach --init --restart unless-stopped -v xysat-conf-dmnj7jk65:/etc/xysat -v /var/run/docker.sock:/var/run/docker.sock -e XYSAT_config_file="/etc/xysat/config.json" -e XYOPS_setup="http://m2ni.lan:5522/api/app/satellite/config?t=549c74d29660000000000000000000000000a1f89af03" --name "xyops-worker-dmnj7jk65" --hostname "docker-dmnj7jk65" ghcr.io/pixlcore/xysat:latest

So you just need to setup the "equivalent" attributes in Unraid. Does Unraid come with a Docker CLI? If so, you should be able to use the "Add Server..." button in xyOps, and copy / paste the Docker one-liner install command, executing it on your Unraid host.

The key to making the container "last" across restarts and upgrades is the named volume mount (-v xysat-conf-dmnj7jk65:/etc/xysat), and also repointing the config file to live inside the mount (-e XYSAT_config_file="/etc/xysat/config.json").

But again, I have to stress that I am a total Unraid n00b. I only learned about its existence 3 days ago, when I found that someone added the xyOps app to the Unraid portal marketplace, but they messed it all up. More info in this discussion thread here: #230 -- I have been unable to contact the author, and honestly not sure what to do 😞

The last thing I want to mention, which is something that EVERYONE is getting tripped up on (my fault in not making this more obvious in the docs), is that before you start adding servers, you need to setup your primary xyOps conductor to have a hostname that resolves and is accessible on your network. Meaning, you can't just use a default docker container hostname or something like "xyops01". You need to use a "real" hostname that resolves using your internal DNS system, Tailscale Magic DNS, or use something like /etc/hosts files on all your servers.

The bottom line is, xySat needs to be able to establish a HTTP connection back to the primary conductor in order to install and run, and that is all done via the "hostname" of the server or container where xyOps is running.

Lastly, are there any plans to implement 2FA for logging into the xyOps portal?

The current way to do this is to use SSO, and then simply use an IdP (Identity Provider) that supports 2FA. There are several open source ones you can use.

I may add "native" support for 2FA and passkeys in the future, but it's currently not a high priority, as most companies use SSO anyway.

Have a great weekend!

[W13N3N]

It's so funny, I've also worked in the industry for about as long as you have, but always on Linux, and I only just recently learned Windows for running xySat on it. So we had basically opposite or criss-crossed experiences between the two worlds 😉

Who knows we can learn something from each other 😁

is the intended workflow to clone the Shell Script plugin so you have multiple versions with specific permissions/settings?

Exactly -- you got it. I kept the UID/GID permission thing at the Plugin level, because I suspect most people will set it to a single "service account", and use that for everything, or maybe have a few other Plugins (or clones) tied to specific user accounts or groups.

great, I will start using it this way.

Forgive me, I am very new to Unraid, but I think it is a Docker-compatible container management platform, right? If so, all you need is a volume mount for the xySat configuration, plus an environment variable to point the configuration file to live inside the mount. This was very recently added to the one-liner Docker install command in xyOps:

Haha no problem, i'm new to Unraid aswell, just switched 2 weeks ago 😅 and am still learning on the job.

The onliner you provided isn't really usefull in my case, to give you a better understanding of how Unraid works, i'll provide you with some extra context. Because EN isn't my native language i requested some help 😅

"AI Mode ON"

What is Unraid?
Unraid is a popular NAS operating system based on a minimal Slackware Linux distribution. Its primary focus is storage management and running Docker/VMs, but it has a very specific architecture that differs from standard persistent Linux distros (like Ubuntu or Debian).

The Key Limitations for xySat:

RAM-based Root Filesystem (Volatile):
Unraid loads its entire OS into a RAM disk at boot. This means that directories like /opt, /etc, and /usr are completely wiped and reset to a "factory state" on every reboot.

Problem: If the xySat installer places the agent in /opt/xyops, it disappears after a restart.

Problem: The config.json containing the Server ID is lost, causing the Conductor to see the machine as a "new server" every time it boots and the installation of XySat is ran by User Scripts.

No Modern Init System (No systemd):
Unraid is extremely lightweight and does not use systemd, upstart, or openrc. It uses basic BSD-style init scripts.

Problem: The pixl-boot module used in the xySat installer fails immediately because it cannot find systemctl. This prevents the agent from being registered as a background service.

The Persistence Strategy:
On Unraid, persistent data must live on the Array or Cache (usually mounted under /mnt/user/appdata/ or /mnt/user/[share_name]/).

Why the "Docker-only" approach isn't enough: (in my case)
While Unraid is great at Docker, many users (like myself) want to use xySat to manage the Host itself—monitoring physical disk health, array status, or triggering native Unraid backup scripts (rsync). A standard Docker container is too isolated for these host-level tasks unless granted extreme (and often unsafe) privileges.

Proposed Improvements for the xySat Installer:

Custom Config Path: It would be great if the installer had a flag like --config-path /path/to/persistent/storage/config.json. This would allow the binary to stay in RAM (fast) while the "Identity" stays on disk.

Manual Start Flag: A way to complete the installation without the installer erroring out when it fails to find an Init system (similar to what --no-service attempts to do, but more robust for Slackware).

Binary-only Download: A simplified "binary-only" download for non-standard distros where we can handle the startup logic ourselves via Unraid's "User Scripts" plugin.

Summary of my workaround:
I managed to get it working by using a custom shell script that runs at Array Start. It:

Downloads the agent into RAM.

Uses the --no-service flag to ignore the systemctl error.

Manually copies a pre-existing config.json from a persistent Unraid share into the RAM directory before launching.

Launches the agent as a background process manually via node main.js &.

This keeps the server "Online" in the dashboard with a consistent ID across reboots!

Here's the script i'm using:

Persistent xySat Installation Script for Unraid

Since Unraid runs from RAM and lacks systemd, I developed this script to handle the installation, identity persistence, and background execution. It should be executed via the User Scripts plugin at "Array Start".

Also it requires a xyops API key, i gave this key only the rights to add new servers.

#!/bin/bash

# --- CONFIGURATION ---
# Replace these values with your actual xyOps server IP and your Permanent API Key
# In case your xyops server runs on another machine
XYOPS_IP="192.168.x.x"
HOSTNAME="xyops"
# Required to connect the agent to the XyOps server
API_KEY="YOUR_PERMANENT_API_KEY_HERE"
# required to store the config.json file in a persistent folder, you can change this to whatever share/disk you want
PERSISTENT_FOLDER="/mnt/user/xysat"

echo "--- Starting xySat Unraid Persistent Installation ---"

# 1. DNS Bypass
# Unraid often struggles with local DNS for custom hostnames in the terminal.
# We manually map the xyOps hostname to its IP in /etc/hosts.
echo "Step 1: Mapping hostname to IP in /etc/hosts..."
if ! grep -q "$HOSTNAME" /etc/hosts; then
    echo "$XYOPS_IP   $HOSTNAME" >> /etc/hosts
fi

# 2. Prepare Persistent Storage
# Ensure the persistent storage on the array exists with correct permissions.
echo "Step 2: Preparing persistent folder at $PERSISTENT_FOLDER..."
mkdir -p "$PERSISTENT_FOLDER"
chown -R nobody:users "$PERSISTENT_FOLDER"
chmod -R 777 "$PERSISTENT_FOLDER"

# 3. Perform Installation in RAM
# Use --no-service to bypass the 'systemctl' check which fails on Unraid.
echo "Step 3: Installing xySat agent into volatile RAM (/opt)..."
curl -s "http://$HOSTNAME:5522/api/app/satellite/install?t=$API_KEY" | bash -s -- --no-service

# 4. Identity Restoration
# Restore config.json from the array to maintain the same Server ID across reboots.
echo "Step 4: Restoring or initializing persistent identity..."
if [ -f "$PERSISTENT_FOLDER/config.json" ]; then
    echo "Found existing config.json. Restoring identity..."
    cp "$PERSISTENT_FOLDER/config.json" /opt/xyops/satellite/config.json
else
    echo "No existing config found. Saving initial config for future reboots..."
    sleep 2
    cp /opt/xyops/satellite/config.json "$PERSISTENT_FOLDER/config.json"
    chown nobody:users "$PERSISTENT_FOLDER/config.json"
fi

# 5. Start the Agent in the Background
# Manual launch since systemd is unavailable. Logs are sent to /var/log/xysat.log.
echo "Step 5: Launching xySat agent in the background..."
cd /opt/xyops/satellite
./bin/node main.js --hostname "hostnameoftheserver" > /var/log/xysat.log 2>&1 &

echo "--- xySat setup complete. Agent is now running! ---"

But again, I have to stress that I am a total Unraid n00b. I only learned about its existence 3 days ago, when I found that someone added the xyOps app to the Unraid portal marketplace, but they messed it all up. More info in this discussion thread here: #230 -- I have been unable to contact the author, and honestly not sure what to do 😞

I saw the discussion, this is caused because any random person can add plugins/apps to the Unraid Application Store. Hopefully you can get in touche with the creator to adjust it. Maybe you can report the plugin, here's a support page for the Unraid Application Store (https://forums.unraid.net/topic/38582-plug-in-community-applications/)

The last thing I want to mention, which is something that EVERYONE is getting tripped up on (my fault in not making this more obvious in the docs), is that before you start adding servers, you need to setup your primary xyOps conductor to have a hostname that resolves and is accessible on your network. Meaning, you can't just use a default docker container hostname or something like "xyops01". You need to use a "real" hostname that resolves using your internal DNS system, Tailscale Magic DNS, or use something like /etc/hosts files on all your servers.

I first read trough the documentation (for the installation part) and for me this was clear at the beginning, maybe you could highlight it to gets people's attention?

Lastly, are there any plans to implement 2FA for logging into the xyOps portal?

The current way to do this is to use SSO, and then simply use an IdP (Identity Provider) that supports 2FA. There are several open source ones you can use.

I may add "native" support for 2FA and passkeys in the future, but it's currently not a high priority, as most companies use SSO anyway.

Great i will add SSO then.

And if you ever need some help with testing on Unraid please let me know.

[jhuckaby]

Oh wow, your Unraid workaround is very clever! Nice job!

Yikes, I didn't realize how crazy restrictive the Unraid host environment is. That's very limited 😳

So, you should be able to install xySat into any directory you want (e.g. /mnt/something/) if you grab the the tarball directly and decompress it yourself:

https://github.com/pixlcore/xysat/releases

Guessing you'd want the linux-x64 variant for your Unraid host. I doubt the self-upgrade system will work when it's living in a custom directory, but the basic functionality should all be there.

In fact, the ONLY time the /opt directory is mentioned across the entire xySat codebase is for setting the PATH environment variable in the control.sh script:

https://github.com/pixlcore/xysat/blob/main/control.sh#L22

So if you set the PATH first, e.g. export PATH=$PATH:/mnt/xysat/bin, it should be able to find its Node.js executable.

You can generate the xySat configuration file by making a request to your xyOps conductor server, using the hash token from the one-liner install command. Like this:

curl "http://YOUR_XYOPS_SERVER:5522/api/app/satellite/config?t=TOKEN_HERE" > config.json

Anyway, just throwing out some options if you are interested, but it sounds like you already have a working solution. Cheers!

Oh, and thank you for all the advice around the Unraid marketplace. I will try to contact them via their support system.

Have a great rest of your weekend!

[W13N3N]

Thanks! For now i will stick to my solution cause i don't want to break the auto update feature and this seems to work for me. If needed, feel free to use my information/script for your documentation.

Enjoy the rest of your weekend!

[W13N3N]

@jhuckaby one last question;

When i use my script to install the xysat plugin, the server where the agent is running on gets the hostname "xyops" while this isn't the hostname of that server. I can change the label withing xyops, but i prefere it gets the right hostname. Do you have an idea what causes this?

[W13N3N]

Nevermind, i've managed to fix this by adding --hostname "hostnameoftheserver" to the startup command;

# 5. Start the Agent in the Background
# Manual launch since systemd is unavailable. Logs are sent to /var/log/xysat.log.
echo "Step 5: Launching xySat agent in the background..."
cd /opt/xyops/satellite
./bin/node main.js --hostname "hostnameoftheserver"> /var/log/xysat.log 2>&1 &

[jhuckaby]

Yup, you figured it out 😊

That is what I was going to recommend. You can also set it via the XYOPS_hostname environment variable, if you prefer doing it that way.

Cheers!